PHP Manual

# Руководство по PHP

2026-07-07
от:
Алексей Пыльцын
Андрей Громов
Евгений Четвериков
Михаил Алфёров
Сергей Зорин
Сергей Пантелеев
от:
Александр Москалёв
Александр Войцеховский
Алексей Асемов
Алексей Егоров
Алексей Шеин
Андрей Безруков
Андрей Деменев
Антон Довгаль
Борис Безруков
Борис Клименко
Борис Флейтлих
Даниил Реужков
Дмитрий Винярчук
Евгений Сюзев
Иван Коваленко
Казбек Джигкаев
Кирилл Барашкин
Максим Чабан
Михаил Баранов
Юрий Бабиков

# Авторские права

Авторские права © 1997—2026 принадлежат группе PHP-документирования. Эти материалы разрешается распространять только на условиях и соглашениях, которые устанавливает лицензия Creative Commons Attribution версии 3.0 или более поздней. Копия лицензии Creative Commons Attribution 3.0 распространяется вместе с руководством. Последняя версия доступна по адресу » http://creativecommons.org/licenses/by/3.0/.

# Руководство по PHP

# О руководстве

PHP, что расшифровывается как PHP: Hypertext Preprocessor («PHP: Препроцессор Гипертекста» — англ.), — распространённый интерпретируемый язык общего назначения с открытым исходным кодом, который создавался специально для ведения веб-разработки и умеет встраиваться в HTML-разметку. Синтаксис языка берёт начало из языков C, Java и Perl и лёгок для изучения. Главная цель языка — помочь веб-разработчикам быстро писать веб-страницы, которые генерируются динамически. Но с PHP делают больше.

Руководство в основном состоит из справочника по функциям, но также содержит справочник языка, объяснения отдельных PHP-функций и другие дополнительные сведения.

Руководство включает информацию, которая касается двух последних мажорных выпусков PHP — версии 7 и 8. Руководство не включает информацию о расширениях, которые эти PHP-версии больше не включают, и об изменениях функций в предыдущих версиях. Архивы старых версий руководства, которые документировали предыдущие PHP-выпуски, доступны в разделе «Дополнительная документация» на странице «» Документация».

Руководство доступно для скачивания в разных форматах по адресу » https://www.php.net/download-docs.php. Подробнее о работе надо руководством рассказывает приложение «О руководстве». Тем, кому интересна история языка, обращаются к разделу «История PHP».

# Авторы и Участники

Много участников помогают переводить документацию или серьёзно помогли проекту в прошлом. Неназванные участники оставляют на страницах руководства заметки для других пользователей. Заметки постоянно включаются в справочные материалы. За эту работу мы также очень благодарны. Списки участников приводятся в алфавитном порядке.

# Авторы и Редакторы

Следующие участники внесли значительный вклад в наполнение документации в прошлом: Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar и Andrei Zmievski.

Следующие участники внесли значительный вклад в редактирование и корректирование документации в прошлом: Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson и Egon Schmid.

# Редакторы пользовательских замечаний

Текущие наиболее активные редакторы: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda и Maciek Sokolewicz.

Эти люди внесли свой вклад в управление пользовательскими замечаниями в прошлом: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles и Jeroen van Wolffelaar.

# Приступая к работе

# Что такое PHP и что он умеет делать

## Что такое PHP?

PHP (рекурсивный акроним словосочетания PHP: Hypertext Preprocessor) — распространённый язык программирования общего назначения с открытым исходным кодом, который сконструировали специально для веб-разработки и который встраивают в HTML-разметку.

Простой ответ, но что он означает? Вот пример кода:

Пример #1 Пример программирования на языке PHP

    <!DOCTYPE html>
    <html>
        <head>
            <title>Пример</title>
        </head>
        <body>

            <?php
            echo "Привет, я — PHP-скрипт!";
            ?>

        </body>
    </html>

Вместо рутинного вывода HTML-кода командами языка (как в языках C или Perl), PHP-страницы содержат HTML-разметку со встроенным кодом, который проделывает полезную работу (в примере — выводит текст «Привет, я — PHP-скрипт!»). PHP-код отделяется начальным и конечным тегами `<?php` и `?>` — инструкциями начала и завершения обработки кода, которые разрешают входить в PHP-режим и выходить из него.

Язык PHP отличается от языка JavaScript, который обрабатывается на клиентской стороне, тем, что PHP-скрипты выполняются на сервере, и генерируют HTML-разметку, которая затем посылается клиенту. Клиент получит результаты запуска этого скрипта, но не будет знать, какой базовый код сгенерировал результаты. Веб-сервер настраивается даже так, чтобы обычные HTML-файлы обрабатывались процессором PHP, и тогда клиенты даже не смогут узнать, получают ли они обычный HTML-файл или результат выполнения скрипта.

Язык PHP чрезвычайно прост для начинающих программистов, но предлагает расширенные возможности программистам с опытом. Не бойтесь читать длинный список возможностей PHP. Написать простые PHP-скрипты получится уже через 1-2 часа после начала знакомства с языком.

Хотя PHP-разработка ориентирована на то, чтобы создавать серверные скрипты, язык этим не ограничивается. Продолжайте чтение и не пропустите главу «Что умеет PHP» или начните непосредственно с «Вводного руководства», чтобы перейти к изучению веб-программирования.

# Что умеет PHP

PHP умеет делать что-угодно. Главное назначение PHP — создавать скрипты, которые обрабатываются на сервере; поэтому PHP умеет выполнять всё то, что выполняет любая другая CGI-программа, например, обрабатывать данные форм, генерировать динамические страницы или отсылать и принимать cookies. Но PHP умеет намного больше.

PHP применяют в двух основных областях.

- Создают скрипты, которые обрабатываются на стороне сервера. Это традиционная и главная цель PHP. Чтобы написать и выполнить скрипт, понадобятся три вещи: Синтаксический анализатор PHP (в виде CGI-программы или серверного модуля), веб-сервер и браузер. Эти инструменты запускают на локальной машине, чтобы просто поэкспериментировать с программированием на PHP. Более подробные сведения даёт раздел «Установка и настройка».
- Создают скрипты для запуска в командной строке. PHP-скрипты запускаются без сервера или браузера, потребуется только парсер — синтаксический анализатор PHP. Такой способ работы с PHP идеально подходит для скриптов, которые требуется выполнять регулярно, например, через cron (на платформах *nix или Linux) или через «Планировщик задач» на платформах Windows. Этими скриптами также просто обрабатывают тексты. Дополнительную информацию даёт раздел «Работа с PHP из командной строки».

PHP работает на большей части операционных систем, включая Linux, многие модификации Unix (например, HP-UX, Solaris и OpenBSD), Microsoft Windows, macOS, RISC OS и многие другие. PHP также поддерживает бо́льшую часть современных веб-серверов наподобие Apache, IIS и многих других. Сюда входит любой веб-сервер, который умеет работать с двоичным PHP-файлом FastCGI-интерфейса, например, серверы Lighttpd и nginx. PHP работает либо как модуль, либо как CGI-процессор.

С PHP разработчик получает свободу выбора операционной системы и веб-сервера. Больше того, у программиста появляется выбор между процедурным или объектно-ориентированным программированием (ООП), или сочетанием обеих парадигм.

Программирование на PHP не ограничивается выводом HTML-разметки. PHP также умеет выводить файлы разных типов, например, изображений или PDF-файлов, шифровать данные и отправлять электронную почту. PHP также легко выводит текст наподобие JSON- или XML-строк. PHP умеет автоматически генерировать эти файлы и сохранять их в файловой системе, а не выводить на печать, чтобы сформировать серверный кеш для динамического содержимого.

Одно из значительных преимуществ языка PHP — поддержка широкого круга баз данных. Написать веб-страницу с поддержкой базы данных невероятно просто. Можно использовать модуль конкретной базы данных (например, mysql) или модуль уровня абстракции наподобие PDO, или соединиться с базой данных с поддержкой стандарта открытого подключения к базе данных (ODBC) через модуль ODBC. Для других баз данных, например, CouchDB, можно использовать библиотеку cURL или сокеты.

PHP также поддерживает взаимодействие с другими службами через протоколы LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (на платформах Windows) и многие другие. PHP также умеет открывать необработанные сетевые сокеты и взаимодействовать по другим протоколам. PHP поддерживает стандарт обмена сложными структурами данных WDDX практически между всеми языками веб-программирования. Обращая внимание на взаимодействие между разными языками, следует упомянуть о поддержке объектов языка Java и возможности использовать их как PHP-объекты.

PHP умеет обрабатывать текст, включая Perl-совместимые регулярные выражения (PCRE) и другие модули и инструменты для обработки и доступа к XML-документам. PHP стандартизирует XML-модули на прочной основе библиотеки libxml2, а также расширяет набор инструментов для обработки XML-документов за счёт добавления поддержки модулей SimpleXML, XMLReader и XMLWriter.

Другие интересные модули распределили как в алфавитном порядке, так и по категориям. Существуют также дополнительные PECL-модули, часть которых описывает это руководство, например, модуль » XDebug.

Как видно, этой страницы недостаточно, чтобы перечислить все возможности и преимущества языка PHP. Прочитайте разделы «Установка и настройка» и просмотрите главу «Справочник по функциям», которые дают дополнительные сведения о модулях, которые упоминает эта часть руководства.

# Простой учебник

## Содержание

- Первая страница на PHP
- Примеры кода
- Работа с формами
- Что дальше?

Это краткое и простое руководство показывает только основы PHP. Текст рассказывает, только как создавать динамические веб-страницы на PHP, хотя PHP умеет больше. Раздел «Что умеет PHP» даёт дополнительную информацию.

Веб-страницы с поддержкой PHP обрабатываются аналогично HTML-страницам: PHP-страницы создают и редактируют аналогично страницам на языке HTML-разметки.

# Первая страница на PHP

Вначале потребуется установить PHP. Инструкция по установке доступна » на странице загрузки.

Теперь создадим файл с названием hello.php и напишем внутри следующий код:

Пример #1 Первый скрипт на PHP: hello.php

    <?php

    echo "Привет, мир!";

В терминале перейдём в каталог, в котором содержится файл, и запустим сервер разработки следующей командой:

    php -S localhost:8000

Для доступа к файлу в браузере указывают URL-адрес, который состоит из адреса веб-сервера и ссылки на файл: `/hello.php`. Из команды, которую выполнили на предыдущем шаге, возьмём адрес веб-сервера и построим полный URL-адрес: `http://localhost:8000/hello.php`. При правильной конфигурации PHP обработает файл, а браузер покажет вывод: "Привет, мир!".

PHP-интерпретатор умеет генерировать веб-страницы из исходного кода, в котором PHP-код встроили в HTML-разметку. Поэтому PHP-инструкции записывают непосредственно внутри разметки будущего HTML-документа, как показывает следующий пример:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Тестируем PHP</title>
        </head>
        <body>
            <?php echo '<p>Привет, мир!</p>'; ?>
        </body>
    </html>

Код сгенерирует следующий HTML-вывод:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Тестируем PHP</title>
        </head>
        <body>
            <p>Привет, мир!</p>
        </body>
    </html>

Эта программа чрезвычайно проста, и чтобы создать настолько простую страницу, даже не обязательно запускать и писать код на PHP. Единственное, что делает программа, — выводит строку `Привет, мир!` PHP-инструкцией echo. Заметьте, что файл не требуется делать исполняемым или ещё каким-то образом отличаться от других файлов. Сервер знает, что этот файл требуется интерпретировать средствами PHP, поскольку расширение файла — ".php", которое сервер настроен передавать PHP. О PHP-файле думают как об обычном HTML-файле, который содержит набор тегов, которые умеют делать много интересного.

Цель примера — показать формат PHP-тегов. Тег `<?php` обозначает начало PHP-кода. Затем идёт PHP-инструкция и тег `?>`, который заставляет парсер выйти из режима интерпретации PHP-кода. Теги указывают в произвольном месте файла, когда требуется переключить режимы интерпретации PHP-кода и анализа HTML-разметки. Подробнее о разборе исходного кода рассказывает раздел руководства «Основы синтаксиса».

> Замечание: Замечание о переводах строк

> У переводов строк небольшое значение в HTML-разметке, однако, HTML-разметка с переносами выглядит аккуратной. PHP автоматически удаляет переводы строки, которые идут сразу после закрывающего тега `?>`. Это может быть чрезвычайно полезно при добавлении ряда блоков PHP-кода или при подключении PHP-файлов с PHP-кодом, который ничего не выводит. Но иногда это сбивает с толку. Можно поставить пробел после закрывающего тега `?>`, чтобы принудительно вывести пробел и перевод строки, или можно явно добавить перевод строки в последний вызов языковых конструкций echo или print из блока PHP-кода.

> Замечание: Кратко о текстовых редакторах

> PHP-файлы создают и редактируют в текстовых редакторах и интегрированных средах разработки (IDE). Список отдельных редакторов содержит статья » Список PHP-редакторов. Попросите администратора страницы добавить редактор, который рекомендуете, в список. Окажется полезным редактор с подсветкой синтаксиса.

> Замечание: Кратко о текстовых процессорах

> В текстовых процессорах наподобие StarOffice Writer, Microsoft Word и Abiword неудобно редактировать PHP-файлы. Убедитесь, что сохраняете файл в формате plain text, если изменяете тестовый скрипт в таком редакторе, иначе не получится прочитать и выполнить PHP-скрипт.

Теперь, когда узнали основы языка, пора создать самый знаменитый PHP-скрипт! Вызовите функцию phpinfo() и увидите много полезной информации о системе и настройке, например, доступные предопределённые переменные, загруженные PHP-модули и параметры настройки. Уделите время изучению этой важной информации.

Пример #2 Получение информации о системе средствами PHP

    <?php

    phpinfo();

# Примеры кода

Теперь напишем полезный код и узнаем, в каком браузере посетитель просматривает страницу. Для этого проверим строку пользовательского агента, которую браузер отправляет как часть HTTP-запроса. Информация об агенте содержится в массиве, который хранится в переменной. В PHP каждая переменная начинается со знака доллара, а значение отдельного элемента массива в переменной получают по ключу. Извлечём строку пользовательского агента из элемента $_SERVER['HTTP_USER_AGENT'].

> Замечание:

> $_SERVER — суперглобальная зарезервированная переменная, которую PHP заполняет информацией о запросе, среде выполнения и серверном окружении. Дополнительную информацию о таких переменных содержит раздел «Суперглобальные переменные».

Для вывода значения элемента массива, который хранится в переменной, напишем следующий код:

Пример #1 Вывод значения элемента массива

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

Пример вывода программы:

    Mozilla/5.0 (Linux) Firefox/112.0

В PHP-переменных хранят числа, строки, массивы и значения других типов. Тип значения, элемент которого выводил код предыдущего примера, называется массивом. Массивы полезны для хранения значений произвольных типов.

Переменная $_SERVER — только один пример переменной, к которой PHP автоматически открывает доступ. Список таких переменных приводит раздел «Зарезервированные переменные» или вывод функции phpinfo(), которую приводил как пример предыдущий раздел.

В PHP-тег разрешается помещать больше одной инструкции и создавать небольшие блоки кода, которые делают больше, чем простой вызов инструкции echo. Например, если требуется проверить, что используется браузер Firefox, делают так:

Пример #2 Пример использования управляющих структур и функций

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'Вы пользуетесь браузером Firefox.';
    }

Пример вывода программы:

    Вы пользуетесь браузером Firefox.

Здесь вводится ряд новых понятий. Во-первых, в коде появилась инструкция if. Если вы знакомы с основами синтаксиса языка C, код выглядит для вас логичным. Иначе, вероятно, лучше взять книгу об основах языка PHP и прочитать одну-две начальных главы или почитать раздел «Справочник языка» этого руководства.

Во-вторых, в коде появился вызов функции str_contains(). Функция str_contains() — встроенная в PHP функция, которая определяет, содержит ли строка другую строку. В примере функция ищет строку `«Firefox»` (т. н. «иголку», или needle) в элементе $_SERVER['HTTP_USER_AGENT'] (в т. н. «стоге сена», или haystack). Если функция нашла «иголку» в «стоге сена», она возвращает логическое значение `true`. Иначе функция возвращает логическое значение `false`. Если функция вернёт `true`, то условие в выражении конструкции if окажется истинным (`true`), а PHP выполнит код в фигурных скобках {}. Иначе код не выполняется. Попробуйте создать аналогичные примеры с использованием инструкций if и else, а также других функций наподобие strtoupper() и strlen(). Каждая страница руководства также содержит примеры. Почитайте страницу руководства о том, как читать определения функций, и раздел о PHP-функциях, если не знаете, как использовать функции.

Пойдем дальше и покажем, как переходить в режим PHP и выходить из режима интерпретации даже в середине блока PHP-кода:

Пример #3 Смешение режимов HTML и PHP

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        ?>
        <h3>Функция str_contains() вернула значение true</h3>
        <p>Вы просматриваете страницу в браузере Firefox.</p>
        <?php
    } else {
        ?>
        <h3>Функция str_contains() вернула значение false</h3>
        <p>Ваш браузер не похож на Firefox.</p>
        <?php
    }

Пример вывода данной программы:

    <h3>Функция str_contains() вернула значение true</h3>
    <p>Вы просматриваете страницу в браузере Firefox.</p>

Вместо вывода текста инструкцией echo, мы вышли из режима интерпретации PHP-кода и написали HTML-разметку. Логическая последовательность выполнения PHP-кода при этом сохраняется: PHP отправит пользователю только один блок HTML-разметки на основе значения, которое вернёт функция str_contains() по результатам поиска подстроки `Firefox`.

# Работа с формами

Список преимуществ PHP дополняет способ обработки HTML-форм. Основа заключается в том, что PHP-скрипт автоматически получает доступ к каждому элементу формы. Подробнее о работе с формами в PHP рассказывает раздел «Переменные из внешних источников». Вот пример HTML-формы:

Пример #1 Простейшая HTML-форма

    <form action="action.php" method="post">
        <label for="name">Имя:</label>
        <input name="name" id="name" type="text">

        <label for="age">Возраст:</label>
        <input name="age" id="age" type="number">

        <button type="submit">Отправить</button>
    </form>

В этой форме нет ничего особенного. Это обычная HTML-форма без каких-либо специальных тегов. Когда пользователь заполнит форму и нажмёт кнопку отправки, PHP вызовет страницу action.php. В файле пишут что-то вроде этого:

Пример #2 Выводим данные формы

    Привет, <?php echo htmlspecialchars($_POST['name']); ?>.
    Тебе <?php echo (int) $_POST['age']; ?> лет.

Пример вывода программы:

    Привет, Сергей. Тебе 30 лет.

Кроме частей, в которых вызывается функция htmlspecialchars() и приводится тип `(int)`, понятно, что делает код. Функция htmlspecialchars() гарантирует, что специальные HTML-символы правильно закодировались, поэтому люди не смогут внедрить HTML-теги или Javascript-код на страницу. Поскольку известно, что поле age — число, можно просто преобразовать значение в целое число (int), что автоматически избавит нас от случайных символов. PHP также может сделать это автоматически через модуль filter. PHP автоматически устанавливает переменные в элементах $_POST['name'] и $_POST['age']. Раньше мы использовали суперглобальную переменную $_SERVER, а здесь мы точно так же используем суперглобальную переменную $_POST, которая содержит POST-данные. Обратите внимание, что для атрибута method в форме установили значение POST. Если бы указали метод GET, информацию формы содержала бы суперглобальная переменная $_GET. В коде также обращаются к суперглобальной переменной $_REQUEST, если источник данных запроса не имеет значения. Эта переменная содержит объединенную информацию о GET-, POST- и COOKIE-данных.

# Что дальше?

Новые знания помогут понять бо́льшую часть руководства.

В частности, рекомендуется изучить следующие возможности:

- Чтение и запись файлов с помощью функций для работы с файловой системой
- Обработка выгрузки файлов
- Получение удалённых страниц и файлов через Curl
- Хранение и анализ данных в базе данных через PDO (SQLite разрешается использовать без запуска сервера базы данных)
- Сохранение данных между запросами через сессии

На » сайте репозитория Packagist доступно множество библиотек и » фреймворков на любой случай, которые устанавливают через менеджер пакетов Composer.

За помощью и советом сообщества рекомендуется обращаться к » странице поддержки.

Подкасты, презентации и другие видеоматериалы доступны на » PeerTube-канале сообщества.

Среди прочих ресурсов сообщества полезными будут «awesome-списки» (тематические подборки ссылок) и «developer roadmaps» (списки связанных тем для изучения).

Если непонятно, с чего начать, попробуйте разбить проект или задачу на более мелкие части, чтобы было проще увидеть, что уже знакомо, а что предстоит изучить. Список разбивают настолько подробно, насколько потребуется. Например, разработку блога можно разделить на следующие части:

- Список и просмотр страниц
  - Чтение записей (страниц) из базы данных
- Создание страниц
  - Обработка отправки формы
  - Запись записей (страниц) в базу данных
- Вход администратора
  - Чтение записей (пользователей) из базы данных
  - Работа с паролями
  - Сохранение данных (входа пользователя) между запросами и страницами (сессии)

Если конкретной идеи для разработки нет, можно поискать упражнения по программированию: каты, испытания и «код-гольф». Даже если они не нацелены конкретно на PHP, бо́льшую часть из них разрешается решить, и это, вероятно, поможет проверить знания и развить мышление.

- Введение — Что такое PHP и что он умеет делать
- Простой учебник
  - Первая страница на PHP
  - Примеры кода
  - Работа с формами
  - Что дальше?

# Установка и настройка

# Общие инструкции по установке

Перед установкой требуется понять, какие задачи будет решать PHP. Раздел «Что может PHP?» описывает две основных цели работы с PHP:

- Создавать сайты и веб-приложения (скрипты выполняются на стороне сервера)
- Писать скрипты для запуска в командной строке

Для первой и самой распространённой цели требуются три вещи: сам PHP, веб-сервер и веб-браузер. Вероятно, в системе уже содержится веб-браузер и, в зависимости от настроек операционной системы, также установлен и веб-сервер (например, Apache в системах Linux и macOS; или IIS в ОС Windows). Можно также арендовать веб-сервер или дисковое пространство на веб-сервере. Тогда не потребуется устанавливать дополнительное программное обеспечение, только писать PHP-скрипты, загружать скрипты на сервер и просматривать результат работы скриптов в браузере.

При самостоятельной настройке сервера и PHP у разработчика есть два способа подключения PHP к серверу. Для многих серверов у PHP есть прямой модульный интерфейс, который называется SAPI. К этим серверам относятся серверы Apache, Microsoft Internet Information Server, Netscape и iPlanet. Если PHP не поддерживает модуль для веб-сервера, можно запускать PHP как CGI- или FastCGI-обработчик: когда сервер настроили на обработку каждого PHP-файла, который запросили на сервере, исполняемым CGI-файлом языка PHP.

Для запуска PHP-скриптов в командной строке (например, чтобы генерировать изображения в автономном режиме или по-разному обрабатывать текстовые файлы в зависимости от аргументов, которые передали файлам, и т. д.), потребуется исполняемый PHP-файл командной строки. Подробнее об этом рассказывает раздел «Работа с PHP в командной строке». Тогда не потребуется ни сервер, ни браузер.

С этого момента рассматривается настройка PHP на веб-серверах Unix и Windows с модулем, у которого есть интерфейс для взаимодействия с PHP, и исполняемым CGI-файлом. Информацию об исполняемом файле командной строки дадут следующие разделы.

Исходный код PHP и бинарные сборки для ОС Windows доступны по адресу: » https://www.php.net/downloads.php.

# Установка в Unix-системы

## Содержание

- Установка из пакетов в ОС Debian GNU/Linux и родственных дистрибутивах
- Установка из пакетов в дистрибутивы GNU/Linux с менеджером пакетов DNF
- Установка из пакетов или портов в ОС OpenBSD
- Установка из исходного кода в системы Unix и macOS
- Установка с интерфейсами CGI и командной строки
- Apache 2.x на Unix системах
- Установка Nginx 1.4.x на систему Unix
- Установка PHP на Lighttpd 1.4 на Unix-системах
- Веб-серверы LiteSpeed и OpenLiteSpeed в системах Unix
- Инструкции по инсталляции для ОС Solaris

Бо́льшая часть операционных систем и дистрибутивов Unix и Linux включают упакованную версию PHP и модули, доступные через их систему пакетов. Руководство содержит разделы с базовой информацией об установке PHP через эти системы пакетов.

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

PHP также устанавливают как компонент отдельных сторонних серверов приложений.

Наконец, установка PHP доступна из исходных дистрибутивов, что даёт максимальную гибкость в выборе функций, модулей и API-интерфейсов сервера для включения. Руководство содержит разделы с информацией о компиляции и настройке PHP для работы с разными серверными API-интерфейсами.

## Установка из пакетов в ОС Debian GNU/Linux и родственных дистрибутивах

Хотя PHP доступен для установки из исходного кода, язык также доступен для установки из пакетов с сайта » Debian GNU/Linux. Это также справедливо для других дистрибутивов на основе Debian наподобие Ubuntu, Kali Linux и Linux Mint.

Внимание

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

Пакеты устанавливают командой apt или командой aptitude. Эта страница руководства взаимозаменяет обе команды.

### Команда APT

Во-первых, обратите внимание, что иногда требуются и другие связанные пакеты: `libapache-mod-php` требуется для интеграции с веб-сервером Apache 2, а пакет `php-pear` для интеграции с репозиторием PEAR.

Во-вторых, перед установкой проверяют актуальность списка пакетов. Это часто делают командой apt update.

Пример #1 Пример установки Apache 2 в ОС Debian

    # apt install php-common libapache2-mod-php php-cli

Команда APT автоматически установит PHP-модуль для Apache 2 и зависимости, а затем активирует их. Потребуется перезапустить веб-сервер Apache, чтобы изменения вступили в силу. Например:

Пример #2 Остановка и запуск веб-сервера Apache после установки PHP

    # /etc/init.d/apache2 stop
    # /etc/init.d/apache2 start

### Контроль конфигурации

В последнем разделе PHP установили только с модулями ядра. Дополнительные модули наподобие MySQL, cURL, GD и другие устанавливают командой `apt`.

Пример #3 Методы перечисления дополнительных PHP-пакетов

    # apt-cache search php
    # apt search php | grep -i mysql
    # aptitude search php

Список пакетов включит много пакетов, в которых будут базовые компоненты PHP наподобие php-cgi, php-cli и php-dev, и много других модулей. После установки модулей автоматически установятся дополнительные пакеты, которые удовлетворят зависимости пакетов модулей.

Пример #4 Установка PHP с MySQL и cURL

    # apt install php-mysql php-curl

APT автоматически добавит строки в файлы вроде /etc/php/7.4/php.ini, /etc/php/7.4/conf.d/*.ini и другие, которые связаны и соответствуют файлу php.ini, и в зависимости от модуля добавит записи наподобие `extension=foo.so`. Потребуется перезапустить веб-сервер вроде того же Apache, чтобы изменения вступили в силу

### Стандартные проблемы

- Веб-сервер не обрабатывает PHP-скрипты. Самая частая причина состоит в том, что PHP не добавили в файл конфигурации веб-сервера. В ОС Debian файл конфигурации часто лежит по пути /etc/apache2/apache2.conf или аналогичном. Подробнее рассказывает руководство по ОС Debian.
- PHP не находит функции модуля. Причина часто состоит в том, что не загрузили INI-файл и (или) после установки модуля не перезапустили веб-сервер.

## Установка из пакетов в дистрибутивы GNU/Linux с менеджером пакетов DNF

Хотя PHP устанавливают из исходного кода, в системах наподобие Red Hat Enterprise Linux, OpenSUSE, Fedora, CentOS, Rocky Linux и Oracle Enterprise Linux, которые работают с менеджером пакетов DNF, он также доступен в виде пакетов.

Внимание

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

Пакеты устанавливают командой dnf.

### Установка пакетов

Первое, обратите внимание, что часто требуются и другие связанные пакеты, например пакет `php-pear` для установки модулей из репозитория » PEAR или пакет `php-mysqlnd` для установки модуля MySQL .

Второе, перед установкой пакета лучше обновить список пакетов. Обычно это делают путём запуска команды dnf update.

Пример #1 Пример установки пакета через пакетный менеджер DNF

    # dnf install php php-common

Менеджер пакетов DNF автоматически установит PHP-конфигурацию для веб-сервера, а чтобы изменения вступили в силу потребуется перезапустить веб-сервер. Например:

Пример #2 Перезапуск веб-сервера Apache после установки PHP

    # sudo systemctl restart httpd

### Улучшенный контроль конфигурации

В последнем разделе PHP установили только с базовыми модулями. Вероятно, потребуются дополнительные модули наподобие MySQL, cURL, GD, другие. Дополнительные модули также устанавливают через команду dnf.

Пример #3 Вывод списка дополнительных PHP-пакетов

    # dnf search php

В список попадёт много пакетов — базовые PHP-компоненты наподобие `php-cli`, `php-fpm` и `php-devel` и много PHP-модулей. При установке модулей автоматически установятся дополнительные пакеты, которые удовлетворят зависимости пакетов.

Пример #4 Установка PHP с модулями MySQL и GD

    # dnf install php-mysqlnd php-gd

Пакетный менеджер DNF автоматически добавит строки конфигурации в файлы наподобие /etc/php/8.3/php.ini, /etc/php/8.3/conf.d/*.ini и другие файлы, которые связаны с файлом PHP-конфигурации php.ini, и добавит для модулей записи вроде `extension=foo.so`. Изменения вступят в силу после перезапуска веб-сервера, того же Apache.

## Установка из пакетов или портов в ОС OpenBSD

Cекция содержит замечания и советы, которые касаются установки PHP на ОС » OpenBSD.

### Работа с бинарными пакетами

Бинарные пакеты для установки PHP на OpenBSD — простейший и рекомендованный способ. Ядро (основной пакет) отделили от модулей, но каждый из них устанавливается или удаляется независимо от другого. Файлы, которые потребуются для установки, доступны на CD-диске с ОС OpenBSD или на FTP-сервере.

Основной пакет, который потребуется установить — php, он содержит базовый движок (плюс модули fpm, gettext и iconv) и доступен в разных версиях на выбор. Затем обратите внимание на пакеты модулей наподобие php-mysqli или php-imap. Включением модулей в файле php.ini управляют командой phpxs.

Пример #1 Пример установки пакетов в OpenBSD

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      (install the PEAR libraries)
    # pkg_add pear

    Следуйте инструкциям, которые выводят пакеты во время установки!

      (to remove packages)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

Страница руководства к функции » packages(7) даёт больше информации о бинарных пакетах в ОС OpenBSD.

### Использование портов

PHP также компилируют из исходного кода » дерева портов. Способ рекомендуют только пользователям с опытом работы в ОС OpenBSD. Порт PHP разделили на ядро и модули. Модули генерируют подпакеты для каждого модуля, который поддерживается PHP. Параметр вроде no_*, где вместо символа звёздочки указали название модуля, не станет создавать модуль. Например, чтобы пропустить и не создавать модуль imap, устанавливают параметр no_imap.

### Стандартные проблемы

- Веб-серверы Apache и Nginx больше не веб-серверы по умолчанию для OpenBSD, но они доступны в портах и пакетах. Новый сервер по умолчанию называется 'httpd'.
- Стандартная установка httpd работает » в изоляции chroot(2), что запрещает PHP доступ к файлам вне каталога /var/www. Поэтому потребуется создать директорию /var/www/tmp, чтобы сохранять файлы PHP-сессий, или использовать альтернативный бэкенд для управления сессиями. Сокеты баз данных потребуется разместить в изоляции или прослушивать на интерфейсе localhost. При работе с сетевыми функциями отдельные файлы из каталога /etc наподобие /etc/resolv.conf и /etc/services потребуется переместить в каталог /var/www/etc. Пакет OpenBSD репозитория PEAR автоматически устанавливается в правильные каталоги chroot.
- Пакет модуля » gd для OpenBSD требует установки графического интерфейса Xorg. Пакет добавляют после базовой установки (смотрите » OpenBSD FAQ#4), если пакет ещё не установили при базовой установке путём добавления набора файлов xbase.tgz.

## Установка из исходного кода в системы Unix и macOS

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

- » GNU-пакет make
- Компилятор языка C (начиная с PHP 8.0.0 требуется совместимость с C99; начиная с PHP 8.4.0 требуется совместимость с C11)
- Веб-сервер
- Компоненты, характерные для модуля, наподобие библиотек GD, PDF и другие

При сборке из исходного кода репозитория Git или после пользовательских модификаций иногда требуются следующие дополнительные инструменты:

- Автоматический конструктор сценариев настройки » autoconf, версия которого соответствует версии PHP:
  - PHP 7.3 и новее: 2.68+
  - PHP 7.2: 2.64+
  - PHP 7.1 и старше: 2.59+
- Генератор лексеров » re2c, версия которого соответствует версии PHP:
  - PHP 8.3 и новее: 1.0.3+
  - PHP 8.2 и старше: 0.13.4+
- Генератор парсеров » bison, версия которого соответствует версии PHP:
  - PHP 7.4 и новее: 3.0.0+
  - PHP 7.3 и старше: 2.4+ (включая Bison 3.x)

Более подробную информацию о компиляции PHP из исходного кода содержит файл » README.md в архиве с исходным кодом.

Процесс первоначальной установки и настройки PHP контролируется параметрами командной строки пакета настройки скриптов — configure. Список доступных опций с краткими пояснениями показывает запуск команды ./configure --help. Это руководство документирует опции отдельно. Основные параметры описывает «Список основных опций конфигурации», тогда как другие опции, характерные для модулей, описывают справочные страницы.

После запуска скрипта конфигурации PHP собирают командой make. Раздел ЧАВО «Установка» содержит дополнительную информацию о разрешении проблем при сборке.

> Замечание: Из-за вопросов безопасности отдельные Unix-системы наподобие OpenBSD и SELinux иногда запрещают отображение в памяти страниц, к которым открыт доступ и на запись, и на выполнение. Такая защита называется » PaX MPROTECT или » W^X-защита от нарушений. Такое отображение памяти требуется для поддержки JIT-компиляции регулярных выражений PCRE-библиотек, поэтому PHP собирают либо без поддержки JIT-компиляции регулярных выражений PCRE-библиотек, либо вносят двоичный файл в белый список доступными системе средствами.

> Замечание: Кросс-компиляция для ARM-архитектуры через набор инструментов Android пока не поддерживается.

## Установка с интерфейсами CGI и командной строки

По умолчанию, PHP собирается одновременно как CLI и CGI программа, которая может быть использована для обработки CGI-запросов. PHP как модуль сервера выигрывает в производительности, однако PHP CGI позволяет запускать PHP от пользователя, отличного от того, под которым исполняется сервер.

Внимание

Сервер, который развернули в режиме CGI, открывается для ряда возможных уязвимостей. Пожалуйста, прочитайте раздел «О безопасности PHP в режиме CGI-программы», который объясняет, как защититься от таких атак.

### Тестирование

Если вы собрали PHP как CGI, вы можете протестировать вашу сборку командой make test. Тестирование вашей сборки - всегда хорошая идея. Таким образом вы сможете раньше обнаружить проблемы PHP на вашей платформе, вместо того, чтобы бороться с ними позже.

### Использование переменных

Некоторые переменные окружения сервера не определены в текущей » спецификации CGI/1.1. Определены только следующие переменные: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL и SERVER_SOFTWARE. Все остальное должно обрабатываться как дополнительные модули (vendor extensions).

## Apache 2.x на Unix системах

Раздел описывает установку PHP c веб-сервером Apache 2.x на Unix-системах.

Внимание

Разработчики PHP не рекомендуют использовать многопоточный MPM-модуль в производственной среде, в которой работает Apache 2. Лучше предпочесть prefork-версию модуля MPM, которая в Apache 2.0 и 2.2 идёт по умолчанию. Подробнее о причинах рассказывает ответ раздела FAQ о работе Apache2 с многопоточным MPM-модулем

Наиболее авторитетный источник информации по Apache 2.x — » документация к Apache. Документация даёт подробную информацию о настройках при установке.

Последняя версия веб-сервера Apache HTTP Server доступна для загрузки » на странице загрузки Apache, а совместимая версия PHP — на странице Download на этом сайте. Это краткое руководство описывает только базовую установку Apache 2.x и PHP. Дополнительную информацию даёт » документация к Apache. В инструкции ниже опустили номера версий — замените 'NN' на номер, который соответствует версии Apache.

Сайт веб-сервера предлагает для загрузки две версии Apache 2.x — 2.4 и 2.2. Лучше предпочесть последнюю версию — 2.4, если нет причин для установки версии 2.2. Инструкции этого раздела будут работать как для версии 2.4, так и для версии 2.2. Обратите внимание, что поддержку Apache httpd 2.2 официально прекратили, поэтому разработку этой версии остановили и больше не выпускают исправлений.

1. Скачайте Apache HTTP Server по приведённой ссылке и распакуйте его:

       tar -xzf httpd-2.x.NN.tar.gz

2. Аналогичным способом скачайте и распакуйте исходные коды PHP:

       tar -xzf php-NN.tar.gz

3. Скомпилируйте и установите Apache. Подробнее об установке рассказывает документация к Apache.

       cd httpd-2_x_NN
       ./configure --enable-so
       make
       make install

4. Теперь Apache 2.x.NN доступен по адресу /usr/local/apache2, установщик настроил веб-сервер на поддержку загружаемых модулей и работу через стандартный мультипроцессный MPM-модуль, который отвечает на запросы по модели prefork: обрабатывает запросы в отдельном потоке однопоточных процессов. Правильно ли прошла установка, проверяют через стандартную процедуру запуска Apache — командой наподобие вот такой:

       /usr/local/apache2/bin/apachectl start

   Затем остановите сервер, чтобы сконфигурировать и установить PHP:

       /usr/local/apache2/bin/apachectl stop

5. Теперь сконфигурируем и соберём PHP. На этом этапе PHP настраивают через опции конфигурации, чтобы указать, например, какие модули требуется включить. Запустите команду ./configure --help, чтобы получить список доступных параметров конфигурации. В примере мы выполним простую настройку с поддержкой веб-сервера Apache и БД MySQL.

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

       cd ../php-NN
       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
       make
       make install

   Если потребуется изменить параметры конфигурации после установки, то потребуется повторно выполнить шаги configure, make и make install. Просто перезапустите Apache, чтобы изменения вступили в силу и новый модуль начал работать. Перекомпиляция Apache для этого не требуется.

   Обратите внимание: если не указали иное, команда make install установит также пакетный менеджер » PEAR, инструменты PHP наподобие phpize, установит CLI-интерфейс для работы с PHP в командной оболочке и другие компоненты.

6. Настройте файл php.ini.

       cp php.ini-development /usr/local/lib/php.ini

   Установка параметров PHP доступна через редактирование файла `.ini`. Укажите параметр `--with-config-file-path=/some/path` в шаге 5, если предпочитаете хранить файл php.ini в другом месте.

   Если вместо этого вы выберете файл php.ini-production, прочитайте список изменений внутри, поскольку они влияют на поведение PHP.

7. Отредактируйте файл httpd.conf, чтобы Apache загружал модуль PHP. Путь к PHP-модулю указывают справа от инструкции `LoadModule`. Команда make install, возможно, уже добавила эту инструкцию автоматически, ну лучше проверить.

   Для PHP 8:

       LoadModule php_module modules/libphp.so

   Для PHP 7:

       LoadModule php7_module modules/libphp7.so

8. Скажите веб-серверу Apache, чтобы он разбирал файлы с конкретными расширениями как PHP-код. Например, пусть Apache разбирает как PHP-код файлы с расширением `.php`. Вместо установки только Apache-директивы `AddType` избегают исполнения опасных загрузок и файлов наподобие exploit.php.jpg. Аналогично следующему примеру указывают одно или больше произвольных расширений, которые веб-сервер будет разбирать как файлы с PHP-кодом. Для демонстрации добавим расширение `.php`.

       <FilesMatch \.php$>
           SetHandler application/x-httpd-php
       </FilesMatch>

   Или, когда требуется разрешить запуск PHP-кода из файлов с расширениями `.php`, `.php2`, `.php3`, `.php4`, `.php5`, `.php6` и `.phtml`, но не другими, настройка выглядит вот так:

       <FilesMatch "\.ph(p[2-6]?|tml)$">
           SetHandler application/x-httpd-php
       </FilesMatch>

   А чтобы фильтр исходного PHP-кода обрабатывал файлы с расширением `.phps` и показывал как исходный код с подсветкой синтаксиса, настройку записывают вот так:

       <FilesMatch "\.phps$">
           SetHandler application/x-httpd-php-source
       </FilesMatch>

   Модуль `mod_rewrite` умеет показывать произвольные файлы с расширением `.php` как исходный код с подсветкой синтаксиса без переименования или копирования в файл с расширением `.phps`:

       RewriteEngine On
       RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

   Фильтр исходного PHP-кода отключают в производственной среде, поскольку он раскрывает конфиденциальную или другую чувствительную информацию, которую встроили в исходный код.

9. Сервер Apache запускают стандартной процедурой наподобие:

       /usr/local/apache2/bin/apachectl start

   ИЛИ

       service httpd restart

Выполнение действий, которые описала эта страница, запускает веб-сервер Apache2 с поддержкой PHP в виде `SAPI`-модуля. Конечно, для PHP и Apache доступно гораздо больше параметров конфигурации. Дополнительную информацию даёт команда ./configure --help при запуске в соответствующем дереве исходного кода.

Сборка веб-сервера Apache будет работать в многопоточном режиме, если при сборке Apache вместо стандартного мультипроцессного MPM-модуля prefork выбрать мультипроцессный MPM-модуль, который отвечает на запросы по модели worker: обрабатывает отдельный запрос в отдельном потоке многопоточного процесса. Чтобы сделать это, к аргументу, который передали команде ./configure на шаге 3, добавляют следующую опцию:

    --with-mpm=worker

Веб-сервер собирают для работы по такой модели, только если осознают последствия решения и отчётливо понимают смысл действий. Документация Apache » к MPM-модулям рассматривает работу модулей MPM подробнее.

> Замечание:

> В разделе FAQ в ответе на вопрос о параметре MultiViews в настройках Apache обсуждается согласование контента множественного представления при работе веб-сервера с PHP-файлами.

> Замечание:

> Только в системах с поддержкой потоков получится собрать многопоточную версию Apache. Тогда требуется и PHP-сборка с поддержкой потокобезопасного ZTS-режима (англ. Zend Thread Safety). В этой конфигурации не каждое расширение будет доступно. Разработчики PHP рекомендуют настраивать сборку Apache на работу с MPM-модулем prefork по умолчанию.

## Установка Nginx 1.4.x на систему Unix

Эта документация описывает установку и настройку PHP с менеджером процессов PHP-FPM для HTTP-сервера Nginx 1.4.x.

Это краткое руководство предполагает, что Nginx собран из исходного кода и поэтому бинарные файлы и файлы конфигурации лежат в директории `/usr/local/nginx`. Если нет, и вы получили Nginx другим способом, тогда, пожалуйста, обратитесь к » Nginx Wiki, чтобы получить похожее на это руководство для вашей установки.

В этом кратком руководстве будут рассмотрены основы настройки Nginx-сервера для обработки PHP-приложений и их обслуживания на порту 80. Рекомендовано изучить документацию Nginx и PHP-FPM, если нужно оптимизировать установку за рамками этой документации.

Пожалуйста, обратите внимание, что в этой документации номера версий были заменены на символ «x», чтобы документация оставалась корректной в будущем. Пожалуйста, замените «x» на необходимый номер версии.

1. Рекомендовано зайти » на страницу установки Nginx Wiki, чтобы получить и установить HTTP-сервер Nginx на свою систему.

2. Распаковать полученный исходный код PHP:

       tar zxf php-x.x.x

3. Настроить и собрать PHP. Здесь вы настраиваете PHP с нужными параметрами. Запустите команду ./configure --help, чтобы получить список доступных опций. В примере будут сделаны простые настройки для включения менеджера процессов PHP-FPM с поддержкой модуля MySQLi.

       cd ../php-x.x.x
       ./configure --enable-fpm --with-mysqli
       make
       sudo make install

4. Переместить файлы конфигурации в правильные места

       cp php.ini-development /usr/local/php/php.ini
       cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
       cp sapi/fpm/php-fpm /usr/local/bin

5. Важно запретить серверу Nginx передавать запросы в бэкенд менеджера PHP-FPM, если файл не существует, что помогает предотвратить атаки произвольного внедрения скрипта.

   Это исправляют установкой для директивы cgi.fix_pathinfo значения `0` в файле php.ini.

   Отредактировать файл php.ini:

       vim /usr/local/php/php.ini

   Найти директиву `cgi.fix_pathinfo=` и изменить вот так:

       cgi.fix_pathinfo=0

6. Файл php-fpm.conf нужно изменить, чтобы указать, что модуль php-fpm должен работать от имени пользователя www-data и группы www-data, до того как мы запустим сервис:

       vim /usr/local/etc/php-fpm.d/www.conf

   Найти и изменить следующее:

       ; Unix user/group of processes
       ; Замечание: Пользователь обязателен. Если группа не установлена,
       ; будет использована стандартная группа пользователя.
       user = www-data
       group = www-data

   Теперь можно запускать сервис php-fpm:

       /usr/local/bin/php-fpm

   Это руководство не рассматривает другие настройки модуля php-fpm. Обратитесь к документации по php-fpm, если нужны дополнительные настройки.

7. Настроить Nginx на поддержку обработки PHP-приложений:

       vim /usr/local/nginx/conf/nginx.conf

   Измените блок «location» по умолчанию так, чтобы HTTP-сервер знал, что он должен обслуживать файлы .php:

       location / {
           root   html;
           index  index.php index.html index.htm;
       }

   Следующий шаг — убедиться, что файлы .php передаются в бэкенд PHP-FPM. Введите следующее:

       location ~* \.php$ {
           fastcgi_index   index.php;
           fastcgi_pass    127.0.0.1:9000;
           include         fastcgi_params;
           fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
           fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
       }

   Перезапустите Nginx.

       sudo /usr/local/nginx/sbin/nginx -s stop
       sudo /usr/local/nginx/sbin/nginx

8. Создайть тестовый файл

       rm /usr/local/nginx/html/index.html
       echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

   Теперь откройте в браузере адрес http://localhost. Должна отобразиться информация, которую выводит функция phpinfo().

Выполнив описанные шаги, вы получите работающий Nginx-сервер с поддержкой PHP в качестве модуля интерфейса `FPM` `SAPI`. Конечно, для Nginx и PHP доступно больше параметров конфигурации. Наберите в директории с исходным кодом команду ./configure --help, чтобы получить больше информации.

## Установка PHP на Lighttpd 1.4 на Unix-системах

Этот раздел содержит информацию по установке PHP на Unix-системы с сервером Lighttpd 1.4.

Прочитайте, пожалуйста, инструкции по установке Lighttpd в » документации по Lighttpd перед установкой PHP.

FastCGI - предпочитаемый интерфейс для связи PHP и Lighttpd. FastCGI доступен по умолчанию в php-cgi.

### Управление процессами php через Lighttpd

Для настройки Lighttpd на соединение с PHP и порождения процессов FastCGI необходимо отредактировать конфигурационный файл lighttpd.conf. Предпочтительнее подключаться к процессам FastCGI используя Unix-сокеты.

Пример #1 Пример части файла lighttpd.conf

    server.modules += ( "mod_fastcgi" )

    fastcgi.server = ( ".php" =>
      ((
        "socket" => "/tmp/php.socket",
        "bin-path" => "/usr/local/bin/php-cgi",
        "bin-environment" => (
          "PHP_FCGI_CHILDREN" => "16",
          "PHP_FCGI_MAX_REQUESTS" => "10000"
        ),
        "min-procs" => 1,
        "max-procs" => 1,
        "idle-timeout" => 20
      ))
    )

Директива bin-path позволяет lighttpd динамически запускать процессы FastCGI. Lighttpd будет динамически создавать дочерние процессы php, согласно переменной окружения PHP_FCGI_CHILDREN. Директива `bin-environment` задаёт настройки для дочерних процессов. PHP_FCGI_MAX_REQUESTS определяет порог, при достижении которого PHP завершит дочерний процесс. Директив `min-procs` и `max-procs` обычно стоит избегать. PHP управляет только своими дочерними процессами, и инструменты кеширования в байт-код (например, APC) будут использоваться только в этих дочерних процессах. Если значение `min-procs` установлено больше `1`, общее количество процессов, обрабатывающих запросы, будет равно PHP_FCGI_CHILDREN * min-procs.

### Управление процессами с помощью spawn-fcgi

Lighttpd предоставляет программу spawn-fcgi для облегчения управления дочерними процессами FastCGI.

### Управление процессами с помощью php-cgi

Управлять процессами можно и без spawn-fcgi, но это потребует некоторых доработок. Переменная окружения PHP_FCGI_CHILDREN указывает количество дочерних процессов, запускаемых PHP для обработки входящих запросов. Переменная PHP_FCGI_MAX_REQUESTS отвечает за количество запросов, которые обработает один процесс. Ниже приведён простой bash-скрипт, облегчающий создание дочерних процессов.

Пример #2 Создание FastCGI-обработчиков

    #!/bin/sh

    # Местоположение бинарного файла php-cgi
    PHP=/usr/local/bin/php-cgi

    # Местоположение PID-файла
    PHP_PID=/tmp/php.pid

    # Привязка к адресу
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Привязка к сокету
    FCGI_BIND_ADDRESS=/tmp/php.sock

    PHP_FCGI_CHILDREN=16
    PHP_FCGI_MAX_REQUESTS=10000

    env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
           PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
           $PHP -b $FCGI_BIND_ADDRESS &

    echo $! > "$PHP_PID"

### Подключение к удалённым процессам FCGI

Обработчики FastCGI могут находиться на нескольких отдельных машинах для масштабирования нагрузки.

Пример #3 Подключение к удалённым процессам fastcgi

    fastcgi.server = ( ".php" =>
       (( "host" => "10.0.0.2", "port" => 1030 ),
        ( "host" => "10.0.0.3", "port" => 1030 ))
    )

## Веб-серверы LiteSpeed и OpenLiteSpeed в системах Unix

LiteSpeed PHP — оптимизированная сборка PHP для работы с продуктами LiteSpeed через SAPI-интерфейс LiteSpeed. LSPHP запускается как самостоятельный процесс из отдельного исполняемого файла, с которым также работают как со стандартной утилитой для выполнения PHP-скриптов в командной строке.

LSAPI — высокопроизводительный API для взаимодействия веб-серверов LiteSpeed с веб-приложениями. Протоколы взаимодействия с интерфейсами LSAPI и FCGI архитектурно аналогичны, но с веб-серверами LiteSpeed интерфейс LSAPI работает эффективнее.

Документация описывает установку и настройку сборки PHP для работы с веб-серверами LiteSpeed (LSWS) и OpenLiteSpeed (OLS) через LSAPI.

Руководство предполагает, что веб-сервер LSWS или OLS установили по стандартным путям и со стандартными флагами. Директория установки по умолчанию для обоих веб-серверов — /usr/local/lsws, и оба сервера запускаются из подкаталога bin.

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

1. Скачайте исходный код веб-сервера с сайта документации: » страница с инструкциями по установке веб-сервера LiteSpeed или » страница с инструкциями по установке веб-сервера OpenLiteSpeed.

2. Скачайте и распакуйте исходный код PHP:

       mkdir /home/php
       cd /home/php
       wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
       tar -zxvf php-x.x.x.tar.gz
       cd php-x.x.x

3. Сконфигурируйте и соберите PHP. На этом этапе определяют параметры сборки — указывают опции компиляции, SAPI и модули, которые требуется включить в PHP-сборку. Команда ./configure --help выведет список доступных опций. Следующий пример показывает стандартные рекомендованные параметры конфигурации для LSWS:

       ./configure ... '--with-litespeed'
       make
       sudo make install

4. Проверьте установку LSPHP

   Корректность установки PHP проверяют следующими командами:

       cd /usr/local/lsws/fcgi-bin/
       ./lsphp5 -v

   Команда вернёт информацию о PHP-сборке:

       PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
       Copyright (c) 1997-2014 The PHP Group
       Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

   Обратите внимание на маркер `litespeed` в скобках. Маркер указывает, что исполняемый файл PHP собрали с поддержкой LSAPI.

Выполнение приведённых шагов подготовит веб-сервер LiteSpeed или OpenLiteSpeed к запуску и добавит в PHP поддержку SAPI-интерфейса LiteSpeed. О дополнительных параметрах конфигурации связки веб-сервера LSWS или OLS с PHP рассказывает раздел » об управлении LSPHP на сайте документации к веб-серверу LiteSpeed.

Работа с LSPHP в командной строке:

LSPHP — PHP-интерпретатор с поддержкой LSAPI-интерфейса. Двоичный файл lsphp запускают на удалённом хосте в режиме командной строки. LSPHP запустит и обработает PHP-скрипт автономно — устанавливать веб-сервер на удалённом узле не потребуется. В раздельной конфигурации локальный веб-сервер принимает запрос, а PHP-скрипт выполняется на удалённой машине. Раздельная установка повышает масштабируемость сервиса, поскольку обработка PHP-скриптов переносится на удалённый сервер.

Запустите исполняемый файл lsphp из командной строки на удалённом сервере: LSPHP — исполняемый файл, который поддерживает ручной запуск и привязку к IPv4-, IPv6- или Unix-сокету через опцию командной строки -b socket_address.

Пример:

Привязка LSPHP к порту 3000 на всех IPv4- и IPv6-адресах:

    /path/to/lsphp -b [::]:3000

Привязка LSPHP к порту 3000 на всех IPv4-адресах:

    /path/to/lsphp -b *:3000

Привязка LSPHP к адресу 192.168.0.2:3000:

    /path/to/lsphp -b 192.168.0.2:3000

Настройка LSPHP на приём запросов через сокет Unix-домена `/tmp/lsphp_manual.sock`:

    /path/to/lsphp -b /tmp/lsphp_manual.sock

Перед запуском LSPHP поддерживается установка переменных окружения:

    PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

LiteSpeed PHP поддерживает работу с веб-серверами LiteSpeed, OpenLiteSpeed и модулем mod_lsapi веб-сервера Apache. Инструкции по настройке серверов доступны на страницах документации: » LiteSpeed и » OpenLiteSpeed.

Другие способы установки LSPHP:

CentOS: компоненты LSPHP доступны для установки в виде » RPM-пакетов из репозиториев LiteSpeed или Remi.

Debian: компоненты LSPHP устанавливают из репозитория LiteSpeed командой » apt.

cPanel: об установке компонентов LSPHP на веб-серверах LSWS и OLS с панелью управления cPanel через инструмент EasyApache 4 рассказывает » страница документации.

Plesk: об управлении компонентами LSPHP через панель Plesk на машинах под управлением операционных систем CentOS, CloudLinux, Debian и Ubuntu рассказывает » страница документации.

## Инструкции по инсталляции для ОС Solaris

Данный раздел содержит инструкции и советы для установки PHP на ОС Solaris.

### Требования к программному обеспечению

Зачастую в составе операционной системы Solaris отсутствует компиляторы языка C и сопутствующие им утилиты. Ознакомьтесь с этим FAQ, чтобы узнать, почему необходимо использовать GNU-версии этих утилит.

Для распаковки дистрибутива PHP вам понадобится

- tar
- gzip или
- bzip2

Для компиляции PHP вам понадобится

- gcc (рекомендован, но другие компиляторы C также могут подойти)
- make
- GNU sed

Для сборки некоторых модулей или редактирования исходников PHP также могут понадобиться

- re2c
- bison
- m4
- autoconf
- automake

Дополнительно, вам нужно будет установить (и, возможно, скомпилировать) дополнительное ПО, необходимое в вашей конфигурации, например Oracle или MySQL.

### Использование установочных пакетов

Вы можете упростить процесс установки в Solaris, используя утилиту pkgadd для установки нужных вам компонент. Система управления пакетами (IPS) операционной системы Solaris 11 Express также позволяет установить большинство требуемых компонент с помощью команды pkg.

# Установка на macOS

## Содержание

- Установка в ОС macOS через сторонние пакеты
- Компилирование PHP на macOS
- Работа со встроенным PHP в ОС macOS до версии Monterey

PHP входил в комплект ОС macOS в версиях 10 и 11, но с macOS 12 Monterey PHP перестали включать в комплект. На свежие версии операционной системы PHP устанавливают или через пакеты из источников, которые поддерживаются третьими лицами, или собирают из исходного кода.

## Установка в ОС macOS через сторонние пакеты

Для macOS предварительно упаковали и скомпилировали ряд версий PHP. Предварительная упаковка и компиляция версий PHP помогает в настройке стандартной конфигурации, но когда требуются другой набор функций — сервер с защитой или другой драйвер базы данных — PHP и (или) веб-сервер собирают сами. Разработчики, которые не знакомы со сборкой и компиляцией программного обеспечения, проверяют, не собрал ли версию PHP с необходимыми функциями кто-то другой.

Менеджер пакетов » Homebrew упрощает установку PHP на машину с ОС macOS.

1. Установите менеджер пакетов Homebrew по инструкциям на сайте.

2. Запустите команду brew install php, чтобы установить пакет PHP.

Следующие альтернативные ресурсы также предлагают простые в установке пакеты и предварительно скомпилированные двоичные файлы для PHP в операционной системе macOS:

- » MacPorts
- » Fink

## Компилирование PHP на macOS

Для компиляции PHP на macOS прочтите руководство по установке на Unix.

## Работа со встроенным PHP в ОС macOS до версии Monterey

PHP поставляли с операционными системами macOS с macOS 10.0.0 X по macOS 12.0.0 Monterey. На стандартном веб-сервере PHP включают путём удаления комментариев в ряде строк в конфигурационном файле httpd.conf веб-сервера Apache, тогда как CGI- и (или) CLI-версии PHP-интерпретатора поставляли включёнными по умолчанию, и в этих режимах PHP оставался доступным для терминальных программ.

Включение PHP согласно приведённой ниже инструкции предназначено для быстрой настройки локальной среды разработки. Разработчики языка PHP настоятельно рекомендуют каждый раз обновлять PHP до самой новой стабильной версии. Аналогично большей части программного обеспечения, разработка которого продолжается, новые версии выпускают, чтобы исправить ошибки и добавить новые функции, то же касается и PHP. Читайте документацию по установке PHP в ОС macOS, которая описывает подробности. Следующие инструкции составили для начинающих разработчиков и они описывают стандартную установку, которая помогает быстро приступить к работе. Пользователям рекомендуют скомпилировать или установить из репозитория самую новую версию PHP.

Стандартная установка PHP в виде серверного модуля mod_php, который включается для стандартного веб-сервера macOS (сервер по умолчанию доступен через системные настройки), включает следующие шаги:

1. Найдите и откройте конфигурационный файл Apache. По умолчанию файл лежит по пути /private/etc/apache2/httpd.conf Поиска файла через файловый менеджер `Finder` или встроенный механизм поиска `Spotlight` иногда затруднён, поскольку файл лежит в приватном пространстве и принадлежит пользователю `root`.

   > Замечание: Открыть этот файл помогает консольный редактор наподобие `nano`, который запускают через терминал. Поскольку файл принадлежит пользователю `root`, потребуется выполнить команду `sudo`, чтобы открыть файл. Команда `sudo` повышает привилегии текущего пользователя до пользователя `root`. Просто запустите приложение `Terminal`, введите команду `sudo nano /private/etc/apache2/httpd.conf` и введите пароль, когда команда запросит его. Полезные команды редактора nano: `^w` (найти), `^o` (сохранить) и `^x` (закрыть), где `^` — клавиша Ctrl.

   > Замечание: Версии macOS до 10.5 содержат устаревшие версии PHP и веб-сервера Apache, поэтому конфигурационный файл иногда лежит по пути /etc/httpd/httpd.conf.

2. В текстовом редакторе найдите следующие строки и удалите символ # из начала строки, чтобы удалить комментарии. Эти строки часто находятся в разных местах файла:

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   Запомните путь к файлу, поскольку позднее, при сборке PHP, эти строки иногда требуется изменять.

3. Убедитесь, что файлы с расширениями вроде .php, .html и .inc обрабатываются как PHP-скрипты.

   Поскольку с версии Mac Panther конфигурационный файл httpd.conf уже содержит следующие инструкции, после включения PHP сразу начнёт автоматически обрабатывать файлы с расширением .php.

       <IfModule mod_php5.c>
           # PHP обработает файлы с расширением .php и .phps., если модуль PHP загрузили
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Часто требуется, чтобы PHP рассматривал файл index.php
           # как страницу по умолчанию, если её прямо не указали в URL-адресе.
           # Следующие инструкции делают файлы index.html и index.php файлами по умолчанию
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > Замечание:

   > До macOS 10.5 Leopard в состав ОС включали PHP 4, а не PHP 5, поэтому в инструкциях для 4-й версии просто заменяют 5 на 4.

4. Убедитесь, что директива DirectoryIndex загружает индексный файл по умолчанию. Это поведение задают в файле httpd.conf. Часто указывают файлы index.php и index.html. По умолчанию веб-сервер включает файл index.php, который отключают, если нужно.
5. Определите местоположение файла php.ini или оставьте настройки по умолчанию. Стандартный путь файла конфигурации PHP в ОС macOS — /usr/local/php/php.ini и вызов функции phpinfo() выведет информацию, которая соответствует настройкам в файле. PHP применяет для директив конфигурации значения по умолчанию, если PHP не нашёл и не загрузил файл php.ini. Смотрите также раздел FAQ, который касается поиска файла php.ini.
6. Расположение директивы `DocumentRoot` и установка корневого каталога документов веб-сервера. DocumentRoot — корневой каталог файлов веб-сервера. Файлы в этом каталоге обслуживает веб-сервер, поэтому перед выводом в браузер веб-сервер обработает PHP-файлы как файлы PHP-скриптов. Стандартный путь по умолчанию — /Library/WebServer/Documents, но когда требуется указать другой путь, его изменяют в файле httpd.conf. Для отдельных пользователей как альтернативу значению директивы DocumentRoot по умолчанию устанавливают путь наподобие /Users/yourusername/Sites.
7. Создайте файл с функцией phpinfo().

   Функция phpinfo() выводит информацию о PHP. Создайте в директории, которую указали в директиве DocumentRoot, скрипт с таким кодом:

       <?php phpinfo(); ?>

8. Перезапустите Apache и запросите через браузер файл, который создали прежде.

   Для перезапуска веб-сервера запустите в терминале команду `sudo apachectl graceful` или выполните перезапуск ПО Personal Web Server в системных настройках macOS. По умолчанию локальные файлы загружаются в браузер по URL-адресу наподобие http://localhost/info.php или по DocumentRoot-пути в локальной директории пользователя, которая примет вид: http://localhost/~yourusername/info.php

Название CLI-версии двоичного файла PHP-интерпретатора, или в более старых версиях CGI-версии, соответствует названию языка — php и лежит по пути /usr/bin/php. Откройте терминал, прочитайте раздел документации PHP командная строка и запустите команду `php -v`, чтобы проверить установленную версию PHP. Вызов функции phpinfo() также выведет эту информацию.

# Установка в системы с ОС Windows

## Содержание

- Рекомендуемая конфигурация в системах Windows
- Ручная установка готовых двоичных файлов
- Установка для веб-сервера Apache 2.x в системах Windows
- Установка PHP с веб-сервером IIS для ОС Windows
- Сторонние инструменты для установки PHP
- Сборка из исходного кода
- Запуск PHP в командной строке системы Windows

Официальные версии PHP для Windows рекомендуются для производственных целей, но PHP также собирают из исходного кода.

PHP также устанавливают на платформу Azure App Services, которая ещё называется Microsoft Azure, Windows Azure или (Windows) Azure Web Apps.

Раздел ЧАВО «Установка» рассматривает частые проблемы установки и настройки, с которыми сталкиваются разработчики.

## Рекомендуемая конфигурация в системах Windows

### Модуль OpCache

Разработчики языка PHP настоятельно рекомендуют включать модуль OpCache. Модуль компилирует и оптимизирует PHP-скрипты, а затем кеширует скрипты в памяти, чтобы они не компилировались при каждой загрузке страницы.

Установите в файле php.ini следующие опции:

Пример #1 Рекомендуемая конфигурация модуля OpCache

    opcache.enable=On
    opcache.enable_cli=On

И перезагрузите веб-сервер. Подробнее о настройке модуля рассказывает страница «Конфигурация OpCache».

### Модуль WinCache

При работе с веб-сервером IIS рекомендуют включать модуль WinCache, особенно в окружении, которое даёт виртуальный хостинг, или при запуске приложения с сетевого файлового хранилища NAS (англ. Network Attached Storage). Обратите внимание, начиная с PHP 8.0.0 модуль WinCache больше не поддерживается. Приложения PHP автоматически получат преимущества, которые даёт модуль WinCache. Операции файловой системы кешируются в памяти. Модуль WinCache также умеет кешировать в памяти пользовательские объекты и разделять эти объекты между процессами файла php.exe или php-cgi.exe — совместно использовать объекты между запросами. В большие веб-приложения часто устанавливают плагин, модуль или настраивают параметр конфигурации, чтобы работать с кешем пользовательских объектов через модуль WinCache. Кеш объектов включают в приложениях, когда требуется высокая производительность. Модуль WinCache скачивают в каталог PHP-модулей, который определяет директива extension_dir в файле php.ini. Модуль доступен как DLL-файл или файл архива WINCACHE_*.tgz на сайте » https://pecl.php.net/package/WinCache. Установите в файле php.ini следующие опции:

Пример #2 Рекомендуемая конфигурация модуля WinCache

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; Директиву удалили с wincache 2.0.0.0

Подробнее о настройке модуля рассказывает страница «Конфигурация WinCache».

## Ручная установка готовых двоичных файлов

### Требования к установке

PHP доступен только для 32-битных x86- или 64-битных x64-систем и не работает на Windows RT или Windows на ARM. Начиная с версии 8.3.0 PHP требует Windows 8 или Windows Server 2012. Версии после 7.2.0 требуют Windows 2008 R2 или Windows 7. Версии до 7.2.0 поддерживают Windows 2008 и Vista.

PHP требует среду выполнения Visual C (CRT). Многим другим приложениям также требуется эта среда выполнения поэтому её, скорее всего, уже установили, а если нет, — устанавливают пакет Microsoft Visual C++ Redistributable для Visual Studio 2022, который совместим со всеми версиями PHP и доступен для скачивания » на сайте Microsoft.

Для работы с x86-сборкой PHP требуется x86-версия CRT и x64-версия CRT для x64-сборок PHP. Установщик выведет сообщение о том, что пакет уже установили, и не внесёт изменений, если пакет CRT уже установили. Установщик пакета CRT поддерживает переключатели командной строки /quiet и /norestart, поэтому установку получится выполнить через скрипт.

### Где скачать исполняемые файлы PHP

Сборки Windows доступны для скачивания » с сайта PHP для Windows. Каждую сборку оптимизировали техникой PGO (англ. Profile-guided optimization), а QA- и GA-выпуски тщательно протестировали.

### Готовые PECL-модули

Для ОС Windows готовые сборки PECL-модулей распространяются как DLL-файлы. В репозитории PECL для каждого такого модуля предусмотрели отдельную страницу.

Двоичные файлы недоступны для модулей, которые используют функции, характерные для других систем наподобие Unix или зависят от библиотек, которые недоступны в ОС Windows.

### Типы сборок

Четыре типа PHP-сборок:

- Потокобезопасная сборка Thread-Safe (TS) — для однопроцессных веб-серверов наподобие Apache с PHP-модулем mod_php.

- Непотокобезопасная сборка Non-Thread-Safe (NTS) — для веб-сервера IIS и веб-серверов наподобие Apache с модулем mod_fastcgi, которые работают через интерфейс FastCGI. Этот тип сборки рекомендуют для скриптов, которые запускают через интерфейс командной строки.

- Сборка x86 — для 32-битных систем.

- Сборка x64 — для 64-битных систем.

## Установка для веб-сервера Apache 2.x в системах Windows

Раздел содержит примечания и подсказки, которые касаются установки PHP для веб-сервера Apache 2.x в системах Microsoft Windows.

> Замечание:

> Сначала лучше прочитать пошаговую инструкцию по ручной установке PHP.

Прежде чем продолжить чтение руководства, разработчики PHP настаивают на знакомстве » с документацией к веб-серверу Apache, чтобы получить базовое представление о сервере Apache 2.x, и » примечаниями, которые касаются установки веб-сервера Apache 2.x в системы Windows.

Загрузите последнюю версию веб-сервера » Apache 2.x и совместимую версию PHP. Следуйте пошаговой инструкции по ручной установке PHP и возвращайтесь, чтобы продолжить интеграцию PHP и Apache.

Для работы с веб-сервером Apache 2.x в операционных системах Windows двоичные файлы PHP настраивают тремя способами. PHP запускают как обработчик — Apache-модуль, через который веб-сервер обрабатывает файлы с PHP-кодом, как CGI-программу или программу, которая работает через FastCGI-интерфейс.

> Замечание: Обратите внимание: при указании путей в конфигурационных файлах веб-сервера Apache, который работает под ОС Windows, обратные слеши в путях наподобие c:\directory\file.ext требуется заменить прямыми: c:/directory/file.ext. Для путей с директориями также иногда требуется слеш в конце.

### Установка PHP как Apache-обработчика PHP-файлов

> Замечание: При работе через обработчик apache2handler, который обслуживает запросы к SAPI-интерфейсу, устанавливают потокобезопасные версии PHP (англ. TS, Thread Safe).

В файл конфигурации веб-сервера Apache httpd.conf вставляют следующие строки, чтобы загрузить PHP-модуль для Apache 2.x:

Пример #1 Пример конфигурации для обработки PHP-файлов модулем PHP в составе веб-сервера Apache 2.x

    # До PHP 8.0.0 модуль назывался php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # Настраиваем путь к файлу php.ini
    PHPIniDir "C:/php"

> Замечание: В приведённых примерах вместо пути C:/php/ подставляют фактический путь к PHP. Убедитесь, что файл, который указали в директиве `LoadModule`, лежит в заданном месте. Для PHP 7 указывают файл php7apache2_4.dll или файл php8apache2_4.dll для PHP 8.

### Запуск PHP как CGI-программы

» Документация Apache к CGI-интерфейсу даёт более полное понимание о запуске CGI-скриптов на веб-сервере Apache.

PHP-файлы, которые запускаются как CGI-скрипты, располагают в каталоге, который через директиву ScriptAlias назначали как каталог CGI-скриптов, чтобы запускать PHP-скрипты как программу, которая работает по протоколу CGI.

В PHP-файлы потребуется поместить строку `#!`, которая указывает на расположение двоичного файла PHP:

Пример #2 Пример расположения двоичного файла PHP и взаимодействие с веб-сервером Apache 2.x через CGI-интерфейс

    #!C:/php/php.exe
    <?php

    phpinfo();

    ?>

Внимание

Сервер, который развернули в режиме CGI, открывается для ряда возможных уязвимостей. Пожалуйста, прочитайте раздел «О безопасности PHP в режиме CGI-программы», который объясняет, как защититься от таких атак.

### Запуск PHP для работы по протоколу FastCGI

Запуск программ на языке PHP в режиме FastCGI даёт ряд преимуществ перед запуском PHP-программ в режиме CGI. Настройка этого способа несложная:

Скачайте модуль `mod_fcgid` с сайта » https://www.apachelounge.com. Бинарные файлы Win32 доступны для загрузки с этого сайта. Установите модуль по инструкции, которая идёт с файлами.

Настройте веб-сервер как в следующем примере, и внимательно измените пути так, чтобы они соответствовали установке веб-сервера в конкретной системе:

Пример #3 Настройка Apache для запуска PHP как FastCGI

    LoadModule fcgid_module modules/mod_fcgid.so
    # Где лежит файл php.ini?
    FcgidInitialEnv PHPRC        "c:/php"
    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

Теперь файлы с расширением `.php` будет исполнять FastCGI-обёртка PHP.

## Установка PHP с веб-сервером IIS для ОС Windows

### Установка веб-сервера ISS

Веб-сервер Internet Information Services (IIS) встроили в операционную систему Windows. На ОС Windows Server роль IIS добавляют через диспетчер серверов Server Manager. Функцию роли CGI-интерфейса требуется включить. На настольных системах Windows Desktop роль IIS добавляется через пункт Панели управления «Установка и удаление программ». Документация Microsoft содержит » подробные инструкции о включении IIS. Для разработки также устанавливают версию веб-сервера » IIS Express.

> Замечание: При запуске веб-сервера IIS с обработчиком FastCGI устанавливают непотокобезопасную версию PHP (англ. Non-Thread Safe, NTS).

### Настройка PHP с IIS

В диспетчере IIS устанавливают модуль FastCGI и сопоставляют обработку файлов с расширением `.php` с обработчиком скриптов по пути php-cgi.exe, но не php.exe.

Скрипт конфигурации веб-сервера IIS создают инструментом командной строки APPCMD.

### Пример пакетного скрипта

Пример #1 Скрипт командной строки для настройки IIS и PHP

    @echo off

    REM download .ZIP file of PHP build from http://windows.php.net/downloads/

    REM path to directory into which PHP .ZIP file was decompressed (no trailing \)
    set phppath=c:\php

    REM Clear current PHP handlers
    %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
    REM The following command will generate an error message if PHP is not installed. This can be ignored.
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

    REM Set up the PHP handler
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

    REM Configure FastCGI Variables
    %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

## Сторонние инструменты для установки PHP

Внимание

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

Сборки » XAMPP, » WampServer и » Bitnami также настроят PHP-приложения для работы с веб-сервером Apache в системе Windows.

## Сборка из исходного кода

О сборке со средой разработки Visual Studio рассказывает » пошаговая инструкция по сборке.

## Запуск PHP в командной строке системы Windows

Раздел содержит примечания и подсказки, которые касаются запуска PHP из командной строки Windows.

> Замечание:

> Сначала прочитайте пошаговое руководство по установке!

PHP запускают из командной строки без внесения каких бы то ни было изменений в Windows.

    C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

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

> Замечание:

> Переменные окружения PATH и PATHEXT — важные переменные, которые появились в Windows в самом начале и которые нельзя перезаписывать, а только добавлять для них значения.

- Добавьте расположение исполняемого файла PHP — php.exe, php-win.exe или php-cli.exe, в зависимости от версии PHP и предпочтений отображения — в переменную окружения PATH. Подробнее о добавлении каталога PHP в переменную окружения PATH рассказывает запись часто задаваемых вопросов.

- Добавьте расширение `.PHP` к переменной окружения PATHEXT. Это делают одновременно с изменением переменной окружения PATH. Выполните те же действия, что и в ЧАВО, но измените переменную окружения PATHEXT, а не PATH.

  > Замечание:

  > Позиция, в которую помещают расширение `.PHP`, будет определять, какой скрипт или программа выполнится при совпадении имён файлов. Например, расположение расширения `.PHP` перед расширением `.BAT` запустит скрипт, а не пакетный файл, если каталог содержит пакетный файл с тем же названием.

- Настройте ассоциацию расширения `.PHP` с типом файла путём запуска следующей команды:

      assoc .php=phpfile

- Настройте ассоциацию типа файла `phpfile` с исполняемым файлом PHP, который соответствует этому типу файла, путём запуска следующей команды:

      ftype phpfile="C:\php\php.exe" -f "%1" -- %~2

Эти шаги настроят запуск PHP-скриптов из любого каталога без ввода исполняемого PHP-файла или расширения `.PHP`, а параметры передадутся скрипту для обработки.

Следующий пример приводит отдельные изменения в реестре, которые вносят вручную.

Пример #1 Пример изменений в реестре

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
    @="phpfile"
    "Content Type"="application/php"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
    @="PHP Script"
    "EditFlags"=dword:00000000
    "BrowserFlags"=dword:00000008
    "AlwaysShowExt"=""

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
    @="C:\\php\\php-win.exe,0"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
    @="Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
    @="&Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
    @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

С этими изменениями эту же команду получится записать вот так:

    "C:\PHP Scripts\script" -arg1 -arg2 -arg3

или, если путь `"C:\PHP Scripts"` записали в переменную окружения PATH:

    script -arg1 -arg2 -arg3

> Замечание:

> При такой технике запуска возникает небольшая проблема с запуском PHP-скриптов в качестве фильтра командной строки, как в примере ниже:

>     dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3

> или

>     dir | script -arg1 -arg2 -arg3

> Иногда скрипт просто зависает и ничего не выводит. В реестр вносят ещё одно изменение, чтобы это заработало.

>     Windows Registry Editor Version 5.00

>     [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
>     "InheritConsoleHandles"=dword:00000001

> Дополнительную информацию по этой проблеме даёт » статья базы знаний Microsoft: 321788. В Windows 10 этот параметр изменили на противоположный, и стандартная установка Windows 10 поддерживает унаследованные дескрипторы консоли. Это » сообщение на форуме Microsoft даёт объяснение.

# Установка на платформах Cloud Computing

## Содержание

- Azure App Services
- Amazon EC2
- DigitalOcean

PHP устанавливают на облачные платформы.

## Azure App Services

PHP часто устанавливают на облачный сервис Azure App Services, который также знают по названиям Microsoft Azure, Windows Azure и Azure Web Apps.

Azure App Services управляет пулом Windows Web Servers для хостинга веб-приложений и представляет альтернативу созданию собственного веб-сервера на собственном Azure Compute VMs и других платформах.

PHP по умолчанию доступен для веб-сайта в Azure App Services. Просто выберите на Azure Portal сайт и выберите нужную версию PHP. Доступен выбор более свежей версии, чем версия по умолчанию.

Таким образом, PHP и его модули будут работать в Azure App Services так же, как и на других серверах Windows. Тем не менее, интерфейс управления для Azure App Services отличается:

- Azure portal: создание, настройка и удаление сайтов. » Azure Portal

- Панель управления службы Kudu: для сайта с URL-адресом `site_name.azurewebsites.net` адрес панели управления движка Kudu будет таким: `https://site_name.scm.azurewebsites.net/`. Панель управления открывает доступ к отладке, управлению файлами и модулями сайта. Модули сайта — механизм службы Azure, который добавляет на сайт дополнительные программы, например предварительные PHP-сборки.

- Диспетчер веб-сервера IIS Manager, диспетчер управления сервером Server Manager и удалённый рабочий стол RDP будут недоступны.

PHP SDK позволяет программно использовать множество Azure Services. Смотрите » Azure SDK для PHP.

Для более подробной информации, смотрите » Azure PHP Developer Center

### WinCache

WinCache по умолчанию разрешён в Azure App Services и рекомендуется его не отключать. Если вы установили собственную сборку PHP, вы должны разрешить WinCache.

### Собственные сборки PHP

Вы можете загрузить собственную сборку PHP в D:\Home (C:\ НЕ ДОСТУПЕН для записи). После чего, на Azure Portal, задайте SCRIPT_PROCESSOR для .php равный абсолютному пути к php-cgi.exe из вашей сборки.

## Amazon EC2

PHP устанавливается на » облачную платформу EC2.

Смотрите также » AWS SDK для PHP.

## DigitalOcean

DigitalOcean предлагает следующие платформы для установки PHP и запуска веб-приложений в своей инфраструктуре облачного хостинга.

- » Cloudways: развёртывание основных приложений PHP одним щелчком мыши: WordPress, Magento, Drupal, Laravel и других.

- » Droplet: Блоки виртуальной машины и установка » стека Lamp на Linux-сервере .

- » App Platform: управляемая инфраструктура для быстрого создания, развёртывания и масштабирования приложений. Узнайте, » как запускать PHP-приложения на платформе приложений App Platform. .

- » Functions: Бессерверная платформа, которая помогает разработчикам запускать код без подготовки или управления серверами. Есть встроенная поддержка PHP. Узнайте, » как создавать бессерверные функции в PHP .

# Менеджер процессов FastCGI (FPM)

## Содержание

- Установка
- Настройка

FPM (FastCGI Process Manager, менеджер процессов интерфейса FastCGI) — основная реализация интерфейса FastCGI для PHP, которая в основном содержит функционал, полезный для высоконагруженных сайтов.

Эта функциональность включает:

- Продвинутое управление процессами с корректной (graceful) процедурой остановки и запуска;

- Пулы, которые умеют запускать воркеры с разными uid, gid, chroot и окружением за счёт прослушивания разных портов и работы с разными файлами php.ini (замещение safe_mode);

- Настраиваемое ведение журнала потоков вывода (stdout) и ошибок (stderr);

- Аварийный перезапуск в случае внезапного разрушения opcode-кеша;

- Поддержка ускоренной загрузки (accelerated upload);

- slowlog — логирование необычно медленных скриптов; не только имён, но и PHP-трассировки, которое даёт команда ptrace и другие подобные функции чтения исполняемых данных (execute_data) удалённых процессов;

- fastcgi_finish_request() — специальная функция для завершения запроса и сброса всех буферов данных, причём процесс сможет продолжать выполнение других длительных действий (конвертирование видео, обработка статистики и т. п.);

- Динамическое, по требованию или статическое порождение дочерних процессов;

- Базовая и расширенная информация о состоянии (аналогично модулю mod_status веб-сервера Apache) с поддержкой разных форматов наподобие json, xml и openmetrics;

- Файл конфигурации на основе файла php.ini.

## Установка

### Компиляция из исходников

Для включения FPM в сборку PHP требуется добавить в строку конфигурации параметр `--enable-fpm`.

Следующий список содержит ряд других необязательных опций конфигурации FPM:

- `--with-fpm-user` — установить пользователя FPM. Значение по умолчанию: nobody.

- `--with-fpm-group` — установить группу FPM. Значение по умолчанию: nobody.

- `--with-fpm-systemd` — Включить интеграцию с systemd. Значение по умолчанию: no.

- `--with-fpm-acl` — Включить поддержку списков управления доступом (англ. Access Control Lists, ACL) по стандарту POSIX. Значение по умолчанию: no.

- `--with-fpm-apparmor` — Активировать интеграцию с AppArmor. Значение по умолчанию: no.

- `--with-fpm-selinux` — Активировать интеграцию с SELinux. Значение по умолчанию: no.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Добавили опцию `--with-fpm-selinux`.
8.0.0 | Добавили опцию `--with-fpm-apparmor`.

## Настройка

Формат конфигурационных файлов FPM — php-fpm.conf и файлов конфигурации пулов — аналогичен синтаксису файла php.ini.

### Список глобальных директив файла php-fpm.conf

`pid` string

  Путь к PID-файлу. Значение по умолчанию: none.

`error_log` string

  Путь к файлу журнала ошибок. Значение по умолчанию: `#INSTALL_PREFIX#/log/php-fpm.log`. Менеджер отправляет журнал в демон syslogd, а не в локальный файл, если установили значение "syslog".

`log_level` string

  Уровень журналирования ошибок. Директива принимает значения: alert, error, warning, notice, debug. Значение по умолчанию: notice.

`log_limit` int

  Устанавливает ограничение на длину строк журнала, которое разрешает регистрировать сообщения, длина которых превышает 1024 символа без переноса строк. Значение по умолчанию: 1024. Доступно с PHP 7.3.0.

`log_buffering` bool

  Экспериментальное журналирование без дополнительной буферизации. Значение по умолчанию: yes. Доступно с PHP 7.3.0.

`syslog.facility` string

  Указывает, какой тип программ будет логировать сообщения. Значение по умолчанию: daemon.

`syslog.ident` string

  Добавляется перед каждым сообщением. Значение по умолчанию изменяют на то, которое удовлетворит общим требованиям, если на сервере работает больше одного экземпляра FPM. Значение по умолчанию: php-fpm.

`emergency_restart_threshold` int

  FPM перезагрузится, если это количество дочерних процессов завершится с сигналом SIGSEGV или SIGBUS в течение интервала времени, который установили в директиве `emergency_restart_interval`. Значение 0 означает 'Off' — отключено. Значение по умолчанию: 0 (Off).

`emergency_restart_interval` mixed

  Интервал времени, с которым будет работать директива `emergency_restart_interval`, чтобы определить, когда FPM-менеджер мягко перезагрузится. Это полезно для устранения случайных повреждений общей памяти ускорителя (accelerator). Доступные единицы измерения: s (секунды), m (минуты), h (часы) или d (дни). Единица измерения по умолчанию: секунды. Значение по умолчанию: 0 (Off).

`process_control_timeout` mixed

  Время, в течение которого дочерние процессы ждут ответа на сигналы мастер-процессу. Доступные единицы измерения: s (секунды), m (минуты), h (часы) или d (дни). Единица измерения по умолчанию: секунды. Значение по умолчанию: 0.

`process.max` int

  Максимальное количество процессов, которое породит FPM. Директиву разработали для контроля глобального количества процессов при работе с динамическим PM в большом количестве пулов. При работе с директивой соблюдают осторожность. Значение по умолчанию: 0.

`process.priority` int

  Указывает приоритет (Unix nice(2)) мастер-процесса (только если установили). Принимает значения от -19, которое означает максимальный приоритет, до 20 — минимальный. Значение по умолчанию: нет.

`daemonize` bool

  Запускает FPM в фоновом режиме. Установка значения 'no' запускает FPM в диспетчере для отладки. Значение по умолчанию: yes.

`rlimit_files` int

  Устанавливает rlimit открытых файловых дескрипторов для мастер-процесса. Значение по умолчанию: значение, которое определила система.

`rlimit_core` int

  Устанавливает rlimit максимального размера ядра для мастер-процесса. По умолчанию 0.

`events.mechanism` string

  Указывает, какой событийный механизм будет использовать FPM. Доступны значения: epoll, kqueue (*BSD), port (Solaris), poll, select. Значение по умолчанию: нет, работает автоопределение, отдавая предпочтение epoll и kqueue.

`systemd_interval` int

  Указывает интервал, в секундах, между оповещениями systemd о своём состоянии, если FPM собрали с интеграцией с systemd. Значение 0 отключает оповещения. Значение по умолчанию: 10.

### Список директив для пулов.

Через FPM запускают набор пулов процессов с разными настройками. Эти параметры разрешается передавать пулу.

`listen` string

  Адрес, который будет принимать FastCGI-запросы. Синтаксис: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. Опция обязательна для каждого пула.

`listen.backlog` int

  Устанавливает listen(2) backlog. Значение `-1` означает максимум на системах BSD. Значение по умолчанию: `-1` (FreeBSD или OpenBSD) или `511`. (Linux и другие платформы).

`listen.allowed_clients` string

  Список IPv4- или IPv6-адресов клиентов FastCGI, которым разрешается подключение. Эквивалент переменной окружения FCGI_WEB_SERVER_ADDRS в оригинальном PHP FastCGI (5.2.2+). Смысл в установке директивы появляется только с TCP-сокетом прослушивания. Каждый адрес разделяют запятой. Соединения будут приниматься с любого IP-адреса, если оставить значение пустым. Значение по умолчанию: нет, принимается любой IP-адрес.

`listen.owner` string

  Устанавливает разрешения для Unix-сокета, если подключение установили через Unix-сокет. В Linux для разрешения соединений к веб-серверу устанавливают права на чтение и запись. Часто системы на основе BSD разрешают соединения независимо от прав доступа. Значение по умолчанию: пользователь и группа задаются как пользователь, от имени которого запускается сервер, для режима устанавливаются разрешения 0660.

`listen.group` string

  Смотрите `listen.owner`.

`listen.mode` string

  Смотрите `listen.owner`.

`listen.acl_users` string

  Опция настраивает список управления доступом (англ. Access Control List, ACL) по стандарту POSIX, если список поддерживается. Директивы `listen.owner` и `listen.group` проигнорируются, если директиву установили. Значение задаётся списком имён через запятую.

`listen.acl_groups` string

  Смотрите описание директивы `listen.acl_users`. Значение задаётся списком имён групп через запятую.

`listen.setfib` int

  Опция устанавливает таблицу маршрутизации (англ. Forwarding Information Base, FIB) для исходящих соединений, которые инициируются процессами пула FPM. Опция доступна только на ОС FreeBSD. Значение по умолчанию: `-1`. Опция доступна с PHP 8.2.0.

`user` string

  Unix-пользователь FPM-процессов. Параметр обязателен.

`group` string

  Unix-группа FPM-процессов. Группа по умолчанию равна имени пользователя, если директиву не установили.

`pm` string

  Выбор того, как менеджер процессов будет контролировать создание дочерних процессов. Возможные значения: `static`, `ondemand`, `dynamic`. Параметр обязателен.

  `static` — фиксированное число дочерних процессов (`pm.max_children`).

  `ondemand` — число процессов, которые порождаются по требованию (когда появляются запросы, в отличие от опции dynamic, когда стартует конкретное количество процессов, равное `pm.start_servers`, вместе с запуском службы). `dynamic` — количество дочерних процессов, которое изменяется динамически, задаётся на основе следующих директив: `pm.max_children`, `pm.start_servers`, `pm.min_spare_servers`, `pm.max_spare_servers`.
`pm.max_children` int
  Число дочерних процессов, которые создадутся, когда `pm` установили в режим `static`, или максимальное количество процессов, которые создадутся, когда `pm` установили в режим `dynamic` или `ondemand`. Параметр обязателен.

  Параметр устанавливает ограничение на число одновременных запросов, которое обслужит менеджер. Эквивалент директивы ApacheMaxClients с модулем mpm_prefork и переменной окружения PHP_FCGI_CHILDREN в оригинальном FastCGI-интерфейсе PHP.

`pm.start_servers` int

  Количество дочерних процессов, которое менеджер создаёт при запуске. Директива работает, только когда для параметра `pm` установили значение `dynamic`. Значение по умолчанию: (min_spare_servers + max_spare_servers) / 2.

`pm.min_spare_servers` int

  Минимальное число неактивных процессов сервера. Директива работает, только когда для параметра `pm` установили значение `dynamic`. В таких случаях параметр становится обязательным.

`pm.max_spare_servers` int

  Максимальное число неактивных процессов сервера. Директива работает, только когда для параметра `pm` установили значение `dynamic`. В таких случаях параметр становится обязательным.

`pm.max_spawn_rate` int

  Количество одновременных порождений дочерних процессов. Директива работает, только когда для параметра `pm` установили значение `dynamic`. Значение по умолчанию: 32

`pm.process_idle_timeout` mixed

  Количество секунд, по истечении которых процесс, который простаивает, завершится. Директива работает, только когда для параметра `pm` установили значение `ondemand`. Допустимые единицы: s (секунды) (значение по умолчанию), m (минуты), h (часы) или d (дни). Значение по умолчанию: 10s.

`pm.max_requests` int

  Число запросов дочернего процесса, после которого процесс перезапустится. Это полезно для устранения утечек памяти при работе со сторонними библиотеками. Для бесконечной обработки запросов устанавливают значение '0'. Эквивалент PHP_FCGI_MAX_REQUESTS. Значение по умолчанию: 0.

`pm.status_listen` string

  Адрес, по которому менеджер примет запрос состояния FastCGI-интерфейса. Директива создаёт новый невидимый пул, который умеет обрабатывать запросы независимо. Это полезно, когда основной пул занят запросами, которые долго выполняются, поскольку страница состояния FPM по-прежнему доступна для получения до завершения длительных запросов. Синтаксис значений директивы аналогичен синтаксису директивы listen. Значение по умолчанию: none.

`pm.status_path` string

  URI-идентификатор для просмотра страницы состояния FPM-менеджера. Значение начинается со слеша /. URI не распознается как страница состояния, если значение директивы не установили. Значение по умолчанию: none.

`ping.path` string

  Ссылка на ping-страницу FPM-мониторинга. Ping-страница отображаться не будет, если значение не установили. Директивой пользуются для тестирования из внешнего мира, чтобы убедиться, что FPM жив и отвечает. Обратите внимание, что значение начинается со слеша /.

`ping.response` string

  Директивой настраивают ответ на ping-запрос. Ответ формируется как text/plain с кодом ответа 200. Значение по умолчанию: pong.

`process.priority` int

  Устанавливает приоритет nice(2), который применяется к рабочему процессу, только если процесс установили. Директива принимает значения от -19 для высшего приоритета до 20 для самого низкого. Значение по умолчанию: нет.

`process.dumpable` bool

  Устанавливает флаг процесса dumpable (PR_SET_DUMPABLE prctl), даже если пользователь процесса или группа отличается от пользователя мастер-процесса. Это разрешает создавать дамп ядра процесса и выполнять ptrace процесса для пользователя пула. Значение по умолчанию: no. Директива доступна с PHP 7.0.29, 7.1.17 и 7.2.5.

`prefix` string

  Задаёт префикс для вычисления пути

`request_terminate_timeout` mixed

  Время ожидания обслуживания одного запроса, после которого рабочий процесс завершится. Опцию задействуют, когда опция 'max_execution_time' в файле php.ini не останавливает выполнение скрипта по каким-то причинам. Значение '0' означает «выключено». Доступные единицы измерения: s (секунды), m (минуты), h (часы) или d (дни). Значение по умолчанию: 0.

`request_terminate_timeout_track_finished` bool

  Время ожидания, которое установили в директиве request_terminate_timeout, не включается после сброса данных ответа клиенту функцией fastcgi_finish_request или когда приложение завершилось и вызываются внутренние функции завершения работы. Директива разрешает безоговорочно применять ограничение времени ожидания даже в таких случаях. Значение по умолчанию: нет, начиная с версии PHP 7.3.0.

`request_slowlog_timeout` mixed

  Время ожидания для обслуживания одного запроса, после которого обратная трассировка PHP сохранится в файл 'slowlog'. Значение '0' означает «выключено». Доступные единицы измерения: s (секунды), m (минуты), h (часы) или d (дни). Значение по умолчанию: 0.

`request_slowlog_trace_depth` int

  Глубина трассировки стека журнала slowlog. Значение по умолчанию: 20 с PHP 7.2.0.

`slowlog` string

  Файл журнала для медленных запросов. Значение по умолчанию: `#INSTALL_PREFIX#/log/php-fpm.log.slow`.

`rlimit_files` int

  Устанавливает лимит дескрипторов открытых файлов rlimit для дочерних процессов в этом пуле. Значение по умолчанию: определяется значением системы.

`rlimit_core` int

  Устанавливает максимальное количество ядер rlimit для дочерних процессов в этом пуле. Возможные значения: 'unlimited' или целое число, которое больше или равно 0. Значение по умолчанию: определяется значением системы.

`chroot` string

  Директория chroot окружения при старте. Значение определяют как абсолютный путь. Каталог chroot не используется, если значение не установили.

`chdir` string

  Chdir изменяет текущую директорию при старте. Значение определяют как абсолютный путь. Значение по умолчанию: текущая директория или / при работе с chroot.

`catch_workers_output` bool

  Перенаправление стандартных потоков STDOUT и STDERR рабочего процесса в главный лог ошибок. Потоки STDOUT и STDERR перенаправятся в файл /dev/null по правилам спецификаций FastCGI, если директиву не установили. Значение по умолчанию: no.

`decorate_workers_output` bool

  Включает оформление вывода для вывода рабочих процессов при включённой опции catch_workers_output. Значение по умолчанию: yes. Директива доступна с PHP 7.3.0.

`clear_env` bool

  Очищает окружение в рабочих процессах FPM-менеджера. Директива предотвращает попадание произвольных переменных окружения в рабочие процессы FPM-менеджера и очищает окружение в рабочих процессах перед добавлением переменных окружения, которые указали в этой конфигурации. Значение по умолчанию: Yes.

`security.limit_extensions` string

  Ограничивает модули, которые FPM проанализирует. Директива помогает предотвратить ошибки конфигурации на стороне веб-сервера. FPM-менеджер ограничивают только расширениями .php, чтобы злоумышленники не выполнили PHP-код с другими расширениями. Значение по умолчанию: .php .phar

`apparmor_hat` string

  Директива разрешает «менять шляпу» (использовать другой контекст безопасности), если программу защиты AppArmor включили. Значение по умолчанию: нет.

`access.log` string

  Файл журнала доступа. Значение по умолчанию: нет.

`access.format` string

  Формат файла журнала доступа. Значение по умолчанию: `"%R - %u %t \"%m %r\" %s"`:

  Допустимые значения
  Заполнитель | Описание
  --- | ---
  `%%` | Символ `%`
  `%C` | %ЦП, с которым работал запрос. Опция принимает следующие форматы: `%{user}C` — только ЦП пользователя, `%{system}C` — только ЦП системы, `%{total}C` — ЦП пользователя + системы (формат по умолчанию)
  `%d` | Время, которое потребовалось для обслуживания запроса. Опция принимает следующие форматы точности: `%{seconds}d` — секунды (значение по умолчанию), `%{milliseconds}d` — миллисекунды, `%{microseconds}d` — микросекунды
  `%{name}e` | Переменная FastCGI-окружения, по аналогии с переменными $_ENV или $_SERVER). Имя переменной указывают в фигурных скобках, чтобы указать название переменной окружения. Например, характерные для сервера названия переменных наподобие `%{REQUEST_METHOD}e` или `%{SERVER_PROTOCOL}e`, HTTP-заголовки наподобие `%{HTTP_HOST}e` или `%{HTTP_USER_AGENT}e`
  `%f` | Название файла скрипта
  `%l` | Заголовок запроса `Content-Length`; только для POST-запроса по HTTP-протоколу
  `%m` | HTTP-метод запроса
  `%M` | Пик памяти, которую выделил PHP. Параметр принимает следующие форматы: `%{bytes}M` — байты (формат по умолчанию), `%{kilobytes}M` или `%{kilo}M` — килобайты, `%{megabytes}M` или `%{mega}M` — мегабайты
  `%n` | Название пула
  `%{name}o` | Заголовок вывода. Название заголовка указывают внутри фигурных скобок. Например: `%{Content-Type}o`, `%{X-Powered-By}o` , `%{Transfer-Encoding}o`
  `%p` | PID-идентификатор дочернего процесса, в котором обслуживался запрос
  `%P` | PID-идентификатор родителя дочернего процесса, в котором обслуживался запрос
  `%q` | Строка с аргументами запроса
  `%Q` | Символ склеивания `'?'` между строкой с аргументами запроса `%q` и URI-идентификатором запроса `%r`, если URL-адрес содержал строку запроса
  `%r` | URI-идентификатор запроса без аргументов запроса, смотрите описание опций `%q` и `%Q`
  `%R` | Удалённый IP-адрес
  `%s` | Код статуса ответа
  `%t` | Серверное время получения запроса. Аргумент принимает строку формата даты и времени в стиле библиотечной C-функции `strftime(3)`: `%d/%b/%Y:%H:%M:%S %z` — значение по умолчанию. Строку формата в стиле функции `strftime(3)` потребуется инкапсулировать в тег `%{<strftime_format>}t`, например, для форматирования строки времени по стандарту ISO8601: `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | Время записи в журнал, когда запрос завершился. Аргумент принимает строку формата даты и времени в стиле библиотечной C-функции `strftime(3)`: `%d/%b/%Y:%H:%M:%S %z` — значение по умолчанию. Строку формата в стиле функции `strftime(3)` потребуется инкапсулировать в тег `%{<strftime_format>}T`, например, для форматирования строки времени по стандарту ISO8601: `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | Базовая аутентификация пользовательского доступа, если указали в `Authorization` заголовке

`access.suppress_path` array

  Список значений поля request_uri, которые требуется отфильтровать и не включать в журнал доступа. Значение по умолчанию: нет. Опция доступна с PHP 8.2.0.

Передача дополнительных переменных окружения обновляет настройки PHP для конкретного пула. Для этого добавляют следующие параметры в файл настройки пула.

Пример #1 Передача переменных окружения и PHP-настроек пулу

    env[HOSTNAME] = $HOSTNAME
    env[PATH] = /usr/local/bin:/usr/bin:/bin
    env[TMP] = /tmp
    env[TMPDIR] = /tmp
    env[TEMP] = /tmp

    php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
    php_flag[display_errors] = off
    php_admin_value[error_log] = /var/log/fpm-php.www.log
    php_admin_flag[log_errors] = on
    php_admin_value[memory_limit] = 32M

Настройки PHP, которые передали через FPM-директивы `php_value` или `php_flag`, перезапишут своё предыдущее значение. Обратите внимание, что определение disable_functions не перезапишет значения, которые прежде определили в файле php.ini, а добавит новые значения.

Настройки, которые определили через FPM-директивы `php_admin_value` и `php_admin_flag`, невозможно перезаписать функцией ini_set().

Настройки PHP разрешается устанавливать в конфигурации веб-сервера.

Пример #2 Установка PHP-настроек в файле nginx.conf

    set $php_value "pcre.backtrack_limit=424242";
    set $php_value "$php_value \n pcre.recursion_limit=99999";
    fastcgi_param  PHP_VALUE $php_value;

    fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

Предостережение

Поскольку эти настройки передаются в php-fpm как FastCGI-заголовки, php-fpm не привязывают к адресу, который доступен из внешнего мира, иначе кто угодно изменит настройки PHP. Смотрите также описание директивы listen.allowed_clients.

> Замечание: Пулы — не механизм безопасности, поскольку не обеспечивают полного разделения; например пулы будут использовать один экземпляр OPcache.

# Установка PECL-модулей

## Содержание

- Введение в установку модулей из репозитория PECL
- Загрузка модулей PECL
- Установка PHP-модуля в Windows
- Компиляция разделяемых модулей командой pecl
- Компиляция разделяемых модулей командой phpize
- php-config
- Компиляция модулей PECL статически в PHP

## Введение в установку модулей из репозитория PECL

> Замечание: Установщик PHP-модулей (англ. PHP Installer for Extensions, PIE) — новый инструмент, который заменит репозиторий PECL после устаревания. Рекомендуем устанавливать модули через PIE. Дополнительная информация доступна на странице » https://github.com/php/pie.

» PECL — репозиторий PHP-модулей. Модули устанавливают непосредственно из репозитория или через » PEAR — платформу и систему распространения PHP-компонентов. Эта часть руководства рассказывает, как получить и установить PECL-модули.

Эти инструкции подразумевают, что `/path/to/php/src/dir/` — путь к каталогу с дистрибутивом исходного кода PHP, а `extname` — название PECL-модуля. Так что указывайте соответствующие коррективы. Эти инструкции также подразумевают знакомство с » командой pear. Информация в руководстве PEAR для команды pear также применима для команды pecl.

Общедоступный модуль потребуется создать, установить и загрузить, чтобы модуль стал доступен для работы. Следующие разделы описывают методы, которые дают инструкции по сборке и установке модулей, но эти способы не загружают модули автоматически. Модули загружают через директиву extension в файле php.ini или функцией dl().

При сборке PHP-модулей потребуется установить стабильные версии утилит autoconf, automake, libtool и других инструментов сборки и компиляции. Подробная информация об инструментах и совместимых версиях доступна на странице » Инструкции по анонимному доступу к Git.

## Загрузка модулей PECL

> Замечание: Установщик PHP-модулей (англ. PHP Installer for Extensions, PIE) — новый инструмент, который заменит репозиторий PECL после устаревания. Рекомендуем устанавливать модули через PIE. Дополнительная информация доступна на странице » https://github.com/php/pie.

PECL-модули загружают следующими способами:

- Команда pecl install extname автоматически скачивает исходный код модуля, компилирует и устанавливает файл модуля в каталог с расширениями, поэтому отдельно скачивать и компилировать файлы не потребуется.
- Сайт » https://pecl.php.net/. Сайт PECL содержит информацию о модулях, которые предлагает команда разработчиков языка PHP. Доступная на сайте информация включает: лог изменений, заметки о выпусках, требования и другие похожие сведения.
- pecl download extname Модули PECL, выпуски которых перечисляются на сайте PECL, доступны для скачивания и установки » командой pecl. При скачивании возможно указать конкретную версию модуля.
- git Часть PECL-модулей доступна на сайте GitHub.
- SVN Часть PECL-модулей также доступна в SVN. Веб-интерфейс для просмотра доступен по адресу » https://svn.php.net/pecl/. Для загрузки прямо из SVN выполняют следующую последовательность команд:

      $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

- Загрузка для Windows Проект PHP компилирует и предлагает DLL-файлы для ОС Windows для большей части PECL-модулей на странице с пакетами.

## Установка PHP-модуля в Windows

В ОС Windows PHP-модули подключают двумя способами: либо компилируют PHP с модулем, либо загружают модуль как DLL-файл. Загрузка заранее скомпилированного модуля — самый простой и предпочтительный способ.

Модуль загрузится, только если доступен в системе как файл с расширением .dll. Группа разработчиков PHP автоматически и периодически компилирует PHP-модули. Подробнее о скачивании рассказывает следующий раздел.

О компиляции модуля вместе с PHP рассказывает раздел документации «Сборка из исходного кода».

Для компиляции отдельного модуля в виде DLL-файла, обратитесь к разделу «Сборка из исходного кода». Возможно, перед подключением модуль потребуется скомпилировать, если DLL-файла не оказалось ни в стандартной поставке PHP, ни в репозитории PECL.

### Где найти модуль?

PHP-модулям часто присваивают названия вида php_*.dll, где звёздочка — название модуля, и размещают модули в папке PHP\ext.

PHP поставляется с наиболее полезными для большей части разработчиков модулями. Такие модули называются встроенными.

На сайте » PECL доступны модули, которые решают близкое к 100 % количество задач, поэтому хотя бы один необходимый модуль найдётся в репозитории, если встроенные модули не содержат функций, которые потребовались программисту. Библиотека модулей PHP-сообщества (англ. The PHP Extension Community Library, PECL) — каталогизированный репозиторий PHP-модулей и инфраструктура для хранения, скачивания и разработки модулей.

Одни пользователи размещают в репозитории PECL модули, которые разработали для конкретных целей, а другие пользователи, которым потребовались аналогичные функции, скачивают модули. Разработчики модулей получают шанс на обратную связь, благодарности (надеемся, что так и будет), сообщения об ошибках и даже исправление ошибок или другие полезные изменения. Примечание » на странице отправки нового PECL-модуля даёт инструкции, которые потребуется выполнить перед отправкой модуля в репозиторий PECL.

### Какой модуль скачать?

DLL-модуль выбирают по следующим признакам:

- Номер версий, в котором совпадают хотя бы две первые цифры
- Настройки потокобезопасности
- Архитектура процессора: x86, x64 или другая
- Настройки отладки
- `И другие характеристики`

PHP загрузит модуль, только если характеристики модуля соответствуют параметрам исполняемого PHP-файла. Следующий PHP-скрипт выведет все настройки PHP:

Пример #1 Вызов функции phpinfo()

    <?php

    phpinfo();

    ?>

Или запустите из командной строки:

    drive:\path\to\php\executable\php.exe -i

### Загрузка модуля

Самый распространённый способ загрузить PHP-модуль — включить модуль в конфигурационном файле php.ini. Обратите внимание, файл php.ini уже содержит записи для части модулей, и для активации достаточно удалить точку с запятой.

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

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; Начиная с PHP 7.2 лучше делать так:
    extension=extname
    zend_extension=another_extension

Однако некоторые веб-серверы создают путаницу, поскольку не используют файл php.ini, который содержится в дистрибутиве PHP. Путь расположения файла php.ini указывается в выводе функции phpinfo():

    Configuration File (php.ini) Path  C:\WINDOWS

    Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

После активации модуля сохраняют файл php.ini, перезагружают веб-сервер и повторно проверяют вывод функции phpinfo(). Для нового модуля появится отдельный раздел.

### Решение проблем

Лог-файлы помогают узнать причину ошибки, когда модуль не появляется в выводе функции phpinfo().

При работе с PHP из командной строки, в режиме CLI, сообщение об ошибке загрузки модуля появится на экране.

При работе PHP с веб-сервером расположение и формат логов определяет ПО сервера. Для поиска путей к журналам знакомятся с документацией к веб-серверу, поскольку сам PHP не устанавливает место хранения серверных логов.

Часто проблемы возникают из-за неправильного расположения DLL-модуля и DLL-файлов, от которых зависит модуль, неправильного значения директивы "extension_dir" в файле php.ini и из-за несовпадения настроек компиляции.

Вероятная причина проблемы, которая возникает из-за несовпадения настроек компиляции, состоит в скачивании неправильного DLL-файла. Попробуйте скачать модуль снова с правильными настройками. И снова в таких ситуациях помогает информация, которую выводит функция phpinfo().

## Компиляция разделяемых модулей командой pecl

PECL упрощает создание общедоступных модулей PHP. Выполните следующую » команду pecl:

    $ pecl install extname

Команда скачает исходный код модуля extname, скомпилирует и установит файл extname.so в директорию extension_dir. После установки файл extname.so получится загрузить через файл php.ini

Команда `pecl` по умолчанию не устанавливает пакеты с отметкой `alpha`- или `beta`-версии. `beta`-версию пакета устанавливают следующей командой, если `stable`-версии пакетов недоступны:

    $ pecl install extname-beta

Следующая команда установит конкретную версию:

    $ pecl install extname-0.1

> Замечание:

> После подключения модуля в файле php.ini потребуется перезапустить веб-сервер, чтобы изменения вступили в силу.

## Компиляция разделяемых модулей командой phpize

Иногда компиляция модулей через установщик `pecl` невозможна. Это связано с брандмауэром или с недоступностью устанавливаемого модуля в качестве PECL-совместимого пакета наподобие модулей из системы управления версиями git, которые ещё не выпустили. Такой модуль собирают вручную через низкоуровневые утилиты сборки.

Команду phpize выполняют для подготовки окружения сборки PHP-модуля. В следующем примере исходные коды модуля лежат в директории с названием extname:

    $ cd extname
    $ phpize
    $ ./configure
    $ make
    # make install

Успешная установка создаст в директории PHP-модулей файл extname.so. Модуль станет доступен для работы после корректировки файла php.ini, в который потребуется добавить строку `extension=extname.so`.

Потребуется установить версию PHP для разработки, которая соответствует текущей установке PHP, если в системе недоступна команда phpize, но доступна работа с предварительно скомпилированными пакетами наподобие RPM. Версия для разработки часто включает команду phpize с правильными файлами заголовков для сборки интерпретатора PHP и PHP-модулей.

Дополнительную информацию о работе утилиты выводит команда phpize --help.

## php-config

php-config — простой скрипт командной строки для получения информации о конфигурации PHP-дистрибутива, который установили в систему.

При компиляции модулей в системах, в которых установили больше одного дистрибутива PHP, возможно указать версию PHP, для которой выполняется сборка модуля. Для этого при настройке сборки в параметре --with-php-config указывают путь к скрипту php-config, версия которого соответствует PHP-установке.

Список доступных для скрипта php-config параметров командной строки доступен при запуске команды php-config с параметром -h:

    Usage: /usr/local/bin/php-config [OPTION]
    Options:
      --prefix            [...]
      --includes          [...]
      --ldflags           [...]
      --libs              [...]
      --extension-dir     [...]
      --include-dir       [...]
      --php-binary        [...]
      --php-sapis         [...]
      --configure-options [...]
      --version           [...]
      --vernum            [...]

Опции скрипта
Опция | Описание
--- | ---
--prefix | Директория, в которую установили PHP, например /usr/local
--includes | Список `-I` параметров со всеми подключаемыми файлами
--ldflags | `LD`, с которыми скомпилировали PHP
--libs | Внешние библиотеки, с которыми скомпилировали PHP
--extension-dir | Директория, в которой PHP по умолчанию ищет модули
--include-dir | Префикс директории, в которую по умолчанию устанавливаются заголовочные файлы
--php-binary | Полный путь до исполняемых файлов php для режимов CLI или CGI
--php-sapis | Показывает все доступные модули SAPI
--configure-options | Конфигурационные опции для воссоздания настроек текущей установки PHP.
--version | Версия PHP
--vernum | Версия PHP в виде целого числа

## Компиляция модулей PECL статически в PHP

Возможно, потребуется собрать модуль PECL статично в бинарный файл PHP. Для этого исходный код модуля размещают в каталоге /path/to/php/src/dir/ext/ и вызывают перегенерацию конфигурационных скриптов через систему сборки PHP.

    $ cd /path/to/php/src/dir/ext
    $ pecl download extname
    $ gzip -d < extname.tgz | tar -xvf -
    $ mv extname-x.x.x extname

Это создаст следующую директорию:

    /path/to/php/src/dir/ext/extname

Затем PHP потребуется принудительно пересобрать скрипт конфигурации, после чего скрипт конфигурации собирается как обычно:

    $ cd /path/to/php/src/dir
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> Замечание: Для запуска скрипта buildconf потребуется команда autoconf версии `2.68` и команда automake версии `1.4+`. Иногда работают и более новые версии скрипта autoconf, но не поддерживаются.

При сборке встроенного модуля указывают команду --enable-extname, а для модулей с внешними зависимостями — --with-extname. При сборке модуля, который не требует внешних библиотек, указывают параметр --enable. Для проверки синтаксиса параметра конкретного расширения выполните после запуска скрипта buildconf следующую команду:

    $ ./configure --help | grep extname

# Установка пакетного менеджера Composer и сторонних пакетов

## Знакомство с пакетным менеджером Composer

» Composer — пакетный менеджер, который управляет зависимостями одних программных компонентов PHP-приложения от других. Composer помогает определять, а затем устанавливать и обновлять сторонние пакеты кода для проекта. Менеджер поддерживает встроенный механизм автозагрузки PHP-классов, управляет репозиториями наподобие » Packagist, в которых хранятся PHP-пакеты, придерживается единообразной структуры проекта и соглашения о кодировании.

Примером работы с пакетным менеджером Composer могло бы быть PHP-приложение или сайт, которому потребовались уникальные идентификаторы UUID, тогда разработчик мог бы определить и установить через менеджер зависимостей пакет Бена Рэмси (Ben Ramsey) — » `ramsey/uuid`, который генерирует разнотипные UUID-идентификаторы по стандарту » RFC 4122 и умеет работать с такими идентификаторами.

Вкратце, для установки пакета в проекте создают файл `composer.json`, затем через пакетный менеджер Composer устанавливают последнюю версию пакета и включают в проект скрипт автозагрузки классов, который входит в Composer, чтобы сделать пакет доступным для кода. Подробнее о работе с менеджером зависимостей Composer рассказывает документация на сайте менеджера в главе » Basic Usage.

Пример #1 Пример файла `composer.json`, который запрашивает один пакет

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# Установка пакетного менеджера PIE и сторонних модулей

## Введение в PIE

» PIE — пакетный менеджер для установки и обновления сторонних PHP-модулей. Работа установщика базируется на части репозитория PHP-расширений » Packagist для поиска исходного кода и сборки модуля или загрузки двоичного файла модуля для ОС Windows, если доступен. При загрузке исходного кода менеджер автоматически соберёт и установит модуль.

После » установки обязательных библиотек и самого менеджера PIE появится доступ к установке других пакетов. Следующая команда установит модуль MongoDB:

Пример #1 Установка модуля MongoDB через PIE

    pie install mongodb/mongodb-extension

Подробнее о работе с установщиком рассказывает страница документации » Работа с PIE.

# Конфигурация времени выполнения

## Содержание

- Файл конфигурации
- Файлы .user.ini
- Места установки параметров конфигурации
- Как изменить настройки конфигурации

## Файл конфигурации

Файл конфигурации (php.ini) считывается при запуске PHP. Для версий серверных модулей PHP это происходит только один раз при запуске веб-сервера. Для CGI- и CLI-версии PHP — при каждом вызове.

PHP ищёт файл php.ini в следующих местах (по порядку поиска):

- По расположению конкретного SAPI-модуля (директива `PHPIniDir` в веб-сервере Apache 2, параметр командной строки `-c` в CGI- и CLI-интерфейсе)
- Переменная окружения PHPRC.
- Расположение файла `php.ini` зависит от версии PHP. Корень ключей реестра ОС зависит от разрядности ОС и PHP. При установке 32-разрядного PHP на 32-разрядной ОС Windows или 64-разрядного PHP на 64-разрядной Windows PHP исследует раздел реестра `[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]`, при установке 32-разрядного PHP на 64-разрядной Windows — раздел `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`. PHP проверяет следующие разделы реестра по порядку для установок с одинаковой разрядностью: `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` и `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`, где x, y и z подразумевают мажорную, минорную и точечную версии выпусков PHP. Для 32-разрядного PHP на 64-разрядной ОС Windows ключи реестра будут другими: `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` и `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`. PHP будет использовать первый найденный ключ как расположение файла `php.ini`, если ключи содержат значение `IniFilePath` (только для ОС Windows).
- Разделы `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` или `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`, значение `IniFilePath` (только для Windows).
- Текущая рабочая директория (исключая CLI-интерфейс).
- Директория веб-сервера (для SAPI-модулей) или директория PHP (иначе в Windows).
- Директория ОС Windows (C:\windows или C:\winnt) (для Windows) или опция времени компиляции `--with-config-file-path`.

Вместо файла php.ini PHP будет работать с файлом php-SAPI.ini, где SAPI — текущий интерфейс, например php-cli.ini или php-apache.ini, если файл SAPI-интерфейса существует. Название SAPI-интерфейса между веб-сервером и PHP узнают через функцию php_sapi_name().

> Замечание:

> Веб-сервер Apache изменяет текущую директорию на корневую при запуске, в результате чего PHP считывает файл php.ini из корневой файловой системы, если файл существует.

В значениях конфигурации в файле php.ini разрешается ссылаться на значения переменных окружения, как показывает следующий пример. Начиная PHP 8.3.0 доступно определение резервных значений, которые директивы принимают, если сослались на неопределённую переменную.

Пример #1 Переменные окружения в файле php.ini

    ; Переменную PHP_MEMORY_LIMIT получили из окружения
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; Резервное значение директивы будет равняться 30, если переменную окружения PHP_MAX_EXECUTION_TIME не определили
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

Директивы файла php.ini, которые обрабатываются модулями, описывают страницы модулей. Список директив ядра приводит приложение «Директивы php.ini». Не каждая PHP-директива задокументирована в руководстве: полный список доступных в установленной версии PHP директив изложили в подробных комментариях файла php.ini. » Последнюю версию php.ini содержит Git-репозиторий.

Пример #2 Пример php.ini

    ; любой текст в строке после точки с запятой (;) без кавычек игнорируется
    [php] ; маркеры разделов (текст в квадратных скобках) также игнорируется
    ; Могут быть установлены следующие логические значения:
    ;    true, on, yes
    ; или false, off, no, none
    register_globals = off
    track_errors = yes

    ; вы можете заключать строки в двойные кавычки
    include_path = ".:/usr/local/lib/php"

    ; обратный слеш обрабатывается так же, как любые другие символы
    include_path = ".;c:\php\lib"

Возможно обращаться к существующим ini-переменным из ini-файлов. Пример: `open_basedir = ${open_basedir} ":/new/dir"`.

### Сканирование директорий

Существует возможность сконфигурировать PHP для сканирования директорий в поисках .ini-файлов после считывания php.ini. Это можно сделать на моменте компиляции, указав опцию --with-config-file-scan-dir. Сканирование директорий может быть переопределено во время исполнения установкой переменной среды PHP_INI_SCAN_DIR.

Можно сканировать несколько директорий, разделяя их разделителем, используемом в вашей операционной системе (`;` в Windows, NetWare и RISC OS; `:` на всех остальных платформах; в PHP есть константа `PATH_SEPARATOR`, которую можно использовать) Если PHP_INI_SCAN_DIR пуста, то PHP также будет сканировать директорию, заданную на этапе компиляции с помощью --with-config-file-scan-dir.

В каждой директории PHP сканирует все файлы заканчивающиеся на `.ini` в алфавитном порядке. Список всех загруженных файлов в том порядке, в котором они были загружены, доступен с помощью функции php_ini_scanned_files(), либо при запуске PHP с опцией --ini.

    Допустим, что PHP сконфигурирован с --with-config-file-scan-dir=/etc/php.d,
    и разделитель путей :...

    $ php
      PHP загрузит все файлы /etc/php.d/*.ini как конфигурационные.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP загрузит все файлы /usr/local/etc/php.d/*.ini как конфигурационные.

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP загрузит все файлы /etc/php.d/*.ini, а потом
      /usr/local/etc/php.d/*.ini как конфигурационные.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP загрузит все файлы /usr/local/etc/php.d/*.ini, а потом
      /etc/php.d/*.ini как конфигурационные.

## Файлы .user.ini

Включена поддержка INI-файлов в стиле .htaccess на уровне каталога. Эти файлы обрабатываются только CGI/FastCGI SAPI. Эта функция делает ненужным модуль PECL htscanner. Если PHP работает как модуль Apache, то для достижения того же эффекта, работают с файлами .htaccess.

В дополнение к основному файлу php.ini PHP ищет INI-файлы в каждой директории, начиная с директории запрошенного PHP-файла и продолжает поиск до корневой директории (установленной в элементе $_SERVER['DOCUMENT_ROOT']). Если PHP-файл лежит вне корневой директории, то сканируется только его директория.

Только INI-настройки с режимами `INI_PERDIR` и `INI_USER` распознаются в INI-файлах в стиле .user.ini.

Две новых INI-директивы — user_ini.filename и user_ini.cache_ttl — контролируют работу с пользовательскими INI-файлами.

Директива user_ini.filename устанавливает имя файла, по которому PHP производит поиск в каждой директории; если установили пустую строку, PHP не производит поиск. Значение по умолчанию — `.user.ini`.

Директива user_ini.cache_ttl устанавливает, насколько часто пользовательские INI-файлы будут обновляться. По умолчанию период обновления составляет 300 секунд (5 минут).

## Места установки параметров конфигурации

Режимы определяют, когда и где разрешается или не разрешается устанавливать PHP-директиву, и у каждой директивы руководства свой режим. Например, одни настройки разрешается устанавливать в PHP-скрипте функцией ini_set(), тогда как другим нужен файл php.ini или httpd.conf.

Приведём пример. Директива output_buffering соответствует режиму `INI_PERDIR`, поэтому её нельзя устанавливать функцией ini_set(), а директива display_errors соответствует режиму `INI_ALL`, поэтому настройку разрешается устанавливать где угодно, включая функцию ini_set().

Константы INI-режима
`INI_USER` (int)
  Запись разрешается устанавливать в пользовательских скриптах (например, функцией ini_set()) или в реестре Windows. Запись разрешается устанавливать в файле .user.ini.
`INI_PERDIR` (int)
  Запись разрешается устанавливать в файлах php.ini, .htaccess, httpd.conf или .user.ini.
`INI_SYSTEM` (int)
  Запись разрешается устанавливать в файле php.ini или httpd.conf.
`INI_ALL` (int)
  Запись разрешается устанавливать где угодно.

## Как изменить настройки конфигурации

### Запуск PHP в качестве модуля Apache

Когда PHP работает как модуль Apache, настройки конфигурации изменяют через директивы в файлах конфигурации Apache (например, httpd.conf) и файлах .htaccess. Для этого потребуются привилегии «AllowOverride Options» или «AllowOverride All».

В Apache предусмотрели директивы, которые разрешают изменить конфигурацию PHP в файлах конфигурации Apache. Список директив `INI_ALL`, `INI_PERDIR` и `INI_SYSTEM` смотрите в приложении «Список директив php.ini».

`php_value` `name` `value`

  Устанавливает значение директивы. Разрешено указывать только с директивами типа `INI_ALL` и `INI_PERDIR`. Чтобы очистить ранее установленное значение, в качестве значения указывают `none`.

  > Замечание: Не используйте директиву `php_value` для установки логических значений. Эту функцию выполняет директива `php_flag`; её описание ниже.

`php_flag` `name` `on|off`

  Устанавливает директивам логические значения. Разрешено указывать только с директивами типа `INI_ALL` и `INI_PERDIR`.

`php_admin_value` `name` `value`

  Устанавливает значение директивы. Нельзя указывать в файлах .htaccess. Директивы любого типа, установленные через директиву `php_admin_value`, нельзя переопределять через файлы .htaccess или функцию ini_set(). Чтобы очистить ранее установленное значение, указывают значение `none`.

`php_admin_flag` `name` `on|off`

  Устанавливает директивам логические значения. Нельзя указывать в файлах .htaccess. Директивы любого типа, установленные через директиву `php_admin_flag`, нельзя переопределять через файлы .htaccess или функцию ini_set().

Пример #1 Пример конфигурации Apache

    <IfModule mod_php5.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>
    <IfModule mod_php4.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>

Предостережение

PHP-константы недоступны вне PHP. Например, в httpd.conf вы не можете использовать константы PHP такие как `E_ALL` или `E_NOTICE`, чтобы установить директиву error_reporting, так как они не будут иметь значения и будут приравниваться к 0. Используйте вместо этого соответствующие значения типа bitmask (битовая маска). Эти константы могут быть использованы в php.ini

### Изменение конфигурации PHP через реестр Windows

При использовании PHP в Windows значения конфигурации могут быть изменены на уровне директории посредством реестра Windows. Значения конфигурации хранятся в ключе реестра `HKLM\SOFTWARE\PHP\Per Directory Values`, в подключах, включающих полный путь. Например, значения конфигурации для директории `c:\inetpub\wwwroot` могут храниться в ключе `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot`. Настройки для директории будут действительны для любых скриптов, запущенных из этой директории или её поддиректории. Значения ключа должны иметь название конфигурационной директивы PHP и строковое значение. PHP-константы в значениях игнорируются. Однако только значения конфигурации, изменяемые в `INI_USER` могут быть установлены таким образом, значения же `INI_PERDIR` не могут, потому что эти значения конфигурации перечитываются для каждого запроса.

### Другие интерфейсы в PHP

Независимо от того, как вы запускаете PHP, вы можете изменять некоторые значения во время выполнения ваших скриптов c помощью ini_set(). Для более детальной информации смотрите документацию на странице функции ini_set().

Если вам интересен полный список конфигурационных настроек вашей системы с текущими значениями, то вы можете запустить функцию phpinfo() и просмотреть результирующую страницу. Вы также можете получить доступ к значениям индивидуально сконфигурированных директив в процессе выполнения, используя ini_get() или get_cfg_var().

- Общие инструкции по установке
- Установка в Unix-системы
  - Установка из пакетов в ОС Debian GNU/Linux и родственных дистрибутивах
  - Установка из пакетов в дистрибутивы GNU/Linux с менеджером пакетов DNF
  - Установка из пакетов или портов в ОС OpenBSD
  - Установка из исходного кода в системы Unix и macOS
  - Установка с интерфейсами CGI и командной строки
  - Apache 2.x на Unix системах
  - Установка Nginx 1.4.x на систему Unix
  - Установка PHP на Lighttpd 1.4 на Unix-системах
  - Веб-серверы LiteSpeed и OpenLiteSpeed в системах Unix
  - Инструкции по инсталляции для ОС Solaris
- Установка на macOS
  - Установка в ОС macOS через сторонние пакеты
  - Компилирование PHP на macOS
  - Работа со встроенным PHP в ОС macOS до версии Monterey
- Установка в системы с ОС Windows
  - Рекомендуемая конфигурация в системах Windows
  - Ручная установка готовых двоичных файлов
  - Установка для веб-сервера Apache 2.x в системах Windows
  - Установка PHP с веб-сервером IIS для ОС Windows
  - Сторонние инструменты для установки PHP
  - Сборка из исходного кода
  - Запуск PHP в командной строке системы Windows
- Установка на платформах Cloud Computing
  - Azure App Services
  - Amazon EC2
  - DigitalOcean
- Менеджер процессов FastCGI (FPM)
  - Установка
  - Настройка
- Установка PECL-модулей
  - Введение в установку модулей из репозитория PECL
  - Загрузка модулей PECL
  - Установка PHP-модуля в Windows
  - Компиляция разделяемых модулей командой pecl
  - Компиляция разделяемых модулей командой phpize
  - php-config
  - Компиляция модулей PECL статически в PHP
- Знакомство с пакетным менеджером Composer
- Введение в PIE
- Конфигурация времени выполнения
  - Файл конфигурации
  - Файлы .user.ini
  - Места установки параметров конфигурации
  - Как изменить настройки конфигурации

# Справочник языка

# Основы синтаксиса

## Содержание

- PHP-теги
- Выход из режима HTML-разметки
- Разделение инструкций
- Комментарии

## PHP-теги

При разборе файла PHP-интерпретатор распознаёт открывающие и закрывающие теги `<?php` и `?>`, чтобы определить границы выполнения PHP-кода. PHP-парсер игнорирует содержимое за пределами этих тегов, что разрешает бесшовно встраивать PHP-код в документы одного или другого типа.

За тегом `<?php` обязательно указывают пробельный символ наподобие пробела, символа табуляции или новой строки, чтобы правильно разделить токены. Без пробельного символа возникнет синтаксическая ошибка.

PHP также включает короткий echo-тег `<?=` — сокращение более многословного синтаксиса `<?php echo`.

Пример #1 Открывающие и закрывающие теги PHP

    1.  <?php echo 'Для PHP-кода в XHTML- или XML-документах
                    указывают эти теги'; ?>

    2. Короткий echo-тег указывают, когда требуется <?= 'вывести эту строку' ?>.
        Короткий синтаксис эквивалентен синтаксису
        <?php echo 'вывести эту строку' ?>.

    3.  <? echo 'этот код разместили внутри коротких тегов, но он будет работать, только если '.
                    'включили опцию short_open_tag'; ?>

Короткие теги третьего примера доступны по умолчанию, но отключаются либо через директиву short_open_tag в файле PHP-конфигурации php.ini, либо при сборке PHP с опцией --disable-short-tags.

> Замечание:

> Лучше указывать только стандартные теги `<?php ?>` и `<?= ?>`, поскольку при отключении коротких тегов код станет несовместимым.

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

Пример #2 Файл только с PHP-кодом

    <?php

    echo "Привет, мир!\n";

    // …ещё код

    echo "Последняя инструкция\n";
    // Скрипт заканчивается в этом месте без PHP-тега, которым закрывается блок кода

## Выход из режима HTML-разметки

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

Пример #1 PHP-код, который встроили в HTML-разметку

    <p>PHP-интерпретатор проигнорирует разбор PHP-кода в этом параграфе, а текст отобразится в браузере.</p>
    <?php echo 'А эту строку файла — разберёт.'; ?>
    <p>Этот параграф PHP тоже не станет анализировать как PHP-код и отправит в браузер.</p>

Это работает предсказуемо, поскольку когда PHP-интерпретатор встречает закрывающие теги ?>, он просто начинает выводить всё, что находит, — за исключением перевода строки, который идёт сразу за закрывающим тегом, как описывает раздел «Разделение инструкций», — пока не встретит другой открывающий тег, если только закрывающий тег не встретился в середине условной инструкции, тогда интерпретатор определяет результат условия, прежде чем решить, что пропустить. Следующий пример показывает это поведение.

Структуры с условиями.

Пример #2 Продвинутый выход из режима HTML-разметки с условиями

    <?php if ($expression == true): ?>
      Это отобразится, если выражение истинно.
    <?php else: ?>
      Иначе отобразится это.
    <?php endif; ?>

В этом примере PHP пропустит блок, для которого условие не выполняется, даже если блок указали за пределами открывающего и закрывающего тегов; PHP пропустит блоки по условию, поскольку PHP-интерпретатор пропустит блоки внутри условия, которое не выполняется.

Для вывода больших блоков текста выход из режима разбора PHP-кода часто эффективнее отправки текста конструкциями echo или print.

> Замечание:

> В XML- или XHTML-документы PHP-код встраивают внутри тегов `<?php ?>`, чтобы документы соответствовали стандартам.

## Разделение инструкций

Как и в языках программирования C или Perl, в языке PHP обязательно заканчивать инструкции символом точки с запятой, который указывают в конце каждой инструкции. Закрывающий тег блока PHP-кода автоматически применяет точку с запятой, поэтому не обязательно ставить точку с запятой в конце последней строки блока с PHP-кодом. PHP не включает в вывод перевод строки, который идёт сразу за закрывающим тегом.

Пример #1 Пример вывода текста между закрывающим тегом и переводом строки

    <?php echo "Какой-то текст"; ?>
    Нет новой строки
    <?= "А сейчас, новая строка" ?>

Результат выполнения приведённого примера:

    Какой-то текстНет новой строки
    А сейчас, новая строка

Пример #2 Примеры входа в режим PHP-парсера и выхода из него

    <?php

    echo "Это тест\n";

    ?>

    <?php echo "Это тест\n" ?>

    <?php echo "Не закрываем блок кода в конце файла PHP-тегом\n";

> Замечание:

> Тег, которым закрывается блок PHP-кода в конце файла, необязателен, а при подключении файлов выражением include или require пропуск тега иногда приносит пользу, чтобы нежелательные пробелы не появлялись в конце файлов и не мешали позже добавлять к ответу сервера дополнительные HTTP-заголовки. При буферизации вывода пропуск тега также помогает исключить нежелательные пробелы в конце частей, которые сгенерировали подключаемые файлы.

## Комментарии

PHP поддерживает комментарии в стиле языков программирования C, C++ и в стиле командной оболочки Unix-систем, которая унаследовала стиль комментариев из языка Perl. Например:

Пример #1 Пример комментариев

    <?php

    echo "Это тест"; // Это однострочный комментарий в стиле языка C++
    /* Это многострочный комментарий
       ещё одна строка комментария */
    echo "Это ещё один тест\n";
    echo "Ещё один последний тест\n"; # Это комментарий в стиле Unix-оболочки

    ?>

Однострочные комментарии распространяются только до конца строки PHP-кода или на текущий блок PHP-кода в HTML-строке, в зависимости от того, что идёт первым. Поэтому HTML-код после начала однострочного комментария `// ... ?>` или `# ... ?>` выводится: тег ?> прерывает режим разбора PHP-кода и возвращает режим HTML-разметки, и символы `//` или `#` не влияют на это.

Пример #2 Пример однострочных комментариев

    <h1>Это <?php # echo "простой";?> пример</h1>
    <p>Заголовок вверху выведет 'Это  пример'.</p>

Комментарии в стиле языка C заканчиваются, когда обнаруживается первая последовательность `*/`. Программисты следят за тем, чтобы комментарии в стиле языка C не оказались вложенными. Ошибку с вложенными C-комментариями часто допускают, когда комментируют большой блок кода.

    <?php

    /*
        echo "Это тест"; /* Этот комментарий вызовет ошибку */
    */

    ?>

# Типы

## Содержание

- Введение
- Система типов
- NULL
- Логические значения
- Целые числа
- Числа с плавающей точкой
- Строки
- Числовые строки
- Массивы
- Объекты
- Перечисления
- Ресурсы
- Вызываемые выражения
- Mixed
- Void
- Never
- Относительные типы классов
- Одноэлементные типы
- Итерируемые значения
- Объявления типов
- Жонглирование типами

## Введение

Каждое выражение в PHP в зависимости от значения принадлежит конкретному типу из следующего списка:

- null
- bool
- int
- float (floating-point number)
- string
- array
- object
- callable
- resource

PHP – динамически типизированный язык, поэтому по умолчанию указывать тип переменной не потребуется; PHP определит тип переменной во время выполнения. Однако PHP разрешает статически типизировать отдельные составляющие языка путём объявлений типов. Типы, которые поддерживает PHP, описывает раздел «Система типов».

Типы ограничивают виды операций, доступных для выполнения со значениями конкретного типа. PHP попытается преобразовать значение в тип, который поддерживает операцию, если значение выражения или переменной участвует в операции, которую тип значения не поддерживает. Этот процесс зависит от контекста, в котором обрабатывается значение. Дополнительную информацию о преобразовании типов даёт раздел «Жонглирование типами».

Подсказка

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

> Замечание: Принудительно преобразовать результат вычисления выражения в значение конкретного типа возможно через приведение типов. Переменную тоже возможно привести на месте к конкретному типу функцией settype().

Значение и тип выражения проверяют функцией var_dump(). Тип выражения получают функцией get_debug_type(). Принадлежность выражения конкретному типу проверяют функциями семейства `is_type`.

Пример #1 Типы

    <?php

    $a_bool = true;   // логическое значение
    $a_str  = "foo";  // строка
    $a_str2 = 'foo';  // строка
    $an_int = 12;     // целое число

    echo get_debug_type($a_bool), "\n";
    echo get_debug_type($a_str), "\n";

    // Проверить, содержит ли переменная целое число, и увеличить значение на четыре
    if (is_int($an_int)) {
        $an_int += 4;
    }
    var_dump($an_int);

    // Проверить, содержит ли переменная $a_bool строку, и вывести строковое значение
    if (is_string($a_bool)) {
        echo "Строка: $a_bool";
    }

    ?>

Результат выполнения приведённого примера в PHP 8:

    bool
    string
    int(16)

> Замечание: До версии PHP 8.0.0, в которой функция get_debug_type() была недоступна, вызывали функцию gettype(), но она не возвращает канонические названия типов.

## Система типов

Язык PHP использует систему номинальных типов с сильным отношением поведенческого подтипирования. PHP проверяет отношение подтипов во время компиляции, тогда как контроль типов язык выполняет динамически во время выполнения.

Система типов данных в PHP поддерживает атомарные типы, которые разрешено объединять, чтобы создавать сложные типы. Часть этих типов допустимо записывать в объявлениях типов.

### Атомарные типы

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

Список базовых типов:

- Встроенные типы
  - Скалярные типы:
    - bool
    - int
    - float
    - string
  - array
  - object
  - resource
  - never
  - void
  - «Относительные типы классов»: self, parent и static
  - Одноэлементные типы
    - false
    - true
  - Объединение типов
    - null
- Определяемые пользователем типы (часто называемые класс-типами)
  - Интерфейсы
  - Классы
  - Перечисления
- callable

#### Скалярные типы

PHP считает значение скалярным, если значение принадлежит типу int, float, string или bool.

#### Пользовательские типы

Язык разрешает определять пользовательские типы данных через интерфейсы, классы и перечисления. PHP рассматривает пользовательские типы как типы классов. Приведём пример. Язык разрешает определить класс с названием `Elephant`, затем создать объект с типом `Elephant`, а потом определить функцию с параметром, который ждёт аргумент с типом `Elephant`.

### Составные типы

Возможно объединение нескольких атомарных типов в составные типы. PHP разрешает объединять типы следующими способами:

- Пересечение класс-типов (интерфейсов и названий классов).
- Объединение типов.

#### Пересечение типов

Пересечение типов принимает значения, которые удовлетворяют не одному, а одновременно нескольким объявлениям класс-типов. Отдельные пересекающиеся типы соединяются символом `&`. Поэтому пересечение типов `T`, `U` и `V` записывает как `T&U&V`.

#### Объединение типов

Объединение типов принимает значения нескольких отличающихся типов, а не одного. Отдельные объединяемые типы соединяются символом `|`. Поэтому объединение типов `T`, `U` и `V`, будет записано как `T|U|V`. Если при объединении типов добавляют пересечение типов, то пересечение типов берут в скобки для записи в дизъюнктивной нормальной форме (DNF): `T|(X&Y)`.

### Псевдонимы типов

PHP поддерживает два псевдонима типов: mixed, который соответствует объединению типов `object|resource|array|string|float|int|bool|null`, и iterable, который соответствует объединению `Traversable|array`.

> Замечание: PHP не поддерживает пользовательские псевдонимы типов.

## NULL

Тип null — единичный PHP-тип с единственным значением: `null`.

Неопределённые и удалённые языковой конструкцией unset() переменные преобразуются в значение `null`.

### Синтаксис

Типу null принадлежит только одно значение — регистронезависимая константа `null`.

    <?php

    $var = NULL;

    ?>

### Приведение к `null`

Внимание

Начиная с PHP 7.2.0 функциональность УСТАРЕЛА, а в PHP 8.0.0 функциональность УДАЛИЛИ. Полагаться на функциональность настоятельно не рекомендуют.

Приведение переменной к null через выражение `(unset) $var` не удаляет переменную и её значение. Это выражение только возвращает значение `null`.

### Смотрите также

- is_null()
- unset()

## Логические значения

Логический тип (bool) принимает только два значения, которые выражают истинность: `true` или `false`.

### Синтаксис

Логические литералы — значения с типом bool — указывают константами `true` или `false`. Обе константы регистронезависимы.

    <?php

    $foo = True; // Присвоить переменной $foo значение TRUE

    var_dump($foo); // bool(true)

Логические условия часто проверяют в управляющих конструкциях. Внутри конструкций выполняют операции, результатом которых становятся значения с типом bool.

    <?php

    $action = "show_version";
    $show_separators = true;

    // Оператор == проверит
    // равенство и выражение вычислится как логическое значение
    if ($action == "show_version") {
        echo "Версия 1.23";
    }

    // Сравнение логической переменной со значением true избыточно,...
    if ($show_separators == TRUE) {
        echo "<hr>\n";
    }

    // ...поскольку проверка без сравнения даёт аналогичный результат:
    if ($show_separators) {
        echo "<hr>\n";
    }

### Преобразование в логический тип

Оператор `(bool)` явно приводит значение к типу bool. В большей части сценариев ручное преобразование типа не потребуется, поскольку в логическом контексте значение автоматически интерпретируется как значение с типом bool. Дополнительную информацию о приведении типов даёт раздел «Жонглирование типами».

При преобразовании в тип bool следующие значения интерпретируются как `false`:

- само значение boolean `false`
- integer `0` (ноль)
- float `0.0` (ноль) и `-0.0` (минус ноль)
- пустая строка `""` и строка `"0"`
- массив без элементов
- особый тип NULL (включая неустановленные переменные)
- внутренние объекты, которые перегружают своё поведение приведения к логическому типу. Например: объекты GMP, которые представляют значение `0`.

Все остальные значения считаются `true` (включая resource и `NAN`).

Внимание

Число `-1` PHP оценивает как логическое значение `true`, как и любое другое ненулевое — отрицательное или положительное — число!

Пример #1 Приведение к логическому типу

    <?php

    var_dump((bool) "");        // bool(false)
    var_dump((bool) "0");       // bool(false)
    var_dump((bool) 1);         // bool(true)
    var_dump((bool) -2);        // bool(true)
    var_dump((bool) "foo");     // bool(true)
    var_dump((bool) 2.3e5);     // bool(true)
    var_dump((bool) array(12)); // bool(true)
    var_dump((bool) array());   // bool(false)
    var_dump((bool) "false");   // bool(true)

## Целые числа

Тип int — число из множества ℤ = {..., -2, -1, 0, 1, 2, ...}.

### Смотрите также

- Числа с плавающей точкой
- Математические операции с числами произвольной точности функциями модуля BCMath
- Математические операции с числами множественной точности функциями модуля GNU Multiple Precision

### Синтаксис

Целые числа (int) указывают в десятичной (основание 10), шестнадцатеричной (основание 16), восьмеричной (основание 8) или двоичной (основание 2) системе счисления. Отрицательные целые числа (int) указывают через оператор отрицания.

Для записи в восьмеричной системе счисления перед числом ставят ноль — `0`. Начиная с PHP 8.1.0 восьмеричную нотацию также дополнили символами `0o` или `0O`, которые записывают перед числом. Для записи в шестнадцатеричной системе счисления перед числом записывают `0x`. Для записи в двоичной системе счисления перед числом указывают символы `0b`.

С PHP 7.4.0 появилась поддержка символов подчёркивания — `_` между цифрами целочисленных литералов. Подчёркивания улучшают читаемость кода и удаляются PHP-сканером.

Пример #1 Целые числа

    <?php

    $a = 1234; // Десятичное число
    $a = 0123; // Восьмеричное число (эквивалентно 83 в десятичной системе)
    $a = 0o123; // Восьмеричное число (начиная с PHP 8.1.0)
    $a = 0x1A; // Шестнадцатеричное число (эквивалентно 26 в десятичной системе)
    $a = 0b11111111; // Двоичное число (эквивалентно 255 в десятичной системе)
    $a = 1_234_567; // Десятичное число (с PHP 7.4.0)

    ?>

Формально структуру целых чисел int приняли в PHP 8.1.0 (раньше не допускались восьмеричные префиксы `0o` или `0O`, а до PHP 7.4.0 не допускалось подчёркивание):

    десятичные        : [1-9][0-9]*(_[0-9]+)*
                      | 0

    шестнадцатеричные : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

    восьмеричные      : 0[oO]?[0-7]+(_[0-7]+)*

    двоичные          : 0[bB][01]+(_[01]+)*

    целые             : десятичные
                      | шестнадцатеричные
                      | восьмеричные
                      | двоичные

Размер типа int зависит от платформы, хотя обычно максимальное значение равно примерно 2 миллиардам — 32 бита со знаком. Максимальное значение на 64-битных платформах обычно составляет около 9E18. PHP не поддерживает беззнаковые целые числа (int). Размер типа int в байтах возвращает константа `PHP_INT_SIZE`, максимальное целочисленное значение — константа `PHP_INT_MAX`, а константа `PHP_INT_MIN` содержит минимальное целочисленное значение.

### Переполнение целых чисел

Если PHP обнаружил, что число превышает размер типа int, язык будет интерпретировать число как float. Аналогично, если результат операции лежит за границами типа int, PHP преобразует результат во float.

Пример #2 Пример переполнения целых чисел

    <?php

    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)

    var_dump(PHP_INT_MAX + 1);       // В 32-разрядной системе system: float(2147483648)
                                     // В 64-разрядной системе: float(9.2233720368548E+18)

    ?>

### Целочисленное деление

В PHP нет оператора целочисленного (int) деления, для этого пользуются функцией intdiv(). Результат вычисления выражения `1/2` выдаёт число с плавающей точкой (float) `0.5`. Приведение этого значения к типу int округлит число в меньшую сторону, но лучше предпочесть функцию round(), которая точнее контролирует округление.

Пример #3 Деление

    <?php

    var_dump(25 / 7);         // float(3.5714285714286)
    var_dump((int) (25 / 7)); // int(3)
    var_dump(round(25 / 7));  // float(4)

    ?>

### Преобразование в целое

Для явного преобразования значение в целое число (int), используйте приведение типов `(int)`. Однако в большей части случаев приведение типа не требуется, поскольку PHP автоматически преобразует значение, если оператору, функции или управляющей структуре требуется аргумент с типом int. Преобразовывать значение в тип int также умеет функция intval().

Преобразование значения с типом resource в тип int вернёт уникальный номер ресурса, который PHP присвоил значению с типом resource во время выполнения.

Смотрите также раздел «Жонглирование типами».

#### Из логического типа

Логическое значение `false` преобразовывается в ноль — `0`, а `true` в единицу — `1`.

#### Из чисел с плавающей точкой

При преобразовании из типа float в тип int PHP округлит число в меньшую сторону. Начиная с PHP 8.1.0 при неявном преобразовании неинтегрального числа с плавающей точкой (float) в целое число (int), которое теряет точность, PHP выдаёт уведомление об устаревании.

Пример #4 Приведение из числа с плавающей точкой

    <?php

    function foo($value): int
    {
        return $value;
    }

    var_dump(foo(8.1)); // "Deprecated: Implicit conversion from float 8.1 to int loses precision" начиная с PHP 8.1.0
    var_dump(foo(8.1)); // 8 до PHP 8.1.0
    var_dump(foo(8.0)); // 8 в обоих случаях

    var_dump((int) 8.1); // 8 в обоих случаях
    var_dump(intval(8.1)); // 8 в обоих случаях

    ?>

Приведение выдаст неопределённый результат, если число с плавающей точкой превышает размеры типа int (обычно `± 2.15e+9 = 2^31` на 32-битных системах и `± 9.22e+18 = 2^63` на 64-битных системах), поскольку у типа float нет достаточной точности, чтобы вернуть правильный результат в виде целого числа (int). PHP для таких случаев не выведет ни предупреждения, ни даже замечания!

> Замечание:

> Значения `NaN`, `Inf` и `-Inf` при приведении к типу int становятся равными нулю.

Внимание

Нельзя приводить неизвестную дробь к типу int, поскольку это иногда даёт неожиданные результаты.

    <?php

    echo (int) ((0.1 + 0.7) * 10); // выводит 7!

    ?>

Подробнее об этом рассказывает параграф с предупреждением о точности чисел с плавающей точкой.

#### Из строк

Числовые строки или строки, которые начинаются с числовых символов, разрешаются в целочисленные значения, остальные строки преобразовываются в значение `0`.

#### Из NULL

Значение `null` преобразовывается в ноль — `0`.

#### Из других типов

Предостережение

У поведения преобразования в тип int из других типов нет определения. Нельзя полагаться на наблюдаемое поведение, поскольку оно изменится в новых версиях языка без предупреждения.

## Числа с плавающей точкой

Числа с плавающей запятой в руководстве называются «числами с плавающей точкой», поскольку в английском языке — языке оригинала PHP-руководства — целую и дробную часть в таких числах разделяет точка, а не запятая. В других языках программирования числа с плавающей точкой называют также: float, double или real. В PHP числа с плавающей точкой записывают следующими синтаксисами:

    <?php

    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // Начиная с PHP 7.4.0

    ?>

Поддержка подчёркиваний в числах появилась с PHP 7.4.0:

    LNUM          [0-9]+(_[0-9]+)*
    DNUM          ({LNUM}?"."{LNUM}) | ({LNUM}"."{LNUM}?)
    EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

Размер числа с плавающей точкой зависит от платформы, хотя максимум обычного значения с плавающей точкой составляет примерно 1.8e308 с точностью около 14 десятичных цифр (64-битный формат стандарта IEEE).

Внимание

# Точность чисел с плавающей точкой

Точность чисел с плавающей точкой ограничена. Хотя точность зависит от операционной системы, PHP обычно использует формат двойной точности, который определяет стандарт IEEE 754, который даёт максимальную относительную погрешность округления порядка 1.11e-16. Неэлементарные арифметические операции иногда дают бо́льшие ошибки, и, конечно, учитывают распространение ошибок при объединении операции.

Кроме того, рациональные числа наподобие `0.1` или `0.7`, которые легко точно представить как числа с плавающей точкой по основанию 10 — в десятичной системе счисления, внутренне невозможно точно представить как числа с плавающей точкой по основанию 2 — в двоичной системе счисления, независимо от размера мантиссы. Поэтому такие числа невозможно преобразовать во внутреннюю двоичную форму без небольшой потери точности. Иногда это даёт противоречивые результаты: например, округление `floor((0.1 + 0.7) * 10)` возвращает значение `7` вместо `8`, которое ожидалось, поскольку внутреннее представление будет примерно таким: `7.9999999999999991118...`.

Точности чисел с плавающей точкой не доверяют до последней цифры и не сравнивают такие числа на предмет равенства. Когда требуется повышенная точность, пользуются функциями математики произвольной точности и функциями математики множественной точности модуля GMP.

«Простое» объяснение даёт » руководство по числам с плавающей точкой, которое также называется «Why don’t my numbers add up?» («Почему мои числа не складываются?» — англ.)

### Преобразование в число с плавающей точкой

#### Из строк

Числовые строки или строки с начальной числовой последовательностью преобразовываются в значение с плавающей точкой, иначе строка преобразуется в целочисленное значение `0`.

#### Из других типов

При преобразовании значений других типов в число с плавающей точкой значение вначале преобразовывается в целое число (int), а затем в число с плавающей точкой (float). Дополнительную информацию о целочисленном преобразовании даёт раздел «Преобразование в целое число».

> Замечание:

> Поскольку поведение отдельных типов при преобразовании в тип int, то же самое происходит и при преобразовании в число с плавающей точкой (float).

### Сравнение чисел с плавающей точкой

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

Для сравнения чисел с плавающей точкой используется верхняя граница относительной ошибки при округлении. Эта величина называется машинной эпсилон или единицей округления (unit roundoff) и представляет собой самую маленькую допустимую разницу при расчётах.

Числа $a и $b равны до 5-ти знаков после точки.

Пример #1 Сравнение чисел с плавающей точкой

    <?php

    $a = 1.23456789;
    $b = 1.23456780;
    $epsilon = 0.00001;

    if (abs($a - $b) < $epsilon) {
        echo "true";
    }

    ?>

### NaN

Некоторые числовые операции могут возвращать значение, представляемое константой `NAN`. Данный результат означает неопределённое или непредставимое значение в операциях с плавающей точкой. Любое строгое или нестрогое сравнение данного значения с другим значением, кроме `true`, включая его самого, возвратит `false`.

Так как `NAN` представляет собой неограниченное количество различных значений, то `NAN` не следует сравнивать с другими значениями, включая её саму. Вместо этого, для определения её наличия необходимо использовать функцию is_nan().

## Строки

Строка (string) — набор символов. Каждый байт строки интерпретируется как один символ. PHP поддерживает набор только из 256 символов и поэтому внутренне не поддерживает кодировку Unicode. Подробнее об этом рассказывает раздел «Подробные сведения о строковом типе».

> Замечание: В 32-битных сборках размер строки (string) ограничивается 2 ГБ — максимум 2 147 483 647 байтов.

### Синтаксис

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

- одинарными кавычками
- двойными кавычками
- heredoc-синтаксисом
- nowdoc-синтаксисом

#### Одинарные кавычки

Простейший способ определить строку — заключить строку в одинарные кавычки — символ `'`.

Буквальную одинарную кавычку при записи в строке экранируют обратным слешем — `\`. Сам обратный слеш дублируют — `\\`. В остальных случаях обратный слеш в одинарных кавычках обрабатывается как буквальный обратный слеш: PHP не интерпретирует последовательности вроде `\r` или `\n` в одинарных кавычках как управляющие, а выводит как записали.

> Замечание: Переменные и управляющие последовательности служебных символов в одинарных кавычках не обрабатываются, в отличие от синтаксиса двойных кавычек и heredoc.

Пример #1 Виды синтаксиса

    <?php

    echo 'Это — простая строка', PHP_EOL;

    echo 'Переводы строки внутри кавычек
    становятся частью строкового значения
    и корректно обрабатываются', PHP_EOL;

    // Выводит: Однажды Арнольд сказал: "I'll be back"
    echo 'Однажды Арнольд сказал: "I\'ll be back"', PHP_EOL;

    // Выводит: Вы удалили C:\*.*?
    // (Обратите внимание на экранирование обратным слешем спецсимвола \ — прим. перев.)
    echo 'Вы удалили C:\\*.*?', PHP_EOL;

    // Выводит: Вы удалили C:\*.*?
    // (Символ * не относится к спецсимволам и не образует в паре с обратным слешем управляющую последовательность,
    // поэтому обратный слеш не экранирует символ * и выводится как есть — прим. перев.)
    echo 'Вы удалили C:\*.*?', PHP_EOL;

    // Выводит: В одинарных кавычках управляющая последовательность \n не разворачивается в символ перевода строки
    echo 'В одинарных кавычках управляющая последовательность \n не разворачивается в символ перевода строки', PHP_EOL;

    // Выводит: Переменные $expand и $either также не разворачиваются
    echo 'Переменные $expand и $either также не разворачиваются', PHP_EOL;

#### Двойные кавычки

В строке в двойных кавычках — `"` — PHP распознает следующие управляющие последовательности служебных символов:

Управляющие последовательности
Последовательность | Значение
--- | ---
`\n` | Перевод строки. В кодировке ASCII управляющий символ обозначается аббревиатурой LF и соответствует коду 0x0A в шестнадцатеричной или 10 в десятичной нотации
`\r` | Возврат каретки. В кодировке ASCII управляющий символ обозначается аббревиатурой CR и соответствует коду 0x0D в шестнадцатеричной или 13 в десятичной нотации
`\t` | Горизонтальная табуляция. В кодировке ASCII этот управляющий символ обозначается аббревиатурой HT и соответствует коду 0x09 в шестнадцатеричной или 9 в десятичной нотации
`\v` | Вертикальная табуляция. В кодировке ASCII этот управляющий символ обозначается аббревиатурой VT и соответствует коду 0x0B в шестнадцатеричной или 11 в десятичной нотации
`\e` | Escape-символ. В кодировке ASCII этот управляющий символ обозначается аббревиатурой HT и соответствует коду 0x1B в шестнадцатеричной или 27 в десятичной нотации
`\f` | Подача страницы. В кодировке ASCII этот управляющий символ обозначается аббревиатурой HT и соответствует коду 0x0C в шестнадцатеричной или 12 в десятичной нотации
`\\` | Обратный слеш
`\$` | Знак доллара
`\"` | Двойная кавычка
`\[0-7]{1,3}` | Восьмеричная запись: последовательность символов, которая соответствует регулярному выражению `[0-7]{1,3}`, — `"\101" === "A"`. При целочисленном переполнении, когда символ не помещается в один байт, старшие биты без предупреждения отбрасываются: `"\400" === "\000"`
`\x[0-9A-Fa-f]{1,2}` | Шестнадцатеричная запись: последовательность символов, которая соответствует регулярному выражению `[0-9A-Fa-f]{1,2}`, — `"\x41" === "A"`
`\u{[0-9A-Fa-f]+}` | Символы Юникода: последовательность символов, которая соответствует регулярному выражению `[0-9A-Fa-f]+`, — кодовая точка Юникода, которая выводится как строка в кодировке UTF-8. Последовательность указывается в фигурных скобках: `"\u{41}" === "A"`

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

Наиболее важное свойство строк в двойных кавычках состоит в том, что названия переменных в них развернутся и обработаются. Подробнее об этом рассказывает раздел «Интерполяция строк».

#### Heredoc

Третий способ определения строк — heredoc-синтаксис: `<<<`. Следом за этим оператором указывают идентификатор, а затем перевод строки. Затем идёт сама строка, за которой снова идёт тот же идентификатор, чтобы закрыть вставку.

Закрывающий идентификатор разрешается отбивать пробелами или символами табуляции, и тогда отступ удалится из каждой строки в блоке документа. До PHP 7.3.0 закрывающий идентификатор указывали в самом начале новой строки.

Кроме того, закрывающий идентификатор подчиняется тем же правилам именования, что и другие метки в PHP: содержит только буквенно-цифровые символы и подчёркивания, и не начинается с цифрового символа или символа подчёркивания.

Пример #2 Базовый пример heredoc-синтаксиса в PHP 7.3.0

    <?php

    // Без отступа перед маркером закрытия
    echo <<<END
          a
         b
        c
    \n
    END;

    // Отступ в 4 пробела перед маркером закрытия
    echo <<<END
          a
         b
        c
        END;

Результат выполнения приведённого примера в PHP 7.3:

          a
         b
        c

      a
     b
    c

PHP выбросит исключение ParseError, если закрывающий идентификатор сместили дальше хотя бы одной строки тела:

Пример #3 Идентификатору закрытия нельзя отступать дальше строк тела

    <?php

    echo <<<END
      a
     b
    c
       END;

Результат выполнения приведённого примера в PHP 7.3:

    Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

В теле и перед идентификатором окончания heredoc-блока разрешается делать отступы символами пробелов и табуляции, но нельзя смешивать символы табуляции и пробелы относительно отступа идентификатора закрытия и отступа тела до начала закрывающего идентификатора; heredoc-синтаксис будет работать с отступом перед маркером закрытия, только если каждая строка тела начинается, но не ограничивается, с того же отступа, что и отступ перед маркером закрытия. При несовпадении отступов в начале строк тела с отступом перед идентификатором закрытия PHP выбросит исключение ParseError. Ограничения на пробельные отступы добавили, потому что смешивание табуляций и пробелов для отступов вредно для разбора.

Пример #4 Пример несовпадения отступов в теле и перед идентификатором закрытия тела

    <?php

    /**
     * Каждый следующий пример кода не работает
     */

    // Отступ тела отличается от отступа маркера окончания:
    // тело — 5 пробелов, маркер окончания — 2 символа табуляции
    {
        echo <<<END
         a
            END;
    }

    // Смешивание пробелов и табуляций в теле:
    // тело — 4 пробела + 1 символ табуляции, маркер окончания — 5 пробелов
    {
        echo <<<END
            a
         END;
    }

    // Смешивание пробелов и табуляций в маркере окончания:
    // тело — 10 пробелов, маркер окончания — 2 символа табуляции + 1 пробел
    {
        echo <<<END
              a
             END;
    }

Результат выполнения приведённого примера в PHP 7.3:

    Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

За идентификатором закрытия строки тела не обязательно ставить точку с запятой или новую строку. Приведём пример кода, который разрешается с PHP 7.3.0:

Пример #5 Продолжение выражения после идентификатора закрытия

    <?php

    $values = [<<<END
    a
      b
        c
    END, 'd e f'];
    var_dump($values);

Результат выполнения приведённого примера в PHP 7.3:

    array(2) {
      [0] =>
      string(11) "a
      b
        c"
      [1] =>
      string(5) "d e f"
    }

Внимание

Парсер примет идентификатор за закрывающий и выбросит исключение ParseError, если найдёт закрывающий идентификатор в начале строки, даже если это часть слова.

Пример #6 Закрывающий идентификатор в теле текста провоцирует исключение ParseError

    <?php

    $values = [<<<END
    a
    b
    END ING
    END, 'd e f'];

Результат выполнения приведённого примера в PHP 7.3:

    Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5

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

Внимание

До PHP 7.3.0 строке с закрывающим идентификатором нельзя было содержать других символов, кроме точки с запятой — `;`. То есть идентификатор нельзя вводить с отступом, а пробелы или знаки табуляции нельзя вводить до или после точки с запятой. Учитывают также, что первым символом перед закрывающим идентификатором идёт символ новой строки, который определяет операционная система. Например, в Unix-системах, включая macOS, это символ `\n`. После идентификатора закрытия должна сразу начинаться новая строка.

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

Пример #7 Пример неправильного до PHP 7.3.0 синтаксиса

    <?php

    class Foo {
        public $bar = <<<EOT
    bar
        EOT;
    // Отступ перед закрывающим идентификатором недопустим
    }

Пример #8 Пример правильного даже до PHP 7.3.0 синтаксиса

    <?php

    class Foo
    {
        public $bar = <<<EOT
    bar
    EOT;
    }

В Heredoc-синтаксисе, который содержит переменные, нельзя инициализировать свойства класса.

Heredoc-текст ведёт себя как строка в двойных кавычках, хотя и не заключается в двойные кавычки. То есть в heredoc кавычки не экранируют, но перечисленные управляющие коды по-прежнему разрешено указывать. Переменные разворачиваются, но в выражениях со сложными переменными внутри heredoc работают так же внимательно, как и при работе со строками.

Пример #9 Пример определения heredoc-строки

    <?php

    $str = <<<EOD
    Пример строки,
    которую записали heredoc-синтаксисом
    в несколько строк.
    EOD;

    /* Более сложный пример с переменными. */
    class Foo
    {
        var $foo;
        var $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new Foo();
    $name = 'Расмус';

    echo <<<EOT
    Меня зовут "$name". Я печатаю $foo->foo.
    Теперь я вывожу {$foo->bar[1]}.
    Это выведет заглавную букву 'A': \x41
    EOT;

Результат выполнения приведённого примера:

    Меня зовут "Расмус". Я печатаю Foo.
    Теперь, я вывожу Bar2.
    Это выведет заглавную букву 'A': A

Heredoc-синтаксис работает также и при передаче данных через аргументы функции:

Пример #10 Пример heredoc-синтаксиса с аргументами

    <?php

    var_dump(array(<<<EOD
    foobar!
    EOD
    ));

В heredoc-синтаксисе разрешено инициализировать статические переменные и свойства или константы класса:

Пример #11 Инициализация статических переменных heredoc-синтаксисом

    <?php

    // Статические переменные
    function foo()
    {
        static $bar = <<<LABEL
    Здесь ничего нет...
    LABEL;
    }

    // Константы/свойства класса
    class Foo
    {
        const BAR = <<<FOOBAR
    Пример использования константы
    FOOBAR;

        public $baz = <<<FOOBAR
    Пример использования поля
    FOOBAR;
    }

Допустимо также окружать heredoc-идентификатор двойными кавычками:

Пример #12 Двойные кавычки в heredoc

    <?php

    echo <<<"FOOBAR"
    Привет, мир!
    FOOBAR;

#### Nowdoc

Nowdoc — то же для строк в одинарных кавычках, что и heredoc для строк в двойных кавычках. Синтаксис Nowdoc похож на heredoc-синтаксис, но внутри него не выполняются интерполяция строк. Конструкция легко встраивает PHP-код или другие большие блоки текста без предварительного экранирования. В этом он отчасти похож на SGML-конструкцию `<![CDATA[ ]]>`, в том, что он объявляет блок текста, который не требует обработки.

Nowdoc задают той же последовательностью символов `<<<`, что и в heredoc, но следующий за ней идентификатор берут в одинарные кавычки, например, `<<<'EOT'`. Условия, которые распространяются на идентификаторы heredoc-синтаксиса, действительны также и для синтаксиса nowdoc, а больше остальных те, что относятся к закрывающему идентификатору.

Пример #13 Пример nowdoc-синтаксиса

    <?php

    echo <<<'EOD'
    Пример текста,
    занимающего несколько строк,
    написанного синтаксисом nowdoc. Обратные слеши выводятся без обработки,
    например, \\ и \'.
    EOD;

Результат выполнения приведённого примера:

    Пример текста,
    занимающего несколько строк,
    написанного синтаксисом nowdoc. Обратные слеши выводятся без обработки,
    например, \\ и \'.

Пример #14 Nowdoc-синтаксис с переменными в строках с двойными кавычками

    <?php

    /* Усложнённый пример с переменными. */
    class Foo
    {
        public $foo;
        public $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new Foo();
    $name = 'Расмус';

    echo <<<'EOT'
    Меня зовут "$name". Я печатаю $foo->foo.
    Теперь я печатаю {$foo->bar[1]}.
    Это не выведет заглавную 'A': \x41
    EOT;

Результат выполнения приведённого примера:

    Меня зовут "$name". Я печатаю $foo->foo.
    Теперь я печатаю {$foo->bar[1]}.
    Это не выведет заглавную 'A': \x41

Пример #15 Пример со статичными данными

    <?php

    class Foo
    {
        public $bar = <<<'EOT'
    bar
    EOT;
    }

#### Интерполяция строк

PHP умеет подставлять внутри строк значения вместо переменных, если строку (string) указали в двойных кавычках или heredoc-синтаксисом.

В PHP предусмотрели два вида синтаксиса для указания переменных в строках: базовый и продвинутый. Базовым синтаксисом пользуются чаще, им легко встраивать переменную, значение массива (array) или свойство объекта (object) с минимумом усилий.

##### Базовый синтаксис

PHP интерпретирует как переменную и подставит вместо переменной значение этой переменной, если встретит в строке знак доллара `$`, за которым идут символы, допустимые для составления названий переменных.

Пример #16 Интерполяция строк

    <?php

    $juice = "яблочного";

    echo "Он выпил немного $juice сока." . PHP_EOL;

Результат выполнения приведённого примера:

    Он выпил немного яблочного сока.

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

    строковая переменная::
         имя-переменной (смещение-или-свойство)?
       | ${ выражение }

    смещение-или-свойство::
         смещение в строке
       | свойство-в-строке

    смещение-в-строке::
         [ имя ]
       | [ имя-переменной ]
       | [ целочисленный-литерал ]

    свойство-в-строке::
         -> имя

    имя-переменной::
         $ имя

    имя::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

Внимание

Синтаксис `${ выражение }` устарел с PHP 8.2.0, поскольку интерпретируется как переменные переменных:

    <?php

    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");

Результат выполнения приведённого примера в PHP 8.2:

    Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6

    Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
    string(3) "foo"
    string(3) "bar"

Результат выполнения приведённого примера:

    string(3) "foo"
    string(3) "bar"

Вместо этого пользуются продвинутым синтаксисом интерполяции строк.

> Замечание: Знак доллара остается в строке как сам знак доллара, если невозможно сформировать допустимое имя:

>     <?php

>     echo "Строка не содержит переменных $ для интерполяции\n";
>     echo "Строка не содержит переменных $\n для интерполяции\n";
>     echo "Строка не содержит переменных $2 для интерполяции\n";

> Результат выполнения приведённого примера:

>     Строка не содержит переменных $ для интерполяции
>     Строка не содержит переменных $
>     для интерполяции
>     Строка не содержит переменных $2 для интерполяции

Пример #17 Пример интерполяции значений первого уровня массива или свойства объекта

    <?php
    $juices = array("яблочного", "апельсинового", "string_key" => "фиолетового");

    echo "Он выпил немного $juices[0] сока.";
    echo PHP_EOL;
    echo "Он выпил немного $juices[1] сока.";
    echo PHP_EOL;
    echo "Он выпил немного $juices[string_key] сока.";
    echo PHP_EOL;

    class A
    {
        public $s = "string";
    }

    $o = new A();

    echo "Значение свойства объекта: $o->s.";

Результат выполнения приведённого примера:

    Он выпил немного яблочного сока.
    Он выпил немного апельсинового сока.
    Он выпил немного фиолетового сока.
    Значение свойства объекта: string.

> Замечание: Ключ массива указывают без кавычек, поэтому невозможно ссылаться на константу как на ключ в базовом синтаксисе. Вместо этого пользуются продвинутым синтаксисом.

В PHP 7.1.0 добавили поддержку отрицательных числовых индексов.

Пример #18 Отрицательные числовые индексы

    <?php

    $string = 'string';
    echo "Символ с индексом -2 равен $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Изменение символа на позиции -3 на 'o' даёт следующую строку: $string.", PHP_EOL;

Результат выполнения приведённого примера:

    Символ с индексом -2 равен n.
    Изменение символа на позиции -3 на «o» даёт следующую строку: strong

Для выражений, которые сложнее этих, лучше пользоваться продвинутым синтаксисом.

##### Продвинутый, или фигурный, синтаксис

Продвинутый синтаксис разрешает интерполировать переменные с произвольными методами доступа.

В строках продвинутым синтаксисом указывают скалярные переменные, элементы массива, статические и динамические свойства объекта со строковым представлением. Выражение записывается как и вне строки, а затем оборачивается в фигурные скобки `{` и `}`. Поскольку знак `{` невозможно экранировать, продвинутый синтаксис распознаётся только тогда, когда знак `$` идёт непосредственно за знаком `{`. Знак доллара экранируют синтаксисом `{\$`, чтобы получить литерал `{$`. Поясняющие примеры:

Пример #19 Синтаксис фигурных скобок

    <?php

    const DATA_KEY = 'const-key';
    $great = 'здорово';

    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Индексное значение',
        'const-key' => 'Ключ со знаком минуса',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // Не работает, выводит: Это { здорово}
    echo "Это { $great}" . PHP_EOL;

    // Работает, выводит: Это здорово
    echo "Это {$great}" . PHP_EOL;

    // Для вывода самих фигурных скобок:
    echo "Это {{$great}}" . PHP_EOL;

    class Square
    {
        public $width;

        public function __construct(int $width)
        {
            $this->width = $width;
        }
    }

    $square = new Square(5);

    // Работает
    echo "Ширина квадрата составляет {$square->width}00 сантиметров." . PHP_EOL;

    // Работает, ключи в кавычках работают только при записи синтаксисом фигурных скобок
    echo "Это работает: {$arr['key']}" . PHP_EOL;

    // Работает
    echo "Это работает: {$arr[3][2]}" . PHP_EOL;

    echo "Работает: {$arr[DATA_KEY]}" . PHP_EOL;

    // При работе с многомерными массивами массивы внутри строк оборачивают в фигурные скобки
    echo "Это работает: {$arr['foo'][2]}" . PHP_EOL;

    echo "Работает: {$obj->values[3]->name}" . PHP_EOL;

    echo "Работает: {$obj->$staticProp}" . PHP_EOL;

    // Не работает, выводит: C:\directory\{fantastic}.txt
    echo "C:\directory\{$great}.txt" . PHP_EOL;

    // Работает, выводит: C:\directory\fantastic.txt
    echo "C:\\directory\\{$great}.txt" . PHP_EOL;

> Замечание: В строках с продвинутым синтаксисом возможно записывать переменные переменных, поскольку продвинутый синтаксис разрешает произвольные выражения.

#### Доступ к символам и изменение символов в строке

Символы внутри строк индексируются с начала строки, индексы начинаются с 0. Смещение символа, который требуется прочитать или изменить внутри строки, указывают после строки в квадратных скобках массива (array), например $str[42]. Для этого о строке думают как о массиве символов. Больше одного символа получают и заменяют функциями substr() и substr_replace().

> Замечание: Начиная с PHP 7.1.0 поддерживаются отрицательные значения смещения. Они задают смещение с конца строки. Раньше отрицательные смещение вызывали ошибку уровня `E_NOTICE` при чтении (возвращая пустую строку) или `E_WARNING` при записи (оставляя строку без изменений).

> Замечание: До PHP 8.0.0 доступ к символам в строках (string) получали, указывая фигурные скобки, например $str{42}. Синтаксис фигурных скобок устарел с PHP 7.4.0 и не поддерживается с PHP 8.0.0.

Внимание

Попытка записи в смещение за границами строки дополнит строку пробелами до этого смещения. Нецелочисленные типы преобразуются в целочисленные. Неверный тип смещения выдаст ошибку уровня `E_WARNING`. При добавлении в смещение строки новых символов присвоится только первый символ (байт). Начиная с PHP 7.1.0 присваивание пустой строки вызовет фатальную ошибку. Раньше присваивался нулевой байт (NULL).

Внимание

Внутренне PHP представляет строки массивами байтов. Поэтому доступ или изменение строки по смещению небезопасны для многобайтовых данных и выполняются только со строками в однобайтовых кодировках, например ISO-8859-1.

> Замечание: Начиная с PHP 7.1.0 попытка указать оператор пустого индекса на пустой строке выдаст фатальную ошибку. Раньше пустая строка преобразовывалась в массив без предупреждения.

Пример #20 Примеры строк

    <?php

    // Получим первый символ строки
    $str = 'This is a test.';
    $first = $str[0];
    var_dump($first);

    // Получим третий символ строки
    $third = $str[2];
    var_dump($third);

    // Получим последний символ строки
    $str = 'This is still a test.';
    $last = $str[strlen($str) - 1];
    var_dump($last);

    // Изменим последний символ строки
    $str = 'Look at the sea';
    $str[strlen($str)-1] = 'e';
    var_dump($str);

Смещение в строке задают либо целым числом, либо целочисленной строкой, иначе PHP выдаст предупреждение.

Пример #21 Пример недопустимого смещения строки

    <?php

    $str = 'abc';

    $keys = [ '1', '1.0', 'x', '1x' ];

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }

Результат выполнения приведённого примера:

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> Замечание:

> Доступ к переменным других типов, кроме массивов и объектов, которые реализуют соответствующие интерфейсы, через операторы `[]` или `{}` без предупреждения возвращает `null`.

> Замечание:

> Доступ к символам в строковых литералах получают через операторы `[]` или `{}`.

> Замечание:

> Доступ к символам в строковых литералах через оператор `{}` объявили устаревшим в PHP 7.4 и удалили в PHP 8.0.

### Полезные функции и операторы

Строки объединяют оператором «.» — точки. Обратите внимание, оператор сложения «+» здесь не работает. Подробнее об этом рассказывает раздел «Строковые операторы».

В языке предусмотрели ряд полезных функций для манипулирования строками.

Общие функции описывает раздел «Функции для работы со строками», а для расширенного поиска и замены — «Функции Perl-совместимых регулярных выражений».

В PHP также предусмотрели функции для работы с URL-адресами и функции шифрования и дешифрования строк (Sodium и Hash).

Наконец, смотрите также функции символьных типов.

### Преобразование в строку

Значение преобразовывают в строку приведением через оператор `(string)` или функцией strval(). В выражениях, в которых требуется строка, преобразование выполняется автоматически. Это выполняется во время вывода через языковые конструкции echo или print, либо когда значение переменной сравнивается со строкой. Разделы руководства «Типы» и «Жонглирование типами», прояснят сказанное ниже. Смотрите также описание функции settype().

Значение bool `true` преобразовывается в строку `"1"`, а логическое значение `false` преобразовывается в `""` (пустую строку). Такое поведение допускает преобразование значения в обе стороны — из логического типа в строковый и наоборот.

Целое число (int) или число с плавающей точкой (float) преобразовывается в строку, которая представит число в текстовом виде, включая экспоненциальную часть для чисел с плавающей точкой. Большие числа с плавающей точкой преобразовываются в экспоненциальную запись: `4.1E+6`.

> Замечание:

> Начиная с PHP 8.0.0 разделитель дробной части обозначается только точкой: "`.`". До PHP 8.0.0 символ десятичной точки определялся функцией setlocale() при установке региональных настроек скрипта для категории LC_NUMERIC.

Массивы преобразовываются в строку `"Array"`. Поэтому конструкции echo или print не умеют выводить содержимое массива (array). Отдельные элементы массива выводятся конструкцией `echo $arr['foo']`. Следующие параграфы расскажут о просмотре содержимого массивов.

Для преобразования объекта (`object`) в строку (string) определяют магический метод __toString.

Ресурс (resource) преобразовывается в строку (string) наподобие `"Resource id #1"`, где `1` — номер ресурса, который PHP назначает типу resource во время исполнения кода. Идентификатор отдельного ресурса уникален только в рамках текущего выполнения скрипта — веб-запроса или CLI-процесса, — но не гарантирует одинаковых значений при очередном запуске, поэтому нельзя полагаться на точное повторение значения идентификатора. Тип ресурса возвращает функция get_resource_type().

Значение `null` всегда преобразовывается в пустую строку.

Как указано выше, прямое преобразование в строку массивов, объектов или ресурсов не даёт полезной информации о значении, кроме типа. Более эффективные инструменты вывода значений для отладки этих типов — это функции print_r() и var_dump().

Бо́льшая часть значений в PHP преобразуема в строку для постоянного хранения. Этот метод преобразования называется сериализацией. Сериализуют значения функцией serialize().

### Подробные сведения о строковом типе

Строковый тип (string) в PHP реализовали в виде массива байтов и целочисленного значения, которое содержит длину буфера. В этой структуре нет информации о том, как преобразовывать байты в символы, эту задачу решает программист. Нет ограничений на значения, из которых состоит строка, например, байт со значением `0` (NUL-байт) разрешается где угодно в строке (однако рекомендуют учитывать, что ряд функций, которые в этом руководстве назвали «бинарно небезопасными», передают строки библиотекам, которые игнорируют данные после NUL-байта).

Такая природа строкового типа объясняет, почему в PHP не предусмотрели отдельного типа «byte» — строки выполняют эту роль. Функции, которые не возвращают текстовых данных, — например, произвольный поток данных, считываемый из сетевого сокета, — по-прежнему возвращают строки.

С учётом того, что PHP не диктует конкретную кодировку для строк, возникает вопрос: Как тогда кодируются строковые литералы? Например, эквивалентна ли строка `"á"` символу `"\xE1"` в кодировке ISO-8859-1, последовательности символов `"\xC3\xA1"` в кодировке UTF-8 с формой нормализации C, последовательности `"\x61\xCC\x81"` в кодировке UTF-8 с формой нормализации D или другому возможному представлению? Ответ такой: строка закодируется способом, которым её закодировали в файле скрипта. Поэтому, если скрипт записан в кодировке ISO-8859-1, то и строка кодируется в кодировке ISO-8859-1 и т. д. Однако это правило не выполняется при включённом режиме Zend Multibyte: скрипт записывают в произвольной кодировке, объявляя её или полагаясь на автоопределение, а затем конвертируют в конкретную внутреннюю кодировку, в которой и кодируются строковые литералы. Учтите, что на кодировку скрипта (или на внутреннюю кодировку, если включён режим Zend Multibyte) накладывается ряд ограничений: почти в каждом случае эта кодировка должна быть надмножеством кодировки ASCII, например, UTF-8 или ISO-8859-1. Учтите также, что кодировки, зависящие от состояния, где одни и те же значения байтов допустимы в начальном и не начальном состоянии сдвига, создают риск проблем.

Строковые функции, чтобы быть полезными, пробуют предположить кодировку строки. Единство в этом вопросе не помешало бы, но PHP-функции работают с текстом по-разному:

- Одни — предполагают, что строка закодирована в какой-то однобайтовой кодировке, но для корректной работы им не нужно интерпретировать байты как конкретные символы. Сюда попадают функции вроде substr(), strpos(), strlen() и strcmp(). Другой способ мышления об этих функциях — представлять, что они оперируют буферами памяти, т. е. работают непосредственно с байтами и их смещениями.
- Другим — передаётся кодировка строки или они принимают значение по умолчанию, если кодировку не передали. Это относится к функции htmlentities() и большей части функций модуля mbstring.
- Третьи — работают с текущими настройками локали (смотрите setlocale()), но оперируют побайтово.
- Наконец четвёртые — предполагают, что строка использует конкретную кодировку, обычно UTF-8. Сюда попадает бо́льшая часть функций из модулей intl и PCRE (для последнего — только при указании модификатора `u`).

Программа правильно обработает строки в кодировке Unicode, только если вместо функций, которые не гарантируют правильную обработку или повреждают строки в Юникоде, вызывать функции модулей intl и mbstring, которые корректно обрабатывают строки с многобайтовыми символами. Работа с правильными PHP-функциями обработки строк в Юникоде — только начало, дополнительно потребуется изучить спецификацию стандарта Unicode. Строки состоят не только из прописных и строчных букв и часто не только из символов латинского алфавита, поэтому лучше готовить программу к обработке строк из многобайтовых символов.

## Числовые строки

PHP считает строку (string) числовой, если строку возможно интерпретировать как целое число (int) или как число с плавающей точкой (float).

Формально с PHP 8.0.0:

    WHITESPACES      \s*
    LNUM             [0-9]+
    DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
    EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
    INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
    FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
    NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

В PHP также поддерживается концепция префиксной числовой строки. Это строка, которая начинается как числовая и продолжается любыми другими символами.

> Замечание:

> Строка, которая содержит букву `E` (без учёта регистра), ограниченную цифрами, воспринимается как число, которое выразили в научной нотации. Поведение при сравнении строк с числами в научной нотации иногда кажется неожиданным.

> Пример #1 Сравнение строк с числами в научной нотации

>     <?php

>     var_dump("0D1" == "000"); // false, "0D1" — не научная нотация
>     var_dump("0E1" == "000"); // true, "0E1" интерпретируется как выражение 0 * (10 ^ 1), которое равно значению 0
>     var_dump("2E1" == "020"); // true, "2E1" интерпретируется как выражение 2 * (10 ^ 1), которое равно значению 20

>     ?>

### Строки в числовых контекстах

Когда строку необходимо использовать как число (например арифметические операции, декларация целочисленного типа, и т. д.), применяют следующий алгоритм действий:

1. Строка приводится к типу int, если строка числовая, представляет целое число и не превышает максимально допустимого значения для типа int, которое определяет константа `PHP_INT_MAX`, иначе строка приводится к типу float.
2. Тип string приводится к типу int, если контекст разрешает строки, которые начинаются с числа, и значение string начинается с целочисленной числовой части, которая не превышает значение константы `PHP_INT_MAX`, которая определяет в PHP наибольшее значение для типа int, иначе строка разрешается в тип float и дополнительно выдаёт ошибку уровня `E_WARNING`.
3. Для нечисловых строк выбрасывается ошибка TypeError.

### Поведение до PHP 8.0.0

До PHP 8.0.0 строка считалась числовой, только если она начиналась с пробельных символов. PHP считал строку префиксной числовой, если строка завершалась пробельными символами.

До PHP 8.0.0 при работе со строкой как с числом применялся приведённый алгоритм, но с рядом отличий:

- Использование префиксной числовой строки вызывало ошибку уровня `E_NOTICE`, а не `E_WARNING`.
- Нечисловые строки вызывали ошибку уровня `E_WARNING`, а сама строка приводилась к числу `0`.

До PHP 7.1.0 не вызывалась ошибка ни уровня `E_NOTICE`, ни уровня `E_WARNING`.

    <?php

    $foo = 1 + "10.5";                // Переменная $foo — число с плавающей точкой (11.5)
    $foo = 1 + "-1.3e3";              // Переменная $foo — число с плавающей точкой (-1299)
    $foo = 1 + "bob-1.3e3";           // TypeError начиная с PHP 8.0.0. Ранее $foo принималось за целое число (1)
    $foo = 1 + "bob3";                // TypeError начиная с PHP 8.0.0, Ранее $foo принималось за целое число (1)
    $foo = 1 + "10 Small Pigs";       // Переменная $foo — целое (11). В PHP 8.0.0 выдаётся ошибка уровня E_WARNING, а в более ранних версиях — уровня E_NOTICE
    $foo = 4 + "10.2 Little Piggies"; // Переменная $foo — число с плавающей точкой (14.2). В PHP 8.0.0 выдаётся ошибка уровня E_WARNING, а в более ранних версиях — уровня E_NOTICE
    $foo = "10.0 pigs " + 1;          // Переменная $foo — число с плавающей точкой (11). В PHP 8.0.0 выдаётся ошибка уровня E_WARNING, а в более ранних версиях — уровня E_NOTICE
    $foo = "10.0 pigs " + 1.0;        // Переменная $foo — число с плавающей точкой (11). В PHP 8.0.0 выдаётся ошибка уровня E_WARNING, а в более ранних версиях — уровня E_NOTICE

    ?>

## Массивы

Список функций для работы с массивами доступен в главе документации «Функции для работы с массивами».

Массив в PHP — упорядоченная структура данных, которая связывает значения и ключи. Этот тип данных оптимизирован для разных целей, поэтому с ним работают как с массивом, списком (вектором), хеш-таблицей (реализацией карты), словарём, коллекцией, стеком, очередью и, возможно, чем-то ещё. Поскольку значениями массива бывают другие массивы, также доступны деревья и многомерные массивы.

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

### Синтаксис

#### Определение массива через языковую конструкцию array()

Массив (array) создают языковой конструкцией array(). Конструкция принимает как аргументы произвольное количество разделённых запятыми пар `ключ => значение`.

    array(
        key  => value,
        key2 => value2,
        key3 => value3,
        ...
    )

Запятая после последнего элемента массива необязательна; пропуск конечной запятой не вызывает ошибок. Конечную запятую часто опускают в определениях однострочных массивов, — лучше предпочесть `array(1, 2)` вместо `array(1, 2, )`. Для многострочных массивов, наоборот, часто указывают конечную запятую, поскольку это упрощает добавление новых элементов в конец массива.

> Замечание:

> PHP поддерживает короткий синтаксис массива, который заменяет языковую конструкцию `array()` выражением `[]`.

Пример #1 Простой массив

    <?php

    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // Работа с коротким синтаксисом массива
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);

В PHP массивы поддерживают только целочисленные (int) и строковые (string) ключи. Тип значений не ограничивается.

Дополнительно выполняются следующие преобразования ключа:

- Строки (string), которые содержат целое число (int), преобразуются в значение int, если только перед числом не указали знак `+`. Например, ключ со значением `"8"` сохранится со значением `8`. При этом значение `"08"` не преобразуется, поскольку не относится к корректным десятичным целым.
- Числа с плавающей точкой (float) также преобразуются в целочисленные значения int — дробная часть отбрасывается. Например, ключ со значением `8.7` сохранится как `8`.
- Значения с типом bool также преобразуются в целочисленный тип int. Например, ключ со значением `true` сохранится как `1`, а ключ со значением `false` — как `0`.
- Тип null преобразуется в пустую строку. Например, ключ со значением `null` сохранится как `""`.
- Массивы (array) и объекты (object) нельзя указывать как ключи. Это сгенерирует предупреждение: `Illegal offset type`.

PHP перезаписывает значение элемента, если встречает в объявлении массива повтор одного и того же ключа, поэтому в массиве остается только последний такой элемент.

Пример #2 Преобразование типов и перезапись элементов

    <?php

    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );

    var_dump($array);

Результат выполнения приведённого примера:

    array(1) {
      [1]=>
      string(1) "d"
    }

Поскольку каждый ключ в этом примере приводится к `1`, значение перезаписывается на каждом новом элементе, и останется единственное значение `"d"`, которое присвоилось последним.

PHP разрешает массивам содержать одновременно целочисленные (int) и строковые (string) ключи, поскольку PHP одинаково воспринимает индексные и ассоциативные массивы.

Пример #3 Смешанные целочисленные (int) и строковые (string) ключи

    <?php

    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);

Результат выполнения приведённого примера:

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

Ключ необязателен: ключом нового элемента, для которого не указали ключ, станет увеличенный на единицу предыдущий наибольший целочисленный (int) ключ.

Пример #4 Индексные массивы без ключа

    <?php

    $array = array("foo", "bar", "hallo", "world");
    var_dump($array);

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hallo"
      [3]=>
      string(5) "world"
    }

Разрешено указывать ключ одним элементам и пропускать для других:

Пример #5 Ключи для некоторых элементов

    <?php

    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

Видно, что последнее значение `"d"` присвоилось ключу `7`. Это произошло потому, что перед этим самым большим значением целочисленного ключа было `6`.

Пример #6 Расширенный пример преобразования типов и перезаписи элементов

Приведённый пример показывает все приведения типов ключей и перезаписи элементов.

    <?php

    $array = array(
        1    => 'a',
        '1'  => 'b', // Значение "b" перезапишет значение "a"
        1.5  => 'c', // Значение "c" перезапишет значение "b"
        -1 => 'd',
        '01'  => 'e', // Строка НЕ перезапишет ключ 1, поскольку она не целочисленная
        '1.5' => 'f', // Строка НЕ перезапишет ключ 1, поскольку она не целочисленная
        true => 'g', // Значение "g" перезапишет значение "c"
        false => 'h',
        '' => 'i',
        null => 'j', // Значение "j" перезапишет значение "i"
        'k', // Значение "k" присваивается ключу 2, потому что самый большой целочисленный ключ до этого был 1
        2 => 'l', // Значение "l" перезапишет значение "k"
    );

    var_dump($array);

Результат выполнения приведённого примера:

    array(7) {
      [1]=>
      string(1) "g"
      [-1]=>
      string(1) "d"
      ["01"]=>
      string(1) "e"
      ["1.5"]=>
      string(1) "f"
      [0]=>
      string(1) "h"
      [""]=>
      string(1) "j"
      [2]=>
      string(1) "l"
    }

Пример #7 Отрицательные индексы

При назначении отрицательного целочисленного ключа `n`, PHP позаботится о том, чтобы назначить следующий ключ `n + 1`.

    <?php

    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);

Результат выполнения приведённого примера:

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

Внимание

До PHP 8.3.0 назначение отрицательного целочисленного ключа `n` присвоило бы следующему ключу значение `0`, поэтому приведённый пример вывел бы:

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### Доступ к элементам массива через синтаксис квадратных скобок

Доступ к элементам массива получают синтаксисом `array[key]`.

Пример #8 Доступ к элементам массива

    <?php

    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);

Результат выполнения приведённого примера:

    string(3) "bar"
    int(24)
    string(3) "foo"

> Замечание:

> До PHP 8.0.0 квадратные и фигурные скобки могли взаимозаменяться при доступе к элементам массива (например, в приведённом примере `$array[42]` и `$array{42}` делали одно и то же). Синтаксис фигурных скобок устарел с PHP 7.4.0 и больше не поддерживается с PHP 8.0.0.

Пример #9 Разыменование массива

    <?php

    function getArray()
    {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);

> Замечание:

> Попытка доступа к неопределённому ключу в массиве — то же, что и попытка доступа к неопределённой переменной: выдаётся ошибка уровня `E_WARNING` или до PHP 8.0.0 ошибка уровня `E_NOTICE`, и результат равняется `null`.

> Замечание:

> Попытка разыменовать не массив, а скалярное значение, которое отличается от строки (string), отдаст `null`, тогда как разыменование значения string трактует строку как индексный массив. При такой попытке до PHP 7.4.0 не выдавалось сообщение об ошибке. С PHP 7.4.0 выдаётся ошибка уровня `E_NOTICE`; с PHP 8.0.0 выдаётся ошибка уровня `E_WARNING`.

#### Создание или модификация массива синтаксисом квадратных скобок

Массив возможно изменить путём явной установки значений.

Присваивание через ключ в квадратных скобках установит значение массива (array), а пара пустых скобок `[]` добавит новое значение.

        $arr[key] = value;
        $arr[] = value;
        // В ключе key указывают только значения типов int или string,
        // а в элементе value — значения произвольного типа

PHP создаст новый массив, если переменную $arr ещё не определили или присвоили переменной значение `null` или `false`, так что это альтернативный способ создать массив array. Однако создавать массив такими способом не рекомендуют, поскольку если переменная $arr уже содержит значение наподобие string-переменной сетевого запроса, это значение или не изменится и вызовет ошибку, или инструкция `[]` интерпретируется как оператор доступа к символу в строке. Лучше инициализировать переменную прямым присваиванием.

> Замечание: Начиная с PHP 7.1.0 оператор пустого индекса на строке выбросит фатальную ошибку. Раньше строка молча преобразовывалась в массив.

> Замечание: С PHP 8.1.0 способ, которым создавали новый массив приведением к нему значения `false`, устарел. Способ, которым создают новый массив приведением к нему значения `null` и неопределённого значения, по-прежнему доступен.

Для изменения конкретного значения указывают ключ элемента и присваивают новое значение. Пару «ключ — значение» удаляют языковой конструкцией unset().

Пример #10 Работа с массивами через квадратные скобки

    <?php

    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // В этом месте скрипта такое аналогично
                    // присваиванию $arr[13] = 56;

    $arr["x"] = 42; // Добавление в массив нового
                    // элемента с ключом "x"

    unset($arr[5]); // Удаление элемента из массива

    var_dump($arr);

    unset($arr);    // Конструкция удаляет весь массив

    var_dump($arr);

> Замечание: Если ключ не указан, новым ключом станет максимальный существующий целочисленный индекс + `1`. Если в массиве нет положительных целочисленных индексов, ключом станет `0`. Начиная с PHP 8.3.0 это также может быть отрицательное целое число.

> При работе с массивами учитывают, что наибольший целочисленный ключ, на основе которого вычисляется новый ключ, не обязательно содержится в массиве в текущий момент. PHP вычислит новый ключ на основе наибольшего целочисленного ключа, который появлялся в массиве с момента последней переиндексации. Следующий пример это иллюстрирует:

>     <?php

>     // Создаём простой массив.
>     $array = array(1, 2, 3, 4, 5);
>     print_r($array);

>     // Теперь удаляем каждый элемент, но массив оставляем нетронутым:
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // Добавляем элемент (обратите внимание, что новым ключом станет 5, а не 0).
>     $array[] = 6;
>     print_r($array);

>     // Переиндексация:
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);

> Результат выполнения приведённого примера:

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### Деструктуризация массива

Массивы деструктурируют языковыми конструкциями `[]` (начиная с PHP 7.1.0) или list(). Эти языковые конструкции разрешено использовать для деструктуризации массива на отдельные переменные.

Пример #11 Деструктуризация массива

    <?php

    $source_array = ['foo', 'bar', 'baz'];
    [$foo, $bar, $baz] = $source_array;
    echo $foo, PHP_EOL;    // Выведет "foo"
    echo $bar, PHP_EOL;    // Выведет "bar"
    echo $baz, PHP_EOL;    // Выведет "baz"

Деструктуризацию массива также выполняют в конструкции `foreach` для деструктуризации многомерного массива во время итерации по массиву.

Пример #12 Деструктуризация массива в конструкции foreach

    <?php

    $source_array = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }

Деструктуризация проигнорирует элементы массива, для которых не указали переменную. Деструктуризация массива начинается с индекса `0`.

Пример #13 Игнорирование элементов

    <?php

    $source_array = ['foo', 'bar', 'baz'];

    // Присваивание элемента с индексом 2 переменной $baz
    [, , $baz] = $source_array;

    echo $baz;    // Выведет "baz"

Начиная с PHP 7.1.0 поддерживается деструктуризация ассоциативных массивов. Это упрощает выбор элемента в массивах с числовым индексом, поскольку разрешает явно указать индекс.

Пример #14 Деструктуризация ассоциативных массивов

    <?php

    $source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // Присваивание элемента с индексом 'baz' переменной $three
    ['baz' => $three] = $source_array;

    echo $three, PHP_EOL;  // Выведет 3

    $source_array = ['foo', 'bar', 'baz'];

    // Присваивание элемента с индексом 2 переменной $baz
    [2 => $baz] = $source_array;

    echo $baz, PHP_EOL;    // Выведет "baz"

Массив деструктурируют, чтобы поменять две переменные местами.

Пример #15 Перестановка двух переменных

    <?php

    $a = 1;
    $b = 2;
    [$b, $a] = [$a, $b];
    echo $a, PHP_EOL;    // Выведет 2
    echo $b, PHP_EOL;    // Выведет 1

> Замечание:

> Оператор `...` не поддерживается в присваиваниях.

> Замечание:

> Попытка получить доступ к неопределённому ключу массива аналогична обращению к любой другой неопределённой переменной: выдаётся сообщение об ошибке уровня `E_WARNING`, или ошибки уровня `E_NOTICE` до PHP 8.0.0, а результатом становится значение `null`.

> Замечание:

> Деструктуризация скалярного значения присваивает значение `null` каждой переменной в левой части выражения присваивания.

### Полезные функции

Для работы с массивами есть довольного много полезных функций. Подробнее об этом рассказано в разделе «Функции для работы с массивами».

> Замечание:

> Языковая конструкция unset() умеет удалять ключи массива. Обратите внимание, что массив НЕ переиндексируется. Массив переиндексируют функцией array_values(), если требуется поведение в стиле «удалить и сдвинуть».

> Пример #16 Удаление промежуточных элементов

>     <?php

>     $a = array(1 => 'один', 2 => 'два', 3 => 'три');

>     /* Удаление элемента изменит массив так, как если бы его определили так:
>        $a = array(1 => 'один', 3 => 'три');
>        но НЕ так:
>        $a = array(1 => 'один', 2 => 'три');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Теперь переменная $b содержит array(0 => 'один', 1 => 'три')
>     var_dump($b);

Управляющая конструкция `foreach` появилась в языке для перебора массивов. Конструкция предлагает простой способ обхода массива.

### Что можно и нельзя делать с массивами

#### Почему выражение `$foo[bar]` неверно?

Строковый литерал в индексе ассоциативного массива лучше брать в кавычки. Например, правильно писать `$foo['bar']`, а не `$foo[bar]`. Но почему? С старых скриптах часто встречается следующий синтаксис:

    <?php

    $foo[bar] = 'враг';
    echo $foo[bar];
    // и т. д.

Неправильно записывать ключ без кавычек, хотя такой код и работает. Причина заключается в интерпретации незакавыченного ключа как неопределённой константы `bar`, а не строки `'bar'` — литерала в кавычках. Код работает из-за автоматического преобразования «голой строки» — строки без кавычек, которая не соответствует ни одному известному символу, — в строку со значением такой «голой строки». PHP подставит вместо bar строку `'bar'`, если в текущей области видимости недоступна константа с названием `bar`.

Внимание

Резервный вариант для обработки неопределённой константы как пустой строки выдаёт ошибку уровня `E_NOTICE`. Начиная с PHP 7.2.0 поведение объявлено устаревшим и выдаёт ошибку уровня `E_WARNING`. Начиная с PHP 8.0.0 удалено и выбрасывает исключение Error.

Это не значит, что в кавычки заключают каждый ключ. В кавычки не берут константы и переменные, поскольку закавычивание помешает интерпретации.

Пример #17 Закавычивание ключей

    <?php

    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // Простой массив:
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\nПроверяем $i: \n";
        echo "Плохо: " . $array['$i'] . "\n";
        echo "Хорошо: " . $array[$i] . "\n";
        echo "Плохо: {$array['$i']}\n";
        echo "Хорошо: {$array[$i]}\n";
    }

Результат выполнения приведённого примера:

    Проверяем 0:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Плохо:
    Хорошо: 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Плохо:
    Хорошо: 1

    Проверяем 1:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Плохо:
    Хорошо: 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Плохо:
    Хорошо: 2

Дополнительные примеры, которые подтверждают этот факт:

Пример #18 Дополнительные примеры

    <?php

    // Показываем все ошибки
    error_reporting(E_ALL);

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // Верно
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // Неверно. Это не работает и выбрасывает PHP-ошибку Error из-за неопределённой константы
    // с названием fruit
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // Определим константу и посмотрим,
    // как изменится поведение кода. Присвоим константе с названием fruit значение "veggie".
    define('fruit', 'veggie');

    // Теперь обратите внимание на разницу
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // Доступ по ключу без кавычек сработает внутри строки. PHP не ищет константы внутри строк,
    // поэтому ошибка здесь не возникнет
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // За одним исключением: PHP интерпретирует константы,
    // если обращение к массиву внутри строки обернули фигурными скобками
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // Ещё один способ вывести значение массива — конкатенация
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple

    <?php

    // Это не сработает и вызовет ошибку разбора наподобие:
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'.
    // Это относится и к суперглобальным переменным в строках
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";

Как указывает раздел о синтаксисе, внутри квадратных скобок '`[`' и '`]`' требуется указывать выражение. Поэтому следующий код работает:

    <?php

    echo $arr[somefunc($bar)];

Это пример работы с возвращаемым функцией значением в качестве индекса массива. PHP также знает о константах:

    <?php

    $error_descriptions[E_ERROR]   = "Произошла фатальная ошибка";
    $error_descriptions[E_WARNING] = "PHP сообщает о предупреждении";
    $error_descriptions[E_NOTICE]  = "Это лишь неофициальное замечание";

Обратите внимание, что `E_ERROR` — это такой же допустимый идентификатор, как и `bar` в первом примере. Но последний пример по существу эквивалентен такой записи:

    <?php

    $error_descriptions[1] = "Произошла фатальная ошибка";
    $error_descriptions[2] = "PHP выдал предупреждение";
    $error_descriptions[8] = "Это просто уведомление";

поскольку значение константы `E_ERROR` соответствует значению `1` и т. д.

##### Так что же в этом плохого?

Когда-нибудь в будущем команда разработчиков PHP, возможно, захочет добавить ещё одну константу или ключевое слово, либо константа из другого кода может вмешаться. Например, неправильно использовать слова `empty` и `default`, поскольку они относятся к зарезервированным ключевым словам.

> Замечание: Повторим, внутри строки (string) в двойных кавычках допустимо не окружать индексы массива кавычками, поэтому `"$foo[bar]"` — допустимая запись. В примерах выше объяснено, почему, дополнительная информация дана в разделе об обработке переменных в строках.

### Преобразование в массив

Преобразование целого числа (int), числа с плавающей точкой (float), строки (string), логического значения (bool) или ресурса (resource) в массив — создаёт массив с одним элементом с индексом 0 и значением скаляра, который был преобразован. Говоря по-другому, выражение `(array) $scalarValue` аналогично выражению `array($scalarValue)`.

При преобразовании объекта (object) в массив элементами массива становятся свойства (переменные-члены) этого объекта. Ключами становятся имена переменных-членов, со следующими примечательными исключениями: целочисленные свойства становятся недоступными; к закрытым полям класса (private) в начало дописывается название класса; к защищённым полям класса (protected) в начало добавляется символ '*'. Эти добавленные с обоих сторон значения также получат `NUL`-байты. Неинициализированные типизированные свойства автоматически отбрасываются.

Пример #19 Преобразование в массив

    <?php

    class A
    {
        private $B;
        protected $C;
        public $D;

        function __construct()
        {
            $this->{1} = null;
        }
    }

    var_export((array) new A());

Результат выполнения приведённого примера:

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

Это может вызвать несколько неожиданное поведение:

Пример #20 Приведение объекта к массиву

    <?php

    class A
    {
        private $A; // Свойство станет ключом '\0A\0A'
    }

    class B extends A
    {
        private $A; // Свойство станет ключом '\0B\0A'
        public $AA; // Свойство станет ключом 'AA'
    }

    var_dump((array) new B());

Результат выполнения приведённого примера:

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

Приведённый код покажет 2 ключа с названием 'AA', хотя один ключ на самом деле называется '\0A\0A'.

Получится пустой массив, если преобразовать в массив значение `null`.

### Сравнение

Массивы сравнивают функцией array_diff() и операторами массивов.

### Распаковка массива

Массив, перед которым указали оператор `...`, распакуется на месте при определении нового массива. Распаковка доступна только массивам и объектам, которые реализуют интерфейс Traversable. Распаковка массива spread-оператором `...` доступна с PHP 7.4.0.

PHP поддерживает многократное чередование распаковки и стандартных элементов до или после оператора `...`:

Пример #21 Простая распаковка массива

    <?php

    // Применение короткого синтаксиса массива.
    // Работает также с синтаксисом array().
    $arr1 = [1, 2, 3];
    $arr2 = [...$arr1]; // [1, 2, 3]
    $arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
    $arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
    $arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

    function getArr() {
      return ['a', 'b'];
    }

    $arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd'];

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);

Распаковка массива оператором `...` соблюдает семантику функции array_merge(), поэтому более поздние строковые ключи перезаписывают более ранние, а целочисленные ключи перенумеровываются:

Пример #22 Распаковка массива с дублирующим ключом

    <?php

    // Строковый ключ
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // Целочисленный ключ
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // Распаковка массивов создаёт массив [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6],
    // в котором исходные целочисленные ключи не сохраняются

> Замечание:

> Ключи, которые не принадлежат ни целочисленному, ни строковому типу, выбрасывают ошибку TypeError. Такие ключи генерируют только объекты, класс которых реализует интерфейс Traversable.

> Замечание:

> До PHP 8.1 распаковка массива со строковым ключом не поддерживалась:

>     <?php

>     $arr1 = [1, 2, 3];
>     $arr2 = ['a' => 4];
>     $arr3 = [...$arr1, ...$arr2];
>     // Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5
>     $arr4 = [1, 2, 3];
>     $arr5 = [4, 5];
>     $arr6 = [...$arr4, ...$arr5]; // Работает: [1, 2, 3, 4, 5]

### Примеры

Массив в PHP — гибкий тип данных. Вот несколько примеров:

Пример #23 Видимость массивов

    <?php

    // Код:
    $a = array( 'color' => 'красный',
                'taste' => 'сладкий',
                'shape' => 'круг',
                'name'  => 'яблоко',
                4        // PHP назначит элементу ключ 0
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // ...эквивалентен следующему коду:
    $a = array();
    $a['color'] = 'красный';
    $a['taste'] = 'сладкий';
    $a['shape'] = 'круг';
    $a['name']  = 'яблоко';
    $a[]        = 4;        // ключом станет 0

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // После выполнения приведённого кода переменная $a станет массивом
    // array('color' => 'красный', 'taste' => 'сладкий', 'shape' => 'круг',
    // 'name' => 'яблоко', 0 => 4), а переменная $b станет массивом
    // array(0 => 'a', 1 => 'b', 2 => 'c'), или просто array('a', 'b', 'c')

    var_dump($a, $b);

Пример #24 Вызов языковой конструкции array()

    <?php

    // Массив как карта (свойств)
    $map = array(
        'version'    => 4,
        'OS'         => 'Linux',
        'lang'       => 'english',
        'short_tags' => true
    );

    var_dump($map);

    // Строго числовые ключи,
    // что эквивалентно массиву array(0 => 7, 1 => 8, ...)
    $array = array(
        7,
        8,
        0,
        156,
        -10
    );
    var_dump($array);

    $switching = array(
        10,         // ключ = 0
        5    =>  6,
        3    =>  7,
        'a'  =>  4,
        11,         // ключ = 6 (максимальным числовым индексом было 5)
        '8'  =>  2, // ключ = 8 (число!)
        '02' => 77, // ключ = '02'
        0    => 12  // значение 10 перезапишется значением 12
    );
    var_dump($switching);

    // пустой массив
    $empty = array();
    var_dump($empty);

Пример #25 Коллекция

    <?php

    $colors = array('красный', 'голубой', 'зелёный', 'жёлтый');

    foreach ($colors as $color) {
        echo "Вам нравится $color?\n";
    }

Результат выполнения приведённого примера:

    Вам нравится красный?
    Вам нравится голубой?
    Вам нравится зелёный?
    Вам нравится жёлтый?

Непосредственное изменение значений массива допустимо через передачу значений по ссылке.

Пример #26 Изменение элемента в цикле

    <?php

    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as &$color) {
        $color = mb_strtoupper($color);
    }
    unset($color); /* Переменную удаляют, чтобы очередные записи
                      в переменной $color не меняли последний элемент массива */

    print_r($colors);

Результат выполнения приведённого примера:

    Array
    (
        [0] => КРАСНЫЙ
        [1] => ГОЛУБОЙ
        [2] => ЗЕЛЁНЫЙ
        [3] => ЖЁЛТЫЙ
    )

Следующий пример создаёт массив, индексация которого начинается с единицы.

Пример #27 Индексация с единицы

    <?php

    $firstquarter = array(1 => 'январь', 'февраль', 'март');
    print_r($firstquarter);

Результат выполнения приведённого примера:

    Array
    (
        [1] => 'январь'
        [2] => 'февраль'
        [3] => 'март'
    )

Пример #28 Заполнение массива

    <?php

    // Заполняем массив элементами из директории
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);

Массивы упорядочены. Порядок изменяют разными функциями сортировки. Подробнее об этом рассказано в разделе «Функции для работы с массивами». Для подсчёта количества элементов в массиве вызывают функцию count().

Пример #29 Сортировка массива

    <?php

    sort($files);
    print_r($files);

Массивы поддерживают значения в виде других массивов, поскольку массивы принимают произвольные значения. Поэтому PHP разрешает создавать рекурсивные и многомерные массивы.

Пример #30 Рекурсивные и многомерные массивы

    <?php

    $fruits = array ( "fruits"  => array ( "a" => "апельсин",
                                           "b" => "банан",
                                           "c" => "яблоко"
                                         ),
                      "numbers"   => array ( 1,
                                           2,
                                           3,
                                           4,
                                           5,
                                           6
                                         ),
                      "holes"   => array (      "первая",
                                           5 => "вторая",
                                                "третья"
                                         )
                    );
    var_dump($fruits);

    // Ряд примеров доступа к значениям предыдущего массива
    echo $fruits["holes"][5];    // Выведет "вторая"
    echo $fruits["fruits"]["a"]; // напечатает "апельсин"
    unset($fruits["holes"][0]);  // удалит "первая"

    // Создаст новый многомерный массив
    $juices["apple"]["green"] = "хороший";
    var_dump($juices);

Присваивание массива включает копирование значения. Чтобы скопировать массив по ссылке, указывают оператор присваивания по ссылке.

Пример #31 Копирование массивов

    <?php

    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // Массив $arr2 изменился,
                 // Массив $arr1 всё ещё выглядит так: array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // Теперь массивы $arr1 и $arr3 одинаковы

    var_dump($arr1, $arr2, $arr3);

## Объекты

### Инициализация объекта

Новые объекты создают выражением `new`, которое создаёт в переменной экземпляр класса:

Пример #1 Создание объекта

    <?php

    class foo
    {
        function do_foo()
        {
            echo "Код foo.";
        }
    }

    $bar = new foo();
    $bar->do_foo();

    ?>

Полное рассмотрение производит раздел «Классы и объекты».

### Преобразование в объект

Преобразование типа object в тип object не изменит тип значения. Объект не изменится при преобразовании значения с типом object в тип object. При преобразовании значения другого типа в object PHP создаёт новый экземпляр встроенного класса stdClass. Новый экземпляр будет пустым, если значение равнялось `null`. Массивы преобразовываются в тип object с именами полей как у ключей массива и теми же значениями. Обратите внимание, что до PHP 7.2.0 при таком преобразовании доступ к числовым ключам появляется только при итерации объекта.

Пример #2 Приведение к объекту

    <?php

    $obj = (object) array('1' => 'foo');

    var_dump(isset($obj->{'1'})); // Выводит 'bool(true)'

    // Начиная с PHP 8.1 вызов функции key() на объектах устарел
    var_dump(key($obj)); // Выводит 'string(1) "1"'

    ?>

Остальные значения при преобразовании PHP поместит в переменную-член объекта с названием `scalar` с исходным типом значения.

Пример #3 Преобразование в объект через приведение типа `(object)`

    <?php

    $obj = (object) 'Привет';
    echo $obj->scalar;  // Выводит 'Привет'

    ?>

## Перечисления

(PHP 8 >= 8.1.0)

### Основы перечислений

Перечисления — это ограничивающий слой над классами и константами классов, предназначенный для предоставления способа определения закрытого набора возможных значений для типа.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);

    ?>

Полное описание даёт глава «Перечисления».

### Приведение типов

При преобразовании типа enum в тип object перечисление не изменяется. При преобразовании типа enum в тип array создаётся массив с одним ключом `name` для чистых перечислений или массив с двумя ключами `name` и `value` для типизированных перечислений. Остальные приведения типов вызовут ошибку.

## Ресурсы

Resource — переменная, которая хранит ссылку на внешний ресурс. Ресурсы создают и передают в отдельный набор функций для работы с ресурсами. Список этих функций и типы ресурсов (resource), которые соответствуют функциям, перечисляет приложение.

Смотрите также описание функции get_resource_type().

### Преобразование в ресурс

Поскольку переменные с типом resource хранят дескрипторы открытых файлов, соединений с базой данных, областей холста изображения и т. п., преобразование в ресурс (resource) бессмысленно.

### Освобождение ресурсов

Сборщик мусора автоматически обнаруживает и освобождает ресурсы, на которые не осталось ссылок, за счёт системы подсчёта ссылок, которая составляет часть движка Zend Engine. Поэтому освобождать память вручную приходится редко.

> Замечание: Постоянные подключения к базам данных — исключение из этого правила. Сборщик мусора не уничтожает такие ссылки. Дополнительную информацию даёт раздел о постоянных соединениях.

## Вызываемые выражения

Вызываемое выражение — ссылка на функцию или метод, которая передаётся в другую функцию как аргумент. Параметрам, которые принимают вызываемые выражения, объявляют тип callable.

    <?php

    function foo(callable $callback) {
        $callback();
    }

Отдельные функции наподобие array_map(), usort() или preg_replace_callback() принимают callback-функции как аргументы.

### Объявление вызываемых выражений

Тип callable представляет значения или выражения, доступные для вызова как функция. Вызываемые выражения вызывают как функции или передают как аргументы в функции или методы, которые ожидают в параметре callback-функцию. Свойствам классов нельзя объявлять тип callable; вызываемым свойствам объявляют тип Closure.

Вызываемыми значениями становятся:

- Объекты класса Closure
- Строки (string) с названием функции или квалифицированным названием метода
- Массивы (array) с названием класса или объектом (object) в элементе с индексом 0 и названием метода в элементе с индексом 1
- Объекты (object), в классе которых объявили магический метод __invoke()

Объекты Closure создают синтаксисом анонимных функций, стрелочных функций, синтаксисом первоклассных вызываемых значений или методом Closure::fromCallable().

> Замечание: Синтаксис первоклассных callable-значений доступен только с PHP 8.1.0.

Пример #1 Пример объявления функций обратного вызова, которые становятся объектами класса Closure

    <?php

    // Синтаксис анонимных функций
    $double1 = function ($a) {
        return $a * 2;
    };

    // Синтаксис первоклассных вызываемых значений
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Синтаксис стрелочных функций
    $double3 = fn($a) => $a * 2;

    // Метод Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Вызов замыкания как callback-функции
    // удваивает значение каждого элемента в диапазоне
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

Результат выполнения приведённого примера в PHP 8.1:

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

Вызываемые выражения объявляют как строку с названием функции или статического метода. PHP поддерживает передачу встроенных и пользовательских функций, но не языковых конструкций: array(), echo, empty(), eval(), isset(), list(), print или unset().

Для ссылки на статический метод класса не потребуется создавать объект (object) этого класса, достаточно создать массив с названием класса в элементе с индексом 0 и названием метода в элементе с индексом 1 или сослаться на метод через синтаксис с оператором `::`, который разрешает область действия метода: `'ClassName::methodName'`.

На методы объектов (object) в вызываемых выражениях ссылаются через массив: объект (object) указывают в элементе с индексом 0, а название метода — в элементе с индексом 1.

Видимость метода в объектах Closure проверяется относительно места объявления, а не вызова замыкания Closure, тогда как видимость методов в выражениях с псевдотипом callable проверяется относительно места вызова выражения, поэтому попытка вызова callable-выражения, которое ссылается на недоступный в точке вызова метод, выдаст ошибку. На методы классов лучше ссылаться через замыкания Closure, поскольку видимость метода в точке вызова замыкания не влияет на доступность вызова метода.

> Замечание: Объекты Closure связываются с областью видимости объявления, тогда как вызываемые выражения со ссылкой на метод класса через строку или массив разрешаются в области видимости вызова. Вызываемое значение со ссылкой на закрытый или защищённый метод класса, который потребуется вызывать извне области видимости класса, создают методом Closure::fromCallable() или синтаксисом первоклассных вызываемых значений.

PHP поддерживает вызываемые выражения, которые возможно передать как аргумент, но невозможно вызывать. К таким выражениям относятся вызываемые значения, которые зависят от контекста и ссылаются на метод класса в иерархии наследования через ключевые слова: `'parent::method'` или `["static", "method"]`.

> Замечание: С PHP 8.2.0 контекстно-зависимые вызываемые выражения устарели. Независимые от контекста ссылки на методы получают путём замены выражений наподобие `'parent::method'` выражениями `parent::class . '::method'` или синтаксисом первоклассных вызываемых значений.

Пример #2 Примеры вызова callable-выражений функцией call_user_function()

    <?php

    // Пример callback-функции
    function my_callback_function()
    {
        echo "Привет, мир!", PHP_EOL;
    }

    // Пример callback-метода
    class MyClass
    {
        static function myCallbackMethod()
        {
            echo "Привет, мир!", PHP_EOL;
        }
    }

    // Тип 1: Простой вызов callback-функции
    call_user_func('my_callback_function');

    // Тип 2: Вызов статического метода класса
    call_user_func(['MyClass', 'myCallbackMethod']);

    // Тип 3: Вызов метода объекта класса
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // Тип 4: Вызов статического метода класса
    call_user_func('MyClass::myCallbackMethod');

    // Тип 5: Вызов статического метода класса с разрешением названия класса через языковую конструкцию ::class
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Тип 6: Вызов статического метода класса по контекстно-зависимой относительной ссылке
    class A
    {
        public static function who()
        {
            echo 'A', PHP_EOL;
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo 'B', PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::who']); // Выводит: A.
    // Начиная с PHP 8.2.0 callable-выражения
    // с относительными названиями методов устарели

    // Тип 7: Объекты, классы которых реализуют магический метод __invoke(),
    // доступны для вызова как функции
    class C
    {
        public function __invoke($name)
        {
            echo 'Привет, ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');

Результат выполнения приведённого примера:

    Привет, мир!
    Привет, мир!
    Привет, мир!
    Привет, мир!
    Привет, мир!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 51
    A
    Привет, PHP!

> Замечание: Callback-функции, которые зарегистрировали функцией call_user_func() или call_user_func_array(), не вызовутся при непойманном исключении, которое выбросила предыдущая callback-функция.

## Mixed

Тип mixed принимает любое значение. Он эквивалентен объединению типов `object|resource|array|string|float|int|bool|null`. Тип доступен с PHP 8.0.0.

На языке теории типов, mixed — верхний тип. Остальные типы — его подтипы.

## Void

void — тип, который поддерживается только в объявлении значения возврата. Тип указывает, что функция не возвращает значение, но прерывание функции конструкцией `return;` остаётся допустимым. Тип void нельзя включать в объединения типов, поскольку void относится не к типу значения, а указывает на отсутствие значения. Тип доступен с PHP 7.1.0.

> Замечание: При объявлении для значения возврата типа void функция возвращает значение `null`.

### Инструкция `(void)` и подавление требования об обработке значения возврата

Синтаксис `(void)` явно игнорирует результат выражения. Инструкцию указывают, когда требуется преднамеренно проигнорировать обработку значения возврата при вызове функции или метода, которые пометили атрибутом NoDiscard.

Инструкция `(void)`, в отличие от других приведений, не преобразовывает тип значения и не возвращает значения. Инструкцию нельзя указывать как часть выражения.

Пример #1 Подавление требования об обработке значения возврата

    <?php

    #[\NoDiscard]
    function process(): bool
    {
        return true;
    }

    (void) process(); // Подавляем требование об обработке значения возврата

## Never

never — тип, который разрешается указывать только как возвращаемое значение, которое указывает, что функция прекратит работу без возврата значения. Функция либо вызывает конструкцию языка exit(), либо выбрасывает исключение, либо это бесконечный цикл. Поэтому этот тип нельзя объявлять в объединении типов. Тип доступен с PHP 8.1.0.

На языке теории типов, never — нижний тип. Это означает, что он — подтип остальных типов и заменяет другие возвращаемые типы при наследовании.

## Относительные типы классов

Эти объявления типов можно использовать только внутри классов.

### self

Значение должно быть `instanceof` того же класса, что и класс, в котором используется объявление типа.

### parent

Значение должно быть `instanceof` родительского класса, наследуемого классом, в котором объявляется тип.

### static

static — это тип только для возвращаемого значения, который требует, чтобы возвращаемое значение было `instanceof` того же класса, что и класс, в котором вызывается метод. Доступен начиная с PHP 8.0.0.

## Одноэлементные типы

К одноэлементным типам (англ. Singleton types) относятся типы, которые допускают единственное значение. PHP поддерживает два одноэлементных типа: false с PHP 8.0.0 и true с PHP 8.2.0.

Внимание

До PHP 8.2.0 язык поддерживал тип false только как часть объединённого типа.

> Замечание: Невозможно определить пользовательские одноэлементные типы. Вместо этого определяют перечисления.

## Итерируемые значения

Iterable — встроенный псевдоним объединения типов `array|Traversable` времени компиляции. Тип iterable поддерживается в объявлениях типов, языковой конструкции `foreach` и в выражении yield from внутри генераторов, но с момента появления в PHP 7.1.0 оставался встроенным псевдотипом, а псевдонимом типа стал с PHP 8.2.0.

> Замечание:

> Объявление iterable в качестве типа возвращаемого значения также поддерживается в функциях, из которых возвращается генератор.

> Пример #1 Пример указания iterable в объявлении типа возврата функции-генератора

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach (gen() as $value) {
>         echo $value, "\n";
>     }

## Объявления типов

Объявления типов добавляют параметрам функций, значениям возврата, начиная с PHP 7.4.0 свойствам класса и начиная с PHP 8.3.0 константам класса. Объявления типов гарантируют, что при вызове значение принадлежит заданному типу, иначе PHP выбросит ошибку TypeError.

Каждый тип, который поддерживает PHP, за исключением ресурсов (resource), разрешается указывать в пользовательском объявлении типа. Страница содержит журнал изменений доступности отдельных типов и документацию, которая описывает правила объявления типов.

> Замечание:

> Класс, который реализует метод интерфейса или переопределяет метод родительского класса, подчиняется правилам совместимости. Метод совместим, если следует правилам вариантности.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Добавили поддержку типизации констант классов, интерфейсов, трейтов и перечислений.
8.2.0 | Добавили поддержку DNF-типов.
8.2.0 | Добавили поддержку самостоятельного типа true.
8.2.0 | Типы null и false разрешили указывать отдельно.
8.1.0 | Добавили поддержку пересечений типов.
8.1.0 | Возврат по ссылке из функции с типом значения возврата void устарел.
8.1.0 | Для значения возврата добавили поддержку типа never.
8.0.0 | Для значения возврата добавили поддержку типа mixed.
8.0.0 | Для значения возврата добавили поддержку типа static.
8.0.0 | Добавили поддержку объединения типов.
7.4.0 | Добавили поддержку типизации свойств классов.
7.2.0 | Для значения возврата добавили поддержку типа object.
7.1.0 | Для значения возврата добавили поддержку типа iterable.
7.1.0 | Для значения возврата добавили поддержку типа void.
7.1.0 | Для значения возврата добавили поддержку обнуляемого типа.

### Атомарные типы

Атомарные типы ведут себя прямолинейно, но с рядом оговорок, которые описывает этот раздел.

#### Скалярные типы

Внимание

Псевдонимы имён для скалярных типов, к которым относятся типы bool, int, float и string, не поддерживаются. Вместо назначения псевдонимов названия классов и интерфейсов трактуются как типы. Например, буквальное название `boolean` в объявлении типа потребует, чтобы значение выполняло условие `instanceof` в отношении класса или интерфейса `boolean`, а не принадлежало типу bool:

    <?php

    function test(boolean $param) {}
    test(true);

    ?>

Результат выполнения приведённого примера в PHP 8:

    Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

    Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
    Stack trace:
    #0 -(3): test(true)
    #1 {main}
      thrown in - on line 2

#### Тип void

> Замечание:

> Возврат по ссылке из void-функции устарел начиная с PHP 8.1.0, поскольку такая функция противоречива. Раньше при вызове такой функции уже выдавалась ошибка уровня `E_NOTICE`: Только ссылки на переменные должны возвращаться по ссылке.

>     <?php

>     function &test(): void {}

>     ?>

#### Тип Callable

Свойствам класса нельзя объявлять тип callable.

> Замечание: Тип callable нельзя указывать как название функции.

#### Объявление типов параметрам, которые принимают ссылку

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

Пример #1 Типизированный параметр, который принимает ссылку

    <?php

    function array_baz(array &$param)
    {
        $param = 1;
    }

    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);

    ?>

Вывод приведённого примера будет похож на:

    int(1)

    Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
    Stack trace:
    #0 -(9): array_baz(1)
    #1 {main}
      thrown in - on line 2

### Примечание по составным типам

На объявления составных типов распространяется ряд ограничений; компилятор выполняет проверку избыточности типов, чтобы предотвратить простые ошибки.

Предостережение

Комбинирование пересечений и объединений типов оставалось невозможным до PHP 8.2.0 и введения DNF-типов.

#### Объединение типов

Внимание

Невозможно определить в объединённом типе два одноэлементных типа false и true. Вместо этого указывают тип bool.

Предостережение

До PHP 8.2.0 запрещали определять типы false и null отдельно, поэтому объединение типов, которое состояло только из этих типов, оставалось недопустимым. К таким объединениям относятся типы: false, `false|null` и `?false`.

##### Синтаксический сахар обнуляемого типа

Объявление отдельного базового типа помечают как nullable путём добавления к типу префикса в виде вопросительного знака (`?`). Поэтому типы `?T` и `T|null` идентичны.

> Замечание: Этот синтаксис поддерживается с PHP 7.1.0 и предшествует поддержке объединения типов.

> Замечание:

> Ещё один способ объявить nullable-параметр — указать значением по умолчанию значение `null`. Объявлять тип таким способом не рекомендуют, поскольку изменение значения по умолчанию в дочернем классе нарушит совместимость типов, и к объявлению типа потребуется добавить тип null. Это поведение также устарело начиная с PHP 8.4.

> Пример #2 Старый способ указать nullable-параметр

>     <?php

>     class C {}

>     function f(C $c = null)
>     {
>         var_dump($c);
>     }

>     f(new C());
>     f(null);

>     ?>

> Результат выполнения приведённого примера:

>     object(C)#1 (0) {
>     }
>     NULL

#### Повторные и избыточные типы

Правила объявления составных типов предусматривают ряд ограничений. При компиляции кода с избыточными типами, которые возможно обнаружить без загрузки классов, возникнет ошибка. Примеры ошибок в объявлениях составных типов включают:

- Повторение типа в объявлениях наподобие `int|string|INT` или `Countable&Traversable&COUNTABLE` вызовет ошибку, поскольку после разрешения названия типа внутренними средствами языка тип встретится больше одного раза.
- Объявление типа mixed или never с другими типами вызовет ошибку.
- Ошибки объединения типов:
  - Избыточное объявление типа false или true вместе с типом bool.
  - Избыточное объявление типа класса вместе с типом object.
  - Избыточное объявление типа array или Traversable вместе с типом iterable.
- Ошибки пересечения типов:
  - Объявление типа, который не относится к классовому типу.
  - Объявление типа self, parent или static.
- Ошибки объявления DNF-типов:
  - Избыточное объявление более строго типа с более общим типом.
  - Объявление дубликатов в пересечении типов.

> Замечание: Эти проверки не гарантируют, что тип «минимален» и не содержит повторений или избыточных типов, поскольку для этого потребовалось бы загрузить все указанные типы классов.

Например, если типы `A` и `B` — псевдонимы классов, то составной тип `A|B` остаётся корректным объединением типов, даже если тип получится свести либо к `A`, либо к `B`. Аналогично, если класс `B extends A {}`, то составной тип `A|B` также относится к корректному объединению типов, даже если тип получится свести только к типу `A`.

    <?php

    function foo(): int|INT {} // Запрещено
    function foo(): bool|false {} // Запрещено
    function foo(): int&Traversable {} // Запрещено
    function foo(): self&Traversable {} // Запрещено

    use A as B;
    function foo(): A|B {} // Запрещено (оператор "use" только создаёт псевдоним через механизм разрешения имён, а не отдельный тип)
    function foo(): A&B {} // Запрещено (оператор "use" только создаёт псевдоним через механизм разрешения имён, а не отдельный тип)

    class_alias('X', 'Y');
    function foo(): X|Y {} // Разрешено (избыточность обнаружится только при выполнении кода)
    function foo(): X&Y {} // Разрешено (избыточность обнаружится только при выполнении кода)

    ?>

### Примеры

Пример #3 Пример объявления типа через название класса

    <?php

    class C {}
    class D extends C {}

    // Класс не наследует класс C
    class E {}

    function f(C $c)
    {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);

    ?>

Результат выполнения приведённого примера в PHP 8:

    C
    D

    Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
    Stack trace:
    #0 -(14): f(Object(E))
    #1 {main}
      thrown in - on line 8

Пример #4 Пример объявления типа через название интерфейса

    <?php

    interface I
    {
        public function f();
    }

    class C implements I
    {
        public function f() {}
    }

    // Класс не реализует интерфейс I
    class E {}

    function f(I $i)
    {
        echo get_class($i) . "\n";
    }

    f(new C);
    f(new E);

    ?>

Результат выполнения приведённого примера в PHP 8:

    C

    Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
    Stack trace:
    #0 -(13): f(Object(E))
    #1 {main}
      thrown in - on line 8

Пример #5 Пример объявления типа значения возврата

    <?php

    function sum($a, $b): float
    {
        return $a + $b;
    }

    // Обратите внимание, что функция вернёт значение с типом float
    var_dump(sum(1, 2));

    ?>

Результат выполнения приведённого примера:

    float(3)

Пример #6 Возврат объекта

    <?php

    class C {}

    function getC(): C
    {
        return new C();
    }

    var_dump(getC());

    ?>

Результат выполнения приведённого примера:

    object(C)#1 (0) {
    }

Пример #7 Объявление параметра с обнуляемым типом

    <?php

    class C {}

    function f(?C $c)
    {
        var_dump($c);
    }

    f(new C());
    f(null);

    ?>

Результат выполнения приведённого примера:

    object(C)#1 (0) {
    }
    NULL

Пример #8 Объявление типа значения возврата как обнуляемого

    <?php

    function get_item(): ?string
    {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }

    ?>

Пример #9 Объявление типа свойства класса

    <?php

    class User
    {
        public static string $foo = 'foo';

        public int $id;
        public string $username;

        public function __construct(int $id, string $username)
        {
            $this->id = $id;
            $this->username = $username;
        }
    }

    ?>

### Строгая типизация

В нестрогом режиме, в котором проверка типов работает по умолчанию, PHP преобразовывает значения неправильного типа в скалярный тип, который указали в объявлении, поэтому, например, при передаче в параметр с типом string аргумента с типом int функция получит значение с типом string.

Строгий режим включается отдельно для каждого файла. В строгом режиме механизм проверки типов признаёт только значения, которые соответствуют типу объявления, иначе выбрасывается ошибка TypeError. Единственное исключение из правила — значения с типом int, которые передают в объявления типа float.

Внимание

Объявление директивы `strict_types` не влияет на вызовы функций внутри встроенных функций.

Строгий режим включают инструкцией `declare` с объявлением директивы `strict_types`:

> Замечание:

> На строгость проверки типов при вызове функций влияет режим, который объявили внутри файла вызова, а не режим, который установили в файле объявления функции. Механизм проверки типов применит режим, который установили на стороне вызова, и автоматически приведёт типы значений, если файл без строгой типизации вызывает функцию, которую объявили в файле со строгой типизацией.

> Замечание:

> Строгая типизация определяется только для объявлений скалярных типов.

Пример #10 Строгая типизация для значений аргументов

    <?php

    declare(strict_types=1);

    function sum(int $a, int $b)
    {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));

    ?>

Результат выполнения приведённого примера в PHP 8:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
    Stack trace:
    #0 -(9): sum(1.5, 2.5)
    #1 {main}
      thrown in - on line 4

Пример #11 Приведение типов для значений аргументов

    <?php

    function sum(int $a, int $b)
    {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // Механизм проверки типов приведёт значения аргументов к целым числам: обратите внимание на вывод!
    var_dump(sum(1.5, 2.5));

    ?>

Результат выполнения приведённого примера:

    int(3)
    int(3)

Пример #12 Строгая типизация для значений возврата

    <?php

    declare(strict_types=1);

    function sum($a, $b): int
    {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));

    ?>

Результат выполнения приведённого примера:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
    Stack trace:
    #0 -(9): sum(1, 2.5)
    #1 {main}
      thrown in - on line 5

## Жонглирование типами

PHP не требует явного определения типа при объявлении переменной. Тип переменной определится значением, которое хранит переменная, если тип переменной не определили. Типом переменной $var станет string, если переменной $var присвоили строковое значение (string). Тип переменной изменится на int, если позже переменной $var присвоят целочисленное значение (int).

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

- Числовой
- Строчный
- Логический
- Контекст целых чисел и строк
- Сравнительный
- Контекст функций

> Замечание: Когда значение требуется интерпретировать как другой тип, само значение не изменяет типы.

Как заставить PHP оценивать переменную как конкретный тип, рассказывает раздел «Приведение типов». Описание функции settype() объясняет, как изменить тип переменной.

### Числовой контекст

Числовой контекст возникает при работе с арифметическими операторами.

В этом контексте оба операнда интерпретируются как число с плавающей точкой (float) и результатом станет число с плавающей точкой (float), если один из операндов — число с плавающей точкой (float) (или не интерпретируется как целое число (int)). В противном случае операнды интерпретируются как целое число (int) и результатом также станет целое число (int). С PHP 8.0.0 выбрасывается исключение TypeError, если не получается интерпретировать хотя бы один операнд.

### Строчный контекст

Строчный контекст возникает при работе с языковыми конструкциями echo, print, при интерполяции строк или строковом операторе конкатенации.

В этом контексте значение интерпретируется как значение string. PHP выбросит ошибку TypeError, если не получится интерпретировать значение. До версии PHP 7.4.0 выдавалась ошибка уровня `E_RECOVERABLE_ERROR`.

### Логический контекст

Логический контекст возникает при работе с условными операторами, тернарным оператором или логическими операторами.

В этом контексте значение интерпретируется как логическое — bool.

### Контекст целых чисел и строк

Контекст целых чисел и строк возникает при работе с побитовыми операторами.

В этом контексте результатом станет значение string, если каждый операнд принадлежит типу string, иначе операнды интерпретируются как значения int и результатом также становится тип int. Начиная с версии 8.0.0 PHP выбрасывает ошибку TypeError, если не получается интерпретировать хотя бы один операнд.

### Сравнительный контекст

Сравнительный контекст возникает при работе с операторами сравнения.

Преобразования типов, которые PHP выполняет в этом контексте, объясняет таблица сравнения типов раздела «Операторы сравнения».

### Контекст функций

Контекст функций возникает, когда значение передаётся типизированному параметру, свойству или возвращается из функции, которая объявляет тип возвращаемого значения.

В контексте функции PHP проверяет, соответствует ли значение типу параметра или возврата. Исключение составляют два случая. Первый: значение с типом int преобразовывается в число с плавающей точкой, если тип объявили как float. Второй: значение преобразовывается в принимаемое скалярное значение, если: а) тип объявили как скалярный, б) значение возможно преобразовать в скалярный тип и в) активен режим нестрогой типизации, в котором PHP работает по умолчанию. Описание такого поведения даёт следующий параграф.

Внимание

Встроенные функции автоматически приводят значение `null` к скалярным типам, это поведение УСТАРЕЛО с PHP 8.1.0.

#### Неявная типизация в объявлениях простых типов

- Объявление типа bool: значение интерпретируется как логическое — bool.
- Объявление типа int: PHP интерпретирует значение как целочисленное — int, если однозначно определит само значение, например числовую строку, как целое число.
- Объявление типа float: PHP интерпретирует значение как число с плавающей точкой — float, если однозначно определит само значение, например числовую строку, как число с десятичной дробью.
- Объявление типа string: значение интерпретируется как строка — string.

#### Неявная типизация объединённых типов

Объявления скалярных типов подвергаются ограниченному неявному приведению типов, если директивой `strict_types` не включили режим строгой типизации. PHP выбирает целевой тип из следующего списка в порядке убывания приоритета, если точный тип значения — не часть объединения:

1. int
2. float
3. string
4. bool

Интерпретатор выбирает тип, если объединение включает тип и значение возможно привести к типу по правилам действующей семантики проверки типов PHP. В остальных случаях интерпретатор выбирает следующий по порядку тип.
Предостережение

Исключение: в объединении типов int и float интерпретатор определит предпочтительный тип строкового значения действующей семантикой числовой строки. Например, для значения `"42"` PHP выберет тип int, а для значения `"42.0"` — тип float.

> Замечание:

> Типы, которые не входят в список предпочтений, не станут целями для неявного приведения. Говоря конкретнее, никакого неявного приведения к типам null, false и true не выполняется.

Пример #1 Пример неявного приведения типов к типу в составе объединения

    <?php

    // int|string
    42    --> 42          // Точное соответствие типу — выбор типа int
    "42"  --> "42"        // Точное соответствие типу — выбор типа string
    new ObjectWithToString --> "Результат работы метода __toString()"
                          // Объект несовместим с типом int — переход к типу string
    42.0  --> 42          // Значение float совместимо с типом int — выбор типа int
    42.1  --> 42          // Значение float совместимо с типом int — выбор типа int
    1e100 --> "1.0E+100"  // Значение float превышает диапазон типа int — переход к типу string
    INF   --> "INF"       // Значение float превышает диапазон типа int — переход к типу string
    true  --> 1           // Значение bool совместимо с типом int — выбор типа int
    []    --> TypeError   // Массив несовместим с типами int или string — генерация ошибки

    // int|float|bool
    "45"    --> 45        // Целочисленная числовая строка — выбор типа int
    "45.0"  --> 45.0      // Строка с числом с плавающей точкой — выбор типа float

    "45X"   --> true      // Нечисловая строка — переход к типу bool
    ""      --> false     // Нечисловая строка — переход к типу bool
    "X"     --> true      // Нечисловая строка — переход к типу bool
    []      --> TypeError // Массив несовместим с типами int, float или bool — генерация ошибки

    ?>

### Приведение типов

Приведение типа — преобразование значения в конкретный тип. Для преобразования типа перед значением записывают оператор приведения типа — идентификатор типа в круглых скобках.

Пример #2 Приведение типа

    <?php

    $foo = 10;            // Переменная $foo содержит целое число
    $bar = (bool) $foo;   // Переменная $bar содержит логическое значение

    var_dump($bar);

    ?>

PHP поддерживает следующие приведения типов:

- `(int)` — приведение типа к целому числу (int)
- `(bool)` — приведение типа к логическому значению (bool)
- `(float)` — приведение типа к числу с плавающей точкой (float)
- `(string)` — приведение типа к строке (string)
- `(array)` — приведение типа к массиву (array)
- `(object)` — приведение типа к объекту (object)
- `(unset)` — приведение типа к NULL

С версии PHP 8.5.0 также доступно приведение `(void)`, но оно не выполняет преобразование значения. Приведение используется как инструкция, чтобы явно отбросить результат выражения.

Внимание

`(integer)` — псевдоним приведения типа `(int)`. `(boolean)` — псевдоним приведения типа `(bool)`. `(binary)` — псевдоним приведения типа `(string)`. `(double)` и `(real)` — псевдонимы приведения типа `(float)`. Эти приведения не используют каноническое имя типа и являются устаревшими начиная с PHP 8.5.0.

Внимание

Псевдоним приведения типа `(real)` устарел с PHP 7.4.0, а с PHP 8.0.0 псевдоним удалили.

Внимание

Приведение типа `(unset)` устарело с версии PHP 7.2.0. Обратите внимание, что приведение `(unset)` равносильно присваиванию переменной или вызову значения NULL. Приведение `(unset)` удалили в PHP 8.0.0.

Предостережение

Приведение типа `(binary)` и префикс `b` существуют для прямой поддержки. Типы `(binary)` и `(string)` идентичны, однако, это может измениться, не нужно на это полагаться.

> Замечание:

> PHP игнорирует пробелы в круглых скобках при приведении типа. Поэтому следующие два приведения типов эквивалентны:

>     <?php

>     $foo = (int) $bar;
>     $foo = ( int ) $bar;

>     ?>

Приведение строк (string) и переменных к бинарным строкам (string):

    <?php

    $binary = (binary) $string;
    $binary = b"binary string";

    ?>

Вместо приведения переменной к типу string переменную берут в двойные кавычки.

Пример #3 Механизмы приведения к строке

    <?php

    $foo = 10;            // Переменная $foo содержит целое число
    $str = "$foo";        // Переменная $str содержит строку
    $fst = (string) $foo; // Переменная $fst тоже содержит строку

    // Выводит: "они одинаковые"
    if ($fst === $str) {
        echo "они одинаковые", PHP_EOL;
    }

    ?>

Не всегда ясно, что произойдет при приведении между конкретными типами. Дополнительную информацию дают разделы:

- Преобразование типа к логическому значению (boolean)
- Преобразование типа к целому числу (integer)
- Преобразование типа к числу с плавающей точкой (float)
- Преобразование типа к строке (string)
- Преобразование типа к массиву (array)
- Преобразование типа к объекту (object)
- Преобразование типа к ресурсу (resource)
- Преобразование типа к NULL
- Отбрасывание значения с помощью `(void)`
- Таблицы сравнения типов

> Замечание: Следующий пример справедлив для всех версий PHP, поскольку PHP поддерживает доступ к символам строк (string) через смещения по индексу синтаксисом, аналогичным обращению по индексу к значениям массива (array):

> Пример #4 Работа с символами строки по индексу

>     <?php

>     $a    = 'car'; // Переменная $a содержит строку
>     $a[0] = 'b';   // Переменная $a по-прежнему содержит строку
>     echo $a;       // Выводит: bar

>     ?>

> Дополнительную информацию даёт раздел « Доступ к символу в строке и его изменение ».

# Переменные

## Содержание

- Основы
- Предопределённые переменные
- Область видимости переменной
- Переменные переменных
- Переменные из внешних источников

## Основы

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

Правильное название переменной начинается с буквы в диапазонах `A-Z` или `a-z`, ASCII-символа в диапазоне со 128-го по 255-й байт или символа подчёркивания. Затем идёт произвольное количество букв, цифр или подчёркиваний. В виде регулярного выражения правило именования переменных выражалось бы вот так: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> Замечание: PHP не поддерживает названия переменных в Юникоде, однако, отдельные кодировки символов наподобие UTF-8 кодируют символы так, что каждый байт многобайтового символа попадает в допустимый диапазон, поэтому такое название переменной становится допустимым.

> Замечание: Переменная `$this` — специальная переменная, которой нельзя присваивать значение. До PHP 7.1.0 было возможно косвенное присваивание (например, через переменные переменных).

Подсказка

Смотрите также «Руководство по именованию».

Пример #1 Правильные названия переменных

    <?php
    $var = 'Боб';
    $Var = 'Джо';
    echo "$var, $Var";      // Инструкция выведет "Боб, Джо"

    $_4site = 'ещё нет';    // Правильно; название переменной начинается с символа подчёркивания
    $täyte = 'mansikka';    // Правильно; символ 'ä' — 228-я кодовая точка в кодировке Extended ASCII

Пример #2 Неправильные названия переменных

    <?php

    $4site = 'not yet';     // Неправильно; название начинается с цифры

PHP принимает последовательность произвольных байтов как названия переменной. Названия переменных, которые не соответствуют правилам именования, доступны только динамически во время выполнения. Раздел «Переменные переменных» рассказывает, как получить доступ к переменным переменных.

Пример #3 Доступ к неизвестным именам переменных

    <?php

    ${'invalid-name'} = 'bar';
    $name = 'invalid-name';
    echo ${'invalid-name'}, " ", $$name;

Результат выполнения приведённого примера:

    bar bar

По умолчанию переменные присваиваются по значению. Поэтому когда переменной присваивают выражение, значение исходного выражения копируется в целевую переменную. Это означает, например, что после присваивания значения одной переменной другой переменной, изменение одной переменной не повлияет на другую. Дополнительную информацию об этом способе присваивания смотрите в разделе «Выражения».

PHP также предлагает другой способ присваивания значений переменным: присваивание по ссылке. Это означает, что новая переменная просто ссылается (иначе говоря, «становится псевдонимом» или «указывает») на оригинальную переменную. Изменения в новой переменной отражаются на оригинале, и наоборот.

Для присваивания по ссылке к началу имени присваиваемой (исходной) переменной просто добавляют амперсанд &. Например, следующий фрагмент кода дважды выводит «`Меня зовут Боб`»:

    <?php

    $foo = 'Боб';              // Присваивает переменной $foo значение «Боб»
    $bar = &$foo;              // Ссылка на значение переменной $foo через переменную $bar
    $bar = "Меня зовут $bar";  // Изменение значения переменной $bar...
    echo $bar . PHP_EOL;
    echo $foo . PHP_EOL;       // ...меняет и значение переменной $foo

Важно отметить, что по ссылке присваиваются только переменные.

    <?php
    $original = 25;
    $ref1 = &$original;        // Это верное присваивание
    $ref2 = &(24 * 7);         // Неверно; ссылка на неименованное выражение

    <?php
    // Обратите внимание на отсутствие символа &, который обозначает возвращаемую ссылку, в объявлении функции,
    // то есть функция не возвращает ссылку, поэтому результат нельзя присвоить по ссылке
    function test()
    {
       $original = 25;
       return $original;
    }

    // Обратите внимание: выдаётся уведомление, но значение, которое не относится к ссылке, всё равно присваивается
    $result1 = &test();        // Неверно, потому что функция test() не возвращает переменную по ссылке
    var_dump($result1);

    // Эта функция объявлена как возвращающая ссылку, но возвращает не переменную
    function &test2()
    {
        return 26;             // Неверно, поскольку возвращаемое значение не является ссылкой на переменную
    }

    // Обратите внимание: значение, которое не относится к ссылке, всё равно присваивается
    $result2 = &test2();
    var_dump($result2);

PHP не требует объявлять переменные, хотя рекомендует. Доступ к неопределённой переменной до PHP 8.0.0 выдавал уведомление `E_NOTICE`, а в новых версиях языка выдаёт предупреждение `E_WARNING`. Неопределённая переменная по умолчанию содержит значение `null`. Языковая конструкция isset() помогает определить, инициализировали ли переменную; конструкция считает переменную инициализированной, если значение переменной не равняется `null`.

Пример #4 Значение по умолчанию в неинициализированной переменной

    <?php

    // Пример переменной, которую не установили и (!) не упомянули в строковом,
    // логическом, целочисленном или другом контексте
    var_dump($unset_var);

Результат выполнения приведённого примера:

    Warning: Undefined variable $unset_var in ...
    NULL

PHP разрешает автовивификацию массивов из неопределённых переменных. Автовивификация (букв.: автоматическое оживление) — операция, при которой новый массив создаётся автоматически при добавлении в него значения. Добавление элемента к неопределенной переменной создаст новый массив и не вызовет предупреждения.

Пример #5 Автовивификация массива из неопределённой переменной

    <?php

    $unset_array[] = 'value'; // Предупреждение не выдаётся
    var_dump($unset_array);

Внимание

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

Переменную уничтожают языковой конструкцией unset().

Подробнее о функциях работы с переменными рассказывает раздел «Функции обработки переменных».

## Предопределённые переменные

PHP предлагает набор предопределённых переменных, и набор предопределённых массивов, в которых содержатся переменные веб-сервера если контекст взаимодействия предполагает такие переменные, переменные окружения и переменные пользовательского ввода. Доступ к этим массивам открывается из каждой области видимости. Поэтому эти массивы называются «суперглобальными». В PHP нет механизма для пользовательских суперглобальных переменных. Раздел «Суперглобальные переменные» приводит список и подробнее рассказывает о суперглобальных массивах.

> Замечание: Переменные переменных

> Суперглобальные переменные нельзя использовать как переменные переменных внутри функций или методов класса.

Предопределённые массивы, которые соответствуют переменным, останутся пустыми, если какие-то переменные не установили в директиве variables_order.

## Область видимости переменной

Область видимости переменной — контекст, в котором определили переменную. В PHP предусмотрели область видимости функции и глобальную область видимости. Переменная, которую определили за пределами функции, ограничивается глобальной областью видимости. Код включаемого файла наследует ту же область видимости переменных, что и строка, на которой включается файл.

Пример #1 Пример глобальной области видимости переменных

    <?php
    $a = 1;
    include 'b.inc'; // Код внутри файла b.inc получит доступ к переменной $a

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

Пример #2 Пример локальной области видимости переменных

    <?php

    $a = 1; // Определяем переменную $a в глобальной области видимости

    function test()
    {
        var_dump($a); // Переменная $a не определена, поскольку конструкция echo указывает на локальную версию переменной $a
    }

    test();

До PHP 8.0.0 при вызове функции приведённый пример сгенерирует ошибку уровня `E_NOTICE` о неопределённой переменной, а в новых версиях ошибку уровня `E_WARNING`. Причина ошибки состоит в том, что языковая конструкция echo указывает на локальную версию переменной $a, а переменной не присвоили значение в локальной области видимости. Обратите внимание, поведение переменных отличается от языка C в том, что глобальные переменные в C автоматически доступны функциям, если только глобальную переменную не перезаписали локальным определением. Несовпадение поведения иногда вызывает проблемы при непреднамеренном изменении глобальной переменной. В PHP глобальные переменные потребуется объявить глобальными внутри функции, если функция будет использовать эти переменные.

### Ключевое слово `global`

Ключевое слово `global` связывает переменную глобальной области видимости с локальной областью действия переменной. Ключевое слово принимает отдельную переменную или список переменных. Ключевое слово создаст локальную переменную, которая ссылается на глобальную переменную с тем же названием. Ключевое слово создаст переменную в глобальной области видимости со значением `null`, если переменную не установили в глобальной области действия переменной.

Пример #3 Пример поведения ключевого слова `global`

    <?php

    $a = 1;
    $b = 2;

    function Sum()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Sum();
    echo $b;

Результат выполнения приведённого примера:

    3

При объявлении переменных $a и $b глобальными внутри функции ссылки на эти переменные будут указывать на глобальную версию. Количество глобальных переменных, которыми умеет манипулировать функция, не ограничивается.

Второй способ доступа к переменным глобальной области видимости — суперглобальный PHP-массив $GLOBALS. Перепишем предыдущий пример так:

Пример #4 Работа с суперглобальной переменной $GLOBALS вместо ключевого слова global

    <?php

    $a = 1;
    $b = 2;

    function Sum()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Sum();
    echo $b;

Массив $GLOBALS — ассоциативный массив, в котором ключ представляет название глобальной переменной, а значение элемента массива — содержимое переменной. Обратите внимание, суперглобальная переменная $GLOBALS доступна в любой области видимости, причина состоит в том, что $GLOBALS — суперглобальная переменная. Пример ниже показывает силу суперглобальных переменных:

Пример #5 Суперглобальные переменные и область видимости

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }

> Замечание: Не будет ошибкой, если указать ключевое слово `global` вне функции, например в файле, который включается внутри функции другого файла.

### Переменные, которые определили через ключевое слово `static`

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

Пример #6 Пример показывает, когда требуется статическая переменная

    <?php

    function test()
    {
        $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Эта функция бесполезна, поскольку при каждом вызове устанавливает для переменной $a значение `0` и выводит `0`. Инкремент переменной $a++ здесь не играет роли, поскольку при выходе из функции переменная $a исчезает. Чтобы написать полезную функцию подсчёта, которая не потеряет текущего значения счётчика, переменную $a объявляют статической:

Пример #7 Пример со статической переменной

    <?php

    function test()
    {
        static $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

Теперь функция проинициализирует переменную $a только при первом вызове, а при каждом вызове функция `test()` будет выводить значение переменной $a, а затем инкрементировать значение.

Со статическими переменными также работают в рекурсивных функциях. Следующая функция рекурсивно считает до 10, а статическая переменная $count помогает определить момент остановки:

Пример #8 Статические переменные и рекурсивные функции

    <?php

    function test()
    {
        static $count = 0;

        $count++;
        echo $count . PHP_EOL;

        if ($count < 10) {
            test();
        }

        $count--;
    }

    test();

До PHP 8.3.0 статические переменные разрешалось инициализировать только константными выражениями. С PHP 8.3.0 также разрешили динамические выражения наподобие вызовов функций:

Пример #9 Объявление статических переменных

    <?php

    function foo()
    {
        static $int = 0;         // Правильно
        static $int = 1 + 2;     // Правильно
        static $int = sqrt(121); // Правильно с PHP 8.3.0

        $int++;
        echo $int;
    }

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

Пример #10 Статические переменные в анонимных функциях

    <?php

    function exampleFunction($input)
    {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Функция получила значение: $input, счётчик: $counter\n";
        });

        return $result();
    }

    // Вызов функции exampleFunction пересоздаст анонимную функцию, поэтому статическая
    // переменная не сохранит значение
    echo exampleFunction('A'); // Выводит: Функция получила значение: A, счётчик: 1
    echo exampleFunction('B'); // Выводит: Функция получила значение: B, счётчик: 1

Начиная с PHP 8.1.0 при наследовании, но не переопределении, метода со статическими переменными унаследованный метод будет использовать статические переменные совместно с родительским методом. Поэтому статические переменные в методах теперь ведут себя как статические свойства класса.

Начиная PHP 8.3.0 статические переменные разрешили инициализировать произвольными выражениями. Поэтому статическую переменную получится инициализировать, например, вызовом метода.

Пример #11 Статические переменные в унаследованных методах

    <?php

    class Foo
    {
        public static function counter()
        {
            static $counter = 0;
            $counter++;
            return $counter;
        }
    }

    class Bar extends Foo {}

    var_dump(Foo::counter()); // int(1)
    var_dump(Foo::counter()); // int(2)
    var_dump(Bar::counter()); // int(3), до PHP 8.1.0 int(1)
    var_dump(Bar::counter()); // int(4), до PHP 8.1.0 int(2)

### Ссылки с глобальными (`global`) и статическими (`static`) переменными

PHP использует модификаторы переменных static и global как ссылки. Например, реальная глобальная переменная, которую внедрили в область видимости функции через ключевое слово `global`, в действительности создаёт ссылку на глобальную переменную. Это приводит к неожиданному поведению, как показывает следующий пример:

    <?php

    function test_global_ref()
    {
        global $obj;
        $new = new stdClass();
        $obj = &$new;
    }

    function test_global_noref()
    {
        global $obj;
        $new = new stdClass();
        $obj = $new;
    }

    test_global_ref();
    var_dump($obj);
    test_global_noref();
    var_dump($obj);

Результат выполнения приведённого примера:

    NULL
    object(stdClass)#1 (0) {
    }

Аналогично ведёт себя и инструкция `static`. Ссылки не хранятся статично:

    <?php

    function &get_instance_ref()
    {
        static $obj;

        echo 'Статический объект: ';
        var_dump($obj);

        if (!isset($obj)) {
            $new = new stdClass();

            // Присвоить ссылку статической переменной
            $obj = &$new;
        }

        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }

        return $obj;
    }

    function &get_instance_noref()
    {
        static $obj;

        echo 'Статический объект: ';

        var_dump($obj);

        if (!isset($obj)) {
            $new = new stdClass();

            // Присвоить объект статической переменной
            $obj = $new;
        }

        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }

        return $obj;
    }

    $obj1 = get_instance_ref();
    $still_obj1 = get_instance_ref();
    echo "\n";
    $obj2 = get_instance_noref();
    $still_obj2 = get_instance_noref();

Результат выполнения приведённого примера:

    Статический объект: NULL
    Статический объект: NULL

    Статический объект: NULL
    Статический объект: object(stdClass)#3 (1) {
      ["property"]=>
      int(1)
    }

Пример показывает, что при назначении ссылки статической переменной эта переменная не запоминается, при повторном вызове функции `&get_instance_ref()`.

## Переменные переменных

Иногда переменные имена переменных повышают удобство работы с кодом. Переменное имя переменной — имя переменной, которое устанавливается и изменяется динамически. Стандартную переменную устанавливают вот такой инструкцией:

    <?php
    $a = 'hello';
    var_dump($a);

Переменная переменной принимает значение переменной и обрабатывает значение как имя переменной. Значение hello из приведённого примера станет именем переменной при обращении к переменной, которая хранит значение, через двойной знак доллара. То есть:

    <?php
    $a = 'hello';
    $$a = 'world';
    var_dump($hello);

Теперь дерево символов PHP хранит два определения переменных: переменная $a, которая содержит значение "hello", и переменная $hello, которая содержит значение "world". Поэтому инструкция:

    <?php
    $a = 'hello';
    $$a = 'world';
    echo "{$a} {$$a}";

...выведет то же, что и инструкция

    <?php
    $a = 'hello';
    $$a = 'world';
    echo "{$a} {$hello}";

Обе инструкции создадут строку: hello world.

Для работы с переменными переменных и массивами потребуется разрешить неоднозначность. Анализатору синтаксиса требуется знать, что имел в виду разработчик в записи $$a[1]: использовать $a[1] как переменную или $$a, а затем индекс [1] этой переменной. Синтаксис, который разрешит эту неоднозначность, выглядит вот так: ${$a[1]} для первого случая и ${$a}[1] для второго.

Доступ к свойствам класса также получают через переменные имена свойств. Переменное имя свойства разрешается внутри области видимости, в которой вызывают свойство класса. Например, для выражения $foo->$bar PHP проверит присутствие в локальной области видимости переменной $bar, значение которой возьмёт как имя свойства объекта $foo. Это справедливо и тогда, когда через переменную $bar обращаются к элементу массива.

Фигурные скобки также указывают, чтобы точно отделить название свойства. Скобки наиболее полезны, когда получают доступ к значениям внутри свойства, которое содержит массив, когда имя свойства состоит из нескольких частей, либо когда имя свойства содержит символы, которые иначе не действительны (например, из функции json_decode() или из модуля SimpleXML).

Пример #1 Пример переменного имени свойства

    <?php

    class Foo
    {
        public $bar = 'Я bar.';
        public $arr = array('Я A.', 'Я B.', 'Я C.');
        public $r   = 'Я r.';
    }

    $foo = new Foo();
    $bar = 'bar';
    $baz = ['foo', 'bar', 'baz', 'quux'];
    echo $foo->$bar . "\n";
    echo $foo->{$baz[1]} . "\n";

    $start = 'b';
    $end   = 'ar';
    echo $foo->{$start . $end} . "\n";

    $arr = 'arr';
    echo $foo->{$arr[1]} . "\n";
    echo $foo->{$arr}[1] . "\n";

Результат выполнения приведённого примера:

    Я bar.
    Я bar.
    Я bar.
    Я r.
    Я B.

Внимание

Обратите внимание, переменные переменных нельзя использовать с суперглобальными массивами PHP. Переменная `$this` — тоже специальная переменная, на которую нельзя ссылаться динамически.

## Переменные из внешних источников

### HTML-формы. Методы GET и POST

PHP-скрипт автоматически получает доступ к данным формы после отправки формы скрипту. Данные формы получают несколькими способами, например:

Пример #1 Простая HTML-форма

    <form action="foo.php" method="post">
        Имя:  <input type="text" name="username" /><br />
        Email: <input type="text" name="email" /><br />
        <input type="submit" name="submit" value="Отправь меня!" />
    </form>

Доступ к данным HTML-формы получают только двумя способами. Следующие параграфы перечисляют эти способы:

Пример #2 Доступ к данным несложной HTML-формы, которую отправили методом POST

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];

GET-формы обрабатывают аналогично, за исключением того, что вместо суперглобальной переменной POST обрабатывают предопределённую суперглобальную переменную GET. Суперглобальная переменная GET также умеет работать с элементом `QUERY_STRING` (информация в URL-адресе после знака вопроса «?»). Так, например, адрес `http://www.example.com/test.php?id=3` содержит GET-данные, к которым получают доступ через $_GET['id']. О переменных HTTP-запроса рассказывает раздел $_REQUEST.

> Замечание:

> Точки и пробелы в именах переменных преобразовываются в знаки подчёркивания. Например, `<input name="a.b" />` станет `$_REQUEST["a_b"]`.

PHP также понимает массивы в контексте переменных формы (смотрите раздел PHP и HTML). Связанные переменные, например, группируют по имени или получают значения из полей ввода с множественным выбором. Отправим форму сами себе и отобразим данные:

Пример #3 Более сложные переменные формы

    <?php

    if ($_POST) {
        echo '<pre>';
        echo htmlspecialchars(print_r($_POST, true));
        echo '</pre>';
    }

    ?>
    <form action="" method="post">
        Имя:  <input type="text" name="personal[name]" /><br />
        Email: <input type="text" name="personal[email]" /><br />
        Пиво: <br />
        <select multiple name="beer[]">
            <option value="warthog">Warthog</option>
            <option value="guinness">Guinness</option>
            <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
        </select><br />
        <input type="submit" value="Отправь меня!" />
    </form>

> Замечание: PHP без предупреждения проигнорирует конечные символы, если имя внешней переменной начинается с корректного синтаксиса массива. Например, `<input name="foo[bar]baz">` станет `$_REQUEST['foo']['bar']`.

#### Имена переменных кнопки с картинкой для отправки формы

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

    <input type="image" src="image.gif" name="sub" />

Когда пользователь щёлкнет по изображению, браузер передаст форму на сервер с двумя дополнительными переменными — sub_x и sub_y. Эти переменные содержат координаты места, по которому пользователь нажал на изображении. Программисты с опытом, наверное, заметили, что имена переменных, которые отправил браузер, содержат точку, а не подчёркивание, но PHP автоматически преобразует точку в подчёркивание.

### HTTP Cookies

PHP прозрачно поддерживает блоки данных cookies по HTTP-протоколу в соответствии с требованиями стандарта » RFC 6265. Cookies — механизм хранения данных в удалённом браузере, по которым сервер отслеживает или идентифицирует пользователей, которые вернулись на сайт. Cookies устанавливают функцией setcookie(). Cookies — часть HTTP-заголовка, поэтому функцию SetCookie требуется вызывать перед отправкой вывода браузеру. Это же ограничение касается функции header(). Данные, которые хранят cookie, доступны в массивах данных cookie наподобие суперглобальных переменных $_COOKIE или $_REQUEST. Подробности и примеры даёт описание функции setcookie().

> Замечание: Начиная с PHP 7.2.34, 7.3.23 и 7.4.11 по соображениям безопасности имена входящих cookie больше не декодируются из URL-кодированной строки.

Когда одной переменной cookie требуется присвоить больше одного значения, значения присваивают как массив. Например:

    <?php
    setcookie("MyCookie[foo]", 'Testing 1', time() + 3600);
    setcookie("MyCookie[bar]", 'Testing 2', time() + 3600);

Такой вызов создаст два разных блока данных cookie, хотя в скрипте переменная MyCookie теперь будет одним массивом. Если требуется установить только один блок данных cookie с несколькими значениями, сначала обдумывают вызов для таких значений функции наподобие serialize() или explode().

Обратите внимание, что блок данных cookie заменит в браузере предыдущий блок данных cookie с тем же именем, если только путь или домен не отличаются. Так в приложении с корзиной покупок можно сохранить количество товаров:

Пример #4 Пример использования функции setcookie()

    <?php
    if (isset($_COOKIE['count'])) {
        $count = $_COOKIE['count'] + 1;
    } else {
        $count = 1;
    }
    setcookie('count', $count, time() + 3600);
    setcookie("Cart[$count]", $item, time() + 3600);

### Точки в именах входящих переменных

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

    <?php
    $varname.ext;  /* Неправильное имя переменной */

В приведённом примере интерпретатор видит переменную $varname, после которой идёт оператор конкатенации, а затем голая строка (то есть строка, которую не заключили в кавычки, и которая не соответствует ни одному из ключевых или зарезервированных слов) «ext». Очевидно, что это не даст ожидаемого результата.

Поэтому важно отметить, что PHP будет автоматически заменять точки в именах входящих переменных на символы подчёркивания.

### Определение типов переменных

Поскольку PHP определяет типы переменных и преобразовывает типы (как правило) по мере необходимости, не всегда очевидно, какому типу принадлежит переменная в каждый момент времени. PHP содержит несколько функций, которые умеют определять тип переменной, например: gettype(), is_array(), is_float(), is_int(), is_object() и is_string(). Подробнее о типах данных, которые поддерживает PHP, рассказывает раздел «Типы».

HTTP — текстовый протокол, и большая, если не вся, часть содержимого, которое попадает в суперглобальные массивы наподобие $_POST и $_GET, останется в виде строк. PHP не будет преобразовывать значения в конкретный тип. В приведённом примере элемент $_GET["var1"] будет содержать строку «null», а элемент $_GET["var2"] — строку «123».

    /index.php?var1=null&var2=123

### Список изменений

Версия | Описание
--- | ---
7.2.34, 7.3.23, 7.4.11 | По соображениям безопасности имена входящих cookie больше не декодируются из URL-кодированной строки.

# Константы

## Содержание

- Синтаксис
- Предопределённые константы
- Магические константы

Константа — идентификатор, или имя, для простого значения. Как подсказывает название, это значение нельзя изменять во время работы скрипта (кроме магических констант, которые на самом деле не относятся к константам). Константы чувствительны к регистру. По принятому соглашению, названия констант записывают в верхнем регистре.

> Замечание:

> До PHP 8.0.0 константам, которые определяли функцией define(), разрешалось быть нечувствительными к регистру.

Названия констант подчиняются тем же правилам именования, которым следуют другие PHP-идентификаторы. Правильное название начинается с буквы или символа подчёркивания, за которым следует любое количество букв, цифр и символов подчёркивания. Регулярное выражение для проверки корректности имени константы выглядит так: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

Функция define() умеет определять константы с названиями, которые совпадают с зарезервированными словами или даже нарушают правила языка по именованию идентификаторов, при этом значение таких констант вернёт только функция constant(), но делать так не рекомендуют.

Подсказка

Смотрите также «Руководство по именованию».

Пример #1 Правильные и неправильные названия констант

    <?php

    // Правильные названия констант
    define("FOO",     "что-то");
    define("FOO2",    "что-то ещё");
    define("FOO_BAR", "что-то большее");

    // Неправильные названия констант
    define("2FOO",    "что-то");

    // Это допустимое объявление, но константы лучше так не называть:
    // константа нарушит работу скрипта, если в PHP зарегистрируют магическую константу
    // с таким названием
    define("__FOO__", "что-то");

> Замечание: Понятие «буквы» здесь — символы a-z, A-Z, и другие символы с ASCII-кодами от 128 до 255 (0x80-0xff).

Как и superglobals, константы доступны из любой области видимости. Константы разрешается использовать из любого места скрипта независимо от области видимости. Дополнительную информация об области видимости даёт раздел руководства «Область видимости переменной».

> Замечание: Начиная с PHP 7.1.0 константам класса доступны объявления видимости — защищённая или закрытая, которые делают константу доступной только в иерархической области видимости класса, в котором константа определена.

## Синтаксис

Константу определяют через ключевое слово `const` или функцией define(). Функция define() разрешает определить константу для произвольного выражения, тогда как конструкция `const` содержит ряд ограничений, которые описывает следующий параграф. После определения константу нельзя изменить или сделать неопределённой.

При определении константы через ключевое слово `const` допускаются только скалярные выражения с типами bool, int, float и string и массивы (array), которые содержат только скалярные выражения. Для константы возможно определить значение с типом resource, но из-за непредсказуемого поведения так делать не рекомендуют.

Значение константы получают по названию константы. Символ `$` перед названиями констант, как перед названиями переменных, не указывают. Значение константы также получают функцией constant(), если название константы формируется динамически. Список всех определённых констант получают функцией get_defined_constants().

> Замечание: Константы и переменные, в том числе глобальные, принадлежат разным пространствам имён. Поэтому, например, логическая константа `true` и переменная $TRUE — не одно и то же.

При попытке обратиться к неопределённой константе выбрасывается ошибка Error. До PHP 8.0.0 неопределённые константы интерпретировались как простое строковое (string) слово, поэтому идентификатор CONSTANT сравнивался со строкой "CONSTANT". Этот резервный вариант устарел в PHP 7.2.0, при этом генерируется ошибка уровня `E_WARNING`. До PHP 7.2.0 вместо этого выдавалась ошибка уровня E_NOTICE. Смотрите также главу руководства, которая разъясняет, почему $foo[bar] — это неправильно, если только `bar` не константа. Это не относится к полным и абсолютным константам, которые каждый раз будут выбрасывать ошибку Error, если эти константы не определили.

> Замечание: Установку константы проверяют функцией defined().

Отличия констант от переменных:

- Перед константами не указывают знак доллара `$`;
- Константы определяют и получают к ним доступ в произвольном месте кода. Определение и доступность констант не зависит от правил определения области видимости переменных;
- Константы нельзя переопределять или удалять после первоначального объявления;
- Константы содержат только скалярные значения или массивы.

Пример #1 Определение констант

    <?php

    define("CONSTANT", "Здравствуй, мир.");
    echo CONSTANT; // Выводит "Здравствуй, мир."
    echo Constant; // Выбросит ошибку: Неопределённая константа Constant
                   // До PHP 8.0.0 выводит "Constant" и выдаёт предупреждение

Пример #2 Определение констант через ключевое слово `const`

    <?php

    // Простое скалярное значение
    const CONSTANT = 'Здравствуй, мир.';

    echo CONSTANT . "\n";

    // Скалярное выражение
    const ANOTHER_CONST = CONSTANT . ' Прощай, мир.';
    echo ANOTHER_CONST . "\n";

    const ANIMALS = array('dog', 'cat', 'bird');
    echo ANIMALS[1] . "\n"; // Выводит "cat"

    // Массивы в константе
    define('ANIMALS_DEF', array(
        'dog',
        'cat',
        'bird'
    ));
    echo ANIMALS_DEF[1] . "\n"; // Выводит "cat"

> Замечание:

> В отличие от определения констант функцией define(), константы, которые объявили через ключевое слово `const`, требуется объявлять в самой верхней области видимости, потому что константы определяются при компилировании скрипта. Поэтому константы нельзя объявлять внутри функций, циклов, инструкций `if`, или блоков `try` и `catch`.

### Смотрите также

- Константы классов

## Предопределённые константы

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

## Магические константы

PHP включает ряд магических констант, значение которых изменяется в зависимости от контекста. Значение константы `__LINE__`, например, зависит от строки скрипта, на которой указали константу. PHP разрешает «магические» константы во время компиляции, в отличие от стандартных констант, которые PHP разрешает во время выполнения. Специальные константы нечувствительны к регистру, а список таких констант приводит следующий параграф:

Магические константы PHP
Имя | Описание
--- | ---
`__LINE__` | Текущий номер строки файла.
`__FILE__` | Полный путь и имя текущего файла с разрешёнными символическими ссылками. PHP возвращает имя подключённого файла, если константу указали внутри него.
`__DIR__` | Каталог файла. PHP возвращает каталог подключённого файла, если константу указали внутри подключаемого файла. Значение константы эквивалентно вызову `dirname(__FILE__)`. Имя каталога возвращается без слеша в конце, если только это не корневой каталог.
`__FUNCTION__` | Название функции или `{closure}` для анонимной функции.
`__CLASS__` | Название класса. Название класса включает пространство имён, в котором объявили класс, например `Foo\Bar`. Внутри методов трейтов значение константы __CLASS__ равно названию класса, в котором вызывают метод трейта.
`__TRAIT__` | Имя трейта. Имя трейта включает пространство имён, в котором объявили трейт, например: `Foo\Bar`.
`__METHOD__` | Имя метода класса.
`__PROPERTY__` | Название свойства. Константа действует только внутри хука свойства.
`__NAMESPACE__` | Имя текущего пространства имён.
`ClassName::class` | Абсолютное имя класса.

### Смотрите также

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# Выражения

Выражения — самые важные строительные элементы PHP. Почти всё, что разработчик пишет в PHP, — выражение. Самое простое и точное определение выражения — «всё, что вычисляется как значение».

Главные формы выражений — константы и переменные. В записи `$a = 5` значение `5` присвоится переменной $a. Значение `5`, очевидно, содержит значение 5 или, говоря по-другому, `5` — выражение со значением 5; в этом случае `5` — целочисленная константа.

После этого присваивания ожидается, что значение переменной $a тоже равно 5, поэтому, когда записывают `$b = $a`, ожидают, что это сработает так же, как если бы написали `$b = 5`. Говоря по-другому, переменная $a — тоже выражение со значением 5. Всё так и произойдёт, если всё работает правильно.

Немного более сложные примеры выражений — функции. Например, рассмотрим следующую функцию:

    <?php

    function foo ()
    {
        return 5;
    }
    ?>

Разработчик, который познакомился с концепцией функций в главе «О функциях», мог бы предположить, что присваивание `$c = foo()` по смыслу аналогично присваиванию `$c = 5`, и оказался бы прав. Функция — выражение, значение которого равно тому, что возвращает функция. Значение выражения `foo()` равно 5, поскольку функция `foo()` возвращает 5. Часто функции не просто возвращают статическое значение, а что-то вычисляют.

Конечно, значения в PHP не обязаны быть целочисленными, и часто это не так. Язык PHP поддерживает четыре типа скалярных значений: целочисленные int, значения с плавающей точкой float, строковые string и логические bool. Скалярными называются значения, которые нельзя «разбить» на меньшие части, в отличие, например, от массивов. Ещё PHP поддерживает два сложных (составных, композитных — нескалярных) типа: массивы и объекты. Каждый из этих типов значений возможно присвоить переменной или вернуть из функции.

Однако PHP использует выражения значительно шире, точно так же, как это делают другие языки. PHP — язык с ориентацией на выражения, который почти всё в коде рассматривает как выражение. Вернёмся к тому примеру, с которым уже имели дело: `$a = 5`. Легко заметить, что здесь содержится два значения — значение целочисленной константы `5` и значение переменной $a, которая также принимает значение 5. Но, хотя это неочевидно, здесь содержится ещё одно значение — значение самого присваивания. Само присваивание вычисляется в значение, которое присваивется переменной, в приведённом примере — в значение 5. Поэтому выражение `$a = 5` независимо от того, что оно делает, — это выражение со значением 5. Поэтому запись `$b = ($a = 5)` равносильна записи `$a = 5; $b = 5;` (точка с запятой означает конец инструкции). Разработчику также доступна запись `$b = $a = 5`, поскольку операции присваивания анализируются справа налево.

Другой хороший пример ориентированности на выражения — префиксный и постфиксный инкремент и декремент. Пользователи PHP и других языков, возможно, уже знакомы с формой записи `variable++` и `variable--`. Это операторы инкремента и декремента. Как и язык Си, язык PHP поддерживает два типа инкремента — префиксный и постфиксный. Они оба инкрементируют значение переменной и эффект их действия на неё одинаков. Разница состоит в значении выражения инкремента. Префиксный инкремент, записываемый как `++$variable`, вычисляется в инкрементированное значение (PHP инкрементирует переменную до того как прочесть её значение, отсюда название «преинкремент»). Постфиксный инкремент, записываемый как `$variable++`, вычисляется в первоначальное значение переменной $variable до её приращения (PHP вначале читает значение переменной и только потом инкрементирует её, отсюда название «постинкремент»).

Распространённые типы выражений — выражения сравнения. Эти выражения вычисляются либо как `false` (ложь), либо как `true` (истина). PHP поддерживает операции сравнения > (больше), >= (больше либо равно), == (равно), != (не равно), < (меньше) и <= (меньше либо равно). Он также поддерживает операторы строгого равенства: === (равно и одного типа) и !== (не равно или не одного типа). Обычно этими выражениями пользуются в операторах условного выполнения, например, инструкции `if`.

Последний пример выражений, который здесь рассматривается, это смешанные выражения операции и присваивания. Уже известно, что когда требуется увеличить значение переменной $a на 1, записывают `$a++` или `++$a`. Но что, если потребуется прибавить больше единицы, например 3? Можно было бы написать `$a++` много раз, однако, очевидно, это нерационально и неудобно. Наиболее распространённая практика — запись вида `$a = $a + 3`. Выражение `$a + 3` вычисляется в значение переменной $a, к которому прибавляется 3 и снова присваивается значение переменной $a, увеличивая в результате значение переменной $a на 3. В PHP, как и в ряде других языков, например Си, это же присваивание записывается короче, что увеличит очевидность смысла и скорость понимания кода по прошествии времени. Тройку к текущему значению переменной $a прибавляют так: `$a += 3`. Это означает дословно «взять значение переменной $a, прибавить к нему значение 3 и снова присвоить результат сложения переменной $a». Кроме большей понятности и краткости, это быстрее работает. Значением выражения `$a += 3`, как и стандартного присваивания, станет значение, которое присвоилось переменной. Обратите внимание, что это НЕ 3, а суммированное значение переменной $a плюс 3 (то, что присвоилось перменной $a). Поэтому разрешается использовать любой бинарный оператор, например, `$a -= 5` (вычесть 5 из значения переменной $a), `$b *= 7` (умножить значение переменной $b на 7) и т. д.

Ещё одно выражение, которое выглядит необычно, если читатель не встречал такое выражение в других языках, — тернарный условный оператор:

    <?php

    $first ? $second : $third

    ?>

Если значение первого подвыражения — `true` (ненулевое значение), то выполняется второе подвыражение, которое и будет результатом условного выражения. Или выполняется третье подвыражение и его значение будет результатом.

Задача следующего примера — помочь немного улучшить понимание префиксного и постфиксного инкремента и выражений:

    <?php

    function double($i)
    {
        return $i * 2;
    }

    $b = $a = 5;        /* Присвоить значение пять переменным $a и $b */
    $c = $a++;          /* Постфиксный инкремент, присвоить значение переменной
                           $a (5) — переменной $c */
    print "a = {$a}; b = {$b}; c = {$c}" . PHP_EOL;

    $e = $d = ++$b;     /* Префиксный инкремент, присвоить увеличенное
                           значение переменной $b (6) — переменным $d и $e */
    print "b = {$b}; d = {$d}; e = {$e}" . PHP_EOL;

    /* в этой точке и переменная $d, и переменная $e равны 6 */

    $f = double($d++);  /* Присвоить удвоенное значение перменной $d перед
                           инкрементом (2 * 6 = 12) — переменной $f */
    print "d = {$d}; f = {$f}" . PHP_EOL;

    $g = double(++$e);  /* Присвоить удвоенное значение перменной $e после
                           инкремента (2 * 7 = 14) — переменной $g */
    print "e = {$e}; g = {$g}" . PHP_EOL;

    $h = $g += 10;      /* Сначала переменная $g увеличивается на 10,
                           приобретая, в итоге, значение 24. Затем значение
                           присваивания (24) присваивается переменной $h,
                           которая в итоге также становится равной 24. */
    print "g = {$g}; h = {$h}" . PHP_EOL;
    ?>

Иногда PHP рассматривает выражения как инструкции. В этом случае у инструкции следующий вид — «`expr ;`», то есть выражение, за которым следует точка с запятой. В записи `$b = $a = 5;`, часть `$a = 5` — допустимое выражение, но оно само — не инструкция. Тогда как запись `$b = $a = 5;` — допустимая инструкция.

Последнее, что вспомним, — истинность значения выражений. Обычно в условных операторах и циклах может интересовать не конкретное значение выражения, а только его истинность (значение `true` или `false`). Регистронезависимые константы `true` и `false` — два возможных логических значения. Выражения автоматически преобразовываются в логические значения, когда требуется. Подробнее о преобразовании типов рассказывает раздел Приведение типов.

Язык PHP со всей полнотой и мощностью реализует выражения, а полное документирование выражений выходит за рамки руководства. Приведённые примеры дают представление о выражениях, о том, что они из себя представляют, и как создавать полезные выражения. В остальной части руководства допустимые PHP-выражения обозначают сокращением expr.

# Операторы

## Содержание

- Приоритет
- Арифметика
- Инкремент и декремент
- Присваивание
- Побитовые операторы
- Сравнение
- Управление ошибками
- Выполнение
- Логика
- Строки
- Массивы
- Проверка типа
- Функциональность

Оператором называется то, что принимает одно или больше значений (или выражений, если говорить на жаргоне программирования), и вычисляет новое значение; поэтому всю конструкцию рассматривают как выражение.

Операторы группируются по количеству принимаемых значений. Унарные операторы принимают только одно значение, например `!` — (оператор логического отрицания — или `++` — инкремент. Бинарные операторы принимают два значения; это, например, знакомые каждому арифметические операторы `+` (плюс) и `-` (минус), бо́льшая часть поддерживаемых в PHP операторов входит в эту категорию. И на последок, в языке предусмотрели только один тернарный оператор, `? :`, который принимает три значения, и его часто называют просто — «тернарный оператор»; хотя, возможно, точнее было бы назвать его «условный оператор».

Полный список PHP-операторов перечисляет раздел «Приоритет оператора». Раздел также описывает порядок выполнения и ассоциативность операторов. Порядок и ассоциативность точно определяют, как вычисляются выражения с несколькими разными операторами.

## Приоритет оператора

Приоритет оператора определяет, насколько «тесно» он связывает между собой два выражения. Например, выражение `1 + 5 * 3` вычисляется как `16`, а не `18`, поскольку у оператора умножения «*» более высокий приоритет, чем у оператора сложения «+». Порядок выполнения операторов изменяют круглыми скобками, поэтому выражение `(1 + 5) * 3` вычисляется как `18`.

Выполнятся ли операторы с равным приоритетом слева направо или справа налево, определяет ассоциативность. Например, оператор «-» относится к левоассоциативным, поэтому выражение `1 - 2 - 3` сгруппируется как `(1 - 2) - 3` и пересчитается в `-4`. При этом оператор «=» относится к правоассоциативным, потому выражение `$a = $b = $c` сгруппируется как `$a = ($b = $c)`.

Неассоциативные операторы с одинаковым приоритетом нельзя указывать совместно. Например, выражение `1 < 2 > 1` не сработает в PHP. При этом выражение `1 <= 1 == 1` сработает, поскольку у оператора `==` более низкий приоритет, чем у оператора `<=`.

Ассоциативность касается только двоичных и тернарных операторов. Унарные операторы бывают префиксными или постфиксными, поэтому понятие ассоциативности к ним не относится. Например, `!!$a` получится сгруппировать только как `!(!$a)`.

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

Следующая таблица приводит список операторов, отсортированный по убыванию приоритетов. У операторов, которые перечислили в одной строке, одинаковый приоритет, а порядок выполнения этих операторов определяется группировкой.

Порядок выполнения операторов
Ассоциативность | Оператор | Дополнительная информация
--- | --- | ---
(неассоциативен) | `clone` `new` | clone и new
правая | `**` | арифметические операторы
(неассоциативен) | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | арифметические операторы (унарные `+` и `-`), инкремент/декремент, побитовые операторы, приведение типов и оператор управления ошибками
левая | instanceof | типы
(неассоциативен) | ! | логические операторы
левая | `*` `/` `%` | арифметические операторы
левая | `+` `-` `.` | арифметические операторы (бинарные `+` и `-`), операторы, работающие с массивами и строковые операторы (`.` до PHP 8.0.0)
левая | `<<` `>>` | побитовые операторы
левая | `.` | строковые операторы (начиная с PHP 8.0.0)
левая | `|>` | оператор конвейеризации
(неассоциативен) | `<` `<=` `>` `>=` | операторы сравнения
(неассоциативен) | `==` `!=` `===` `!==` `<>` `<=>` | операторы сравнения
левая | `&` | побитовые операторы и ссылки
левая | `^` | побитовые операторы
левая | `|` | побитовые операторы
левая | `&&` | логические операторы
левая | `||` | логические операторы
правая | `??` | операторы сравнения с null
(неассоциативен) | `? :` | тернарный оператор (левоассоциативный до PHP 8.0.0)
правая | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | операторы присваивания
(неассоциативен) | `yield from` | yield from
(неассоциативен) | `yield` | yield
(неассоциативен) | `print` | print
левая | `and` | логические операторы
левая | `xor` | логические операторы
левая | `or` | логические операторы
(неассоциативен) | `throw` | throw

> Замечание: Унарные операторы, которые находятся в одной строке с операторами приведения типа (`~`, `@` и унарные `+`/`-`), имеют более высокий приоритет, чем `instanceof`, тогда как у оператора `!` приоритет ниже. Поэтому выражение `(int) $x instanceof Foo` группируется как `((int) $x) instanceof Foo`, а выражение `!$x instanceof Foo` группируется как `!($x instanceof Foo)`.

Пример #1 Ассоциативность

    <?php

    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);

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

Пример #2 Явный приоритет

    <?php

    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // Начиная с PHP 8 такие выражения запретили
    // $a = true ? 0 : true ? 1 : 2;

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

Пример #3 Неопределённый порядок вычисления

    <?php

    $a = 1;
    echo $a + $a++; // В зависимости от версии выводит 2 или 3

    $i = 1;
    $array[$i] = $i++; // В зависимости от версии устанавливает индекс 1 или 2

Пример #4 Приоритет операторов `+`, `-` и `.`

    <?php

    $x = 4;
    // Следующий код иногда выдаёт неожиданный результат:
    echo "x минус 1 равно " . $x - 1 . ", ну, я надеюсь\n";

    // Круглые скобки помогают указать явный приоритет:
    echo "x minus one equals " . ($x - 1) . ", ну, я надеюсь\n";

    // Так нельзя, код выбросит ошибку TypeError:
    echo (("x минус 1 равно " . $x) - 1) . ", ну, я надеюсь\n";

Результат выполнения приведённого примера:

    -1, ну, я надеюсь
    -1, ну, я надеюсь
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

Пример #5 До PHP 8 приоритет операторов `+`, `-` и `.` был одинаковым

    <?php

    $x = 4;
    // Следующий код иногда выдаёт неожиданный результат:
    echo "x минус 1 равно " . $x - 1 . ", ну, я надеюсь\n";

    // Поскольку до PHP 8.0.0 код вычислялся вот так:
    echo (("x минус один равно " . $x) - 1) . ", ну, я надеюсь\n";

    // Явный приоритет определяют круглыми скобками:
    echo "x минус 1 равно " . ($x - 1) . ", ну, я надеюсь\n";

Результат выполнения приведённого примера:

    -1, ну, я надеюсь
    -1, ну, я надеюсь
    x минус 1 равно 3, ну, я надеюсь

> Замечание:

> Хотя у оператора `=` более низкий приоритет, чем у большей части других операторов, PHP всё же разрешает писать так: `if (!$a = foo())`, в этом примере результат выполнения функции `foo()` присвоится переменной $a.

> Это возможно потому, что левая часть присваивания обязана быть переменной, поэтому присваивание группируется с этой переменной, а не с окружающим префиксным оператором, у которого приоритет выше. То же касается других префиксных операторов, которые принимают выражение в качестве операнда, таких как `clone`, операторы приведения типа, `@` и `~`: например, `clone $a = $b` группируется как `clone ($a = $b)`, а не как `(clone $a) = $b`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | У объединения строк оператором `.` теперь более низкий приоритет, чем у арифметических операторов сложения `+` и вычитания `-`, и побитового сдвига влево `<<` и вправо `>>`; раньше у оператора конкатенации строк был тот же приоритет, что и у операторов `+` и `-`, и более высокий приоритет, чем у операторов `<<` и `>>`.
8.0.0 | Тернарный оператор `? :` стал неассоциативным; раньше оператор относился к левоассоциативным.
7.4.0 | В выражениях с совместным указанием операторов теперь не рекомендуют полагаться на приоритет конкатенации строк оператором `.` при арифметических операциях сложения `+` или вычитания `-` и побитовом сдвиге влево `<<` или вправо `>>`).
7.4.0 | В выражениях с бесскобочным вложением ряда тернарных операторов теперь не рекомендуют полагаться на левоассоциативность тернарного оператора `? :`.

## Арифметические операторы

Помните школьные основы арифметики? Арифметические операторы в PHP работают аналогично.

Арифметические операторы
Пример | Название | Результат
--- | --- | ---
`+$a` | Идентичность | Приведение значения $a к типу int или float, если требуется.
`-$a` | Отрицание | Изменение знака числа $a.
`$a + $b` | Сложение | Сумма чисел $a и $b.
`$a - $b` | Вычитание | Разность чисел $a и $b.
`$a * $b` | Умножение | Произведение чисел $a и $b.
`$a / $b` | Деление | Частное от деления чисел $a и $b.
`$a % $b` | Взятие остатка | Остаток от деления чисел $a и $b.
`$a ** $b` | Возведение в степень | Степень с основанием $a и показателем $b.

Оператор деления `/` возвращает значение с типом float, если только оба операнда не значения с типом int или числовые строки, которые приводятся к типу int, и числитель не кратен знаменателю, при которых возвращается целочисленное значение. Для целочисленного деления вызывают функцию intdiv().

При взятии остатка операнды приводятся к типу int перед обработкой. Для нахождения остатка от деления чисел с плавающей точкой вызывают функцию fmod().

При взятии остатка оператором `%` результат наследует знак делимого, поэтому результатом вычисления выражения `$a % $b` становится значение со знаком операнда $a. Например:

Пример #1 Оператор взятия остатка

    <?php

    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);

Результат выполнения приведённого примера:

    int(2)
    int(2)
    int(-2)
    int(-2)

### Смотрите также

- Математические функции

## Операторы инкремента и декремента

PHP поддерживает префиксные и постфиксные операторы инкремента и декремента. Эти унарные операторы разрешают увеличивать или уменьшать значение на единицу.

Операторы инкремента и декремента
Пример | Название | Действие
--- | --- | ---
++$a | Префиксный инкремент | Увеличивает $a на единицу, затем возвращает значение $a.
$a++ | Постфиксный инкремент | Возвращает значение $a, затем увеличивает $a на единицу.
--$a | Префиксный декремент | Уменьшает $a на единицу, затем возвращает значение $a.
$a-- | Постфиксный декремент | Возвращает значение $a, затем уменьшает $a на единицу.

Пример #1 Примеры инкремента и декремента

    <?php

    echo 'Постфиксный инкремент:', PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);

    echo 'Префиксный инкремент:', PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);

    echo 'Постфиксный декремент:', PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);

    echo 'Префиксный декремент:', PHP_EOL;
    $a = 5;
    var_dump(--$a);
    var_dump($a);

Результат выполнения приведённого примера:

    Постфиксный инкремент:
    int(5)
    int(6)
    Префиксный инкремент:
    int(6)
    int(6)
    Постфиксный декремент:
    int(5)
    int(4)
    Префиксный декремент:
    int(4)
    int(4)

Внимание

Операторы инкремента и декремента не влияют на логические значения (bool). Начиная с PHP 8.3.0 вызывается ошибка уровня `E_WARNING`, потому что в будущем это будет неявно приведено к значению целого числа (int).

Оператор декремента не влияет на значения null. Начиная с PHP 8.3.0 вызывается ошибка уровня `E_WARNING`, потому что в будущем это будет неявно приведено к значению целого числа (int).

Оператор декремента не влияет на не- числовые строки. Начиная с PHP 8.3.0 вызывается ошибка уровня `E_WARNING`, потому в будущем будет выбрасываться исключение TypeError.

> Замечание:

> Внутренние объекты, которые поддерживают перегрузку сложения и/или вычитания, могут также быть инкрементированы и/или декрементированы. Один такой внутренний объект — это GMP.

### Функция увеличения строки PERL

Внимание

Начиная с PHP 8.3.0 эта функция мягко устарела. Вместо этого вызывают функцию str_increment().

В PHP можно инкрементировать не- числовую строку. Строка должна быть буквенно-цифровой последовательностью в кодировке ASCII. Буквы увеличиваются до следующей буквы, при достижении буквы `Z` инкремент переносится в следующий разряд слева. Например, выражение `$a = 'Z'; $a++;` превратит значение переменной $a в значение `«AA»`.

Пример #2 Пример увеличения строки PERL

    <?php

    echo '== Буквенные строки ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // Буквенно-цифровые строки ведут себя иначе
    echo '== Буквенно-цифровые строки ==' . PHP_EOL;
    $d = 'A8';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    $d = 'A08';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }

Результат выполнения приведённого примера:

    == Буквенные строки ==
    X
    Y
    Z
    AA
    AB
    AC
    == Буквенно-цифровые строки ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

Внимание

Если буквенно-цифровая строка может быть интерпретирована как числовая строка, она будет приведена к типу int или float. Эта проблема встаёт особенно остро со строками, которые выглядят как числа с плавающей точкой, записанные в научной нотации. Функция str_increment() не страдает от эти неявных приведений типов.

Пример #3 Буквенно-цифровая строка, преобразованная в число с плавающей точкой

    <?php

    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);

Результат выполнения приведённого примера:

    string(3) "5e0"
    float(6)

Так происходит потому, что значение `«5e0»` было интерпретировано как число с плавающей точкой (float) и приведено к значению `5.0` перед началом увеличения.

## Операторы присваивания

Базовый оператор присваивания обозначается символом «=». Кажется, что это оператор «равно». Это не так. Оператор присваивания означает, что левый операнд получает значение правого выражения (то есть левому операнду «будет присвоено значение»).

Результатом выполнения оператора присваивания будет само присвоенное значение. То есть, результат выполнения выражения «`$a = 3`» будет равен 3. Это разрешает делать трюки наподобие:

Пример #1 Вложенное присваивание

    <?php

    $a = ($b = 4) + 5; // Значение переменной $a равно 9, а переменной $b присвоилось значение 4
    var_dump($a);

    ?>

В дополнение к базовому оператору присваивания существуют «комбинированные операторы» для всех бинарных арифметических операций, операций объединения массивов и строковых операций, которые дают присвоить значение в выражении, а затем установить его значение в результат этого выражения. Например:

Пример #2 Составное присваивание

    <?php

    $a = 3;
    $a += 5; // Устанавливает для переменной $a значение 8, как если бы написали: $a = $a + 5;
    $b = "Привет";
    $b .= "-привет!"; // Устанавливает переменной $b значение "Привет-привет!", как и присваивание $b = $b . "-привет!";

    var_dump($a, $b);

    ?>

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

Исключение из обычного для PHP способа присваивания по значению — объекты (object), которые присваиваются по ссылке. Принудительно скопировать объекты по значению можно через ключевое слово clone.

### Присваивание по ссылке

Присваивание по ссылке тоже поддерживается, для этого можно использовать синтаксис $var = &$othervar;. Присваивание по ссылке означает, что обе переменные указывают на одни и те же данные и ничего никуда не копируется.

Пример #3 Assigning by reference

    <?php

    $a = 3;
    $b = &$a; // $b — это ссылка на переменную $a

    print "$a\n"; // печатает 3
    print "$b\n"; // печатает 3

    $a = 4; // меняем переменную $a

    print "$a\n"; // печатает 4
    print "$b\n"; // также печатает 4, так как переменная $b — это ссылка на переменную $a,
                  // а значение переменной $a успело измениться

    ?>

Оператор new автоматически возвращает ссылку, поэтому присваивание результата операции new по ссылке вызывает ошибку.

Пример #4 Оператор new по ссылке

    <?php

    class C {}

    $o = &new C();

    ?>

Результат выполнения приведённого примера:

    Parse error: syntax error, unexpected token ";", expecting "("

Подробнее о ссылках рассказывает раздел «Объяснение ссылок».

### Операторы арифметического присваивания

Пример | Эквивалент | Операция
--- | --- | ---
$a += $b | $a = $a + $b | Сложение
$a -= $b | $a = $a - $b | Вычитание
$a *= $b | $a = $a * $b | Умножение
$a /= $b | $a = $a / $b | Деление
$a %= $b | $a = $a % $b | Модуль
$a **= $b | $a = $a ** $b | Возведение в степень

### Операторы побитового присваивания

Пример | Эквивалент | Операция
--- | --- | ---
$a &= $b | $a = $a & $b | Побитовое И
$a |= $b | $a = $a | $b | Побитовое ИЛИ
$a ^= $b | $a = $a ^ $b | Побитовое исключающее ИЛИ (Xor)
$a <<= $b | $a = $a << $b | Побитовый сдвиг влево
$a >>= $b | $a = $a >> $b | Побитовый сдвиг вправо

### Другие операторы присваивания

Пример | Эквивалент | Операция
--- | --- | ---
$a .= $b | $a = $a . $b | Конкатенация строк
$a ??= $b | $a = $a ?? $b | Объединение с Null

### Смотрите также

- Арифметические операторы
- Побитовые операторы
- Операторы объединения с null

## Побитовые операторы

Побитовые операторы вычисляют и управляют конкретными битами внутри целого числа.

Побитовые операторы
Пример | Название | Результат
--- | --- | ---
`$a & $b` | И | Устанавливаются биты, установленные и в значении $a, и в значении $b.
`$a | $b` | ИЛИ | Устанавливаются биты, установленные или в значении $a, или в значении $b.
`$a ^ $b` | Исключающее ИЛИ | Устанавливаются биты, установленные либо только в значении $a, либо только в значении $b, но не в обоих одновременно.
`~ $a` | Отрицание | Биты инвертируются: в значении $a неустановленные биты устанавливаются, а установленные — сбрасываются.
`$a << $b` | Сдвиг влево | Биты значения $a сдвигаются влево на $b разрядов; каждый шаг эквивалентен умножению на 2.
`$a >> $b` | Сдвиг вправо | Биты значения $a сдвигаются вправо на $b разрядов; каждый шаг эквивалентен делению на 2.

Побитовый сдвиг в PHP — арифметическая операция. Биты, которые сдвинулись за границы числа, отбрасываются. Сдвиг влево дополняет число нулями справа, при этом знаковый бит числа сдвигается влево, поэтому знак операнда не сохраняется. Сдвиг вправо сохраняет копию сдвинутого знакового бита слева, поэтому знак операнда сохраняется.

Приоритет операторов изменяют скобками. Например, выражение `$a & $b == true` сначала проверяет на равенство, а потом выполняет побитовое «И»; тогда как выражение `($a & $b) == true` сначала выполняет побитовое «И», а потом выполняет проверку на равенство.

Операция выполняется с ASCII-кодом каждого символа строки и возвращает строку, если оба операнда операторов `&`, `|` и `^` — строки. В остальных случаях оба операнда преобразуются к целому числу и возвращается целое число.

Операция выполняется с ASCII-кодом каждого символа строки и возвращает строку, если операнд оператора `~` — строка, иначе операнд и результат обрабатываются как целые числа.

Операнды и результат выполнения операторов `<<` и `>>` обрабатываются как целые числа.

В PHP ini-настройка error_reporting принимает побитовые значения, показывая практический пример сброса битов. Инструкции в файле php.ini сообщают: комбинация `E_ALL & ~E_NOTICE` включит отчёт обо всех ошибках, кроме уведомлений:

         Начинаем со значения E_ALL:
         00000000000000000111011111111111
         Затем берём значение E_NOTICE...
         00000000000000000000000000001000
         ... и инвертируем его оператором ~:
         11111111111111111111111111110111
         Наконец, указываем побитовое И (&), чтобы найти биты,
         которые установили в обоих значениях:
         00000000000000000111011111110111

Другой способ достичь этого — указать «исключающее ИЛИ» (XOR, `^`), чтобы найти только те биты, которые установили либо только в одном, либо только в другом значении: `E_ALL ^ E_NOTICE`

На примере директивы error_reporting получится показать и то, как устанавливают биты. Вот способ показа только неустранимых и исправимых ошибок: `E_ERROR | E_RECOVERABLE_ERROR`

         Здесь процесс сочетает значение константы E_ERROR —
         00000000000000000000000000000001 —
         со значением
         00000000000000000001000000000000
         через оператор ИЛИ (|),
         чтобы установить биты в заданных позициях:
         00000000000000000001000000000001

Пример #1 Пример побитовых операции И, ИЛИ и исключающее ИЛИ (AND, OR и XOR) над целыми числами

    <?php

    /*
     * Не обращайте внимания на верхний раздел кода,
     * это просто форматирование для более ясного вывода
     */
    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
        . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ----------  ----------- -- ----------
     Результат   Значение    Тестовая операция
     ----------  ----------- -- ----------
    EOH;

    /*
     * Вот сами примеры
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n Побитовое И (AND) \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n Побитовое (включающее) ИЛИ (OR) \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n Побитовое исключающее ИЛИ (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }

    ?>

Результат выполнения приведённого примера:

     ---------     ---------  -- ---------
     Результат     Значение   Тестовая операция
     ---------     ---------  -- ---------
     Побитовое И
    ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
    ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
    ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
    ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
    ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

     Побитовое ИЛИ
    ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
    ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
    ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

     Побитовое исключающее ИЛИ (XOR)
    ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
    ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
    ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Пример #2 Пример побитовых операций «исключающее ИЛИ» (XOR) над строками

    <?php

    echo 12 ^ 9, PHP_EOL; // Выводит '5'

    echo "12" ^ "9", PHP_EOL; // Выводит символ Backspace (ASCII-код 8)
                     // ('1' (ascii 49)) ^ ('9' (ASCII-код 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // Выводит ASCII-значения #0 #4 #0 #0 #0
                            // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // Выводит 1
                  // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // Выводит 1
                  // ((int) "2") ^ 3 == 1

    ?>

Пример #3 Пример сдвига битов в целых числах

    <?php

    /*
     * Несколько примеров
     */

    echo "\n--- СДВИГ ВПРАВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'слева вставилась копия знакового бита');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'биты сдвинулись за правый край');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'то же, что и выше; нельзя сдвинуть дальше 0');

    echo "\n--- СДВИГ ВПРАВО НАД ОТРИЦАТЕЛЬНЫМИ ЦЕЛЫМИ ЧИСЛАМИ ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'слева вставилась копия знакового бита');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'биты сдвинулись за правый край');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'то же, что и выше; нельзя сдвинуть дальше -1');

    echo "\n--- СДВИГ ВЛЕВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'правый край дополнился нулями');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 4;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'знаковые биты сдвинулись');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'биты сдвинулись за левый край');

    echo "\n--- СДВИГ ВЛЕВО НАД ОТРИЦАТЕЛЬНЫМИ ЦЕЛЫМИ ЧИСЛАМИ ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'правый дополнился нулями');

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'биты сдвинулись за левый край, включая знаковый бит');

    /*
     * Не обращайте внимания на нижний раздел кода,
     * это только форматирование для более ясного вывода
     */

    function p($res, $val, $op, $places, $note = '')
    {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Выражение: %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Десятичный вид:\n";
        printf(" val=%d\n", $val);
        printf(" res=%d\n", $res);

        echo " Двоичный вид:\n";
        printf(' val=' . $format, $val);
        printf(' res=' . $format, $res);

        if ($note) {
            echo " ЗАМЕЧАНИЕ: $note\n";
        }

        echo "\n\n";
    }

    ?>

Результат выполнения приведённого примера на 32-битных машинах:

    --- СДВИГ ВПРАВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---
    Выражение: 2 = 4 >> 1
     Десятичный вид:
      val=4
      res=2
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000010
     ЗАМЕЧАНИЕ: слева вставилась копия знакового бита

    Выражение: 1 = 4 >> 2
     Десятичный вид:
      val=4
      res=1
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000001

    Выражение: 0 = 4 >> 3
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за правый край

    Выражение: 0 = 4 >> 4
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     ЗАМЕЧАНИЕ: то же, что и выше; нельзя сдвинуть дальше 0

    --- СДВИГ ВПРАВО НА ОТРИЦАТЕЛЬНЫХ ЦЕЛЫХ ЧИСЛАХ ---
    Выражение: -2 = -4 >> 1
     Десятичный вид:
      val=-4
      res=-2
     Двоичный вид:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111110
     ЗАМЕЧАНИЕ: слева вставилась копия знакового бита

    Выражение: -1 = -4 >> 2
     Десятичный вид:
      val=-4
      res=-1
     Двоичный вид:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     ЗАМЕЧАНИЕ: биты сдвинулись за правый край

    Выражение: -1 = -4 >> 3
     Десятичный вид:
      val=-4
      res=-1
     Двоичный вид:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111111
     ЗАМЕЧАНИЕ: то же, что и выше; нельзя сдвинуть дальше -1

    --- СДВИГ ВЛЕВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---
    Выражение: 8 = 4 << 1
     Десятичный вид:
      val=4
      res=8
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000001000
     ЗАМЕЧАНИЕ: правый край дополнился нулями

    Выражение: 1073741824 = 4 << 28
     Десятичный вид:
      val=4
      res=1073741824
     Двоичный вид:
      val=00000000000000000000000000000100
      res=01000000000000000000000000000000

    Выражение: -2147483648 = 4 << 29
     Десятичный вид:
      val=4
      res=-2147483648
     Двоичный вид:
      val=00000000000000000000000000000100
      res=10000000000000000000000000000000
     ЗАМЕЧАНИЕ: знаковые биты сдвинулись

    Выражение: 0 = 4 << 30
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=00000000000000000000000000000100
      res=00000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за левый край

    --- СДВИГ ВЛЕВО НАД ОТРИЦАТЕЛЬНЫМИ ЦЕЛЫМИ ЧИСЛАМИ ---
    Выражение: -8 = -4 << 1
     Десятичный вид:
      val=-4
      res=-8
     Двоичный вид:
      val=11111111111111111111111111111100
      res=11111111111111111111111111111000
     ЗАМЕЧАНИЕ: правый край дополнился нулями

    Выражение: -2147483648 = -4 << 29
     Десятичный вид:
      val=-4
      res=-2147483648
     Двоичный вид:
      val=11111111111111111111111111111100
      res=10000000000000000000000000000000

    Выражение: 0 = -4 << 30
     Десятичный вид:
      val=-4
      res=0
     Двоичный вид:
      val=11111111111111111111111111111100
      res=00000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за левый край, включая знаковый бит

Результат выполнения приведённого примера на 64-битных машинах:

    --- СДВИГ ВПРАВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---
    Выражение: 2 = 4 >> 1
     Десятичный вид:
      val=4
      res=2
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000010
     ЗАМЕЧАНИЕ: слева вставилась копия знакового бита

    Выражение: 1 = 4 >> 2
     Десятичный вид:
      val=4
      res=1
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000001

    Выражение: 0 = 4 >> 3
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за правый край

    Выражение: 0 = 4 >> 4
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     ЗАМЕЧАНИЕ: то же, что и выше; нельзя сдвинуть дальше 0

    --- СДВИГ ВПРАВО НАД ОТРИЦАТЕЛЬНЫМИ ЦЕЛЫМИ ЧИСЛАМИ ---
    Выражение: -2 = -4 >> 1
     Десятичный вид:
      val=-4
      res=-2
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111110
     ЗАМЕЧАНИЕ: слева вставилась копия знакового бита

    Выражение: -1 = -4 >> 2
     Десятичный вид:
      val=-4
      res=-1
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     ЗАМЕЧАНИЕ: биты сдвинулись за правый край

    Выражение: -1 = -4 >> 3
     Десятичный вид:
      val=-4
      res=-1
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111111
     ЗАМЕЧАНИЕ: то же, что и выше; нельзя сдвинуть дальше -1

    --- СДВИГ ВЛЕВО НАД ПОЛОЖИТЕЛЬНЫМИ ЦЕЛЫМИ (НАТУРАЛЬНЫМИ) ЧИСЛАМИ ---
    Выражение: 8 = 4 << 1
     Десятичный вид:
      val=4
      res=8
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000001000
     ЗАМЕЧАНИЕ: правый край дополнился нулями

    Выражение: 4611686018427387904 = 4 << 60
     Десятичный вид:
      val=4
      res=4611686018427387904
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0100000000000000000000000000000000000000000000000000000000000000

    Выражение: -9223372036854775808 = 4 << 61
     Десятичный вид:
      val=4
      res=-9223372036854775808
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=1000000000000000000000000000000000000000000000000000000000000000
     ЗАМЕЧАНИЕ: знаковые биты сдвинулись

    Выражение: 0 = 4 << 62
     Десятичный вид:
      val=4
      res=0
     Двоичный вид:
      val=0000000000000000000000000000000000000000000000000000000000000100
      res=0000000000000000000000000000000000000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за левый край

    --- СДВИГ ВЛЕВО НАД ОТРИЦАТЕЛЬНЫМИ ЦЕЛЫМИ ЧИСЛАМИ ---
    Выражение: -8 = -4 << 1
     Десятичный вид:
      val=-4
      res=-8
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1111111111111111111111111111111111111111111111111111111111111000
     ЗАМЕЧАНИЕ: правый край дополнился нулями

    Выражение: -9223372036854775808 = -4 << 61
     Десятичный вид:
      val=-4
      res=-9223372036854775808
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=1000000000000000000000000000000000000000000000000000000000000000

    Выражение: 0 = -4 << 62
     Десятичный вид:
      val=-4
      res=0
     Двоичный вид:
      val=1111111111111111111111111111111111111111111111111111111111111100
      res=0000000000000000000000000000000000000000000000000000000000000000
     ЗАМЕЧАНИЕ: биты сдвинулись за левый край, включая знаковый бит

Внимание

Для побитовых операций над числами, которые превышают значение константы `PHP_INT_MAX`, вызывают функции модуля gmp.

### Смотрите также

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## Операторы сравнения

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

Операторы сравнения
Пример | Название | Результат
--- | --- | ---
$a == $b | Равно | Возвращается `true`, если значение переменной $a после преобразования типов равно значению переменной $b.
$a === $b | Тождественно равно | Возвращается `true`, если значение переменной $a равно значению переменной $b и имеет тот же тип.
$a != $b | Не равно | Возвращается `true`, если значение переменной $a после преобразования типов не равно значению переменной $b.
$a <> $b | Не равно | Возвращается `true`, если значение переменной $a после преобразования типов не равно значению переменной $b.
$a !== $b | Тождественно не равно | Возвращается `true`, если значение переменной $a не равно значению переменной $b или они разных типов.
$a < $b | Меньше | Возвращается `true`, если значение переменной $a строго меньше значения переменной $b.
$a > $b | Больше | Возвращается `true`, если значение переменной $a строго больше значения переменной $b.
$a <= $b | Меньше или равно | Возвращается `true`, если значение переменной $a меньше или равно значению переменной $b.
$a >= $b | Больше или равно | Возвращается `true`, если значение переменной $a больше или равно значению переменной $b.
$a <=> $b | Космический корабль (spaceship) | Целое число (int) меньше, больше или равное нулю, когда значение переменной $a меньше, больше или равно значению переменной $b.

Сравнение выполняется численно, если оба операнда — числовые строки, или один операнд — число, а другой — числовая строка. Эти правила также справедливы для оператора switch. Типы не преобразовываются при сравнениях вида `===` или `!==`, поскольку это включает сравнение значения и типа.

Внимание

До PHP 8.0.0, если строка (string) сравнивалась с числом или числовой строкой, то перед выполнением сравнения строка (string) преобразовывалась в число. Это иногда давало неожиданные результаты, как видно в следующем примере:

    <?php

    var_dump(0 == "a");
    var_dump("1" == "01");
    var_dump("10" == "1e1");
    var_dump(100 == "1e2");

    switch ("a") {
        case 0:
            echo "0";
            break;
        case "a":
            echo "a";
            break;
    }

    ?>

Результат выполнения приведённого примера в PHP 7:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

Результат выполнения приведённого примера в PHP 8:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

Пример #1 Операторы сравнения

    <?php

    // Целые числа
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // Числа с плавающей точкой
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // Строки
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' ';  // -1
    echo "zz" <=> "aa", ' '; // 1

    // Массивы
    echo [] <=> [], ' ';               // 0
    echo [1, 2, 3] <=> [1, 2, 3], ' '; // 0
    echo [1, 2, 3] <=> [], ' ';        // 1
    echo [1, 2, 3] <=> [1, 2, 1], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 4], ' '; // -1

    // Объекты
    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 0

    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "c"];
    echo $a <=> $b, ' '; // -1

    $a = (object) ["a" => "c"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 1

    // Сравниваются не только значения; ключи тоже должны совпадать
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

Для различных типов сравнение происходит в соответствии со следующей таблицей (по порядку).

Сравнение типов
Тип операнда 1 | Тип операнда 2 | Результат
--- | --- | ---
null или string | string | Значение `null` преобразовывается в пустую строку (""), числовое или лексическое сравнение
bool или null | значение любого типа | Преобразуется в bool, `false` < `true`
object | object | Встроенные классы могут определять свои правила сравнения, объекты разных классов не сравниваются, про сравнение объектов одного класса рассказано в разделе «Сравнение объекта»
string, resource, int или float | string, resource, int или float | Строки и ресурсы переводятся в числа, обычная математика
array | array | Массив с меньшим количеством элементов меньше, если PHP не нашёл ключ из первого массива во втором массиве — массивы несравнимы, иначе идёт сравнение значения за значением (смотрите пример ниже)
array | значение любого типа | Тип array всегда больше
object | значение любого типа | Тип object всегда больше

Пример #2 Примеры сравнения boolean- и null-значений со значениями других типов

    <?php

    // Логические значения и null сравниваются как логические
    var_dump(1 == TRUE); // TRUE  — то же, что и (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE  — то же, что и (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE  — то же, что и (bool) 100 < TRUE
    var_dump(-10 < FALSE); // FALSE  — то же, что и (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL  — (bool) NULL < (bool) -100 это FALSE < TRUE

    ?>

Пример #3 Транскрипция стандартного сравнения массивов

    <?php

    // Массивы сравниваются как в этом примере — со стандартными операторами сравнения, и оператором «космический корабль» (spaceship).
    function standard_array_compare($op1, $op2)
    {
        if (count($op1) < count($op2)) {
            return -1; // $op1 < $op2
        } elseif (count($op1) > count($op2)) {
            return 1; // $op1 > $op2
        }

        foreach ($op1 as $key => $val) {
            if (!array_key_exists($key, $op2)) {
                return 1;
            } elseif ($val < $op2[$key]) {
                return -1;
            } elseif ($val > $op2[$key]) {
                return 1;
            }
        }

        return 0; // $op1 == $op2
    }

Внимание

# Сравнение чисел с плавающей точкой

Из-за внутреннего представления чисел с плавающей точкой (float) не нужно проверять два числа с плавающей точкой (float) на равенство.

Подробнее об этом рассказывает в документации к типу float.

> Замечание: Когда пишут код, помнят, что жонглирование типами в PHP не всегда даёт предсказуемый результат при сравнении значений разных типов, особенно при сравнении целых чисел (int) с логическими значениями (bool) или целых чисел (int) со строками (string). Поэтому лучше пользоваться операторами `===` и `!==`, а не `==` и `!=`.

### Несравнимые значение

Хотя тождественные сравнения `===` и `!==` применяют к произвольным значениям, другие операторы сравнения лучше применять только к сравнимым значениям. Результат сравнения несравнимых значений не определён и на него не нужно полагаться.

### Смотрите также

- strcasecmp()
- strcmp()
- Операторы работы с массивами
- Типы

### Тернарный оператор

Список условных операторов дополняет тернарный оператор «?:».

Пример #4 Присваивание значения по умолчанию

    <?php

    // Пример выражения с тернарным оператором
    $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

    // Код выше аналогичен блоку с конструкциями if/else
    if (empty($_POST['action'])) {
        $action = 'default';
    } else {
        $action = $_POST['action'];
    }

    ?>

Выражение `(expr1) ? (expr2) : (expr3)` интерпретируется как expr2, если expr1 равно `true`, или как expr3, если expr1 равно `false`.

Можно не писать среднюю часть тернарного оператора. Выражение `expr1 ?: expr3` оценивается как результат выражения expr1, если оно оценивается как `true`, иначе как результат выражения expr3. Выражение expr1 оценивается только один раз.

> Замечание: Обратите внимание, что тернарный оператор — это выражение, и он оценивается не как переменная, а как результат выражения. Это важно, если нужно вернуть переменную по ссылке. Выражение `return $var == 42 ? $a : $b;` не будет работать в функции, возвращающей значение по ссылке, а в более поздних версиях PHP также будет выдано предупреждение.

> Замечание:

> Рекомендовано избегать «нагромождения» тернарных выражений. Поведение PHP при указании более чем одного тернарного оператора без скобок в одном выражении неочевидно в сравнении с другими языками. Впрямь, до PHP 8.0.0 троичные выражения оценивались как левоассоциативные, а не правоассоциативные, как в большей части других языков программирования. Опора на левую ассоциативность устарела начиная с PHP 7.4.0. Начиная с PHP 8.0.0 тернарный оператор неассоциативен.

> Пример #5 Неочевидное поведение тернарного оператора

>     <?php

>     // Кажется, что следующий код выведет "true"
>     echo (true ? 'true' : false ? 't' : 'f');

>     // Однако код выводит "t" до PHP 8.0.0.
>     // Причина состоит в том, что тернарные выражения левоассоциативны

>     // Следующая запись — более очевидная версия приведённого кода
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // Здесь видно, что первое выражение оценивается как строковое "true", которое
>     // оценивается как логическое (bool) true, поэтому возвращает истинную ветвь
>     // второго тернарного выражения

>     ?>

> Замечание:

> Цепочка коротких тернарных операторов (`?:`), однако, стабильна и ведёт себя обоснованно. Она будет оценивать первый аргумент, который оценивается как не ложное значение. Обратите внимание, что неопределённые значения все равно вызовут предупреждение.

> Пример #6 Цепочка коротких тернарных операторов

>     <?php

>     echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; // 1
>     echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; // 2
>     echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; // 3

>     ?>

### Оператор объединения с null

Другой полезный сокращённый оператор — это оператор объединения с NULL — «??» (null coalescing).

Пример #7 Присваивание значения по умолчанию

    <?php

    // Пример работы с оператором нулевого слияния
    $action = $_POST['action'] ?? 'default';

    // Пример выше аналогичен этому выражению с if/else
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'default';
    }

Выражение `(expr1) ?? (expr2)` вычисляется так: expr2, если expr1 равно `null`, иначе expr1.

Этот оператор не вызывает предупреждения или ошибки, если левый операнд не существует, точно как языковая конструкция isset(). Это очень полезно для ключей массива.

> Замечание: Обратите внимание, оператор объединения с NULL — это выражение, и он оценивается не как переменная, а как результат вычисления выражения. Это важно, если нужно вернуть значение по ссылке. Выражение `return $foo ?? $bar;` в функции, возвращающей ссылку, будет не работать, а выводить предупреждение.

> Замечание:

> У оператора объединения с NULL низкий приоритет. То есть при смешивании его с другими операторами (например, с операторами конкатенации строк или арифметическими операторами), скорее всего, потребуются круглые скобки.

>     <?php

>     // Вызывает предупреждение о том, что переменную $name не определили
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // Выведет "Mr. Anonymous"
>     print 'Mr. ' . ($name ?? 'Anonymous');

>     ?>

> Замечание:

> Обратите внимание, оператор объединения с NULL разрешает простую вложенность:

> Пример #8 Вложенный оператор null coalescing

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // Выведет 1

>     ?>

## Оператор управления ошибками

PHP поддерживает один оператор управления ошибками: знак `@`, который указывают перед PHP-выражениями. Оператор подавит диагностическую ошибку, которое сгенерировало выражение.

Пользовательская функция обработчика ошибок, которую устанавливают функцией set_error_handler(), вызывается, даже если диагностику подавили.

Внимание

До PHP 8.0.0 функция error_reporting() при вызове внутри пользовательского обработчика ошибок возвращала для ошибок, которые подавили оператором `@`, значение `0`. Начиная с PHP 8.0.0 функция возвращает значение побитового выражения: `E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`.

Сообщение об ошибке, которое сгенерировало выражение, доступно в элементе с ключом `"message"` в массиве, который возвращает функция error_get_last(). Результат функции изменяется при каждой ошибке, поэтому результат лучше проверить заранее.

Пример #1 Преднамеренная ошибка считывания файла

    <?php

    $my_file = @file('non_existent_file') or
        die("При открытии файла возникла ошибка: '" . error_get_last()['message'] . "'");

    ?>

Пример #2 Подавление ошибок в выражениях

    <?php

    // Оператор работает с каждым выражением, а не только с функциями
    $value = @$cache[$key];
    // Уведомление не отобразится, если массив не содержит ключ $key

    ?>

> Замечание: Оператор `@` работает только с выражениями. Простое эмпирическое правило: оператор `@` добавляют перед инструкциями, которые вычисляются как значение. Оператор `@` указывают перед названием переменной, произвольной функцией, вызовом выражения include и т. д. При этом нельзя указывать оператор перед определением функции или класса, условными конструкциями наподобие `if`, циклом `foreach` и другими инструкциями, которые не вычисляются как значение.

Внимание

До PHP 8.0.0 оператор `@` подавлял критические ошибки, которые прерывали выполнение скрипта. Скрипт завершал выполнение без указания причины, если оператор `@` указывали, например, перед вызовом функции, которую не определили, не импортировали или в названии которой допустили опечатку.

### Смотрите также

- error_reporting()
- Обработка ошибок и функции логирования

## Операторы выполнения

PHP поддерживает один оператор выполнения: обратные машинописные апострофы, или обратные кавычки, — ````. Обратите внимание, что это не одинарные кавычки! PHP попытается выполнить строку в обратных апострофах как консольную команду; PHP вернёт данные вывода, а не просто сбросит данные в поток вывода; вывод присваивают переменной. Оператор выполнения работает аналогично функции shell_exec().

Пример #1 Оператор выполнения

    <?php

    $output = `ls -al`;
    echo "<pre>$output</pre>";

> Замечание:

> Обратные кавычки недоступны, если функцию shell_exec() отключили.

> Замечание:

> В отличие от ряда других языков, обратные кавычки не несут отдельного значения внутри строк в двойных кавычках.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Оператор выполнения устарел; обратные кавычки больше не работают как синоним функции shell_exec().

### Смотрите также

- Функции выполнения программ
- popen()
- proc_open()
- Работа с PHP из командной строки

## Логические операторы

Логические операторы
Пример | Название | Результат
--- | --- | ---
$a and $b | И | `true`, если и $a, и $b `true`.
$a or $b | Или | `true`, если или $a, или $b `true`.
$a xor $b | Исключающее или | `true`, если $a, или $b `true`, но не оба.
! $a | Отрицание | `true`, если $a не `true`.
$a && $b | И | `true`, если и $a, и $b `true`.
$a || $b | Или | `true`, если или $a, или $b `true`.

Причина существования двух разных операторов «И» и «ИЛИ» в том, что они работают с разным приоритетом (смотрите таблицы в разделе «Приоритет оператора»).

Пример #1 Объяснение логических операторов

    <?php

    // --------------------
    // Функция foo() никогда не будет вызвана, т. к. эти операторы шунтирующие (short-circuit)

    $a = (false && foo());
    $b = (true || foo());
    $c = (false and foo());
    $d = (true or foo());

    // --------------------
    // У оператора «||» больший приоритет, чем у «or»

    // Результат выражения (false || true) присваивается переменной $e
    // Действует как: ($e = (false || true))
    $e = false || true;

    // Константа false присваивается переменной $f, а затем значение true игнорируется
    // Действует как: (($f = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // У оператора «&&» больший приоритет, чем у «and»

    // Результат выражения (true && false) присваивается переменной $g
    // Действует как: ($g = (true && false))
    $g = true && false;

    // Константа true присваивается переменной $h, а затем значение false игнорируется
    // Действует как: (($h = true) and false)
    $h = true and false;

    var_dump($g, $h);

Вывод приведённого примера будет похож на:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## Строковые операторы

В PHP со строками (string) работают два оператора. Первый — оператор конкатенации («.»), который возвращает строку, которая представляет соединение левого и правого аргумента. Второй — оператор присваивания с конкатенацией («`.=`»), который присоединяет правый аргумент к левому. Подробнее об этом рассказывает раздел «Операторы присваивания».

Пример #1 Конкатенация строк

    <?php

    $a = "Привет, ";
    $b = $a . "Мир!"; // Переменная $b теперь содержит строку "Привет, Мир!"
    var_dump($b);

    $a = "Привет, ";
    $a .= "Мир!";   // Переменная $a теперь содержит строку "Привет, Мир!"
    var_dump($a);

    ?>

### Смотрите также

- Строки
- Функции для работы со строками

## Операторы для работы с массивами

Операторы массивов
Пример | Название | Результат
--- | --- | ---
$a + $b | Объединение | Объединение массива $a с массивом $b.
$a == $b | Равно | Возвращает `true`, если массив в переменной $a и массив в переменной $b содержат одни и те же пары «ключ — значение».
$a === $b | Тождественно равно | Возвращает `true`, если массив в переменной $a и массив в переменной $b содержат одни и те же пары «ключ — значение» в том же порядке и того же типа.
$a != $b | Не равно | Возвращает `true`, если массив в переменной $a не равен массиву в переменной $b.
$a <> $b | Не равно | Возвращает `true`, если массив в переменной $a не равен массиву в переменной $b.
$a !== $b | Тождественно не равно | Возвращает `true`, если массив в переменной $a не равен тождественно массиву в переменной $b.

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

Пример #1 Оператор добавления одного массива в конец другого

    <?php

    $a = array("a" => "яблоко", "b" => "банан");
    $b = array("a" => "груша", "b" => "клубника", "c" => "вишня");

    $c = $a + $b; // Объединение массивов $a и $b
    echo "Объединение массивов \$a и \$b:\n";
    var_dump($c);

    $c = $b + $a; // Объединение массивов $b и $a
    echo "Объединение массивов \$b и \$a:\n";
    var_dump($c);

    $a += $b; // Выражение $a += $b объединяет массивы $a и $b
    echo "Объединение массивов выражением \$a += \$b:\n";
    var_dump($a);

    ?>

Результат выполнения приведённого примера:

    Объединение массивов $a и $b:
    array(3) {
      ["a"]=>
      string(12) "яблоко"
      ["b"]=>
      string(10) "банан"
      ["c"]=>
      string(10) "вишня"
    }
    Объединение массивов $b и $a:
    array(3) {
      ["a"]=>
      string(10) "груша"
      ["b"]=>
      string(16) "клубника"
      ["c"]=>
      string(10) "вишня"
    }
    Объединение массивов $a += $b:
    array(3) {
      ["a"]=>
      string(12) "яблоко"
      ["b"]=>
      string(10) "банан"
      ["c"]=>
      string(10) "вишня"
    }

При сравнении элементы массива признаются идентичными, если совпадает и ключ, и значение ключа.

Пример #2 Сравнение массивов

    <?php

    $a = array("apple", "banana");
    $b = array(1 => "banana", "0" => "apple");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)

    ?>

### Смотрите также

- Массивы
- Функции работы с массивами

## Оператор проверки принадлежности типу

Оператор `instanceof` определяет, содержит ли PHP-переменная экземпляр объекта конкретного класса.

Пример #1 Проверка принадлежности объекта классу оператором `instanceof`

    <?php

    class MyClass {}

    class NotMyClass {}

    $a = new MyClass();

    var_dump($a instanceof MyClass);
    var_dump($a instanceof NotMyClass);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

Оператор `instanceof` также определяет, принадлежит ли объект, который хранит переменная, классу-наследнику:

Пример #2 Проверка принадлежности объекта класса-наследника супертипу оператором `instanceof`

    <?php

    class ParentClass {}

    class MyClass extends ParentClass {}

    $a = new MyClass();

    var_dump($a instanceof MyClass);
    var_dump($a instanceof ParentClass);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)

Для проверки непринадлежности объекта классу указывают логический оператор `not`.

Пример #3 Проверка непринадлежности объекта экземпляру класса оператором `instanceof` с оператором логического не

    <?php

    class MyClass {}

    $a = new MyClass();
    var_dump(!($a instanceof stdClass));

    ?>

Результат выполнения приведённого примера:

    bool(true)

Наконец, оператор `instanceof` также проверяет, реализует ли объект интерфейс:

Пример #4 Проверка принадлежности типа объекта интерфейсу оператором `instanceof`

    <?php

    interface MyInterface {}

    class MyClass implements MyInterface {}

    $a = new MyClass();

    var_dump($a instanceof MyClass);
    var_dump($a instanceof MyInterface);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)

Оператор `instanceof` чаще указывают с буквальным названием класса, но оператор также работает с переменной объекта или строковой переменной:

Пример #5 Проверка принадлежности объекта типу оператором `instanceof` с другими переменными

    <?php

    interface MyInterface {}

    class MyClass implements MyInterface {}

    $a = new MyClass();
    $b = new MyClass();
    $c = 'MyClass';
    $d = 'NotMyClass';

    var_dump($a instanceof $b); // Переменная $b — объект класса MyClass
    var_dump($a instanceof $c); // Переменная $c — строка 'MyClass'
    var_dump($a instanceof $d); // Переменная $d — строка 'NotMyClass'

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)

Оператор instanceof не выбрасывает ошибок, если проверяемая переменная — не объект, оператор только вернёт значение `false`. Проверка принадлежности констант, однако, до PHP 7.3.0 выбрасывала фатальную ошибку.

Пример #6 Проверка принадлежности классу переменных других типов оператором `instanceof`

    <?php

    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');

    var_dump($a instanceof stdClass); // Переменная $a — целое типа integer
    var_dump($b instanceof stdClass); // Переменная $b — NULL
    var_dump($c instanceof stdClass); // Переменная $c — значение с типом resource
    var_dump(FALSE instanceof stdClass);

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof expects an object instance, constant given

Начиная с PHP 7.3.0 константы в левой части оператора `instanceof` стали допустимыми.

Пример #7 Проверка принадлежности типа константы классу оператором `instanceof`

    <?php

    var_dump(FALSE instanceof stdClass);

    ?>

Результат выполнения приведённого примера в PHP 7.3:

    bool(false)

Начиная с PHP 8.0.0 оператор `instanceof` разрешили указывать с произвольными выражениями. Требования к выражению: записывается в круглых скобках и возвращает значение с типом string.

Пример #8 Пример работы оператора `instanceof` с произвольным выражением

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return ClassA::class;
    }

    var_dump(new ClassA instanceof ('std' . 'Class'));
    var_dump(new ClassB instanceof ('Class' . 'B'));
    var_dump(new ClassC instanceof ('Class' . 'A'));
    var_dump(new ClassD instanceof (getSomeClass()));

    ?>

Результат выполнения приведённого примера в PHP 8:

    bool(true)
    bool(true)
    bool(false)
    bool(true)

Оператор `instanceof` аналогичен функции is_a().

### Смотрите также

- get_class()
- is_a()

## Функциональный оператор

PHP версии 8.5 и новее поддерживает один оператор, который работает с callable-выражениями. Оператор `|>`, или оператор конвейеризации, принимает в правой части callable-выражение с единственным параметром, передаёт в него значение левой части и возвращает результат вычисления вызываемого выражения. В правой части оператор принимает допустимое в PHP callable-выражение: объект класса Closure, callable-выражение как объект первого класса, объект, класс которого реализует метод __invoke(), и другие вызываемые значения.

Каждые две следующие строки эквивалентны.

Пример #1 Оператор `|>`

    <?php

    $result = "Привет, мир!" |> strlen(...);
    print $result, PHP_EOL;

    $result = strlen("Привет, мир!");
    print $result, PHP_EOL;

Результат выполнения приведённого примера:

    21
    21

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

Пример #2 Цепочка вызовов через оператор |>

    <?php

    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'));
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);

Результат выполнения приведённого примера:

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

В левой части оператор конвейера принимает произвольное значение или выражение, а в правой — допустимое в PHP callable-выражение, которое принимает только один аргумент. Функции с двумя или больше обязательными параметрами не сработают и вызовут ошибку, как при стандартном вызове с недостаточным количеством аргументов. В правой части оператора нельзя указывать функции, которые принимают переменную по ссылке. PHP выбросит ошибку Error, если в правую часть оператора передали значение, которое невозможно вызвать как функцию.

> Замечание:

> Стрелочные функции в правой части оператора конвейеризации ОБЯЗАТЕЛЬНО указывают в круглых скобках, чтобы избежать синтаксической двусмысленности, как в предыдущем примере. При нарушении требования PHP выдаст фатальную ошибку.

### Смотрите также

- Closure

# Управляющие конструкции

## Содержание

- Введение
- if
- else
- elseif/else if
- Альтернативный синтаксис управляющих структур
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## Введение

Любой сценарий PHP состоит из последовательности инструкций. Инструкцией может быть присваивание, вызов функции, повтор кода (цикл), сравнение, или даже инструкция, которая ничего не делает (пустой оператор). После инструкции обычно ставится точка с запятой. Кроме того, инструкции могут быть объединены в блоки заключением их в фигурные скобки. Блок инструкций также сам по себе является инструкцией. В этом разделе описываются различные типы инструкций.

### Смотрите также

Ниже также рассматриваются языковые конструкции, даже если они упоминаются в функциях руководства.

- list()
- array()
- echo
- eval()
- print

## if

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

Конструкция `if` — основополагающая структура языков программирования, включая PHP. Эта структура разрешает условное выполнение фрагментов кода. Синтаксис и поведение конструкции `if` в PHP похожи на работу аналогичной конструкции в языке C:

    if (выражение)
        инструкция

Как описывает раздел «Выражения», PHP вычисляет выражение как логическое значение. Если PHP вычислит выражение как `true`, он выполнит инструкцию, а если вычислит выражение как `false` — проигнорирует инструкцию. Больше информации о том, какие значения PHP вычисляет как `false`, даёт раздел «Преобразование в логический тип».

Следующий пример выведет «a больше b», если значение переменной $a больше, чем значение переменной $b:

    <?php

    if ($a > $b)
      echo "a больше b";

    ?>

Часто нужно, чтобы по условию выполнялось больше одной инструкции. Конечно, каждую инструкцию не оборачивают в условие `if`. Вместо этого инструкции объединяют в группу. Например, следующий код выведет «a больше b», если значение переменной $a больше, чем значение переменной $b, а затем присвоит переменной $b значение переменной $a:

    <?php

    if ($a > $b) {
        echo "a больше b";
        $b = $a;
    }

    ?>

PHP разрешает вкладывать инструкции `if` в другие инструкции `if` бесконечно, что даёт полную гибкость в организации условного выполнения частей программы.

## else

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

Часто необходимо выполнить одну инструкцию, если конкретное условие верно, и другую — если неверно. Вот для чего нужна конструкция `else`. Конструкция `else` расширяет инструкцию `if`, чтобы выполнять другую инструкцию тогда, когда выражение внутри инструкции `if` PHP оценивает как `false`. Например, следующий код выведет «a больше b», если значение переменной $a больше, чем значение переменной $b, иначе — «a НЕ больше b»:

    <?php

    if ($a > $b) {
      echo "a больше b";
    } else {
      echo "a НЕ больше b";
    }

    ?>

PHP выполнит инструкцию `else`, только если вычислит выражение `if` как `false`, а если были выражения `elseif` — то только если тоже вычислит их как `false`. О конструкции elseif.

> Замечание: Болтающийся else

> В случае вложенных инструкций `if`-`else`, конструкция `else` связывается с близлежащей конструкцией `if`.

>     <?php

>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";

>     ?>

> Независимо от расстановки отступов, которые не влияют на PHP-код, конструкция `else` связана с конструкцией `if ($b)`, поэтому пример ничего не выведет. Код с такой расстановкой отступов будет работать, но лучше избегать такого кода и использовать фигурные скобки, чтобы устранить неоднозначности.

## elseif/else if

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

Конструкция `elseif`, как ясно из названия, объединяет конструкции `if` и `else`. Как и конструкция `else`, она расширяет инструкцию `if`, чтобы выполнять другую инструкцию тогда, когда PHP вычисляет выражение начальной конструкции `if` как `false`. Отличие от конструкции `else` состоит в том, что конструкция `elseif` выполнит альтернативное выражение только тогда, когда PHP вычислит условное выражение `elseif` как `true`. Следующий код, в зависимости от значений переменных, будет выводить «a больше b», «a равно b» или «a меньше b»:

    <?php

    if ($a > $b) {
        echo "a больше b";
    } elseif ($a == $b) {
        echo "a равно b";
    } else {
        echo "a меньше b";
    }

    ?>

Допустимо указывать больше одной конструкции `elseif` в одной инструкции `if`. PHP выполняет первое выражение `elseif`, которое вычисляет как `true`. В PHP допустимо писать `else if` в два слова, тогда поведение будет идентичным конструкции `elseif` в одно слово. Синтаксическое отличие есть (в языке C пишут в два слова), но в итоге оба выражения дадут один и тот же результат.

PHP выполнит инструкцию `elseif` только тогда, когда вычислит предшествующее выражение `if` и предшествующие выражения `elseif` как `false`, а текущее выражение `elseif` — как `true`.

> Замечание: Заметьте, что записи `elseif` и `else if` будут равнозначны только в синтаксисе с фигурными скобками, как в приведённом примере. В синтаксисе с двоеточием для определения условий `if` и `elseif`, конструкция `elseif` пишется в одно слово. PHP выдаст ошибку синтаксического анализа и завершит работу, если запись конструкции `else if` разделена на два слова.

    <?php

    /* Некорректный способ: */
    if ($a > $b):
        echo $a . " больше " . $b;
    else if ($a == $b): // Не скомпилируется
        echo "Строка выше вызывает фатальную ошибку.";
    endif;

    ?>

    <?php

    /* Корректный способ: */
    if ($a > $b):
        echo $a . " больше " . $b;
    elseif ($a == $b): // Заметьте, тут одно слово
        echo $a . " равно " . $b;
    else:
        echo $a . " не больше и не равно " . $b;
    endif;

    ?>

## Альтернативный синтаксис управляющих структур

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

PHP предлагает альтернативный синтаксис для отдельных управляющих структур языка, а точнее: `if`, `while`, `for`, `foreach` и `switch`. Для каждой управляющей структуры базовую форму альтернативного синтаксиса получают путём изменения открывающей фигурной скобки на двоеточие :, а закрывающей — на инструкцию, которая соответствует названию структуры: `endif;`, `endwhile;`, `endfor;`, `endforeach;` или `endswitch;`.

    <?php if ($a == 5): ?>
    A равно 5
    <?php endif; ?>

В приведённом примере, HTML-блок "A равно 5" вложили в конструкции `if`, которую записали альтернативным синтаксисом. Блок HTML-разметки отобразится, только если переменная $a равна 5.

Альтернативный синтаксис также применяется к конструкциям `else` и `elseif`. Следующий пример показывает структуру конструкции `if` с конструкциями `elseif` и `else` в альтернативном формате:

    <?php

    if ($a == 5):
        echo "Значение переменной $a равно 5";
        echo "...";
    elseif ($a == 6):
        echo "Значение переменной $a равно 6";
        echo "!!!";
    else:
        echo "Значение переменной $a не равно ни 5, ни 6";
    endif;

    ?>

> Замечание:

> Смешивание синтаксиса в одном и том же блоке управления не поддерживается.

Внимание

Любой вывод, включая пробельные символы, между инструкцией `switch` и первой инструкцией `case` вызовет синтаксическую ошибку. Например, следующий синтаксис недопустим:

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

При этом следующий пример содержит допустимый код, поскольку завершающий символ новой строки после инструкции `switch` PHP рассматривает как часть закрывающего тега `?>` и поэтому между инструкциями `switch` и `case` ничего не выводится:

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

Дополнительные примеры приводят страницы описания циклов while и for, и конструкци if.

## while

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

Циклы `while` являются простейшим видом циклов в PHP. Они ведут себя так же, как и в языке C. Простейшей формой цикла `while` является следующее выражение:

    while (expr)
        statement

Смысл выражения `while` очень прост. Оно указывает PHP выполнять вложенные выражения повторно до тех пор, пока выражение в самом `while` является `true`. Значение выражения `expr` проверяется каждый раз перед началом цикла, поэтому даже если значение выражения изменится в процессе выполнения вложенных выражений в цикле, выполнение не прекратится до конца итерации (каждый раз, когда PHP выполняет выражения в цикле - это одна итерация). Если выражение `while` равно `false` с самого начала, вложенные выражения ни разу не будут выполнены.

Также, как и с оператором `if`, вы можете группировать несколько выражений внутри одного цикла `while`, заключая эти выражения между фигурными скобками или используя альтернативный синтаксис:

    while (expr):
        statement
        ...
    endwhile;

Следующие примеры идентичны, и оба выведут числа от 1 до 10:

    <?php
    /* пример 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* выводиться будет значение переменной
                       $i перед её увеличением
                       (post-increment) */
    }

    /* пример 2 */

    $i = 1;
    while ($i <= 10):
        echo $i;
        $i++;
    endwhile;
    ?>

## do-while

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

Циклы `do-while` похожи на циклы `while`, за исключением того, что истинность выражения проверяется в конце каждой итерации, а не в начале. Основное отличие от стандартных циклов `while` состоит в том, что первая итерация цикла `do-while` гарантированно выполняется, поскольку истинность выражения проверяется только в конце итерации, тогда как в стандартном цикле `while` выполнение первой итерации необязательно, поскольку истинность выражения проверяется в начале каждой итерации, и если с са́мого начала выражение окажется ложным и примет значение `false`, выполнение цикла немедленно завершится.

Единственный синтаксис цикла `do-while`:

    <?php

    $i = 0;

    do {
        echo $i;
    } while ($i > 0);

    ?>

В примере цикл выполнится ровно один раз, потому что после первой итерации выражения оценивается как ложное (переменная $i не больше 0) и принимает значение `false`, а выполнение цикла завершается.

Разработчики с опытом программирования на языке C при работе с циклом `do-while` пользуются подходом, который останавливает выполнение циклов в середине блоков кода. Для этого блок кода оборачивают конструкцией `do-while` (0) и указывают в блоке инструкцию `break`. Следующий фрагмент кода демонстрирует этот подход:

    <?php

    do {
        if ($i < 5) {
            echo "Значение переменной \$i ещё недостаточно велико";
            break;
        }

        $i *= $factor;

        if ($i < $minimum_limit) {
            break;
        }

        echo "Теперь значение переменной \$i в порядке";

        /* Обрабатываем переменную $i */

    } while (0);

    ?>

Вместо этого «хака» иногда пользуются оператором `goto`.

## for

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

Цикл `for` самый сложный цикл в PHP. Цикл ведёт себя аналогично языку C. Синтаксис цикла `for` выглядит вот так:

    for (expr1; expr2; expr3)
        statement

Первое выражение expr1 вычисляется или выполняется только один раз безусловно в начале цикла.

В начале каждой итерации оценивается выражение expr2. Цикл продолжается, а вложенные инструкции выполняются, если выражение принимает значение `true`. Выполнение цикла заканчивается, если выражение принимает значение `false`.

В конце каждой итерации вычисляется или выполняется выражение expr3.

Каждое из выражений разрешается оставлять пустым или указывать в каждом выражении набор выражений через запятую. В части expr2 каждое выражение, которое отделили запятой, вычисляется, но результат берётся из последнего. Цикл выполняется бесконечно, если выражение expr2 оставили пустым; PHP неявно рассматривает пустое выражение как значение `true`, по аналогии с языком C. Это бывает не так бесполезно, как кажется, поскольку вместо выражения истинности в списке выражений цикла `for` цикл часто требуется прервать по условию в теле цикла путём вызова инструкции `break`.

Рассмотрим следующие примеры. Каждый пример выводит числа от 1 до 10:

    <?php

    /* Пример 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* Пример 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }

        echo $i;
    }

    /* Пример 3 */

    $i = 1;
    for (; ; ) {
        if ($i > 10) {
            break;
        }

        echo $i;
        $i++;
    }

    /* Пример 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);

    ?>

Конечно, первый пример кажется самым красивым (или, возможно, четвёртый), но программисты часто находят пустые выражения в циклах `for` удобными.

PHP также поддерживает для циклов `for` альтернативный синтаксис с двоеточием.

    for (expr1; expr2; expr3):
        statement
        ...
    endfor;

Следующий пример перебирает массивы стандартным способом, к которому привыкли разработчики.

    <?php

    /**
     * Это массив с данными, которые требуется изменить
     * в цикле
     */
    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for ($i = 0; $i < count($people); ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }

    ?>

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

    <?php

    $people = array(
        array('name' => 'Kalle', 'salt' => 856412),
        array('name' => 'Pierre', 'salt' => 215863)
    );

    for($i = 0, $size = count($people); $i < $size; ++$i) {
        $people[$i]['salt'] = mt_rand(000000, 999999);
    }

    ?>

## foreach

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

Языковой конструкцией `foreach` удобно перебирать массивы (array) и объекты, классы которых реализуют интерфейс Traversable. Конструкция `foreach` выдаст ошибку при попытке перебора переменной с другим типом данных или неинициализированной переменной. Разработчику доступны два вида синтаксиса:

Конструкция `foreach` умеет получать ключ каждого элемента, если требуется, и присваивать значение ключа переменной `key`:

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

Первая форма обходит доступные для перебора данные, заданные выражением `iterable_expression`. На каждой итерации значение текущего элемента присваивается переменной `$value`.

Вторая форма дополнительно будет присваивать ключ текущего элемента переменной `$key` на каждой итерации.

Обратите внимание, что конструкция `foreach` не изменяет внутренний указатель массива, с которым, например, работают функции current() и key().

Разработчику доступна настройка итерации объектов.

Пример #1 Базовая работа с конструкцией `foreach`

    <?php

    /* Пример перебора только значений */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Значение текущего элемента массива \$array: $value.\n";
    }

    /* Пример перебора ключей и значений */
    $array = [
        "one" => 1,
        "two" => 2,
        "three" => 3,
        "seventeen" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Ключ: $key => Значение: $value\n";
    }

    /* Пример итерации по ключам и значениям многомерного массива */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Значение на позиции x=$x и y=$y: $value\n";
        }
    }

    /* Пример итерации по динамическому массиву */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }

    ?>

> Замечание:

> Конструкция `foreach` не поддерживает подавление сообщений об ошибках оператором `@`.

### Распаковка вложенных массивов

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

В PHP доступна итерация по массиву массивов и распаковка вложенного массива в переменные цикла. Массив распаковывают либо путём деструктуризации массива через конструкцию `[]`, либо указывают языковую конструкцию list() как значение цикла.

> Замечание: Деструктуризация массивов через конструкцию `[]` возможна только с PHP 7.1.0

В обоих следующих примерах переменной `$a` присваивается первый элемент вложенного массива, а переменная `$b` получит второй элемент:

    <?php

    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }

    ?>

Результат выполнения приведённого примера:

    A: 1; B: 2
    A: 3; B: 4

Распаковка проигнорирует оставшиеся элементы, если в значении цикла указали меньшее переменных, чем элементов в массиве. Аналогично элементы пропускают, оставляя только запятую:

    <?php

    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Обратите внимание, переменную $c не указали
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // Пропускаем переменные $a и $b
        echo "$c\n";
    }

    ?>

Результат выполнения приведённого примера:

    1 2
    3 4
    5
    6

При недостаточном количестве элементов для заполнения переменных в конструкции list() или конструкции с квадратными скобками генерируется уведомление:

    <?php

    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }

    ?>

Результат выполнения приведённого примера:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 1; B: 2; C:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 3; B: 4; C:

### Конструкция foreach и ссылки

Элементы массива возможно напрямую модифицировать внутри цикла путём указания перед значением `$value` знака `&`, тогда значение присваивается по ссылке.

    <?php

    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // Массив $arr теперь содержит значения [2, 4, 6, 8]
    unset($value); // Разрываем ссылочную связь с последним элементом

    ?>

Внимание

Ссылка на значение `$value` последнего элемента массива сохраняется даже после завершения цикла `foreach`. Поэтому рекомендуют уничтожать ссылку конструкцией unset(), иначе возникнет следующее поведение:

    <?php

    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // Массив $arr теперь содержит значения [2, 4, 6, 8]

    // Без уничтожения ссылки конструкцией unset($value) переменная $value по-прежнему ссылается на последний элемент: $arr[3]

    foreach ($arr as $key => $value) {
        // Элемент $arr[3] обновляется с каждым значением массива $arr...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...пока предпоследнее значение не скопируется в последнее

    ?>

Результат выполнения приведённого примера:

    0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
    1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
    2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
    3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )

Пример #2 Итерация по значениям константного массива по ссылке

    <?php

    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }

    ?>

### Смотрите также

- array
- Traversable
- iterable
- list()

## break

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

Инструкция `break` прерывает выполнение текущей структуры `for`, `foreach`, `while`, `do-while` или `switch`.

Инструкция `break` принимает необязательный числовой аргумент, который сообщает ей, выполнение скольких окружающих вложенных структур требуется прервать. Значение по умолчанию равно `1`, прерывается только ближайшая окружающая структура.

    <?php

    $arr = array('один', 'два', 'три', 'четыре', 'стоп', 'пять');

    foreach ($arr as $val) {
        if ($val === 'стоп') {
            break;    /* В этом месте можно было бы написать 'break 1;'. */
        }

        echo "$val<br />\n";
    }

    /* Передача необязательного аргумента. */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "Итерация 5<br />\n";
                break 1;  /* Выйти только из конструкции switch. */
            case 10:
                echo "Итерация 10; выходим<br />\n";
                break 2;  /* Выходим из конструкции switch и из цикла while. */
            default:
                break;
        }
    }

    ?>

## continue

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

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

> Замечание: В PHP инструкция `continue` считает инструкцию switch циклической структурой. Без аргументов инструкция `continue` внутри инструкции switch ведёт себя аналогично инструкции `break`, но выдаёт предупреждение, поскольку предполагает, что допустили ошибку. Вызов `continue 2` внутри блока switch продолжит выполнение кода со следующей итерации внешнего цикла, если инструкцию `switch` указали внутри цикла.

Инструкция `continue` принимает необязательный числовой аргумент, который сообщает, на внешнем цикле какого уровня требуется пропустить оставшуюся часть итерации. Значение по умолчанию равно `1`, поэтому пропускается оставшаяся часть итерации текущего цикла.

    <?php

    $arr = ['ноль', 'один', 'два', 'три', 'четыре', 'пять', 'шесть'];

    foreach ($arr as $key => $value) {
        if (0 === ($key % 2)) { // Условие пропуска элементов с чётным ключом
            continue;
        }

        echo $value . "\n";
    }

    ?>

Результат выполнения приведённых примеров:

    один
    три
    пять

    <?php

    $i = 0;

    while ($i++ < 5) {
        echo "Внешний\n";

        while (1) {
            echo "Средний\n";

            while (1) {
                echo "Внутренний\n";
                continue 3;
            }

            echo "Это никогда не выведется.\n";
        }

        echo "Это тоже не выведется.\n";
    }

    ?>

Результат выполнения приведённых примеров:

    Внешний
    Средний
    Внутренний
    Внешний
    Средний
    Внутренний
    Внешний
    Средний
    Внутренний
    Внешний
    Средний
    Внутренний
    Внешний
    Средний
    Внутренний

Пропуск точки запятой после инструкции `continue` сбивает с толку. Вот пример, как лучше не делать:

    <?php

    for ($i = 0; $i < 5; ++$i) {
        if ($i == 2)
            continue
        print "$i\n";
    }

    ?>

Ожидается, что код выведет числа, а не выдаст фатальную ошибку:

    0
    1
    3
    4

Список изменений, которые затронули инструкцию `continue`
Версия | Описание
--- | ---
7.3.0 | Инструкция `continue` внутри инструкции `switch`, которая пытается действовать как инструкция `break` для инструкции `switch`, вызовет ошибку уровня `E_WARNING`.

## switch

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

Инструкция `switch` похожа на серию инструкций IF, которые проверяют одно и то же выражение. Одну и ту же переменную или выражение часто сравнивают с разными значениями, чтобы выполнить ту часть кода, условию выполнения которой соответствует значение переменной или выражения. Инструкция `switch` выполняет такие проверки.

> Замечание: Обратите внимание, что в отличие от отдельных языков программирования, действие инструкции continue распространяется на блок `switch`, а не на отдельный случай, и ведёт себя аналогично инструкции `break`. При вызове инструкции `continue 2` выполнение перейдёт к следующей итерации внешнего цикла, если блок `switch` выполняет проверки внутри цикла.

> Замечание:

> Обратите внимание, конструкция switch/case выполняет нестрогое сравнение.

В следующем примере блоки кода выполняют эквивалентные проверки. Один блок выполняет проверки через серию инструкций `if` и `elseif`, другой — через инструкцию `switch`. Каждый блок кода выдаёт одинаковый результат.

Пример #1 Структура инструкции `switch`

    <?php

    // Инструкция switch:

    switch ($i) {
        case 0:
            echo "Значение переменной \$i равно 0";
            break;
        case 1:
            echo "Значение переменной \$i равно 1";
            break;
        case 2:
            echo "Значение переменной \$i равно 2";
            break;
    }

    // ...эквивалентна:

    if ($i == 0) {
        echo "Значение переменной \$i равно 0";
    } elseif ($i == 1) {
        echo "Значение переменной \$i равно 1";
    } elseif ($i == 2) {
        echo "Значение переменной \$i равно 2";
    }

    ?>

Понимание того, в каком порядке инструкция `switch` выполняет инструкции случаев, помогает избегать ошибок. Инструкция `switch` выполняет строку за строкой, или точнее — выражение за выражением. В начале никакой код не выполняется. PHP начинает выполнение инструкции случаев, только когда находит инструкцию `case`, выражение которой вычисляется как значение, которое совпадает со значением выражения в инструкции `switch`. Тогда PHP или продолжает выполнять инструкции случаев до конца блока `switch`, даже если значение случая не совпадает со значением инструкции switch, или пока не увидит первую инструкцию `break`. PHP продолжит выполнять инструкции следующих случаев, если в конце списка инструкций случая не записали инструкцию `break`. Приведём пример:

    <?php

    switch ($i) {
        case 0:
            echo "Значение переменной \$i равно 0";
        case 1:
            echo "Значение переменной \$i равно 1";
        case 2:
            echo "Значение переменной \$i равно 2";
    }

    ?>

PHP выполнит инструкцию echo каждого случая, если значение переменной $i равно 0! PHP выполнит инструкции echo двух последних случаев, если значение переменной $i равно 1. Код поведёт себя предсказуемо и выведет «Значение переменной $i равно 2», только если значение переменной $i равно 2. Поэтому лучше помнить об инструкциях `break`, даже если в конкретных обстоятельствах инструкции прерывания умышленно не указываются.

В инструкции `switch` условие вычисляется только один раз, а результат сравнивается со значением выражения каждой инструкции `case`. В инструкции `elseif` вычисление условия повторяется. Инструкция `switch` часто работает быстрее, если условие сложнее простого сравнения «и-или» проверяется в плотном цикле.

Список инструкций в секциях case разрешается оставлять пустым, тогда управление передаётся списку инструкций следующей секции case.

    <?php

    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "Значение переменной \$i меньше 3, но не отрицательно";
            break;
        case 3:
            echo "Значение переменной \$i равно 3";
    }

    ?>

Инструкция `default` управляет случаями по умолчанию. Управление переходит к случаю по умолчанию при несовпадении значения выражения switch со значениями выражений других случаев. Приведём пример:

    <?php

    switch ($i) {
        case 0:
            echo "Значение переменной \$i равно 0";
            break;
        case 1:
            echo "Значение переменной \$i равно 1";
            break;
        case 2:
            echo "Значение переменной \$i равно 2";
            break;
        default:
           echo "Значение переменной \$i не равно 0, 1 или 2";
    }

    ?>

> Замечание: Многократные инструкции default вызовут ошибку уровня `E_COMPILE_ERROR`.

> Замечание: Технически инструкцию `default` разрешается указывать в произвольном месте списка случаев. Инструкции случая по умолчанию выполняются, только если ни один другой случай не совпал. Однако, по общему правилу, лучше расположить инструкцию по умолчанию в конце, как последнюю ветвь.

Код не выполнится, как если бы ни одна инструкция `if` не оказалась истинной, если ни одна ветвь инструкций `case` не соответствует значению проверки и инструкцию `default` не указали.

Значение секции case разрешается указывать в виде выражения. Однако это выражение вычисляется само по себе, а затем нестрого сравнивается со значением инструкции switch. Поэтому выражение нельзя использовать для сложных оценок значения конструкции switch. Приведём пример несложной оценки:

    <?php

    $target = 1;
    $start = 3;

    switch ($target) {
        case $start - 1:
            print "A";
            break;
        case $start - 2:
            print "B";
            break;
        case $start - 3:
            print "C";
            break;
        case $start - 4:
            print "D";
            break;
    }

    // Код выведет "B"

    ?>

Для более сложных сравнений в значении инструкции `switch` указывают значение `true`, или выполняют сравнения альтернативным способом — в блоках `if`-`else`.

    <?php

    $offset = 1;
    $start = 3;

    switch (true) {
        case $start - $offset === 1:
            print "A";
            break;
        case $start - $offset === 2:
            print "B";
            break;
        case $start - $offset === 3:
            print "C";
            break;
        case $start - $offset === 4:
            print "D";
            break;
    }

    // Код выведет "B"

    ?>

Блоки switch поддерживают альтернативный синтаксис управляющих конструкций. Дополнительную информацию содержит раздел «Альтернативный синтаксис управляющих конструкций».

    <?php

    switch ($i):
        case 0:
            echo "Значение переменной \$i равно 0";
            break;
        case 1:
            echo "Значение переменной \$i равно 1";
            break;
        case 2:
            echo "Значение переменной \$i равно 2";
            break;
        default:
            echo "Значение переменной \$i не равно 0, 1 или 2";
    endswitch;

    ?>

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

    <?php

    switch ($beer) {
        case 'Tuborg';
        case 'Carlsberg';
        case 'Stella';
        case 'Heineken';
            echo 'Хороший выбор';
            break;
        default;
            echo 'Пожалуйста, выберите заново...';
            break;
    }

    ?>

### Смотрите также

- match

## match

(PHP 8)

Выражение `match` выбирает ветвь вычисления на основе проверки, которая показывает, идентично ли значение условного выражения значению входного условного выражения. Аналогично инструкции `switch` выражение `match` принимает на вход выражение, которое сравнивается с набором альтернатив. В отличие от инструкции `switch`, выражение сопоставления оценивает значение в стиле, который больше похож на тернарный оператор. Выражение выполняет строгое сравнение `===`, а не слабую проверку на равенство `==`, как это делает инструкция `switch`. Выражения сопоставления доступны с PHP 8.0.0.

Пример #1 Структура выражения `match`

    <?php

    $return_value = match (subject_expression) {
        single_conditional_expression => return_expression,
        conditional_expression1, conditional_expression2 => return_expression,
    };

    ?>

Пример #2 Базовый пример сопоставления значений в выражении `match`

    <?php

    $food = 'cake';

    $return_value = match ($food) {
        'apple' => 'На столе лежит яблоко',
        'banana' => 'На столе лежит банан',
        'cake' => 'На столе стоит торт',
    };

    var_dump($return_value);

    ?>

Результат выполнения приведённого примера:

    string(35) "На столе стоит торт"

Пример #3 Пример сопоставления значений в выражении `match` с операторами сравнения

    <?php

    $age = 18;

    $output = match (true) {
        $age < 2 => "Младенец",
        $age < 13 => "Ребёнок",
        $age <= 19 => "Подросток",
        $age >= 40 => "Взрослый",
        $age > 19 => "Молодой человек",
    };

    var_dump($output);

    ?>

Результат выполнения приведённого примера:

    string(8) "Подросток"

> Замечание: Результат выражения `match` использовать не обязательно.

> Замечание: Выражение `match` должно завершаться точкой с запятой `;`, если записывается как отдельное выражение.

Выражение `match` похоже на инструкцию `switch`, за исключением отдельных ключевых отличий:

- В отличие от нестрогого сравнения в инструкции switch, в ветке сопоставления значений в выражении `match` значения сравниваются строго — `===`
- Выражение `match` возвращает значение
- В выражении `match` выполнение кода не переходит к следующей ветви сопоставления значений после первого совпадения значений, в отличие от провалов к следующему случаю в инструкции `switch`
- Выражение `match` должно быть исчерпывающим

Как и инструкциях `switch`, в выражениях `match` ветви сопоставления значений выполняются одна за другой. В начале никакой код не выполняется. Условные выражения оцениваются, только если предыдущие условные выражения не соответствуют входному выражению. Выражение match вычислит только то выражение возврата, которое соответствует условному выражению, значение которого совпало. Приведём пример:

    <?php

    $result = match ($x) {
        foo() => 'value',
        $this->bar() => ..., // Метод $this->bar() не вызывается, если значение возврата функции foo() === $x
        $this->baz => beep(), // Функция beep() выполнится, если только входное выражение $x === $this->baz
        // и т. д.
    };

    ?>

Ветвям сопоставления значений в выражении `match` разрешается содержать множественные выражения, разделённые запятыми. Множественные выражения проверяются по условию логического ИЛИ и представляют короткую запись для множественных ветвей сопоставления значений с одним и тем выражением в правой части.

    <?php

    $result = match ($x) {
        // Эта ветвь сопоставления значений:
        $a, $b, $c => 5,
        // ...эквивалентна следующему набору из трёх ветвей сопоставления:
        $a => 5,
        $b => 5,
        $c => 5,
    };

    ?>

Выражение сопоставления управляет случаями по умолчанию через шаблон `default`. Управление переходит к шаблону по умолчанию при несовпадении значений в предыдущих ветвях сопоставления. Например:

    <?php

    $expressionResult = match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };

    ?>

> Замечание: Многократные шаблоны default вызовут ошибку уровня `E_FATAL_ERROR`.

Выражение `match` должно быть исчерпывающим. Выражение выбрасывает исключение UnhandledMatchError, если входное выражение не обработала ни одна ветвь сопоставления.

Пример #4 Пример необработанного выражения match

    <?php

    $condition = 5;

    try {
        match ($condition) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }

    ?>

Результат выполнения приведённого примера:

    object(UnhandledMatchError)#1 (7) {
      ["message":protected]=>
      string(33) "Unhandled match value of type int"
      ["string":"Error":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(9) "/in/ICgGK"
      ["line":protected]=>
      int(6)
      ["trace":"Error":private]=>
      array(0) {
      }
      ["previous":"Error":private]=>
      NULL
    }

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

Выражение `match` умеет обрабатывать случаи с нетождественными условиями. Для этого входное выражении указывают как значение `true`.

Пример #5 Пример обобщения выражения match для ветвления на основе целочисленных диапазонов

    <?php

    $age = 23;

    $result = match (true) {
        $age >= 65 => 'пожилой',
        $age >= 25 => 'взрослый',
        $age >= 18 => 'совершеннолетний',
        default => 'ребёнок',
    };

    var_dump($result);

    ?>

Результат выполнения приведённого примера:

    string(11) "совершеннолетний"

Пример #6 Пример обобщения выражения match для выбора ветви вычисления на основе содержимого строки

    <?php

    $text = 'Bienvenue chez nous';

    $result = match (true) {
        str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
        str_contains($text, 'Bienvenue'), str_contains($text, 'Bonjour') => 'fr',
        // ...
    };

    var_dump($result);

    ?>

Результат выполнения приведённого примера:

    string(2) "fr"

## declare

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

Конструкция `declare` устанавливает директивы выполнения для блока кода. Синтаксис конструкции `declare` аналогичен синтаксису других конструкций управления потоком:

    declare (directive)
        statement

Часть `directive` задаёт поведение блока `declare`. PHP пока распознаёт только три директивы:

- `ticks`
- `encoding`
- `strict_types`

Директивы поддерживают только литеральные значения, покольку обрабатываются при компиляции файла. Нельзя указывать переменные и константы. Пример:

    <?php

    // Правильно:
    declare(ticks=1);

    // Недопустимо:
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);

PHP выполнит часть `statement` блока `declare` — как PHP выполнит инструкции и какие побочные эффекты возникают во время выполнения, зависит от директивы, которую установили в блоке `directive`.

Конструкцию `declare` разрешается объявлять в глобальной области видимости, чтобы повлиять на весь код за ней (однако, если файл с объявлением конструкции `declare` включили в родительский файл, конструкция не повлияет на родительский файл).

    <?php

    // Это то же самое:

    // Конструкцию declare объявляют вот так:
    declare(ticks=1) {
        // Скрипт записывается внутри блока с фигурными скобками
    }

    // или так:
    declare(ticks=1);
    // Скрипт записывается после объявления конструкции declare

### Тики

Тик — событие, которое возникает каждые N низкоуровневых инструкций, которые парсер отмечает как такт и выполняет внутри блока `declare`. Значение N указывают как `ticks=N` внутри части `directive` блока `declare`.

Парсер отмечает как такт не каждую инструкцию. Обычно условные выражения и выражения аргументов не подсчитываются.

События, которые возникают на каждом тике, помогает определить функция register_tick_function(). Подробности содержит следующий пример. Обратите внимание, что для каждого тика иногда возникает больше одного события.

Пример #1 Пример использования тика

    <?php

    declare(ticks=1);

    // Функция, которую PHP будет вызывать при каждом тике
    function tick_handler()
    {
        echo "PHP вызвал функцию tick_handler()\n";
    }

    register_tick_function('tick_handler'); // Вызывает событие тика

    $a = 1; // Вызывает событие тика

    if ($a > 0) {
        $a += 2; // Вызывает событие тика
        print $a; // Вызывает событие тика
    }

Смотрите также описание функций register_tick_function() и unregister_tick_function().

### Кодировка

Директива `encoding` умеет указывать кодировку скрипта для каждого отдельного скрипта.

Пример #2 Объявление кодировки скрипта

    <?php

    declare(encoding='ISO-8859-1');
    // В этом месте идёт код

Предостережение

Единственный допустимый синтаксис для конструкции declare в сочетании с пространствами имён выглядит вот так: `declare(encoding='...');` где `...` — значение кодировки. В сочетании с пространствами имён запись `declare(encoding='...') {}` вызовет ошибку парсера.

Смотрите также описание директивы zend.script_encoding.

## return

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

Инструкция `return` возвращает управление программой модулю, из которого выполнили вызов. Выполнение программы продолжается в модуле — с выражения, которое идёт за местом вызова.

При вызове из функции инструкция `return` немедленно прекращает выполнение функции и возвращает свой аргумент как значение вызова функции. Инструкция `return` также завершит выполнение инструкции eval() или файла скрипта.

При вызове из глобальной области видимости инструкция `return` завершает выполнение текущего файла скрипта. Управление возвращается в файл, из которого для подключения файла скрипта вызвали инструкции include или require. Значение инструкции `return` вернётся как значение вызова инструкции include, когда файл скрипта подключили через include. Выполнение скрипта завершается, если инструкция `return` вызывается из главного файла скрипта. Если опции конфигурации auto_prepend_file или auto_append_file в файле php.ini называют текущий файл скрипта, выполнение этого файла скрипта завершается.

Дополнительную информацию даёт раздел «Возврат значений».

> Замечание: Обратите внимание: поскольку инструкция `return` — языковая конструкция, а не функция, круглые скобки вокруг аргумента инструкции необязательны и не приветствуются.

> Замечание: При вызове без аргумента инструкция `return` вернёт `null`. При вызове инструкции возврата без аргумента круглые скобки указывать нельзя. Вызов инструкции `return` со скобками, но без аргумента вызовет синтаксическую ошибку.

Начиная с PHP 7.1.0 инструкции возврата без аргумента в функциях, которые объявляют возвращаемый тип, вызывают ошибку уровня `E_COMPILE_ERROR`, если только возвращаемый тип не void, тогда инструкции возврата с аргументом вызывают такую ошибку.

## require

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

Выражение `require` работает идентично выражению include, за исключением того, что выражение `require` также выбросит ошибку Error или до PHP 8.0.0 выдаст ошибку уровня `E_COMPILE_ERROR`, тогда как выражение include только выдаст предупреждение в виде ошибки уровня `E_WARNING`.

Документация по выражению include рассказывает, как это работает.

## include

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

Выражение `include` включает и оценивает код файла как PHP-код.

Документация текущего раздела также относится к выражению require.

Файлы включаются на основе заданного пути к файлу или, если путь не указали, на основе путей в директиве include_path. Перед выдачей ошибки выражение `include` проверит директорию текущего скрипта, в который включается файл, и текущую рабочую директорию, если PHP не нашёл файл в списке путей директивы include_path. Выражение `include` выдаст ошибку уровня `E_WARNING`, если не найдёт файл; поведение отличается от выражения require, которое выдаст фатальную ошибку `E_ERROR`.

Обратите внимание, при недоступности файла для чтения оба выражения выдадут дополнительную ошибку уровня `E_WARNING` перед выдачей окончательной ошибки уровня `E_WARNING` выражением `include` или ошибки уровня `E_ERROR` выражением `require`, которые возникают, когда PHP не находит файл.

PHP проигнорирует директиву include_path, если указали абсолютный путь (который начинается с буквы диска, или с обратного слеша `\` в Windows и с прямого слеша `/` в Unix- и Linux-системах) или путь относительно текущей директории (который начинается с символа `.` или символов `..`). Например, парсер будет искать запрошенный файл в родительской директории, если название файла начинается с `../`.

Документация к директиве include_path подробнее рассказывает об обработке языком PHP включаемых файлов и путей.

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

Пример #1 Простой пример подключения файла выражением `include`

    vars.php
    <?php

    $color = 'зелёное';
    $fruit = 'яблоко';

    ?>

    test.php
    <?php

    echo "Одно $color $fruit"; // Одно

    include 'vars.php';

    echo "Одно $color $fruit"; // Одно зелёное яблоко

    ?>

Внутри функции, в которой включают файл, код включаемого файла ведёт себя так, как будто его определили внутри функции; код последует области видимости переменных функции, в которую включается. Исключение к этому правилу — магические константы, которые выполняются парсером перед включением.

Пример #2 Включение внутри функции

    <?php

    function foo()
    {
        global $color;

        include 'vars.php';

        echo "Одно $color $fruit";
    }

    /**
     * Файл vars.php следует области видимости функции foo(),
     * поэтому переменная $fruit недоступна за пределами области видимости функции.
     * Переменная $color — доступна, поскольку её объявили глобальной
     */

    foo();                     // Одно зелёное яблоко
    echo "Одно $color $fruit"; // Одно зелёное

    ?>

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

PHP разрешает вместо локального пути указывать файлы для включения по URL-адресу, если разрешили работу URL-обёрток с include-выражениями. Файлы включают по HTTP-протоколу или через другие обработчики, которые поддерживает язык. Список протоколов, которые поддерживаются PHP, приводит страница «Протоколы и обёртки». Переменные передают в файл, который включается с удалённого сервера, в строке запроса URL-адреса аналогично передаче аргументов методом GET по протоколу HTTP, если целевой удалённый сервер интерпретирует целевой файл как PHP-код. Включение файла с удалённого сервера отличается от включения файла, который наследует родительскую область видимости файла, в который включается; скрипт выполняется на удалённом сервере, а результат затем включается в локальный скрипт.

Пример #3 Пример включения вывода, который сгенерировал скрипт удалённого сервера, выражением `include` через HTTP-запрос

    <?php

    /**
     * В примере предполагается, что адрес www.example.com настроили на обработку
     * файлов с расширением .php, но не .txt. Кроме того, «Сработает» здесь означает, что переменные
     * $foo и $bar доступны внутри включаемого файла, и значения переменных определили при обработке переменных GET-запроса
     */

    // Не сработает; файл file.txt не обрабатывается адресом www.example.com как PHP-код
    include 'http://www.example.com/file.txt?foo=1&bar=2';

    // Не сработает; включающий скрипт будет искать файл 'file.php?foo=1&bar=2'
    // в локальной файловой системе
    include 'file.php?foo=1&bar=2';

    // Сработает: удалённому скрипту будут доступны переменные $foo и $bar
    include 'http://www.example.com/file.php?foo=1&bar=2';

    ?>

Внимание

# Предупреждение безопасности

Локальный сервер ожидает, что удалённый сервер создаст и вернёт допустимый PHP-код, поскольку скрипт обрабатывается на локальном сервере, даже если удалённый сервер работает на PHP и обработал файл на основе расширения. Вывод только результата обработки файла на удалённом сервере лучше получить вызовом функции readfile(), а при включении PHP-кода из файла на удалённом сервере потребуется соблюдать повышенную осторожность и проверять, чтобы удалённый сервер создал корректный и безопасный код.

Раздел «Удалённые файлы» и описания функций fopen() и file() дают дополнительную информацию.

Обработка значений, которые возвращает выражение включения: при ошибке выражение `include` возвращает значение `FALSE` и выдаёт предупреждение. Успешные включения возвращают значение `1`, если только значение возврата не переопределили включаемым файлом. Допускается выполнять инструкцию return внутри включаемого файла, чтобы завершить процесс выполнения во включаемом файле и вернуться к выполнению родительского файла. Из включаемых файлов также доступен возврат значения. Значение вызова включения получают так же, как если бы вызвали функцию. Невозможно получить значение вызова включения удалённого файла, если только вывод удалённого файла не содержит корректные теги начала и конца PHP-кода, как и с локальными файлами. Переменные, которые объявили внутри PHP-тегов, включатся в текущий скрипт в месте включения файла.

Поскольку выражение `include` относится к языковым конструкциям, круглые скобки вокруг аргумента необязательны. При сравнении значения, которое возвращает выражение включения файла, соблюдают осторожность.

Пример #4 Сравнение значения, которое возвращает выражение include

    <?php

    // Не сработает, PHP интерпретирует выражение как include(('vars.php') == TRUE), то есть include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // Cработает
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }

    ?>

Пример #5 Пример работы выражения `include` с инструкцией return

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // выведет 'PHP'

    $bar = include 'noreturn.php';

    echo $bar; // выведет 1

    ?>

Значение переменной `$bar` равно `1`, поскольку инструкция успешно включила файл. Обратите внимание на разницу между приведёнными примерами. В первом записали return внутри включаемого файла, тогда как во втором — нет. Выражение включения возвращает значение `false` и возникает ошибка уровня `E_WARNING`, если файл невозможно включить.

Главный файл получит доступ к вызову функций, которые определили во включаемом файле, независимо от того, объявили функции до инструкции return во включаемом файле или после. PHP выдаст фатальную ошибку при повторном включении файла с определениями функций, поскольку функции получили определение при первом включении. Лучше включить файл выражением include_once, а не проверять, включался ли файл прежде.

Другой путь «включить» PHP-файл в переменную — захватить вывод функциями контроля вывода вместе с выражением `include`. Например:

Пример #6 Буферизация вывода и включение PHP-файла в строку

    <?php

    $string = get_include_contents('somefile.php');

    function get_include_contents($filename)
    {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            return ob_get_clean();
        }

        return false;
    }

    ?>

Обратите внимание на конфигурационные директивы auto_prepend_file и auto_append_file в файле php.ini, чтобы включать файлы в скрипты автоматически.

> Замечание: Конструкцию нельзя вызывать как функцию переменной или передавать как именованный аргумент, поскольку это языковая конструкция, а не функция.

Дополнительную информацию дают описания функций require, require_once, include_once, get_included_files(), readfile(), virtual() и выражения include_path.

## require_once

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

Выражение `require_once` аналогично require за исключением того, что PHP проверит, включался ли уже данный файл, и если да, не будет включать его ещё раз.

Смотрите документацию include_once для информации по поведению `_once` и чем он отличается от таких же функций, без `_once`.

## include_once

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

Выражение `include_once` включает файл и оценивает код файла как PHP-код во время выполнения скрипта. Поведение выражения повторяет поведение выражения include, а отличие состоит только в том, что если код из файла уже включался, PHP не включит файл повторно, а выражение вернёт `true`. Как подсказывает название выражения — файл включится только один раз.

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

Документация к выражению include подробнее рассказывает о работе функции.

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Изображение любезно предоставил сайт веб-комиксов » xkcd

Оператором `goto` пользуются для перехода к другой части программы. Место для перехода обозначают чувствительной к регистру меткой, за которой ставят двоеточие, а инструкцию задают словом `goto`, за которым идёт целевая метка. У перехода `goto` есть ряд ограничений. Целевая метка будет работать, только если метку указали в том же файле и контексте. То есть нельзя ни выйти из функции или метода, ни перейти в них. Нельзя также перейти внутрь цикла или структуры switch, но выйти получится. Оператор `goto`, например, указывают вместо управляющей конструкци `break` с указателем уровня прерывания.

Пример #1 Пример использования оператора `goto`

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

Результат выполнения приведённого примера:

    Bar

Пример #2 Пример использования оператора `goto` в цикле

    <?php

    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j hit 17';

    ?>

Результат выполнения приведённого примера:

    j hit 17

Пример #3 Это не сработает

    <?php

    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

Результат выполнения приведённого примера:

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# Функции

## Содержание

- Пользовательские функции
- Параметры и аргументы функции
- Возврат значений
- Функции переменных
- Внутренние, или встроенные, функции
- Анонимные функции
- Стрелочные функции
- Синтаксис создания первоклассных callable-значений

## Пользовательские функции

Функции определяют ключевым словом `function`, за которым через пробел идёт название функции и круглые скобки. Круглые скобки оставляют пустыми или определяют в скобках список параметров; параметры разделяют символом `,`. За круглыми скобками идёт пара фигурных скобок — тело функции. Приведём пример определения функции:

Пример #1 Объявление новой функции с названием `foo`

    <?php

    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Пример функции.\n";
        return $retval;
    }

> Замечание:

> С PHP 8.0.0 список параметров допускает завершающую запятую:

>     <?php

>     function foo($arg_1, $arg_2,) {}

В теле функции записывают корректный PHP-код, даже другие функции и определения классов.

Имена функций следуют тем же правилам, что и другие метки в PHP. Корректное имя функции начинается с буквы или знака подчёркивания, за которым идёт любое количество букв, цифр или знаков подчёркивания. В виде регулярного выражения имя выражается так: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Подсказка

Смотрите также «Руководство по именованию».

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

Определение функции описывают до вызова функции, когда функцию определяют по условию, как в двух следующих примерах.

Пример #2 Условные функции

    <?php

    $makefoo = true;

    /* Нельзя вызвать функцию foo() в этом месте,
       поскольку функцию ещё не определили, но обращение
       к функции bar() доступно */
    if (function_exists('foo')) {
        foo();
    } else {
        echo "Функция foo пока не определена.\n";
    }

    bar();

    if ($makefoo) {
        function foo()
        {
            echo "Я не существую, пока выполнение программы не дойдёт до меня.\n";
        }
    }

    /* Теперь безопасно вызываем функцию foo(),
       поскольку выражение переменной $makefoo язык интерпретировал как true */

    if ($makefoo) {
        foo();
    }

    function bar()
    {
        echo "Я существую сразу после запуска программы.\n";
    }

Пример #3 Вложенные функции

    <?php

    function foo()
    {
        function bar()
        {
            echo "Я не существую пока не вызовут функцию foo().\n";
        }
    }

    /* Пока нельзя обратиться к функции bar(),
       поскольку функцию ещё не определили */
    if (function_exists('bar')) {
        bar();
    }

    foo();

    /* Теперь функция bar() доступна для вызова,
       обработка функции foo() сделала её доступной */

    bar();

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

PHP не поддерживает перегрузку функций, также невозможно переопределить или удалить функции, которые объявили раньше.

> Замечание: Имена функций не зависят от регистра символов в кодировке ASCII от `A` до `Z`, хотя хорошим тоном будет вызов функций в том виде, в каком функцию указали в объявлении.

Функции PHP поддерживают как списки аргументов переменной длины, так и значения аргументов по умолчанию. Подробнее об этом рассказывают описания функций func_num_args(), func_get_arg() и func_get_args().

В PHP функции разрешается вызывать рекурсивно.

Пример #4 Рекурсивные функции

    <?php

    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }

    recursion(17);

> Замечание: Рекурсивный вызов функций и методов с глубиной более 100-200 уровней рекурсии может вызвать переполнение стека и привести к аварийному завершению скрипта. В частности, бесконечную рекурсию PHP считает программной ошибкой.

## Параметры и аргументы функции

Параметры объявляются в сигнатуре функции. Информацию в параметры функции передают в списке аргументов. Список аргументов состоит из выражений, которые разделяют запятыми. Выражения в списке аргументов вычисляются слева направо, а результат вычислений присваивается параметрам перед действительным вызовом функции. Такое вычисление называется упреждающим.

PHP поддерживает передачу аргументов по значению, это поведение по умолчанию, и по ссылке, и значения по умолчанию. Списки аргументов переменной длины и именованные аргументы тоже поддерживаются.

> Замечание:

> С PHP 7.3.0 список аргументов при вызове функций допускает завершающую запятую:

>     <?php

>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );

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

Пример #1 Список параметров функции с запятой в конце

    <?php

    function takes_many_args(
        $first_arg,
        $second_arg,
        $a_very_long_argument_name,
        $arg_with_default = 5,
        $again = 'a default string', // До PHP 8.0.0 указывать запятую в конце списка не разрешали
    ) {
        // ...
    }

### Передача аргументов по ссылке

По умолчанию аргументы передаются в функцию по значению. Поэтому если значение аргумента внутри функции изменится, значение переменной, в которой передали аргумент, не изменится за пределами функции. Аргументы передают по ссылке, чтобы разрешить функции изменять значения аргументов.

В описании функции перед именем параметра указывают амперсанд &, когда требуется передача аргумента по ссылке:

Пример #2 Передача аргументов по ссылке

    <?php

    function add_some_extra(&$string)
    {
        $string .= 'и кое-что ещё.';
    }

    $str = 'Это строка, ';
    add_some_extra($str);
    echo $str;    // Конструкция выведет «Это строка, и кое-что ещё.»

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

### Значения по умолчанию для параметров

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

Пример #3 Значения по умолчанию для параметров функций

    <?php

    function makecoffee($type = "капучино")
    {
        return "Готовим чашку $type.\n";
    }

    echo makecoffee();
    echo makecoffee(null);
    echo makecoffee("эспрессо");

Результат выполнения приведённого примера:

    Готовим чашку капучино.
    Готовим чашку .
    Готовим чашку эспрессо.

Значениями по умолчанию для параметров разрешается указывать скалярные значения, массивы (array), специальный тип `null` и начиная с PHP 8.1.0 объекты, которые создают синтаксисом new ClassName().

Пример #4 Нескалярные типы как значения по умолчанию

    <?php

    function makecoffee($types = array("капучино"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker)
            ? "вручную"
            : $coffeeMaker
        ;

        return "Готовлю чашку " . join(", ", $types) . " $device. \n";
    }

    echo makecoffee();
    echo makecoffee(array("капучино", "лавацца"), "в чайнике");

Результат выполнения приведённого примера:

    Готовлю чашку капучино вручную.
    Готовлю чашку капучино, лавацца в чайнике.

Пример #5 Объекты как значения по умолчанию, с PHP 8.1.0

    <?php

    class DefaultCoffeeMaker
    {
        public function brew()
        {
            return "Приготовление кофе.\n";
        }
    }

    class FancyCoffeeMaker
    {
        public function brew()
        {
            return "Приготовление прекрасного кофе только для вас.\n";
        }
    }

    function makecoffee($coffeeMaker = new DefaultCoffeeMaker())
    {
        return $coffeeMaker->brew();
    }

    echo makecoffee();
    echo makecoffee(new FancyCoffeeMaker);

Результат выполнения приведённого примера:

    Приготовление кофе.
    Приготовление прекрасного кофе только для вас.

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

Обратите внимание, необязательные параметры потребуется указать после обязательных, иначе необязательные параметры не получится пропустить при вызове, поскольку функция рассматривает необязательные параметры, которые указали перед обязательными, как обязательные. Рассмотрим следующий пример:

Пример #6 Неправильное определение значений по умолчанию для параметров функции

    <?php

    function makeyogurt($container = "миску", $flavour)
    {
        return "Делаем $container с $flavour йогуртом.\n";
    }

    echo makeyogurt("малиновым"); // Значение «малиновым» получит параметр $container, а не параметр $flavour

Результат выполнения приведённого примера:

    Deprecated: makeyogurt(): Optional parameter $container declared before required parameter $flavour is implicitly treated as a required parameter in script on line 2

    Fatal error: Uncaught ArgumentCountError: Too few arguments to function makeyogurt(), 1 passed in script on line 7 and exactly 2 expected in script:2
    Stack trace:
    #0 script(7): makeyogurt('малиновым')
    #1 {main}
      thrown in script on line 2

Теперь сравним приведённый пример со следующим примером:

Пример #7 Правильное определение значений по умолчанию для параметров функции

    <?php

    function makeyogurt($flavour, $container = "миску")
    {
        return "Делаем $container с $flavour йогуртом.\n";
    }

    echo makeyogurt("малиновым"); // Значение «малиновым» получит параметр $flavour

Результат выполнения приведённого примера:

    Делаем миску с малиновым йогуртом.

Начиная с PHP 8.0.0 для пропуска необязательных параметров передают именованные аргументы.

Пример #8 Правильное определение значений по умолчанию для параметров функции

    <?php

    function makeyogurt($container = "миску", $flavour = "малиновым", $style = "греческим")
    {
        return "Делаем $container с $flavour $style йогуртом.\n";
    }

    echo makeyogurt(style: "натуральным");

Результат выполнения приведённого примера:

    Делаем миску с малиновым натуральным йогуртом.

Начиная с PHP 8.0.0 объявление обязательных параметров после необязательных устарело. Часто из таких ситуаций выходят путём отказа от значения по умолчанию, поскольку функция никогда не присвоит параметру, в который передали аргумент, значение по умолчанию. Исключение из этого правила — параметры вида `Type $param = null`, где значение `null` по умолчанию делает тип неявно обнуляемым. Такое определение устарело с PHP 8.4.0 и теперь обнуляемый тип потребуется указать явно.

Пример #9 Объявление необязательных параметров после обязательных

    <?php
    function foo($a = [], $b) {}     // Функция никогда не присвоит значение по умолчанию;
                                     // определение значения по умолчанию для параметра, который идёт
                                     // перед обязательным, устарело с PHP 8.0.0
    function foo($a, $b) {}          // Определение функционально эквивалентно, но не выдаёт уведомление об устаревании

    function bar(A $a = null, $b) {} // С PHP 8.1.0 параметр $a неявно обязателен, поскольку идёт перед обязательным,
                                     // но неявно обнуляем, поскольку для параметра определили значение по умолчанию null.
                                     // Объявления значения по умолчанию null
                                     // без указания обнуляемого типа устарело с PHP 8.4.0
    function bar(?A $a, $b) {}       // Определение, которое рекомендуют

> Замечание: Начиная с PHP 7.1.0 пропуск аргумента для параметра, для которого не задали значение по умолчанию, выбрасывает исключение ArgumentCountError; в предыдущих версиях выдавалось предупреждение.

> Замечание: Параметрам, которые ожидают аргумент по ссылке, разрешается устанавливать значения по умолчанию.

### Списки аргументов переменной длины

В пользовательских функциях PHP поддерживает списки аргументов переменной длины, параметры для которых определяют оператором из трёх точек `...`, который называется spread-оператором.

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

Пример #10 Оператор `...` для доступа к аргументам

    <?php

    function sum(...$numbers) {
        $acc = 0;

        foreach ($numbers as $n) {
            $acc += $n;
        }

        return $acc;
    }

    echo sum(1, 2, 3, 4);

Результат выполнения приведённого примера:

    10

Spread-оператор `...` указывают также при вызове функции, чтобы распаковать в список аргументов массив (array), или распаковать переменную или литерал, которые принадлежат типу Traversable:

Пример #11 Передача аргументов со spread-оператором `...`

    <?php

    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);

Результат выполнения приведённого примера:

    3
    3

Стандартные позиционные параметры разрешается указывать перед токеном `...`, тогда оператор `...` сгенерирует и добавит в массив только конечные аргументы, которые не соответствуют позиционным.

Перед оператором `...` разрешается также добавлять объявление типа. Тогда функция проверит, что аргументы, которые захватил оператор `...`, соответствуют типу параметра, или выбросит ошибку.

Пример #12 Объявление типа для параметра, который ожидает аргументы переменной длины

    <?php

    function total_intervals($unit, DateInterval ...$intervals)
    {
        $time = 0;

        foreach ($intervals as $interval) {
            $time += $interval->$unit;
        }

        return $time;
    }

    $a = new DateInterval('P1D');
    $b = new DateInterval('P2D');

    echo total_intervals('d', $a, $b).' days';

    // Это не сработает, поскольку null — не объект класса DateInterval
    echo total_intervals('d', null);

Результат выполнения приведённого примера:

    3 days
    Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2
    Stack trace:
    #0 script(15): total_intervals('d', NULL)
    #1 {main}
      thrown in script on line 2

В финале добавим, что аргументы переменной длины разрешается также передавать по ссылке, для этого перед оператором `...` указывают амперсанд (`&`).

### Именованные аргументы

В PHP 8.0.0 как расширение позиционных параметров появились именованные аргументы. Именованные аргументы передаются в функцию на основе имени, а не позиции параметра. Назначение аргумента документирует само себя, аргументы перестают зависеть от порядка, в котором передаются, и разрешается произвольно пропускать значения по умолчанию.

Именованные аргументы передают по названию параметра, за которым идёт двоеточие и значение аргумента. Зарезервированные ключевые слова разрешается указывать как имена параметров. Название параметра потребуется указать как идентификатор, нельзя указывать динамические имена параметров.

Пример #13 Синтаксис именованного аргумента

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // НЕ поддерживается
    function_name($variableStoringParamName: $value);

Пример #14 Сравнение позиционных и именованных аргументов

    <?php
    // Передача позиционных аргументов:
    array_fill(0, 100, 50);

    // Передача именованных аргументов:
    array_fill(start_index: 0, count: 100, value: 50);

Порядок передачи именованных аргументов неважен.

Пример #15 Тот же пример, но с другим порядком аргументов

    <?php
    array_fill(value: 50, count: 100, start_index: 0);

Именованные аргументы разрешается комбинировать с позиционными. Тогда именованные аргументы потребуется передать после позиционных. Разрешается также передавать только часть необязательных аргументов функции в произвольном порядке.

Пример #16 Объединение именованных аргументов с позиционными аргументами

    <?php
    htmlspecialchars($string, double_encode: false);
    // Аналогично
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

При передаче именованных аргументов с одним и тем же названием параметра выбрасывается ошибка Error.

Пример #17 Ошибка, которая возникает при передаче нескольких аргументов с названием одного и того же параметра

    <?php
    function foo($param) {}

    foo(param: 1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    foo(1, param: 2);
    // Error: Named parameter $param overwrites previous argument

Начиная с PHP 8.1.0 разрешается передавать именованные аргументы после распаковки аргументов. Именованный аргумент не должен переопределять распакованный аргумент.

Пример #18 Передача именованных аргументов после распаковки

    <?php

    function foo($a, $b, $c = 3, $d = 4) {
        return $a + $b + $c + $d;
    }

    var_dump(foo(...[1, 2], d: 40)); // 46
    var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46
    var_dump(foo(...[1, 2], b: 20)); // Fatal error: Named parameter $b overwrites previous argument

## Возврат значений

Значения возвращаются необязательной инструкцией возврата. Разрешается возвращать любой тип, включая массивы и объекты. Возврат немедленно завершает выполнение функции и передаёт управление обратно — к той строке кода, в которой вызвали функцию. Подробную информацию о возврате значений даёт описание инструкции return.

> Замечание:

> Функция вернёт значение `null`, если инструкцию return не указали.

### Инструкция return

Пример #1 Пример функции с инструкцией return

    <?php

    function square($num)
    {
        return $num * $num;
    }

    echo square(4); // Выводит 16

Функция не умеет возвращать больше одного значения, но аналогичного результата добиваются возвратом массива.

Пример #2 Возврат набора значений в виде массива

    <?php

    function small_numbers()
    {
        return [0, 1, 2];
    }

    // Деструктуризация массива будет собирать каждый элемент массива индивидуально
    [$zero, $one, $two] = small_numbers();
    var_dump($zero, $one, $two);

    // До версии 7.1.0 единственной эквивалентной альтернативой была языковая конструкция list()
    list($zero, $one, $two) = small_numbers();

Оператор & указывают и в описании функции, и в момент присваивания возвращаемого значения переменной, чтобы функция возвращала результат по ссылке:

Пример #3 Возврат результата по ссылке

    <?php

    function &returns_reference()
    {
        return $someref;
    }

    $newref =& returns_reference();

Дополнительную информацию о ссылках даёт раздел документации «Объяснение ссылок».

## Функции переменных

PHP поддерживает концепцию функций переменных. Это означает, что если к имени переменной присоединили круглые скобки, PHP ищет функцию с тем же именем, что и результат вычисления переменной, и пробует выполнить функцию. Этим синтаксисом описывают callback-функции, таблицы функций и т. д.

Функции переменных не работают с языковыми конструкциями echo, print, unset(), isset(), empty(), include, require и т. п. Напишите функцию-обёртку, чтобы эти конструкции работали как функции переменных.

Пример #1 Пример функции переменной

    <?php

    function foo() {
        echo "В foo()\n";
    }

    function bar($arg = '')
    {
        echo "В bar(); аргумент был '$arg'.\n";
    }

    // Функция-обёртка для echo
    function echoit($string)
    {
        echo $string;
    }

    $func = 'foo';
    $func();        // Вызывает функцию foo()

    $func = 'bar';
    $func('test');  // Вызывает функцию bar()

    $func = 'echoit';
    $func('test');  // Вызывает функцию echoit()

Синтаксис функций переменных работает также для вызова методов объектов.

Пример #2 Пример метода переменной

    <?php

    class Foo
    {
        function Variable()
        {
            $name = 'Bar';
            $this->$name(); // Вызывает метод Bar()
        }

        function Bar()
        {
            echo "Это Bar";
        }
    }

    $foo = new Foo();
    $funcname = "Variable";
    $foo->$funcname();  // Вызывает $foo->Variable()

При вызове статических методов вызов функции «сильнее», чем оператор доступа к статическому свойству:

Пример #3 Пример вызова метода переменной со статическим свойством

    <?php

    class Foo
    {
        static $variable = 'статическое свойство';

        static function Variable()
        {
            echo "Вызов метода Variable\n";
        }
    }

    echo Foo::$variable ."\n"; // Это выведет «статическое свойство». В области видимости класса нужна переменная $variable
    $variable = "Variable";
    Foo::$variable();  // Вызывает $foo->Variable() после прочтения переменной $variable в текущей области видимости

Результат выполнения приведённого примера:

    статическое свойство
    Вызов метода Variable

Пример #4 Сложные callable-функции

    <?php

    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }

        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // Выведет "bar"
    $func = array(new Foo(), "baz");
    $func(); // Выведет "baz"
    $func = "Foo::bar";
    $func(); // Выведет "bar"

### Смотрите также

- is_callable()
- call_user_func()
- function_exists()
- Переменные переменных

## Внутренние, или встроенные, функции

PHP поставляется с набором языковых конструкций и встроенных функций. Отдельные функции требуют, чтобы PHP собрали с конкретными модулями, иначе PHP генерирует фатальные ошибки о неизвестной функции. Например, чтобы использовать функции для работы с изображениями наподобие imagecreatetruecolor(), требуется собрать PHP с поддержкой модуля GD. Требуется собрать PHP с поддержкой модуля MySQLi, чтобы использовать функцию mysqli_connect(). Ядро каждой версии PHP включает функции обработки строк и функции для работы с переменными. Вызов функции phpinfo() или get_loaded_extensions() покажет, какие модули загрузил PHP. Часть модулей PHP включает по умолчанию. Документация описывает каждый модуль отдельно. О настройке PHP подробнее рассказывают разделы «Конфигурация», «Установка» и разделы, которые описывают отдельные модули.

Раздел «Как читать определения функции» объясняет, как читать и интерпретировать прототипы функций. Программист должен понимать, что возвращает функция, или как функция модифицирует аргументы, которые передали в функцию. Функция str_replace(), например, вернёт изменённую строку, тогда как функция usort() работает непосредственно с переменной, которую передали в функцию. О каждой функции рассказывает отдельная страница документации: описывает параметры, изменения поведения, значения, которые возвращает функция в случае успешного выполнения или когда возникает ошибка, доступность функции в одной или другой версии PHP. Знание важных и часто тонких различий — ключ к правильному PHP-коду.

> Замечание: Неясно, какое значение вернёт функция, если аргументы, которые передали в функцию, не соответствуют ожиданиям функции; например, передали массив (array) вместо строки (string). Скорее всего, функция вернёт `null`, но это только соглашение, на него нельзя полагаться. Начиная с PHP 8.0.0 в таком случае требуется выбрасывать исключение TypeError.

> Замечание:

> В нестрогом режиме типизации скалярные типы встроенных функций по умолчанию обнуляемы, — принимают значение `null`. Начиная с PHP 8.1.0 передача значения `null` в параметр встроенной функции, который не объявили обнуляемым, не рекомендуется, и в принудительном режиме выдаёт уведомление об устаревании, чтобы соответствовать поведению пользовательских функций, в которых требуется явно помечать скалярные типы как обнуляемые.

> Функция strlen(), например, ожидает, что параметр `$string` будет необнуляемой строкой (string). По историческим причинам в принудительном режиме PHP разрешает передавать значение `null` для этого параметра, и параметр неявно приводится к строке (string). В результате получается значение `""`. В строгом режиме выбрасывается исключение TypeError.

>     <?php

>     var_dump(strlen(null));
>     // "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" начиная с PHP 8.1.0
>     // int(0)

>     var_dump(str_contains("foobar", null));
>     // "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" начиная с PHP 8.1.0
>     // bool(true)

### Смотрите также

- function_exists()
- справочник функций
- get_extension_funcs()
- dl()

## Анонимные функции

Анонимные функции, которые также знают как замыкания (`closures`), — функции без названия. Анонимные функции вызывают или передают как значения в параметры с типом callable.

PHP создаёт анонимные функции через класс Closure.

Пример #1 Пример анонимной функции

    <?php

    echo preg_replace_callback(
        '~-([a-z])~',
        function ($match) {
            return strtoupper($match[1]);
        },
        'hello-world'
    );
    // Выведет helloWorld

Замыкания также присваивают как значения переменным; PHP автоматически преобразовывает такие выражения в экземпляры внутреннего класса Closure. Замыкания присваивают переменной тем же синтаксисом, что и для другого присваивания, включая конечную точку с запятой:

Пример #2 Пример присваивания анонимной функции как значения переменной

    <?php

    $greet = function($name) {
        printf("Привет, %s\r\n", $name);
    };

    $greet('Мир');
    $greet('PHP');

Замыкания умеют наследовать переменные из родительской области видимости. Для связывания с анонимной функцией каждую такую переменную передают в языковую конструкцию `use`. Начиная с PHP 7.1 нельзя связывать с замыканием superglobals, псевдопеременную $this и переменные, названия которых совпадают с названиями параметров анонимной функции. Объявление типа значения возврата указывается после предложения `use`.

Пример #3 Пример наследования переменных из родительской области видимости

    <?php

    $message = 'привет';

    // Без конструкции use
    $example = function () {
        var_dump($message);
    };
    $example();

    // Наследуем переменную $message
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // Анонимная функция наследует переменную с тем значением, которое переменная
    // содержала перед определением функции, а не в месте вызова функции
    $message = 'мир';
    $example();

    // Сбросим message
    $message = 'привет';

    // Наследование по ссылке
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // Значение ссылки, которое изменили в родительской области видимости,
    // отражается внутри вызова функции
    $message = 'мир';
    $example();

    // Замыкания умеют принимать стандартные аргументы
    $example = function ($arg) use ($message) {
        var_dump($arg . ', ' . $message);
    };
    $example("привет");

    // Объявление типа значения возврата идёт после конструкции use
    $example = function () use ($message): string {
        return "привет, $message";
    };
    var_dump($example());

Вывод приведённого примера будет похож на:

    Notice: Undefined variable: message in /example.php on line 6
    NULL
    string(12) "привет"
    string(12) "привет"
    string(12) "привет"
    string(6) "мир"
    string(20) "привет, мир"
    string(20) "привет, мир"

Начиная с PHP 8.0.0 списку переменных, которые функция наследует из области видимости, разрешается включать конечную запятую, которую парсер проигнорирует.

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

Пример #4 Замыкания и область видимости

    <?php

    // Базовая корзина покупок, которая содержит список
    // продуктов и количество каждого продукта. Включает метод,
    // который вычисляет общую цену элементов корзины через
    // callback-замыкание
    class Cart
    {
        const PRICE_BUTTER  = 1.00;
        const PRICE_MILK    = 3.00;
        const PRICE_EGGS    = 6.95;

        protected $products = array();

        public function add($product, $quantity)
        {
            $this->products[$product] = $quantity;
        }

        public function getQuantity($product)
        {
            return isset($this->products[$product]) ? $this->products[$product] :
                   FALSE;
        }

        public function getTotal($tax)
        {
            $total = 0.00;

            $callback = function ($quantity, $product) use ($tax, &$total)
            {
                $pricePerItem = constant(
                    __CLASS__ . "::PRICE_" . strtoupper($product)
                );

                $total += ($pricePerItem * $quantity) * ($tax + 1.0);
            };

            array_walk($this->products, $callback);
            return round($total, 2);
        }
    }

    $my_cart = new Cart;

    // Добавляем элементы в корзину
    $my_cart->add('butter', 1);
    $my_cart->add('milk', 3);
    $my_cart->add('eggs', 6);

    // Выводим общую сумму с налогом 5 % на продажу
    print $my_cart->getTotal(0.05) . "\n";
    // Результат будет равен 54.29

Пример #5 Автоматическая привязка переменной `$this`

    <?php

    class Test
    {
        public function testing()
        {
            return function () {
                var_dump($this);
            };
        }
    }

    $object = new Test();
    $function = $object->testing();
    $function();

Результат выполнения приведённого примера:

    object(Test)#1 (0) {
    }

При объявлении замыкания в контексте класса текущий класс автоматически привязывается к замыканию, а члены функции получают доступ к переменной `$this` в области видимости функции. Статические анонимные функции определяют, когда автоматическая привязка к текущему классу не требуется.

### Статические анонимные функции

Анонимные функции разрешается объявлять статически. Это предотвратит автоматическое связывание замыкания с текущим классом. Объекты тоже не связываются со статическим замыканием во время выполнения кода.

Пример #6 Попытка обратиться к переменной `$this` в статической анонимной функции

    <?php

    class Foo
    {
        function __construct()
        {
            $func = static function () {
                var_dump($this);
            };

            $func();
        }
    };

    new Foo();

Результат выполнения приведённого примера:

    Fatal error: Uncaught Error: Using $this when not in object context in script:7
    Stack trace:
    #0 script(9): Foo::{closure:Foo::__construct():6}()
    #1 script(12): Foo->__construct()
    #2 {main}
      thrown in script on line 7

Пример #7 Попытка связать объект со статической анонимной функцией

    <?php

    $func = static function () {
        // Тело функции
    };

    $func = $func->bindTo(new stdClass());
    $func();

Результат выполнения приведённого примера:

    Warning: Cannot bind an instance to a static closure, this will be an error in PHP 9 in script on line 5

    Fatal error: Uncaught Error: Value of type null is not callable in script:6
    Stack trace:
    #0 {main}
      thrown in script on line 6

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Замыкания, которые создали из магических методов, научились принимать именованные аргументы.
7.1.0 | Анонимным функциям нельзя замыкаться вокруг superglobals, переменной $this или другой переменной, имя которой совпадает с названием параметра.

### Примечания

> Замечание: Внутри замыканий разрешается вызывать функции func_num_args(), func_get_arg() и func_get_args().

## Стрелочные функции

Стрелочные функции появились в PHP 7.4 как лаконичный синтаксис для анонимных функций.

И анонимные, и стрелочные функции реализовали через класс Closure.

Базовая форма записи стрелочных функций: `fn (argument_list) => expr`.

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

Когда стрелочная функция работает с переменной, которую определили в родительской области, переменная неявно захватывается по значению. В следующем примере функции $fn1 и $fn2 ведут себя одинаково.

Пример #1 Стрелочные функции захватывают переменные по значению автоматически

    <?php

    $y = 1;

    $fn1 = fn($x) => $x + $y;

    // Эквивалентно получению переменной $y по значению:
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));

Результат выполнения приведённого примера:

    4

Это также работает во вложенных стрелочных функциях:

Пример #2 Стрелочные функции захватывают переменные по значению автоматически, даже когда функции вложены

    <?php

    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;

    // Выведет 51
    var_export($fn(5)(10));

Как и в анонимных функциях, синтаксис стрелочных функций допускает произвольные сигнатуры функций, включая типы параметров и возвращаемых значений, значения по умолчанию, переменные и передачу и возврат по ссылке. Корректные примеры стрелочных функций:

Пример #3 Примеры определения стрелочных функций

    <?php
    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

Стрелочные функции привязывают переменные по значению. Это примерно эквивалентно выполнению конструкции `use($x)` для каждой переменной $x, с которой стрелочная функция будет работать внутри. Привязка по значению означает, что внутри стрелочной функции невозможно изменить значения из внешней области видимости. Вместо этого для привязок по ссылкам можно пользоваться анонимными функциями.

Пример #4 Стрелочные функции не умеют изменять значения из внешней области видимости

    <?php

    $x = 1;
    $fn = fn() => $x++; // Функция ничего не изменит
    $fn();
    var_export($x);     // Функция выведет значение 1

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Появились стрелочные функции.

### Примечания

> Замечание: Из стрелочной функции разрешается вызывать функции func_num_args(), func_get_arg() и func_get_args().

## Синтаксис создания первоклассных callable-значений

Синтаксис преобразования callable-выражений в объекты первого класса, которые возможно передавать как аргумент, возвращать из функций или присваивать переменным, представили в PHP 8.1.0 как способ, который создаёт анонимные функции из callable-выражений. Новый синтаксис вытесняет предыдущий callable-синтаксис со строками и массивами. Преимущество нового синтаксиса состоит в доступности для статического анализа и наследовании новым синтаксисом области видимости переменных в точке получения callable-выражения.

Синтаксис `CallableExpr(...)` создаёт объект Closure из выражения, доступного для вызова, где `CallableExpr` — элемент синтаксиса, который принимает выражение, доступное для прямого вызова в терминах PHP-грамматики:

Пример #1 Пример создания первоклассных вызываемых значений синтаксисом с многоточием

    <?php
    class Foo
    {
       public function method() {}
       public static function staticmethod() {}
       public function __invoke() {}
    }

    $obj = new Foo();
    $classStr = 'Foo';
    $methodStr = 'method';
    $staticmethodStr = 'staticmethod';

    $f1 = strlen(...);
    $f2 = $obj(...);  // Вызов объекта как функции
    $f3 = $obj->method(...);
    $f4 = $obj->$methodStr(...);
    $f5 = Foo::staticmethod(...);
    $f6 = $classStr::$staticmethodStr(...);

    // Традиционный синтаксис callable-выражений со строками и массивами
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'method'](...);
    $f9 = [Foo::class, 'staticmethod'](...);

> Замечание:

> Оператор `...` — часть синтаксиса, а не пропуск.

Выражение `CallableExpr(...)` и метод Closure::fromCallable() семантически идентичны. Поэтому в отличие от callable-синтаксиса со строками и массивами, синтаксис `CallableExpr(...)` учитывает область видимости контекста, в котором создаёт замыкание:

Пример #2 Сравнение области видимости синтаксиса `CallableExpr(...)` и традиционного callable-синтаксиса

    <?php
    class Foo
    {
        public function getPrivateMethod()
        {
            return [$this, 'privateMethod'];
        }

        private function privateMethod()
        {
            echo __METHOD__, "\n";
        }
    }

    $foo = new Foo();
    $privateMethod = $foo->getPrivateMethod();
    $privateMethod();
    // Fatal error: Call to private method Foo::privateMethod() from global scope
    // Причина фатальной ошибки состоит в вызове замыкания вне класса Foo,
    // при том что видимость метода проверяется в контексте вызова, а не определения

    <?php
    class Foo1
    {
        public function getPrivateMethod()
        {
            // Callable-выражение унаследует область видимости переменных,
            // в которой выражение получат
            return $this->privateMethod(...); // Значение возврата идентично
                                              // значению вызова Closure::fromCallable([$this, 'privateMethod']);
        }

        private function privateMethod()
        {
            echo __METHOD__, "\n";
        }
    }

    $foo1 = new Foo1;
    $privateMethod = $foo1->getPrivateMethod();
    $privateMethod();  // Foo1::privateMethod

> Замечание:

> Синтаксисом наподобие `new Foo(...)` нельзя создать объект, поскольку синтаксис `new Foo()` не относится к вызовам.

> Замечание:

> Синтаксис, который создаёт объекты первого класса из callable-выражений, нельзя комбинировать с null-безопасным оператором. Каждая из следующих строк вызывает ошибку времени компиляции:

>     <?php
>     $obj?->method(...);
>     $obj?->prop->method(...);

# Классы и объекты

## Содержание

- Введение
- Основы
- Свойства
- Хуки свойств
- Константы классов
- Автоматическая загрузка классов
- Конструкторы и деструкторы
- Область видимости
- Наследование
- Оператор разрешения области действия ::
- Ключевое слово static
- Абстракция класса
- Интерфейсы объектов
- Трейты
- Анонимные классы
- Перегрузка
- Итераторы объектов
- Магические методы
- Ключевое слово final
- Клонирование объектов
- Сравнение объектов
- Позднее статическое связывание
- Объекты и ссылки
- Сериализация объектов
- Ковариантность и контравариантность
- Ленивые объекты
- Журнал изменений ООП

## Введение

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

PHP обрабатывает объекты так же, как ссылки или дескрипторы, поэтому каждая переменная, которой присвоили объект, содержит ссылку на объект, а не копию самого объекта. Подробнее об этом рассказывает раздел «Объекты и ссылки».

Подсказка

Смотрите также «Руководство по именованию».

## Основы

### class

Каждое определение класса начинается с ключевого слова `class`, затем идёт имя класса, а потом пара фигурных скобок, в которых определяют свойства и методы класса.

Для класса разрешается выбирать произвольное название, при условии, что это не зарезервированное слово языка PHP. Начиная с PHP 8.4.0 объявление названия класса, которое состоит из одного символа подчёркивания `_`, устарело. Допустимое название класса начинается с буквы или подчеркивания, за которым идёт произвольное количество букв, цифр или символов подчеркивания. В виде регулярного выражения правило именования классов выглядят так: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Классы содержат константы, переменные, которые в классах называют свойствами, и функции, которые в классах называют методами.

Пример #1 Простое определение класса

    <?php

    class SimpleClass
    {
        // Объявление свойства
        public $var = 'значение по умолчанию';

        // Объявление метода
        public function displayVar() {
            echo $this->var;
        }
    }

    ?>

Псевдопеременная $this доступна, когда метод вызывается из контекста объекта. Переменная $this — значение вызывающего объекта.

Внимание

Вызов нестатического метода статически выбрасывает исключение Error. До PHP 8.0.0 это приводило к уведомлению об устаревании, а переменная $this оставалась неопределённой.

Пример #2 Примеры псевдопеременной $this

    <?php

    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo 'PHP определил переменную $this (';
                echo get_class($this);
                echo ")\n";
            } else {
                echo "PHP не определил переменную \$this.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();

    ?>

Результат выполнения приведённого примера в PHP 7:

    PHP определил переменную $this (A)

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
    PHP не определил переменную $this.

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    PHP не определил переменную $this.

    Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    PHP не определил переменную $this.

Результат выполнения приведённого примера в PHP 8:

    PHP определил переменную $this (A)

    Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
    Stack trace:
    #0 {main}
      thrown in %s  on line 27

#### Классы только для чтения

Начиная с PHP 8.2.0 класс можно пометить модификатором readonly. Пометка класса как readonly добавит модификатор readonly к каждому объявленному свойству и не разрешит создавать динамические свойства. Поддержку динамических свойств невозможно добавить даже атрибутом AllowDynamicProperties. Попытка это сделать вызовет ошибку компиляции.

    <?php

    #[\AllowDynamicProperties]
    readonly class Foo {}

    // Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo

    ?>

В классах только для чтения нельзя объявлять нетипизированные и статические свойства, поскольку такие свойства нельзя помечать модификатором `readonly`:

    <?php

    readonly class Foo
    {
        public $bar;
    }

    // Fatal error: Readonly property Foo::$bar must have type

    ?>

    <?php

    readonly class Foo
    {
        public static int $bar;
    }

    // Fatal error: Readonly class Foo cannot declare static properties

    ?>

Класс readonly получится расширить тогда и только тогда, когда дочерний класс тоже readonly-класс.

### Ключевое слово new

Экземпляр класса создаётся директивой `new`. Новый объект создаётся, если только конструктор объекта во время ошибки не выбрасывает исключение. Класс рекомендуют определять перед тем, как создавать экземпляр класса; иногда это обязательное требование.

PHP создаст новый экземпляр класса, если с ключевым словом `new` указали переменную, которая содержит строку (string) с названием класса. Чтобы создать экземпляр класса, который определили в пространстве имён, требуется указывать абсолютное имя класса.

> Замечание:

> Круглые скобки после названия класса разрешается опускать, если нет аргументов, которые требуется передать в конструктор класса.

Пример #3 Создание экземпляра класса

    <?php

    class SimpleClass {}

    $instance = new SimpleClass();
    var_dump($instance);

    // Или создаём экземпляр класса через переменную:
    $className = 'SimpleClass';
    $instance = new $className(); // Аналогично new SimpleClass()
    var_dump($instance);

    ?>

С PHP 8.0.0 поддерживается ключевое слово `new` с произвольными выражениями. Это разрешает создавать более сложные экземпляры, если выражение создаёт строку (string). Выражения берут в круглые скобки.

Пример #4 Пример новых объектов, которые создали через произвольные выражения

Пример показывает варианты допустимых произвольных выражений, которые представляют имя класса. Пример вызова функции, конкатенации строк и константы `::class`.

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return 'ClassA';
    }

    var_dump(new (getSomeClass()));
    var_dump(new ('Class' . 'B'));
    var_dump(new ('Class' . 'C'));
    var_dump(new (ClassD::class));

    ?>

Результат выполнения приведённого примера в PHP 8:

    object(ClassA)#1 (0) {
    }
    object(ClassB)#1 (0) {
    }
    object(ClassC)#1 (0) {
    }
    object(ClassD)#1 (0) {
    }

В контексте класса возможно создать новый объект выражениями `new self` и `new parent`.

Переменная получит доступ к тому же экземпляру класса, что и объект, который присвоили переменной. Такое же поведение наблюдается при передаче экземпляра класса в функцию. Копию объекта создают клонированием.

Пример #5 Присваивание объекта

    <?php

    class SimpleClass
    {
        public string $var;
    }

    $instance = new SimpleClass();

    $assigned   =  $instance;
    $reference  =& $instance;

    $instance->var = 'У экземпляра класса, на который ссылается переменная $assigned, тоже будет это значение';

    $instance = null; // Значения переменных $instance и $reference станут равны null

    var_dump($instance);
    var_dump($reference);
    var_dump($assigned);

    ?>

Результат выполнения приведённого примера:

    NULL
    NULL
    object(SimpleClass)#1 (1) {
      ["var"]=>
      string(152) "У экземпляра класса, на который ссылается переменная $assigned, тоже будет это значение"
    }

Экземпляры объектов создают несколькими способами:

Пример #6 Новые объекты

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // По имени класса
    $obj2 = new $obj1(); // Через переменную, которая содержит объект
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // Через метод класса
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // Через метод класса-наследника
    var_dump($obj4 instanceof Child);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)

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

Пример #7 Доступ к свойствам и методам только что созданного объекта

    <?php

    echo (new DateTime())->format('Y'), PHP_EOL;

    // Начиная с PHP 8.4.0 брать в скобки выражение new не обязательно
    echo new DateTime()->format('Y'), PHP_EOL;

    ?>

Вывод приведённого примера будет похож на:

    2025
    2025

> Замечание: До PHP 7.1 язык не вычислял значения аргументов в круглых скобках выражения, которым инстанциировали объект класса, если в классе не было метода-конструктора.

### Свойства и методы

Свойства и методы класса живут в отдельных «пространствах имён», поэтому свойства и методы допустимо называть одинаково. У ссылок на свойства и методы одинаковая нотация, и получит ли код доступ к свойству или вызовет метод — зависит только от контекста, т. е. обращаются ли к переменной или вызывают функцию.

Пример #8 Сравнение доступа к свойству и вызова метода

    <?php

    class Foo
    {
        public $bar = 'свойство';

        public function bar()
        {
            return 'метод';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    свойство
    метод

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

Пример #9 Вызов анонимной функции, которую содержит свойство

    <?php

    class Foo
    {
        public $bar;

        public function __construct()
        {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    42

### Ключевое слово extends

Класс умеет наследовать константы, методы и свойства другого класса через ключевое слово `extends` в объявлении класса. Невозможно наследовать больше одного класса, одному классу разрешено наследовать только один базовый класс.

Константы, методы и свойства, которые унаследовал класс, разрешается переопределять в дочернем классе путём повторного объявления с таким же именем, которое определили в родительском классе. Метод или константу нельзя переопределить, если в родительском классе метод или константу определили окончательными — с ключевым словом final. Доступ к переопределённым методам или статическим свойствам родительского класса получают, когда ссылаются на них через parent::.

> Замечание: С PHP 8.1.0 разрешается объявлять константы окончательными.

Пример #10 Простое наследование классов

    <?php

    class SimpleClass
    {
        function displayVar()
        {
            echo "Родительский класс\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
        // Переопределение родительского метода
        function displayVar()
        {
            echo "Дочерний класс\n";
            parent::displayVar();
        }
    }

    $extended = new ExtendClass();
    $extended->displayVar();

    ?>

Результат выполнения приведённого примера:

    Дочерний класс
    Родительский класс

#### Правила совместимости сигнатур

При переопределении метода сигнатура метода должна быть совместима с родительским методом. В противном случае PHP выдаст фатальную ошибку или, до PHP 8.0.0, сгенерирует ошибку уровня `E_WARNING`. Сигнатура совместима, если она соответствует правилам вариантности, делает обязательный параметр необязательным, добавляет только необязательные новые параметры и не ограничивает, а только ослабляет видимость. Эти правила называются принципом подстановки Барбары Лисков, или сокращённо LSP. Правила совместимости не распространяются на конструктор и сигнатуру `private`-методов, и поэтому они не выдадут фатальную ошибку, если сигнатура не соответствует.

Пример #11 Совместимость дочерних методов

    <?php

    class Base
    {
        public function foo(int $a)
        {
            echo "Допустимо\n";
        }
    }

    class Extend1 extends Base
    {
        function foo(int $a = 5)
        {
            parent::foo($a);
        }
    }

    class Extend2 extends Base
    {
        function foo(int $a, $b = 5)
        {
            parent::foo($a);
        }
    }

    $extended1 = new Extend1();
    $extended1->foo();
    $extended2 = new Extend2();
    $extended2->foo(1);

    ?>

Результат выполнения приведённого примера:

    Допустимо
    Допустимо

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

Пример #12 Фатальная ошибка, когда дочерний метод удаляет параметр

    <?php

    class Base
    {
        public function foo(int $a = 5)
        {
            echo "Допустимо\n";
        }
    }

    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

    ?>

Результат выполнения приведённого примера в PHP 8 аналогичен:

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Пример #13 Фатальная ошибка, когда дочерний метод делает необязательный параметр обязательным

    <?php

    class Base
    {
        public function foo(int $a = 5)
        {
            echo "Допустимо\n";
        }
    }

    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

    ?>

Результат выполнения приведённого примера в PHP 8 аналогичен:

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

Внимание

Переименование параметра метода в дочернем классе не относится к несовместимости сигнатуры. Однако это не рекомендуется, поскольку приведёт к исключению Error во время выполнения, если передавать именованные аргументы.

Пример #14 Ошибка передачи именованных аргументов в параметры, которые переименовали в дочернем классе

    <?php

    class A
    {
        public function test($foo, $bar) {}
    }

    class B extends A
    {
        public function test($a, $b) {}
    }

    $obj = new B();

    // Передача параметров согласно контракту метода A::test()
    $obj->test(foo: "foo", bar: "bar"); // ОШИБКА!

    ?>

Вывод приведённого примера будет похож на:

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### Константа ::class

Ключевым словом `class` также разрешают имя класса. Запись `ClassName::class` вернёт абсолютное имя класса `ClassName`. Это полезно при работе с классами, которые определили в пространстве имён.

Пример #15 Разрешение имени класса

    <?php

    namespace NS {
        class ClassName {}

        echo ClassName::class;
    }

    ?>

Результат выполнения приведённого примера:

    NS\ClassName

> Замечание:

> Разрешение имени класса через конструкцию `::class` — преобразование во время компиляции. Это означает, что в момент, когда компилятор создаёт строку с именем класса, PHP ещё не выполнил автозагрузку класса. Следствием этого становится то, что имена классов разворачиваются, даже если класс не существует. При этом ошибку PHP не выдаёт.

> Пример #16 Разрешение имени несуществующего класса

>     <?php

>     print Does\Not\Exist::class;

>     ?>

> Результат выполнения приведённого примера:

>     Does\Not\Exist

Начиная с PHP 8.0.0 константа `::class` научилась разрешать имена объектов. Это разрешение константа совершает при выполнении кода, а компиляции. Результат аналогичен вызову функции get_class() на объекте.

Пример #17 Разрешение имени объекта

    <?php

    namespace NS {
        class ClassName {}

        $c = new ClassName();
        print $c::class;
    }

    ?>

Результат выполнения приведённого примера:

    NS\ClassName

### Null-безопасные методы и свойства

Оператор nullsafe появился в PHP 8.0.0 и разрешил безопасно обращаться к свойствам и методам: `?->`. Null-безопасный оператор работает аналогично доступу к свойству или методу, как описывали предыдущие параграфы, за исключением возврата значения `null` вместо генерации исключения, когда разыменовываемый объект равен `null`; PHP пропустит остаток цепочки обращений, если разыменование в цепочке получит значение `null`.

Результат аналогичен предварительному оборачиванию каждого обращения в функцию is_null(), но более компактный.

Пример #18 Пример работы Nullsafe-оператора

    <?php

    // Начиная с PHP 8.0.0 эта строка:
    $result = $repository?->getUser(5)?->name;

    // эквивалентна следующему блоку кода:
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);

        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }

    ?>

> Замечание:

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

## Свойства

Переменные-члены класса называются свойствами. В других языках аналогичные элементы называются полями и другими терминами, но в PHP-документации переменные-члены класса называются свойствами. Свойства класса определяют хотя бы одним модификатором (которые описывают разделы «Область видимости», «Ключевое слово static» или начиная с PHP 8.1.0 readonly), за которым начиная с PHP 7.4 следует необязательное, за исключением `readonly`-свойств, объявление типа, после которого идёт стандартное объявление переменной. При объявлении свойства класса переменную возможно инициализировать, но начальное значение переменной потребуется указать как постоянное значение.

> Замечание:

> Устаревший способ объявления свойств класса — ключевое слово `var` вместо модификатора.

> Замечание: Свойство, которое объявили без модификатора раздела «Область видимости», PHP объявит как `public`.

Внутри методов класса доступ к нестатическим свойствам получают через оператор объекта `->` — $this->property, где `property` — имя свойства. Доступ к статическим свойствам получают через оператор двойного двоеточия `::` — self::$property. Дополнительную информацию об отличиях статических свойств от нестатических даёт раздел «Ключевое слово static».

Псевдопеременная $this доступна внутри каждого метода класса, если метод вызывается из контекста объекта. Переменная $this — значение вызывающего объекта.

Пример #1 Объявление свойств

    <?php

    class SimpleClass
    {
       public $var1 = 'hello ' . 'world';
       public $var2 = <<<EOD
    hello world
    EOD;
       public $var3 = 1+2;
       // Неправильное определение свойств:
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // Правильное определение свойств:
       public $var6 = myConstant;
       public $var7 = [true, false];

       public $var8 = <<<'EOD'
    hello world
    EOD;

       // Без модификатора области видимости:
       static $var9;
       readonly int $var10;
    }

> Замечание:

> Классы и объекты обрабатывают набором функций. Смотрите раздел справки «Функции работы с классами и объектами».

### Объявления типов

Начиная с PHP 7.4.0 определениям свойств разрешается включать «Объявления типов», за исключением типа callable.

Пример #2 Пример типизированных свойств

    <?php

    class User
    {
        public int $id;
        public ?string $name;

        public function __construct(int $id, ?string $name)
        {
            $this->id = $id;
            $this->name = $name;
        }
    }

    $user = new User(1234, null);

    var_dump($user->id);
    var_dump($user->name);

Результат выполнения приведённого примера:

    int(1234)
    NULL

При обращении к типизированному свойству, для которого не определили начальное значение, PHP выбросит исключение Error.

Пример #3 Обращение к свойствам

    <?php

    class Shape
    {
        public int $numberOfSides;
        public string $name;

        public function setNumberOfSides(int $numberOfSides): void
        {
            $this->numberOfSides = $numberOfSides;
        }

        public function setName(string $name): void
        {
            $this->name = $name;
        }

        public function getNumberOfSides(): int
        {
            return $this->numberOfSides;
        }

        public function getName(): string
        {
            return $this->name;
        }
    }

    $triangle = new Shape();
    $triangle->setName("triangle");
    $triangle->setNumberofSides(3);
    var_dump($triangle->getName());
    var_dump($triangle->getNumberOfSides());

    $circle = new Shape();
    $circle->setName("circle");
    var_dump($circle->getName());
    var_dump($circle->getNumberOfSides());

Результат выполнения приведённого примера:

    string(8) "triangle"
    int(3)
    string(6) "circle"

    Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

### Readonly-свойства

Начиная с PHP 8.1.0 разрешили объявлять свойства с модификатором `readonly`, который запрещает изменять свойство после инициализации. До PHP 8.4.0 свойство с модификатором `readonly` автоматически получало закрытую видимость для установки значения, и записывать такое свойство можно было только в том же самом классе, в котором свойство объявили. С PHP 8.4.0 свойства с модификатором `readonly` автоматически получают защищённую видимость для установки значения `protected(set)`, поэтому устанавливать значения для такого свойства можно в дочернем классе. Видимость свойства для записи разрешается переопределять вручную.

Пример #4 Примеры readonly-свойств

    <?php

    class Test
    {
        public readonly string $prop;

        public function __construct(string $prop)
        {
            // Правильная инициализация.
            $this->prop = $prop;
        }
    }

    $test = new Test("foobar");

    // Правильное чтение
    var_dump($test->prop); // string(6) "foobar"

    // Неправильное переопределение. Не имеет значения, что присвоенное значение такое же
    $test->prop = "foobar";
    // Error: Cannot modify readonly property Test::$prop

> Замечание:

> Модификатор readonly разрешается применять только к типизированным свойствам. Тип свойства объявляют как Mixed, когда требуется создать readonly-свойство без ограничений типа.

> Замечание:

> Статические readonly-свойства не поддерживаются.

Readonly-свойство разрешается инициализировать только один раз и только из области видимости, в которой свойство объявили. Другое присваивание или изменение свойства приведёт к исключению Error.

Пример #5 Неправильная инициализация readonly-свойств

    <?php

    class Test1
    {
        public readonly string $prop;
    }

    $test1 = new Test1();

    // Неправильная инициализация за пределами закрытой области
    $test1->prop = "foobar";
    // Error: Cannot initialize readonly property Test1::$prop from global scope

> Замечание:

> Нельзя явным образом указывать значение по умолчанию для readonly-свойств, потому что readonly-свойство со значением по умолчанию по существу совпадает с константой, и поэтому бесполезно.

>     <?php

>     class Test
>     {
>         // Error: Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }

> Замечание:

> Конструкцией unset() нельзя уничтожить readonly-свойство после инициализации. Однако получится уничтожить readonly-свойство до инициализации из области видимости, в которой свойство объявили.

К изменениям относятся не только стандартные присваивания, следующие изменения тоже выбросят ошибку Error:

    <?php

    class Test
    {
        public function __construct(
            public readonly int $i = 0,
            public readonly array $ary = [],
        ) {}
    }

    $test = new Test();
    $test->i += 1;
    $test->i++;
    ++$test->i;
    $test->ary[] = 1;
    $test->ary[0][] = 1;
    unset($test->ary[0]);
    $ref =& $test->i;
    $test->i =& $ref;
    byRef($test->i);
    foreach ($test as &$prop);

При этом readonly-свойства не исключают внутреннюю изменчивость. Объекты и ресурсы, которые хранятся в readonly-свойствах, по-прежнему получится изменить внутри:

    <?php

    class Test
    {
        public function __construct(public readonly object $obj) {}
    }

    $test = new Test(new stdClass());

    // Правильное внутреннее изменение
    $test->obj->foo = 1;

    // Неправильное переопределение
    $test->obj = new stdClass();

Начиная с PHP 8.3.0 свойства, доступные только для чтения, разрешается инициализировать повторно при клонировании объекта через магический метод __clone().

Пример #6 Клонирование readonly-свойств

    <?php

    class Test1
    {
        public readonly ?string $prop;

        public function __clone()
        {
            $this->prop = null;
        }

        public function setProp(string $prop): void
        {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1();
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL

### Динамические свойства

При попытке присвоить несуществующее свойство объекту (object), PHP автоматически создаст такое свойство. Это динамически созданное свойство будет доступно только для этого экземпляра класса.

Внимание

С PHP 8.2.0 динамические свойства устарели. Вместо динамического присваивания свойства классу рекомендуют объявлять свойство. Для обработки произвольных имён свойств класс должен реализовать магические методы __get() и __set(). В крайнем случае класс помечают атрибутом `#[\AllowDynamicProperties]`.

## Хуки свойств

Хуки свойств, которые в ряде других языков ещё называются «аксессорами свойств», представляют способ перехвата и переопределения поведения объектов при чтении и записи свойства. Функциональность хуков преследует две цели:

1. Записывать и считывать значения свойств объектов напрямую, без методов получения и установки свойств, оставляя при этом открытым добавление дополнительного поведения в будущем. Это делает шаблонные геттеры и сеттеры ненужными, даже без хуков.
2. Получать доступ к свойствам объекта без непосредственного хранения значений свойств.

Для нестатических свойств доступны два хука: `get` и `set`. Хуки разрешают переопределять поведение чтения и записи свойства. Хуки доступны как для типизированных, так и для нетипизированных свойств.

Классы поддерживают «реальные» и «виртуальные» свойства. Реальное свойство — то, которое хранит действительное значение. Свойства без хуков — реальные. Виртуальное свойство — то, для которого объявили хуки и эти хуки не взаимодействуют с самим свойством. Хуки виртуальных свойств — практически то же самое, что и методы, и объект не занимает места в памяти для хранения значения такого свойства.

Хуки несовместимы с `readonly`-свойствами. Свойствам устанавливают асимметричную область видимости, когда в дополнение к изменению поведения, которое вносят хуки `get` и `set`, требуется ограничить доступ к операциям чтения или записи.

> Замечание: Сведения о версии
> Хуки свойств появились с PHP 8.4.

### Базовый синтаксис хуков

Общий синтаксис объявления хука следующий.

Пример #1 Пример полной версии объявления хуков для свойств

    <?php

    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modified)';
                }

                return $this->foo;
            }

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'changed';
    print $example->foo;

Объявление свойства $foo заканчивается фигурными скобками `{}`, а не точкой с запятой. Фигурные скобки указывают, что для свойства определили хуки. В примере определили оба хука — и `get`, и `set`, хотя разрешается определять отдельно один или другой. Для каждого хука определили тело, которое обозначается фигурными скобками `{}`. В теле записывают произвольный код.

Хук `set` дополнительно поддерживает объявление типа и названия входящего значения синтаксисом, аналогичным объявлению параметров в методах. Тип значения указывается либо с ограничением как у типа свойства, либо контравариантным к значению — с более широким, или слабым, ограничением. Например, для свойства с типом string в хуке `set` возможно определить параметр с типом string|Stringable, но нельзя определить параметр с типом array, поскольку тип array не принадлежит ни самому строковому типу, ни надтипу строки.

В примере по крайней мере один хук ссылается на само свойство `$this->foo`, поэтому свойство «реально». При вызове `$example->foo = 'changed'` строка вначале приводится к нижнему регистру, затем сохраняется как реальное значение. При чтении свойства сохранённое значение разрешается условно дополнить новым текстом.

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

Фигурные скобки `{}` опускают и заменяют стрелочным выражением, если хук `get` состоит из одного выражения.

Пример #2 Пример свойства с хуком get из одного выражения

Этот пример эквивалентен предыдущему.

    <?php

    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

Параметр в объявлении хука разрешается опустить, если тип параметра в хуке `set` совпадает с типом свойства, что встречается часто. Тогда значению для установки автоматически присваивается имя $value.

Пример #3 Пример установки значения по умолчанию для свойства

Этот пример эквивалентен предыдущему.

    <?php

    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

Хук `set` также можно упростить до выражения со стрелкой, если хук только устанавливает изменённую версию значения аргумента. Значение, которое вычислит выражение, установится как реальное значение свойства.

Пример #4 Пример установки значения свойства выражением в хуке set

    <?php

    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }

Этот пример не эквивалентен предыдущему, поскольку он не изменяет значение свойства `$this->modified`, как предыдущий пример. В теле хука set пользуются версией синтаксиса с фигурными скобками, когда требуется указать больше одной инструкции.

В свойствах разрешается реализовывать ноль, один или оба хука в зависимости от ситуации. Сокращённые версии синтаксиса хуков не зависят одна от другой. Поэтому допустимы и короткий синтаксис хука get с длинным синтаксисом хука set, и короткий синтаксис хука set с явным типом параметра, и другие комбинации.

Пропуск хука `get` или `set` в реальном свойстве означает, что чтение или запись поведут себя по умолчанию.

> Замечание: PHP разрешает определять хуки при продвижении параметров конструктора до свойств класса. При этом в конструктор потребуется передать значения, которые совпадают с типом свойства, независимо от типа, который разрешает хук `set`. Посмотрим на следующий пример:

>     <?php

>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }

>                     $this->created = $value;
>                 }
>             },
>         ) {}
>     }

> Внутренне движок разберёт этот код так:

>     <?php

>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }

>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> Установка свойства в классе, вне передачи аргументов в конструктор, разрешит значения с типом string или DateTimeInterface, но конструктор разрешит только тип DateTimeInterface. Причина этого состоит в том, что тип DateTimeInterface, который определяет свойство, внутри сигнатуры конструктора определяет тип параметра, независимо от того, что разрешает хук `set`. Нельзя продвигать параметры конструктора до свойств класса, если от конструктора требуется такое поведение.

### Виртуальные свойства

Виртуальными называются свойства без реальных значений. Свойство станет виртуальным, если ни хук `get`, ни хук `set` не ссылаются на само свойство точным синтаксисом. Свойство с именем `$foo`, хук которого содержит ссылку на само свойство `$this->foo`, — реальное. Но свойство в следующем примере не относится к реальным и вызовет ошибку:

Пример #5 Пример недопустимого виртуального свойства

    <?php

    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // Инструкция return не ссылается на реальное свойство $this->foo,
                                     // поэтому это не считается
            }
        }
    }

Попытка выполнить с виртуальным свойством операцию, для которой не объявили хук, вызовет ошибку, поскольку поведение по умолчанию для такой операции останется неопределённым. Виртуальные свойства не занимают места в памяти объекта. Виртуальные свойства помогают создавать «производные» свойства наподобие комбинации значений двух других свойств.

Пример #6 Пример виртуального свойства

    <?php

    class Rectangle
    {
        // Виртуальное свойство
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // Выводит 20
    $s->area = 30; // Ошибка, поскольку для свойства не определили комбинацию записи

Для виртуальных свойств поддерживается определение обоих хуков: `get` и `set`.

### Об области видимости

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

За счёт доступа к членам объекта и срабатывания при каждой операции чтения или записи хуки поддерживают не только тривиальную логику, но и, если потребуется, вызов методов произвольной сложности.

Пример #7 Пример вызова метода из хука

    <?php

    class Person
    {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string
        {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }

            return $value;
        }
    }

### Ссылки

Поскольку хуки перехватывают процесс чтения и записи свойств, они вызывают проблемы при получении ссылки на свойство или при косвенной модификации, например, `$this->arrayProp['key'] = 'value';`. Это связано с тем, что попытка изменения значения по ссылке обойдет хук set, если его определили.

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

Нельзя определять одновременно хуки `&get` и `set` для реального свойства. Как уже отмечалось, запись в значение, которое возвращается по ссылке, обойдет хук `set`. Виртуальные свойства не хранят обязательного общего значения, которое хуки разделяют между собой, поэтому хуки для чтения свойства разрешается определять с возвратом по значению или по ссылке.

Значения в индекс свойства-массива также неявно записываются по ссылке. Поэтому запись в свойство с реальным массивом и хуками разрешается, если только в свойстве определили единственный хук `&get`. В виртуальном свойстве запись в массив, который возвращает хук `get` или `&get`, возможна, но повлияет ли это на объект, зависит от реализации хука.

Перезапись самого свойства массива возможна и ведёт себя как и другие свойства. Только работа с элементами массива требует осторожности.

### Наследование

#### Окончательные хуки

Хуки разрешается также объявлять окончательными через ключевое слово final, тогда хуки нельзя переопределять.

Пример #8 Пример с окончательными хуками

    <?php

    class User
    {
        public string $username {
            final set => strtolower($value);
        }
    }

    class Manager extends User
    {
        public string $username {
            // Это возможно
            get => strtoupper($this->username);

            // Но это недопустимо, поскольку хук set окончателен в родительском элементе
            set => strtoupper($value);
        }
    }

Свойство тоже возможно объявить окончательным через ключевое слово final. Окончательное свойство нельзя повторно объявлять в дочернем классе, что исключает изменение хуков или ослабление доступа к операциям хуков.

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

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

Пример #9 Наследование хуков

    <?php

    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Число слишком маленькое');
                }

                $this->x = $value;
            }
        }
    }

Каждый хук переопределяет родительские реализации независимо друг от друга. Значения по умолчанию, которые установили для свойств, удалятся и потребуется объявить значение заново, если дочерний класс добавляет хуки. Это согласуется с тем, как наследование работает в свойствах без хуков.

#### Доступ к родительским хукам

Хук в дочернем классе получает доступ к свойству родительского класса через ключевое слово `parent::$prop`, за которым следует хук, к которому требуется доступ. Например, `parent::$propName::get()`. Это читается как «получить доступ к свойству prop, которое определили в родительском классе, а затем выполнить операцию get, или операцию set, в зависимости от ситуации.

Хук родительского класса игнорируется, если только доступ к родительскому хуку не выполняется непосредственно. Такое поведение соответствует работе методов. Синтаксис обращения к родительскому хуку также открывает доступ к хранилищу родительского класса, если родительский класс содержит такое хранилище. Чтение или запись поведут себя по умолчанию, если хук для родительского свойства не определили. Хукам нельзя получать доступ к другим хукам, за исключением своих хуков в родительских классах.

Проблема предыдущего примера состоит в том, что дочерний класс проигнорирует хук, который добавят в родительском. Модификация примера разрешит добавить хук `set` в классе `Point` в будущем.

Пример #10 Доступ к родительскому хуку (set)

    <?php

    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Число слишком маленькое');
                }

                parent::$x::set($value);
            }
        }
    }

Пример переопределения только хука get:

Пример #11 Доступ к родительскому хуку (get)

    <?php

    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get())
            ;
        }
    }

### Сериализация

В PHP предусмотрели ряд способов сериализовать объект в производственной среде или в целях отладки. Поведение хуков зависит от сценария. В одних случаях берётся необработанное реальное значение свойства, а хуки обходятся. В других — свойство считывается или записывается «через» хук, как и другие стандартные операции чтения и записи.

- Функция var_dump(): берёт необработанное значение
- Функция serialize(): берёт необработанное значение
- Функция unserialize(): берёт необработанное значение
- Магические методы __serialize() и __unserialize(): реализуют пользовательскую логику с хуками чтения или записи
- Приведение массива: берёт необработанное значение
- Функция var_export(): задействует хук get
- Функция json_encode(): задействует хук get
- Интерфейс JsonSerializable: реализует пользовательскую логику с хуком get
- Функция get_object_vars(): задействует хук get
- Функция get_mangled_object_vars(): берёт необработанное значение

## Константы классов

В PHP константы возможно объявлять отдельно для каждого класса. Константы класса сохраняют исходное значение даже при изменении объекта класса, поскольку константы принадлежат классу, а не конкретному экземпляру. Область видимости констант классов по умолчанию устанавливается открытой, как будто константу определили с модификатором `public`.

> Замечание:

> Дочерним классам разрешается переопределять константы родительского класса. Начиная с PHP 8.1.0 константы окончательного класса, который определили с ключевым словом final, нельзя переопределить дочерним классом.

Интерфейсам также разрешается содержать константы. Примеры интерфейсных констант приводит документация по интерфейсам.

К классу возможно обратиться через переменную. Ключевые слова наподобие `self`, `parent` и `static` нельзя указывать как значения переменной, которая ссылается на класс.

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

Начиная с PHP 8.3.0 константы классов поддерживают объявление скалярного типа: `bool`, `int`, `float`, `string` или даже `array`. В значении константы с типом `array` указывают только другие скалярные типы.

Пример #1 Объявление константы и обращение к константе

    <?php

    class MyClass
    {
        const CONSTANT = 'значение константы';

        function showConstant() {
            echo  self::CONSTANT . "\n";
        }
    }

    echo MyClass::CONSTANT . "\n";

    $classname = "MyClass";
    echo $classname::CONSTANT . "\n";

    $class = new MyClass();
    $class->showConstant();

    echo $class::CONSTANT . "\n";

    ?>

Специальная константа `::class` на этапе компиляции разрешает имена классов в абсолютные. Это полезно при работе в классах с пространством имён.

Пример #2 Пример поведения константы ::class в классе с пространством имён

    <?php

    namespace foo
    {
        class bar {}

        echo bar::class; // foo\bar
    }

    ?>

Пример #3 Пример константного выражения класса

    <?php

    const ONE = 1;

    class foo
    {
        const TWO = ONE * 2;
        const THREE = ONE + self::TWO;
        const SENTENCE = 'Значение константы THREE - ' . self::THREE;
    }

    ?>

Пример #4 Модификаторы видимости констант класса начиная с PHP 7.1.0

    <?php

    class Foo
    {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    echo Foo::BAR, PHP_EOL;
    echo Foo::BAZ, PHP_EOL;

    ?>

Результат выполнения приведённого примера в PHP 7.1:

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> Замечание:

> Начиная с PHP 7.1.0 для констант класса разрешается указывать модификаторы области видимости.

Пример #5 Проверка вариантности видимости констант класса начиная с PHP 8.3.0

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }

    ?>

Результат выполнения приведённого примера в PHP 8.3:

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> Замечание: Начиная с PHP 8.3.0 вариантность видимости проверяется строже. До этой версии видимость константы класса могла не совпадать с видимостью константы реализованного интерфейса.

Пример #6 Синтаксис получения константы класса начиная с PHP 8.3.0

    <?php

    class Foo
    {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar

    ?>

> Замечание:

> Начиная с PHP 8.3.0 значения констант класса разрешили получать динамически, через переменную.

Пример #7 Назначение типов константам классов начиная с PHP 8.3.0

    <?php

    class MyClass
    {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);

    ?>

Результат выполнения приведённого примера в PHP 8.3:

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## Автоматическая загрузка классов

Разработчики объектно-ориентированных приложений договорились создавать по одному исходному PHP-файлу для каждого класса. Главная неприятность — приходится в начале каждого скрипта писать длинный список включений, по одному для каждого файла, который требуется загрузить.

Функция spl_autoload_register() регистрирует нужное количество автозагрузчиков для автоматической загрузки классов и интерфейсов, которые пока не определили. Регистрация автозагрузчиков даёт PHP последний шанс загрузить класс или интерфейс, прежде чем скрипт завершит работу с ошибкой.

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

Предостережение

До PHP 8.0.0 классы и интерфейсы загружали автоматически функцией __autoload(). Однако это менее гибкая альтернатива функции spl_autoload_register(), а функцию __autoload() объявили устаревшей в PHP 7.2.0 и удалили в PHP 8.0.0.

> Замечание:

> Функцию spl_autoload_register() разрешается вызывать больше одного раза, чтобы зарегистрировать больше одного автозагрузчика. Если функция автозагрузки выбросит исключение, оно прервёт процесс автозагрузки и не разрешит запускать следующие функции автозагрузки. Поэтому выбрасывать исключения из функции автозагрузки настоятельно не рекомендуется.

Пример #1 Пример автоматической загрузки классов

В этом примере функция пытается загрузить класс `MyClass1` из файла MyClass1.php и класс `MyClass2` из файла MyClass2.php.

    <?php

    spl_autoload_register(function ($class_name) {
        include $class_name . '.php';
    });

    $obj  = new MyClass1();
    $obj2 = new MyClass2();

    ?>

Пример #2 Другой пример автоматической загрузки классов

В этом примере функция пытается загрузить интерфейс `ITest`.

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {}

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */

    ?>

Пример #3 Пример работы с автозагрузчиком пакетного менеджера Composer

» Composer генерирует файл `vendor/autoload.php`, который настраивается на автоматическую загрузку пакетов, которыми управляет менеджер зависимостей. Пакеты готовы к работе сразу после включения файла-автозагрузчика.

    <?php

    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Пакет сгенерировал новый UUID-идентификатор -> ", $uuid->toString(), "\n";

    ?>

### Смотрите также

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## Конструкторы и деструкторы

### Конструктор

function __construct(mixed `...$values` = ""): void

PHP разрешает разработчикам объявлять для классов методы-конструкторы. Классы с методом-конструктором автоматически вызывают этот метод для каждого создаваемого объекта, поэтому объявление конструктора удобно для установки начального состояния объекта — инициализации свойств и другой подготовки объекта к работе.

> Замечание: Конструктор родительского класса не вызывается автоматически при определении конструктора в дочернем классе. Внутри конструктора дочернего класса потребуется вызвать parent::__construct(), чтобы запустить конструктор родительского класса. Дочерний класс унаследует конструктор родительского класса как стандартный метод, если в дочернем классе конструктор не определили и родительский конструктор не закрытый.

Пример #1 Конструкторы при наследовании

    <?php

    class BaseClass
    {
       function __construct()
       {
           print "Конструктор класса BaseClass\n";
       }
    }

    class SubClass extends BaseClass
    {
       function __construct()
       {
           parent::__construct();
           print "Конструктор класса SubClass\n";
       }
    }

    class OtherSubClass extends BaseClass
    {
        // Класс наследует конструктор класса BaseClass
    }

    // Конструктор класса BaseClass
    $obj = new BaseClass();

    // Конструктор класса BaseClass
    // Конструктор класса SubClass
    $obj = new SubClass();

    // Конструктор класса BaseClass
    $obj = new OtherSubClass();

В отличие от других методов, метод __construct() освобождается от правил совместимости сигнатуры при наследовании.

Конструкторы — обыкновенные методы, которые вызываются во время создания объекта класса с конструктором или объекта дочернего класса без конструктора. Поэтому в конструкторах определяют произвольное количество параметров, которые разрешено объявлять обязательными, типизированными, со значением по умолчанию. Параметры конструктора указываются в круглых скобках после имени класса.

Пример #2 Объявление параметров в конструкторах

    <?php

    class Point
    {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0)
        {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // Передаём оба аргумента
    $p1 = new Point(4, 5);

    // Передаём только обязательные аргументы. Переменная $y содержит значение по умолчанию 0
    $p2 = new Point(4);

    // Создаём объект с передачей именованных аргументов, которые поддерживаются начиная с PHP 8.0:
    $p3 = new Point(y: 5, x: 4);

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

#### Конструкторы в старом стиле

До PHP 8.0.0 классы в глобальном пространстве имён интерпретируют названный именем класса метод как конструктор старого стиля. Этот синтаксис устарел и вызовет ошибку уровня `E_DEPRECATED`, но всё равно вызовет этот метод как конструктор. PHP вызовет как конструктор метод __construct(), если в классе определили и метод __construct(), и метод с названием класса.

У метода, название которого совпадает с именем класса, нет особого значения в классах внутри пространства имён, а с PHP 8.0.0 — в любых классах.

В новом коде определяют только метод __construct().

#### Продвижение параметров конструктора до свойств класса

С PHP 8.0.0 параметры конструктора стали поддерживать продвижение до свойств объекта. Это распространённая практика — присваивать свойствам объекта значения только за счёт аргументов, которые передали в конструктор. Определение свойств в конструкторе сокращает количество шаблонного кода. Предыдущий пример переписывается вот так:

Пример #3 Продвижение параметров конструктора до свойств

    <?php

    class Point
    {
        public function __construct(protected int $x, protected int $y = 0) {}
    }

PHP интерпретирует параметры с модификатором видимости одновременно и как параметр конструктора, и как свойство объекта, и устанавливает значение аргумента свойству. За счёт объявления свойств через параметры тело конструктора остаётся пустым, или включает другие инструкции, не связанные с инициализацией свойств. Конструктор выполнит дополнительные инструкции после присваивания значений аргументов свойствам.

Не каждому параметру конструктора требуется продвижение до свойства объекта. Поддерживается смешивание продвигаемых и стандартных параметров в произвольном порядке. Продвигаемые параметры не изменяют порядок вызова конструктора.

> Замечание:

> Модификатор области видимости — `public`, `protected` или `private` — наиболее вероятный способ применить продвинутую установку свойств, но любой другой модификатор, например `readonly`, даст такой же эффект.

> Замечание:

> Нельзя указывать свойствам объекта тип callable. Это связано с неоднозначностью, которую представляют вызываемые значения для движка PHP. Поэтому и для параметров конструктора, которые устанавливают классу свойства, тоже нельзя указывать тип callable. Но остальные декларации типов поддерживаются.

> Замечание:

> PHP накладывает ограничения на именование параметров конструктора как к свойствам класса, так и к параметрам функции, поскольку при разборе кода PHP преобразовывает синтаксический сахар объявления свойств в конструкторе в декларирование свойств класса с теми же модификаторами видимости и типом данных, которые указали в продвигаемом до свойств объекта параметре, и присваивает значение аргумента и параметру функции, и свойству класса.

> Замечание:

> На этапе определения конструктора атрибуты продвигаемого до свойства параметра реплицируются как на параметр конструктора, так и на свойство класса, но значение по умолчанию PHP установит только параметру, но не свойству.

#### Ключевое слово new в инициализаторах

В PHP 8.1.0 разрешили присваивать объекты как значения по умолчанию для параметров, как значения статических переменных и глобальных констант, а также как значения аргументов в атрибутах. Объекты также допустимо передавать в функцию define().

> Замечание:

> При этом динамические или нестроковые имена классов или анонимных классов не разрешены. Использовать распаковку аргументов не разрешено. Неподдерживаемые выражения как аргументы не разрешены.

Пример #4 Пример ключевого слова new при инициализации объекта

    <?php

    // Всё допустимо:
    static $x = new Foo();
    const C = new Foo();

    function test($param = new Foo) {}

    #[AnAttribute(new Foo)]
    class Test
    {
        public function __construct(
            public $prop = new Foo,
        ) {}
    }

    // Всё запрещено (ошибка времени компиляции):
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // Динамическое имя класса
        $b = new class {}, // Анонимный класс
        $c = new A(...[]), // Распаковка аргументов
        $d = new B($abc), // Неподдерживаемое постоянное выражение
    ) {}

#### Статические методы, которые создают объект класса

PHP поддерживает только один конструктор для класса. Однако бывает так, что нужно создавать разные объекты для разных входных данных. Рекомендуемый способ — использовать статические методы как обёртки над конструктором.

Пример #5 Использование статических методов для создания объектов

    <?php

    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Product
    {
        private ?int $id;
        private ?string $name;

        private function __construct(?int $id = null, ?string $name = null)
        {
            $this->id = $id;
            $this->name = $name;
        }

        public static function fromBasicData(int $id, string $name): static
        {
            $new = new static($id, $name);
            return $new;
        }

        public static function fromJson(string $json): static
        {
            $data = json_decode($json, true);
            return new static($data['id'], $data['name']);
        }

        public static function fromXml(string $xml): static
        {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $data->id;
            $new->name = $data->name;
            return $new;
        }
    }

    $p1 = Product::fromBasicData(5, 'Widget');
    $p2 = Product::fromJson($some_json_string);
    $p3 = Product::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

Конструктор разрешено делать закрытым или защищённым, чтобы исключить вызов конструктора извне. Тогда создать объект класса получится только через статический метод. Доступ к закрытым методам класса есть и у конструктора, и у статического метода, поскольку конструктор, статический и закрытый методы определили в одном и том же классе, даже если один экземпляр объекта вызывает закрытый метод другого. Закрытый конструктор необязателен, и будет ли в закрытом конструкторе смысл, определяет ситуация.

В примере выше три открытых статических метода показывают разные способы, которыми они создают экземпляр объекта.

- Метод `fromBasicData()` принимает конкретные параметры, создаёт экземпляр класса через конструктор и возвращает результат.
- Метод `fromJson()` принимает JSON-строку и выполняет над строкой предварительную обработку, чтобы преобразовать строку в формат, который требует конструктор. Затем метод возвращает новый объект.
- Метод `fromXml()` принимает XML-строку, предварительно обрабатывает её, а затем создаёт пустой объект. При этом PHP вызывает конструктор, но поскольку параметры конструктора необязательны, метод пропускает их. Затем непосредственно перед возвратом результата метод присваивает значения свойствам объекта.

В каждом из трёх случаев ключевое слово `static` транслируется в имя класса, в котором вызвали код. В примере — в имя класса `Product`.

### Деструкторы

function __destruct(): void

Концепция деструктора PHP повторяет концепцию других объектно-ориентированных языков, например C++. PHP вызовет деструктор, как только не останется ссылок на конкретный объект, или в другом порядке в течение завершения работы.

Пример #6 Пример использования деструктора

    <?php

    class MyDestructableClass
    {
       function __construct()
       {
           print "Конструктор\n";
       }

       function __destruct()
       {
           print "Уничтожается " . __CLASS__  . "\n";
       }
    }

    $obj = new MyDestructableClass();

Как и конструкторы, движок PHP не будет неявно вызывать деструкторы, которые объявили в родительском классе. Необходимо вызвать parent::__destruct() в теле деструктора дочернего класса, чтобы запустить деструктор родительского класса. Аналогично конструкторам, дочерний класс, в котором не определен деструктор, наследует деструктор из родительского класса.

Движок вызовет деструктор, даже если выполнение скрипта остановила функция exit(). Вызов функции exit() в деструкторе предотвратит запуск остальных процедур завершения работы.

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

Начиная с PHP 8.4.0 при запуске сборки циклических ссылок внутри файбера деструкторы объектов-кандидатов на уничтожение выполняются в отдельном файбере, который называется `gc_destructor_fiber`. Сборщик создаст новый файбер сборки мусора для выполнения оставшихся деструкторов, если текущий файбер сборщика приостановили внутри деструктора уничтожаемого объекта. Сборщик мусора перестанет ссылаться на предыдущий файбер `gc_destructor_fiber`, который станет доступен для сборки, если на него не останется других ссылок. Уничтожение объектов с приостановленным деструктором откладывается до завершения выполнения деструктора или уничтожения самого файбера.

> Замечание:

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

> Замечание:

> Попытка выбросить исключение из деструктора, который вызвали на этапе завершения работы скрипта, вызовет фатальную ошибку.

## Область видимости

Область видимости свойства, метода или начиная c PHP 7.1.0 константы определяют путём добавления перед объявлением ключевого слова: `public`, `protected` или `private`. Доступ к общедоступным членам класса, — которые объявили с ключевым словом public, — разрешается из любой области видимости. Доступ к защищённым членам класса, которые объявили с ключевым словом protected, — возможен только внутри самого класса, и в производных классах-наследниках или родительских классах. Доступ к закрытым членам класса, — которые объявили с ключевым словом private, — открывается только для самого класса, в котором их определили.

### Область видимости свойства

Свойства класса разрешается определять как открытые — public, защищённые — protected или закрытые — private. Свойства, которые объявили без модификатора области видимости, определяются как открытые, как будто свойство объявили с ключевым словом public.

Пример #1 Объявление свойства класса

    <?php

    /**
     * Определение класса MyClass
     */
    class MyClass
    {
        public $public = 'Public';
        protected $protected = 'Protected';
        private $private = 'Private';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj = new MyClass();
    echo $obj->public; // Работает
    echo $obj->protected; // Фатальная ошибка
    echo $obj->private; // Фатальная ошибка
    $obj->printHello(); // Выводит 'Public', 'Protected' и 'Private'

    /**
     * Определение MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Разрешается переопределять открытые и защищённые свойства, но не закрытые
        public $public = 'Public2';
        protected $protected = 'Protected2';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj2 = new MyClass2();
    echo $obj2->public; // Работает
    echo $obj2->protected; // Фатальная ошибка
    echo $obj2->private; // Предупреждение о неопределённом свойстве
    $obj2->printHello(); // Выводит 'Public2', 'Protected2' и предупреждение о неопределённом свойстве

#### Асимметричная область видимости свойств

Начиная с PHP 8.4 свойства объекта дополнительно стали поддерживать установку асимметричной области видимости: отдельно для чтения и записи. Видимость свойства для записи определяют спецификатором `(set)`, который указывают сразу после модификатора видимости, тогда как спецификатор `(get)` после модификатора видимости для чтения не указывают, а подразумевают. Спецификатором `set` нельзя устанавливать уровень доступности свойства для записи слабее, чем уровень доступа для чтения.

Пример #2 Пример асимметричной установки области видимости свойств

    <?php

    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // Всё хорошо
            $this->pubYear = $year; // Критическая ошибка
        }
    }

    $b = new Book('Правильный PHP-код', 'Peter H. Peterson', 2024);

    echo $b->title; // Всё хорошо
    echo $b->author; // Всё хорошо
    echo $b->pubYear; // Критическая ошибка

    $b->title = 'Неправильный PHP-код'; // Критическая ошибка
    $b->author = 'Pedro H. Peterson'; // Критическая ошибка
    $b->pubYear = 2023; // Критическая ошибка

Начиная с PHP 8.5 статические свойства класса тоже стали поддерживать установку отдельной области видимости для записи через спецификатор `set`.

Пример #3 Asymmetric Static Property Visibility

    <?php

    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Выполняем другую работу
            return "Произвольная строка";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Работает
    echo Manager::$calls; // Работает
    Manager::$calls = 5; // Фатальная ошибка

Результат выполнения приведённого примера:

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /some/file.php

Относительно асимметричной области видимости определили ряд условий:

- Отдельную область видимости `set` разрешается устанавливать только типизированным свойствам.
- Ограничение области видимости `set` требуется указывать как у области видимости `get` или сильнее. Так, сочетания модификаторов `public protected(set)` и `protected protected(set)` допустимы, но более слабое условие области видимости для записи наподобие `protected public(set)` вызовет синтаксическую ошибку.
- Область видимости для чтения открытых свойств разрешается пропускать и не указывать модификатор `public`. Поэтому определения `public private(set)` и `private(set)` установят свойству одни и те же области видимости.
- Свойство с областью видимости `private(set)` автоматически становится окончательным (`final`) и его нельзя повторно объявить в дочернем классе.
- Получение ссылки на свойство подчиняется видимости `set`, а не `get`. Это связано с тем, что ссылка разрешает изменять значение свойства.
- Аналогично, попытка записи в массив, который содержится в свойстве, включает в себя как внутреннюю операцию чтения — `get`, так и операцию записи — `set`, и поэтому подчинится области видимости `set`, поскольку ограничение области видимости для записи сильнее.

> Замечание: Пробелы в объявлении области видимости для записи не допускаются. Правильно: `private(set)`. Неправильно и вызовет ошибку синтаксического анализа: `private( set )`.

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

Пример #4 Наследование свойств с асимметричной областью видимости

    <?php

    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // Всё хорошо, поскольку ограничение на чтение слабее, а на запись – такое же
        public string $author; // Всё хорошо, поскольку ограничение на чтение такое же, а на запись – слабее
        public protected(set) int $pubYear; // Критическая ошибка. Свойства с видимостью private(set) — окончательны!
    }

### Область видимости метода

Методы класса разрешается определять как открытые — public, защищённые — protected или закрытые — private. Методы, которые объявили без явного ключевого слова области видимости, определяются как открытые, как будто метод объявили с ключевым словом public.

Пример #5 Объявление метода

    <?php
    /**
     * Определение класса MyClass
     */
    class MyClass
    {
        // Объявление общедоступного конструктора
        public function __construct() {}

        // Объявление общедоступного метода
        public function MyPublic() {}

        // Объявление защищённого метода
        protected function MyProtected() {}

        // Объявление закрытого метода
        private function MyPrivate() {}

        // Это общедоступный метод
        function Foo()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate();
        }
    }

    $myclass = new MyClass();
    $myclass->MyPublic(); // Работает
    $myclass->MyProtected(); // Фатальная ошибка
    $myclass->MyPrivate(); // Фатальная ошибка
    $myclass->Foo(); // Общедоступный, защищённый и закрытый методы работают

    /**
     * Определение класса MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Это общедоступный метод
        function Foo2()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate(); // Фатальная ошибка
        }
    }

    $myclass2 = new MyClass2;
    $myclass2->MyPublic(); // Работает
    $myclass2->Foo2(); // Общедоступный и защищённый методы работают, закрытый — не работает

    class Bar
    {
        public function test()
        {
            $this->testPrivate();
            $this->testPublic();
        }

        public function testPublic()
        {
            echo "Bar::testPublic\n";
        }

        private function testPrivate()
        {
            echo "Bar::testPrivate\n";
        }
    }

    class Foo extends Bar
    {
        public function testPublic()
        {
            echo "Foo::testPublic\n";
        }

        private function testPrivate()
        {
            echo "Foo::testPrivate\n";
        }
    }

    $myFoo = new Foo();
    $myFoo->test(); // Bar::testPrivate
                    // Foo::testPublic

### Область видимости констант

Начиная с PHP 7.1.0 константы класса разрешается определять как открытые — public, защищённые — protected или закрытые — private. Константы, которые объявили без явного ключевого слова области видимости, определяются как открытые, как будто константу объявили с ключевым словом public.

Пример #6 Пример объявления констант с PHP 7.1.0

    <?php
    /**
     * Объявление класса MyClass
     */
    class MyClass
    {
        // Объявление общедоступной константы
        public const MY_PUBLIC = 'public';

        // Объявление защищённой константы
        protected const MY_PROTECTED = 'protected';

        // Объявление закрытой константы
        private const MY_PRIVATE = 'private';

        public function foo()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE;
        }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC; // Работает
    MyClass::MY_PROTECTED; // Фатальная ошибка
    MyClass::MY_PRIVATE; // Фатальная ошибка
    $myclass->foo(); // Выводятся константы с модификаторами public, protected и private

    /**
     * Объявление класса MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Публичный метод
        function foo2()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE; // Фатальная ошибка
        }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // Работает
    $myclass2->foo2(); // Выводятся константы с модификаторами public и protected, но не с модификатором private

### Видимость из других объектов

Объектам одного и того же типа доступны защищённые и закрытые члены друг друга, даже если это разные экземпляры. Это связано с тем, что внутри таких объектов уже известны конкретные детали реализации.

Пример #7 Доступ к закрытым членам объекта того же типа

    <?php

    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Доступ к закрытому методу.';
        }

        public function baz(Test $other)
        {
            // Закрытое свойство доступно для изменения:
            $other->foo = 'привет';
            var_dump($other->foo);

            // Закрытый метод также доступен для вызова:
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));

Результат выполнения приведённого примера:

    string(6) "привет"
    Доступ к закрытому методу.

## Наследование

Наследование — это хорошо зарекомендовавший себя принцип программирования, и PHP использует этот принцип в своей объектной модели. Этот принцип повлияет на то, как многие классы и объекты связаны друг с другом.

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

Это полезно для определения и абстрагирования функциональности и позволяет реализовать дополнительную функциональность в похожих объектах без необходимости реализовывать всю общую функциональность.

Закрытые методы родительского класса недоступны для дочернего класса. В результате дочерние классы могут повторно реализовать закрытый метод без учёта обычных правил наследования. Однако до PHP 8.0.0 к закрытым методам применялись ограничения `final` и `static`. Начиная с PHP 8.0.0, единственное ограничение закрытого метода, которое применяется - это конструкторы `private final`, поскольку это обычный способ «отключить» конструктор при использовании вместо него статичных фабричных методов.

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

> Замечание:

> Если не используется автозагрузка, классы должны быть объявлены до того, как они будут использоваться. Если класс расширяет другой, то родительский класс должен быть объявлен до наследующего класса. Это правило применяется к классам, которые наследуют другие классы или интерфейсы.

> Замечание:

> Не разрешается переопределять свойство чтения-записи с помощью readonly-свойства или наоборот.

>     <?php

>     class A
>     {
>         public int $prop;
>     }

>     class B extends A
>     {
>         // Нельзя: read-write -> readonly
>         public readonly int $prop;
>     }

>     ?>

Пример #1 Пример наследования

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP просто супер.' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // Выведет: 'Foo: baz'
    $foo->printPHP();       // Выведет: 'PHP просто супер.'
    $bar->printItem('baz'); // Выведет: 'Bar: baz'
    $bar->printPHP();       // Выведет: 'PHP просто супер.'

    ?>

### Совместимость типов возвращаемых значений с внутренними классами

До PHP 8.1.0 большинство внутренних классов или методов не объявляли свои типы возвращаемых значений и при их расширении допускался любой тип возвращаемого значения.

Начиная с PHP 8.1.0, большинство внутренних методов начали "предварительно" объявлять тип возвращаемого значения. В этом случае тип возвращаемого значения методов должен быть совместим с расширяемым родителем; в противном случае выдаётся уведомление об устаревании. Обратите внимание, что отсутствие явного объявления типа возвращаемого значения также считается несоответствием сигнатуры и, соответственно, приводит к уведомлению об устаревании.

Если тип возвращаемого значения не может быть объявлен для переопределяемого метода из-за проблем с совместимостью с различными версиями PHP, может быть добавлен атрибут ReturnTypeWillChange, чтобы заглушить уведомление об устаревании.

Пример #2 Переопределяющий метод не объявляет никакого типа возвращаемого значения

    <?php
    class MyDateTime extends DateTime
    {
        public function modify(string $modifier) { return false; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice", начиная с PHP 8.1.0
    ?>

Пример #3 Переопределяющий метод объявляет неверный тип возвращаемого значения

    <?php
    class MyDateTime extends DateTime
    {
        public function modify(string $modifier): ?DateTime { return null; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice", начиная с PHP 8.1.0
    ?>

Пример #4 Переопределяющий метод объявляет неверный тип возвращаемого значения без уведомления об устаревании

    <?php
    class MyDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // Уведомление об устаревании не выводится
    ?>

## Оператор разрешения области действия ::

Оператор разрешения области действия, который ещё называется Paamayim Nekudotayim, или «двойное двоеточие», — токен, который разрешает доступ к константе, статическому свойству или статическому методу текущего или родительского класса. Больше того, статические свойства и методы разрешается переопределять через позднее статическое связывание.

При обращении к элементам класса извне определения класса указывают название класса.

К классу возможно обратиться через переменную, при этом нельзя указывать как значение переменной ключевые слова наподобие `self`, `parent` или `static`.

Вначале словосочетание Paamayim Nekudotayim кажется странным выбором для названия двойного двоеточия. Команда Zend назвала оператор так, пока писала движок Zend Engine версии 0.5, на котором работал PHP 3. Секрет в том, что эти слова и переводятся как «двойное двоеточие» — с иврита!

Пример #1 Пример обращения к элементам класса через оператор :: из-за пределов определения класса

    <?php

    class MyClass
    {
        const CONST_VALUE = 'Значение константы';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;

К свойствам и методам изнутри класса обращаются через ключевые слова self, parent и static.

Пример #2 Пример обращения к элементам класса через оператор :: изнутри определения класса

    <?php

    class MyClass {
        const CONST_VALUE = 'A constant value';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'статическая переменная';

        public static function doubleColon()
        {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    $classname::doubleColon();

    OtherClass::doubleColon();

PHP не вызывает метод родительского класса, когда дочерний класс переопределяет родительский метод. Дочерний класс сам решает, вызывать ли метод родительского класса. Это правило также относится к конструкторам и деструкторам, перегруженным и «магическим» методам.

Пример #3 Пример вызова родительского метода

    <?php

    class MyClass
    {
        protected function myFunc()
        {
            echo "MyClass::myFunc()\n";
        }
    }

    class OtherClass extends MyClass
    {
        // Переопределяем родительский метод
        public function myFunc()
        {
            // Но всё равно вызываем метод родительского класса
            parent::myFunc();
            echo "OtherClass::myFunc()\n";
        }
    }

    $class = new OtherClass();
    $class->myFunc();

Смотрите также примеры статических вызовов.

## Ключевое слово static

Подсказка

Эта страница описывает использование ключевого слова `static` для определения статических методов и свойств. `static` также может использоваться для определения статических переменных, определения статических анонимных функций и позднего статического связывания. Для получения информации о таком применении ключевого слова `static` обратитесь по вышеуказанным страницам.

Объявление свойств и методов класса статическими позволяет обращаться к ним без создания экземпляра класса. К ним также можно получить доступ статически в созданном экземпляре объекта класса.

### Статические методы

Так как статические методы вызываются без создания экземпляра класса, то псевдопеременная $this недоступна внутри статических методов.

Внимание

Вызов нестатических методов статически вызывает ошибку Error.

До PHP 8.0.0 вызов нестатических методов статически был объявлен устаревшим и вызывал ошибку уровня `E_DEPRECATED`.

Пример #1 Пример статического метода

    <?php
    class Foo {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### Статические свойства

Доступ к статическим свойствам осуществляется с помощью оператора разрешения области видимости (`::`), и к ним нельзя получить доступ через оператор объекта (`->`).

На класс можно ссылаться с помощью переменной. Значение переменной в таком случае не может быть ключевым словом (например, `self`, `parent` и `static`).

Пример #2 Пример статического свойства

    <?php
    class Foo
    {
        public static $my_static = 'foo';

        public function staticValue() {
            return self::$my_static;
        }
    }

    class Bar extends Foo
    {
        public function fooStatic() {
            return parent::$my_static;
        }
    }

    print Foo::$my_static . "\n";

    $foo = new Foo();
    print $foo->staticValue() . "\n";
    print $foo->my_static . "\n";      // Не определено свойство my_static

    print $foo::$my_static . "\n";
    $classname = 'Foo';
    print $classname::$my_static . "\n";

    print Bar::$my_static . "\n";
    $bar = new Bar();
    print $bar->fooStatic() . "\n";
    ?>

Результат выполнения приведённого примера в PHP 8 аналогичен:

    foo
    foo

    Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23

    Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23

    foo
    foo
    foo
    foo

## Абстракция класса

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

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

Начиная с PHP 8.4 в абстрактных классах разрешили объявлять абстрактные свойства, как с открытой, так и с защищённой областью видимости. Защищённому абстрактному свойству удовлетворяет свойство, которое доступно для чтения или записи как из защищённой, так и из открытой области видимости.

Абстрактному свойству удовлетворяет либо стандартное свойство, либо свойство, для которого определили хуки, которые соответствуют операции чтения или записи абстрактного свойства.

Пример #1 Пример абстрактного метода

    <?php

    abstract class AbstractClass
    {
        // Эти методы потребуется определить в дочернем классе
        abstract protected function getValue();
        abstract protected function prefixValue($prefix);

        // Общий метод
        public function printOut()
        {
            print $this->getValue() . "\n";
        }
    }

    class ConcreteClass1 extends AbstractClass
    {
        protected function getValue()
        {
            return "ConcreteClass1";
        }

        public function prefixValue($prefix)
        {
            return "{$prefix}ConcreteClass1";
        }
    }

    class ConcreteClass2 extends AbstractClass
    {
        public function getValue()
        {
            return "ConcreteClass2";
        }

        public function prefixValue($prefix)
        {
            return "{$prefix}ConcreteClass2";
        }
    }

    $class1 = new ConcreteClass1();
    $class1->printOut();
    echo $class1->prefixValue('FOO_'), "\n";

    $class2 = new ConcreteClass2();
    $class2->printOut();
    echo $class2->prefixValue('FOO_'), "\n";

    ?>

Результат выполнения приведённого примера:

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

Пример #2 Пример абстрактного метода

    <?php

    abstract class AbstractClass
    {
        // Абстрактному методу необходимо только определить обязательные аргументы
        abstract protected function prefixName($name);
    }

    class ConcreteClass extends AbstractClass
    {
        // Дочернему классу разрешается определять в сигнатуре метода необязательные параметры,
        // которые не объявляли в сигнатуре метода родительского класса
        public function prefixName($name, $separator = ".")
        {
            if ($name == "Pacman") {
                $prefix = "Mr";
            } elseif ($name == "Pacwoman") {
                $prefix = "Mrs";
            } else {
                $prefix = "";
            }

            return "{$prefix}{$separator} {$name}";
        }
    }

    $class = new ConcreteClass();
    echo $class->prefixName("Pacman"), "\n";
    echo $class->prefixName("Pacwoman"), "\n";

    ?>

Результат выполнения приведённого примера:

    Mr. Pacman
    Mrs. Pacwoman

Пример #3 Пример абстрактного свойства

    <?php

    abstract class A
    {
        // В дочернем классе потребуется объявить открытое для чтения свойство
        abstract public string $readable {
            get;
        }

        // В дочернем классе потребуется объявить защищённое или открытое для записи свойство
        abstract protected string $writeable {
            set;
        }

        // В дочернем классе потребуется объявить защищённое или открытое свойство с симметричной областью видимости
        abstract protected string $both {
            get;
            set;
        }
    }

    class C extends A
    {
        // Определение удовлетворяет требованию абстрактного свойства, и делает свойство доступным для записи, что допустимо
        public string $readable;

        // Такое определение того же свойства НЕ удовлетворит требованию,
        // поскольку свойство недоступно для открытого чтения
        protected string $readable;

        // Определение на 100 % удовлетворяет требованию абстракции, поэтому такого определения достаточно.
        // Свойство доступно для записи и только из защищённой области видимости
        protected string $writeable {
            set => $value;
        }

        // Определение расширяет видимость с защищенной до общедоступной, это допустимо
        public string $both;
    }

    ?>

Абстрактное свойство абстрактного класса должно содержать объявление по крайней мере одного абстрактного хука. При объявлении для абстрактного свойства и хука `get`, и хука `set` одному хуку в абстрактном классе разрешается предоставить реализацию, как в приведённом примере.

Пример #4 Пример абстрактного свойства

    <?php

    abstract class A
    {
        // Определение стандартной, но переопределяемой реализации хука set,
        // и требование к дочерним классам предоставить реализацию хука get
        abstract public string $foo {
            get;

            set {
                $this->foo = $value;
            };
        }
    }

    ?>

## Интерфейсы объектов

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

Интерфейсы определяются так же, как классы, но с ключевым словом `interface` вместо слова `class` и с методами, ни один из которых не определяет содержимое тела.

Методы интерфейса объявляются общедоступными, что вытекает из самой природы интерфейса.

Интерфейсы преследуют две взаимодополняющие цели:

- Разрешают разработчикам создавать объекты разноимённых классов, которые умеют взаимно заменять друг друга, поскольку реализуют один и тот же интерфейс или интерфейсы. Интерфейсы часто внедряют в код, когда требуется создать набор служб доступа к базе данных, платёжных шлюзов или стратегий кеширования. Один класс подменяют другим без изменения кода, который его использует.
- Разрешают параметру функции или метода принимать и обрабатывать объект, который подчиняется контракту интерфейса, чтобы не заботиться о том, что ещё умеет делать объект или как его реализовали. Интерфейсы часто называют `Iterable`, `Cacheable`, `Renderable` и другими похожими именами, чтобы описать поведение интерфейса.

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

> Замечание:

> Лучше не включать конструкторы в интерфейсы, чтобы не снижать гибкость объекта, который реализует интерфейс, хотя включение конструкторов и поддерживается. Конструкторы, кроме того, не соблюдают правила наследования, из-за чего поведение иногда становится противоречивым и неожиданным.

### `Оператор implements`

Для реализации интерфейса используется оператор `implements`. Класс должен реализовать все методы, описанные в интерфейсе, иначе произойдёт фатальная ошибка. При желании классы могут реализовывать более одного интерфейса, разделяя каждый интерфейс запятой.

Внимание

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

> Замечание:

> Аналогично классам, интерфейсы расширяют оператором extends.

> Замечание:

> Класс, которым реализуется интерфейс, обязан объявить каждый метод интерфейса по правилам совместимости сигнатур. Реализация методов обязана следовать правилам совместимости сигнатур для каждого интерфейса, когда класс реализует больше одного интерфейса, в котором объявили методы с одинаковым названием. Поэтому при организации иерархии типов PHP-разработчики пользуются доступной в языке ковариантностью и контравариантностью.

### Константы

Интерфейсы поддерживают объявления констант. Константы интерфейсов работают так же, как константы классов. До PHP 8.1.0 константы интерфейса нельзя было переопределять в производном классе или интерфейсе.

### Properties

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

Класс удовлетворяет свойству интерфейса несколькими способами: класс определяет открытое свойство, виртуальное свойство, которое реализует только тот хук, который соответствует хуку интерфейса, или определяет `readonly`-свойство, которое удовлетворяет свойству интерфейса для чтения. Однако в классе нельзя ограничивать доступ на запись свойства модификатором `readonly`, если в интерфейсе свойство объявили доступным для записи.

Пример #1 Пример свойств интерфейса

    <?php

    interface I
    {
        // Класс, в котором реализуется свойство, ДОЛЖЕН объявить открытое для чтения свойство,
        // но объявление свойства в интерфейсе не ограничивает объявление доступа на запись свойства в классе
        public string $readable {
            get;
        }

        // Класс, в котором реализуется свойство, должен объявить открытое для записи свойство,
        // но объявление свойства в интерфейсе не ограничивает объявление доступа на чтение свойства в классе
        public string $writeable {
            set;
        }

        // Класс, в котором реализуется свойство, должен объявить свойство,
        // открытое как для чтения, так и для записи
        public string $both {
            get;
            set;
        }
    }

    // Класс реализует каждое из трёх свойств традиционно, без хуков.
    // Такая реализация свойств допустима
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // Класс реализует каждое из трёх свойств и определяет только те хуки,
    // которые потребовал интерфейс. Такая реализация свойств тоже допустима
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // Класс реализует только хук для чтения, чтобы создать виртуальное свойство.
        // Такое определение удовлетворяет требованию «публичной открытости для чтения».
        // Свойство недоступно для записи, но интерфейс и не требует открытого доступа для записи
        public string $readable {
            get => strtoupper($this->writeable);
        }

        // Интерфейс требует только того, чтобы класс определил свойство, открытое для записи,
        // но включение хука для операции чтения тоже допустимо.
        // Пример создаёт виртуальное свойство, и это нормально
        public string $writeable {
            get => $this->written;

            set {
                $this->written = $value;
            }
        }

        // Свойство требует как операции чтения, так и операции записи,
        // поэтому потребуется либо реализовать оба хука, либо разрешить операциям чтения и записи
        // поведение по умолчанию
        public string $both {
            get => $this->all;

            set {
                $this->all = strtoupper($value);
            }
        }
    }

    ?>

### Примеры

Пример #2 Пример интерфейса

    <?php

    // Объявляем интерфейс 'Template'
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // Реализуем интерфейс
    // Это сработает
    class WorkingTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }

        public function getHtml($template)
        {
            foreach ($this->vars as $name => $value) {
                $template = str_replace('{' . $name . '}', $value, $template);
            }

            return $template;
        }
    }

    // Это не сработает
    // Fatal error: Class BadTemplate contains 1 abstract methods
    // and must therefore be declared abstract (Template::getHtml)
    // (Фатальная ошибка: Класс BadTemplate содержит 1 абстрактный метод
    // и поэтому требуется объявить класс абстрактным (Template::getHtml))
    class BadTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }
    }

    ?>

Пример #3 Наследование интерфейсов

    <?php

    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // Это сработает
    class C implements B
    {
        public function foo() {}

        public function baz(Baz $baz) {}
    }

    // Это не сработает и выдаст фатальную ошибку
    class D implements B
    {
        public function foo() {}

        public function baz(Foo $foo) {}
    }

    ?>

Пример #4 Совместимость с несколькими интерфейсами

    <?php

    class Foo {}
    class Bar extends Foo {}

    interface A
    {
        public function myfunc(Foo $arg): Foo;
    }

    interface B
    {
        public function myfunc(Bar $arg): Bar;
    }

    class MyClass implements A, B
    {
        public function myfunc(Foo $arg): Bar
        {
            return new Bar();
        }
    }

    ?>

Пример #5 Множественное наследование интерфейсов

    <?php

    interface A
    {
        public function foo();
    }

    interface B
    {
        public function bar();
    }

    interface C extends A, B
    {
        public function baz();
    }

    class D implements C
    {
        public function foo() {}

        public function bar() {}

        public function baz() {}

    }
    ?>

Пример #6 Интерфейсы с константами

    <?php

    interface A
    {
        const B = 'Константа интерфейса';
    }

    // Выведет: Константа интерфейса
    echo A::B;

    class B implements A
    {
        const B = 'Константа класса';
    }

    // Выведет: Константа класса
    // До PHP 8.1.0 этот код не сработает,
    // поскольку запрещалось переопределять константы
    echo B::B;

    ?>

Пример #7 Интерфейсы с абстрактными классами

    <?php

    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // Абстрактному классу можно реализовывать только часть интерфейса.
    // Классы, которыми расширяется абстрактный класс, должны реализовать остальные требования интерфейса
    abstract class B implements A
    {
        public function foo(string $s): string
        {
            return $s . PHP_EOL;
        }
    }

    class C extends B
    {
        public function bar(int $i): int
        {
            return $i * 2;
        }
    }

    ?>

Пример #8 Одновременное расширение класса и реализация интерфейсов

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // Порядок ключевых слов здесь важен. Слово extends должно идти первым
    class Two extends One implements
        Usable,
        Updatable
    {
        /* ... */
    }

    ?>

Интерфейс вместе с объявлениями типов предоставляет надёжный способ проверки того, что конкретный объект содержит конкретные методы. Смотрите также описание оператора instanceof и раздел «Объявления типов».

## Трейты

Способ, которым в языке PHP один и тот же код внедряют в несвязанные иерархии классов, называется трейтами (англ. Traits).

Трейты — механизм, который разрешает повторно использовать код в языках с одиночным наследованием наподобие PHP. Задача трейта — уменьшить ограничения одиночного наследования, разрешая разработчику легко переиспользовать наборы методов в нескольких независимых классах, которые находятся в разных иерархиях наследования. Семантику комбинации трейтов и классов определили так, чтобы снизить уровень сложности и избежать типичных проблем, свойственных множественному наследованию и примесям (англ. Mixins).

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

Пример #1 Пример трейта

    <?php

    trait TraitA {
        public function sayHello()
        {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld()
        {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // Класс разрешает внедрять несколько трейтов

        public function sayHelloWorld()
        {
            $this->sayHello();
            echo ' ';

            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

Результат выполнения приведённого примера:

    Hello World!

### Приоритет

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

Пример #2 Пример того, в каком порядке выстраивается приоритет

Метод, который класс унаследовал из базового класса, переопределяется методом, который внедрился в класс MyHelloWorld из трейта SayWorld. Методы трейта ведут себя как методы класса MyHelloWorld. Порядок приоритета такой: методами текущего класса переопределяются методы трейта, которыми переопределяются методы базового класса.

    <?php

    class Base
    {
        public function sayHello()
        {
            echo 'Hello ';
        }
    }

    trait SayWorld
    {
        public function sayHello()
        {
            parent::sayHello();
            echo 'World!';
        }
    }

    class MyHelloWorld extends Base
    {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();

    ?>

Результат выполнения приведённого примера:

    Hello World!

Пример #3 Пример альтернативного порядка приоритета

    <?php

    trait HelloWorld
    {
        public function sayHello()
        {
            echo 'Hello World!';
        }
    }

    class TheWorldIsNotEnough
    {
        use HelloWorld;

        public function sayHello()
        {
            echo 'Hello Universe!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();

    ?>

Результат выполнения приведённого примера:

    Hello Universe!

### Несколько трейтов

Названия трейтов перечисляют через запятую в инструкции `use`, чтобы добавить в класс несколько трейтов.

Пример #4 Пример внедрения нескольких трейтов

    <?php

    trait Hello
    {
        public function sayHello()
        {
            echo 'Hello ';
        }
    }

    trait World
    {
        public function sayWorld()
        {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use Hello, World;

        public function sayExclamationMark()
        {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();

    ?>

Результат выполнения приведённого примера:

    Hello World!

### Разрешение конфликтов

При добавлении двумя трейтами метода с одним и тем же названием возникает фатальная ошибка, если конфликт явно не разрешили.

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

Для добавления псевдонима методу трейта указывают оператор `as`, поскольку предыдущий оператор только исключает методы. Обратите внимание, оператор `as` не переименовывает метод и не влияет ни на какие другие методы.

Пример #5 Пример разрешения конфликтов

В этом примере в класс Talker включили трейты A и B. Поскольку в трейтах A и B содержатся методы, которые вступают в конфликт, класс использует вариант метода smallTalk из трейта B, а вариант метода bigTalk из трейта A.

Оператор `as` в классе Aliased_Talker разрешает вызывать метод bigTalk трейта B по псевдониму `talk`.

    <?php

    trait A
    {
        public function smallTalk()
        {
            echo 'a';
        }

        public function bigTalk()
        {
            echo 'A';
        }
    }

    trait B
    {
        public function smallTalk()
        {
            echo 'b';
        }

        public function bigTalk()
        {
            echo 'B';
        }
    }

    class Talker
    {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
        }
    }

    class Aliased_Talker
    {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
            B::bigTalk as talk;
        }
    }

    ?>

### Изменение видимости метода

Синтаксис с оператором `as` умеет также настраивать видимость метода в классе.

Пример #6 Пример изменения видимости метода

    <?php

    trait HelloWorld
    {
        public function sayHello()
        {
            echo 'Привет, мир!';
        }
    }

    // Изменим видимость метода sayHello
    class MyClass1
    {
        use HelloWorld {
            sayHello as protected;
        }
    }

    // Создадим псевдоним метода и изменим видимость этого метода.
    // Видимость метода sayHello не изменилась
    class MyClass2
    {
        use HelloWorld {
            sayHello as private myPrivateHello;
        }
    }

    ?>

### Импорт трейтов в трейты

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

Пример #7 Пример трейтов, которые состоят из трейтов

    <?php

    trait Hello
    {
        public function sayHello()
        {
            echo 'Hello ';
        }
    }

    trait World
    {
        public function sayWorld()
        {
            echo 'World!';
        }
    }

    trait HelloWorld
    {
        use Hello, World;
    }

    class MyHelloWorld
    {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();

    ?>

Результат выполнения приведённого примера:

    Hello World!

### Абстрактные члены трейтов

Трейты поддерживают абстрактные методы, чтобы установить требования к классу, в который внедрится трейт. Поддерживаются общедоступные, защищённые и закрытые методы. До PHP 8.0.0 поддерживались только общедоступные и защищённые абстрактные методы.

Предостережение

Начиная с PHP 8.0.0 выдаётся фатальная ошибка, если сигнатура конкретного метода не следует правилам совместимости сигнатур. Раньше при несовпадении сигнатуры метода ошибка не выдавалась.

Пример #8 Пример установки требований к классу через абстрактный метод трейта

    <?php

    trait Hello
    {
        public function sayHelloWorld()
        {
            echo 'Hello' . $this->getWorld();
        }

        abstract public function getWorld();
    }

    class MyHelloWorld
    {
        private $world;

        use Hello;

        public function getWorld()
        {
            return $this->world;
        }

        public function setWorld($val)
        {
            $this->world = $val;
        }
    }

    ?>

### Статические члены трейта

В трейтах разрешается определять статические переменные, статические методы и статические свойства.

> Замечание:

> Начиная с PHP 8.1.0 прямой вызов статического метода или прямой доступ к статическому свойству в трейте устарели. Доступ к статическим методам и свойствам получают только в классе, в который внедрили трейт.

Пример #9 Статические переменные

    <?php

    trait Counter
    {
        public function inc()
        {
            static $c = 0;
            $c = $c + 1;
            echo "$c\n";
        }
    }

    class C1
    {
        use Counter;
    }

    class C2
    {
        use Counter;
    }

    $o = new C1();
    $o->inc();

    $p = new C2();
    $p->inc();

    ?>

Результат выполнения приведённого примера:

    1
    1

Пример #10 Статические методы

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Делаем что-нибудь';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

Результат выполнения приведённого примера:

    Doing something

Пример #11 Статические свойства

Предостережение

До PHP 8.3.0 дочерние классы наследовали статические свойства, которые родительские классы получали из трейта, даже если трейт явно внедрялся в дочерний класс. Начиная с PHP 8.3.0 статическое свойство трейта переопределяет в дочернем классе статическое свойство, которое дочерний класс унаследовал из родительского.

    <?php

    trait T
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

Результат выполнения приведённого примера в PHP 8.3:

    2
    1

### Свойства

В трейтах доступно определение свойств.

Пример #12 Пример определения свойств в трейте

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

В классе нельзя определять свойство с названием как у свойства трейта, если свойство класса несовместимо со свойством трейта по области видимости и типу, модификатору readonly и начальному значению, иначе PHP выдаёт фатальную ошибку.

Пример #13 Разрешение конфликтов

    <?php

    trait PropertiesTrait
    {
        public $same = true;
        public $different1 = false;
        public bool $different2;
        public bool $different3;
    }

    class PropertiesExample
    {
        use PropertiesTrait;

        public $same = true;
        public $different1 = true; // Фатальная ошибка
        public string $different2; // Фатальная ошибка
        readonly protected bool $different3; // Фатальная ошибка
    }

    ?>

### Константы

Начиная с версии PHP 8.2.0 в трейтах разрешили также определять константы.

Пример #14 Определение констант

    <?php

    trait ConstantsTrait
    {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample
    {
        use ConstantsTrait;
    }

    $example = new ConstantsExample;
    echo $example::FLAG_MUTABLE;

    ?>

Результат выполнения приведённого примера:

    1

В классе нельзя определять константу с названием как у константы трейта, если константа класса несовместима с константой трейта по области видимости, начальному значению и модификатору final, иначе PHP выдаёт фатальную ошибку.

Пример #15 Разрешение конфликтов

    <?php

    trait ConstantsTrait
    {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample
    {
        use ConstantsTrait;

        public const FLAG_IMMUTABLE = 5; // Фатальная ошибка
    }

    ?>

### Окончательные методы

Начиная с PHP 8.3.0 методы, которые импортировали из трейтов, разрешили делать окончательными через оператор `as` и модификатор final. Определение метода трейта окончательным запрещает дочерним классам переопределять метод. Но самому классу, в который импортировали трейт и в котором сделали метод окончательным, по-прежнему доступно переопределение метода.

Пример #16 Определение метода окончательным путём добавления модификатора `final` при внедрении трейта

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Привет';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // Начиная с PHP 8.3.0 модификатор final
                                          // запретит переопределять метод в дочерних классах
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

Вывод приведённого примера будет похож на:

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## Анонимные классы

Анонимные классы приносят пользу, когда требуется создать простые одноразовые объекты.

    <?php

    // Явный класс
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // Анонимный класс
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

    ?>

Анонимные классы по аналогии с обычными классами умеют передавать аргументы в свои конструкторы, расширять другие классы, реализовывать интерфейсы и использовать трейты:

    <?php

    class SomeClass {}
    interface SomeInterface {}
    trait SomeTrait {}

    var_dump(new class(10) extends SomeClass implements SomeInterface {
        private $num;

        public function __construct($num)
        {
            $this->num = $num;
        }

        use SomeTrait;
    });

    ?>

Результат выполнения приведённого примера:

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

Вложение анонимного класса в другой класс не даёт вложенному классу доступ к закрытым или защищённым методам и свойствам внешнего класса. Анонимному классу потребуется расширить внешний класс, чтобы использовать защищённые свойства и методы внешнего класса. Закрытые свойства внешнего класса потребуется передать в конструктор анонимного класса, чтобы анонимный класс получил к ним доступ:

    <?php

    class Outer
    {
        private $prop = 1;
        protected $prop2 = 2;

        protected function func1()
        {
            return 3;
        }

        public function func2()
        {
            return new class($this->prop) extends Outer {
                private $prop3;

                public function __construct($prop)
                {
                    $this->prop3 = $prop;
                }

                public function func3()
                {
                    return $this->prop2 + $this->prop3 + $this->func1();
                }
            };
        }
    }

    echo (new Outer)->func2()->func3();

Результат выполнения приведённого примера:

    6

Объекты, которые создаёт одно и то же объявление анонимного класса, относятся к экземплярам одного и того же класса.

    <?php

    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'Тот же класс';
    } else {
        echo 'Другой класс';
    }

    ?>

Результат выполнения приведённого примера:

    Тот же класс

> Замечание:

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

>     <?php

>     echo get_class(new class {});

>     ?>

> Вывод приведённого примера будет похож на:

>     class@anonymous/in/oNi1A0x7f8636ad2021

### Анонимные классы только для чтения

Начиная с PHP 8.3.0 к анонимным классам разрешили применять модификатор `readonly`.

Пример #1 Пример определения анонимного класса только для чтения

    <?php

    // Определяем анонимный класс доступным только для чтения и передаём как аргумент
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix) {}

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

    ?>

## Перегрузка

Перегрузка в PHP означает возможность динамически создавать свойства и методы. Эти динамические сущности обрабатываются с помощью магических методов, которые можно создать в классе для различных видов действий.

Методы перегрузки вызываются при взаимодействии со свойствами или методами, которые не были объявлены или не видны в текущей области видимости. Далее в этом разделе будут использоваться термины недоступные свойства или недоступные методы для обозначения этой комбинации объявления и области видимости.

Все методы перегрузки должны быть объявлены как `public`.

> Замечание:

> Ни один из аргументов этих магических методов не может быть передан по ссылке.

> Замечание:

> Интерпретация перегрузки в PHP отличается от большинства объектно-ориентированных языков. Традиционно перегрузка означает возможность иметь несколько одноимённых методов с разным количеством и типами аргументов.

### Перегрузка свойств

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __unset(string `$name`): void

Метод __set() будет выполнен при записи данных в недоступные (защищённые или приватные) или несуществующие свойства.

Метод __get() будет выполнен при чтении данных из недоступных (защищённых или приватных) или несуществующих свойств.

Метод __isset() будет выполнен при использовании isset() или empty() на недоступных (защищённых или приватных) или несуществующих свойствах.

Метод __unset() будет выполнен при вызове unset() на недоступном (защищённом или приватном) или несуществующем свойстве.

Аргумент $name представляет собой имя вызываемого свойства. Метод __set() содержит аргумент $value, представляющий собой значение, которое будет записано в свойство с именем $name.

Перегрузка свойств работает только в контексте объекта. Данные магические методы не будут вызваны в статическом контексте. Поэтому эти методы не должны объявляться статическими. При объявлении любого магического метода как `static` будет выдано предупреждение.

> Замечание:

> Возвращаемое значение __set() будет проигнорировано из-за способа обработки в PHP оператора присваивания. Аналогично, __get() никогда не вызывается при объединении присваиваний, например, подобным образом: ``

>      $a = $obj->b = 8;

> Замечание:

> PHP не будет вызывать перегруженный метод изнутри того же перегруженного метода. Это означает, что, например, написание `return $this->foo` внутри __get() вернёт `null` и вызовет ошибку уровня `E_WARNING`, если не определено свойство `foo`, вместо того, чтобы вызвать метод __get() во второй раз. Однако методы перегрузки могут неявно вызывать другие методы перегрузки (например, метод __set() вызывает метод __get()).

Пример #1 Перегрузка свойств с помощью методов __get(), __set(), __isset() и __unset()

    <?php
    class PropertyTest
    {
        /**  Место хранения перегружаемых данных.  */
        private $data = array();

        /**  Перегрузка не применяется к объявленным свойствам.  */
        public $declared = 1;

        /**  Здесь перегрузка будет использована только при доступе вне класса.  */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Установка '$name' в '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Получение '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Неопределённое свойство в __get(): ' . $name .
                ' в файле ' . $trace[0]['file'] .
                ' на строке ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "Установлено ли '$name'?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Уничтожение '$name'\n";
            unset($this->data[$name]);
        }

        /**  Не магический метод, просто для примера. */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new PropertyTest;

    $obj->a = 1;
    echo $obj->a . "\n\n";

    var_dump(isset($obj->a));
    unset($obj->a);
    var_dump(isset($obj->a));
    echo "\n";

    echo $obj->declared . "\n\n";

    echo "Давайте поэкспериментируем с закрытым свойством 'hidden':\n";
    echo "Закрытые свойства видны внутри класса, поэтому __get() не используется...\n";
    echo $obj->getHidden() . "\n";
    echo "Закрытые свойства не видны вне класса, поэтому __get() используется...\n";
    echo $obj->hidden . "\n";
    ?>

Результат выполнения приведённого примера:

    Установка 'a' в '1'
    Получение 'a'
    1

    Установлено ли 'a'?
    bool(true)
    Уничтожение 'a'
    Установлено ли 'a'?
    bool(false)

    1

    Давайте поэкспериментируем с закрытым свойством 'hidden':
    Закрытые свойства видны внутри класса, поэтому __get() не используется...
    2
    Закрытые свойства не видны вне класса, поэтому __get() используется...
    Получение 'hidden'

    Notice: Неопределённое свойство в __get(): hidden в <file> on line 70 in <file> on line 29

### Перегрузка методов

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

__call() запускается при вызове недоступных методов в контексте объект.

__callStatic() запускается при вызове недоступных методов в статическом контексте.

Аргумент $name представляет собой имя вызываемого метода. Аргумент $arguments представляет собой нумерованный массив, содержащий параметры, переданные в вызываемый метод $name.

Пример #2 Перегрузка методов с помощью методов __call() и __callStatic()

    <?php
    class MethodTest {
        public function __call($name, $arguments) {
            // Замечание: значение $name регистрозависимо.
            echo "Вызов метода '$name' "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments) {
            // Замечание: значение $name регистрозависимо.
            echo "Вызов статического метода '$name' "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodTest;
    $obj->runTest('в контексте объекта');

    MethodTest::runTest('в статическом контексте');
    ?>

Результат выполнения приведённого примера:

    Вызов метода 'runTest' в контексте объекта
    Вызов статического метода 'runTest' в статическом контексте

## Итераторы объектов

PHP предоставляет такой способ объявления объектов, который даёт возможность пройти по списку элементов данного объекта, например, с помощью оператора `foreach`. По умолчанию, в этом обходе (итерации) будут участвовать все видимые свойства объекта.

Пример #1 Итерация простого объекта

    <?php
    class MyClass
    {
        public $var1 = 'значение 1';
        public $var2 = 'значение 2';
        public $var3 = 'значение 3';

        protected $protected = 'защищённая переменная';
        private   $private   = 'закрытая переменная';

        function iterateVisible() {
           echo "MyClass::iterateVisible:\n";
           foreach ($this as $key => $value) {
               print "$key => $value\n";
           }
        }
    }

    $class = new MyClass();

    foreach($class as $key => $value) {
        print "$key => $value\n";
    }
    echo "\n";

    $class->iterateVisible();

    ?>

Результат выполнения приведённого примера:

    var1 => значение 1
    var2 => значение 2
    var3 => значение 3

    MyClass::iterateVisible:
    var1 => значение 1
    var2 => значение 2
    var3 => значение 3
    protected => защищённая переменная
    private => закрытая переменная

Как показывает результат, `foreach` проитерировал все доступные и принадлежащие объекту видимые свойства.

### Смотрите также

- Генераторы
- Iterator
- IteratorAggregate
- Итераторы

## Магические методы

Магические методы — методы, которые переопределяют действие PHP по умолчанию, когда над объектом выполняются отдельные действия.

Предостережение

Названия методов, которые начинаются с двух символов подчёркивания `__`, зарезервировали в PHP, поэтому лучше не указывать методам такие названия, если только не требуется переопределить поведение PHP.

Следующие названия методов относятся к магическим: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state(), __clone() и __debugInfo()

Внимание

Магические методы, за исключением __construct(), __destruct() и __clone(), ТРЕБУЕТСЯ объявлять с модификатором `public`, иначе PHP выдаст ошибку уровня `E_WARNING`. До PHP 8.0.0 для магических методов __sleep(), __wakeup(), __serialize(), __unserialize() и __set_state() не выполнялась проверка.

Внимание

При объявлении типов в определении магического метода требуется повторять сигнатуру, которую описывает этот документ, иначе возникнет фатальная ошибка. До PHP 8.0.0 диагностические сообщения не отправлялись. При этом в методах __construct() и __destruct() тип возврата не объявляют, иначе возникнет фатальная ошибка.

### Методы __serialize() и __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

Функция serialize() проверяет, определили ли в классе магический метод с названием __serialize(). Метод, если его определили в классе, выполняется перед сериализацией. Цель метода — вернуть ассоциативный массив пар «ключ — значение» для представления объекта в сериализованной форме. При невозврате массива выбрасывается ошибка TypeError.

> Замечание:

> При определении в классе обоих методов — и __serialize(), и __sleep(), PHP вызовет только метод __serialize(). Метод __sleep() проигнорируется. PHP проигнорирует интерфейсный метод `serialize()`, и вместо него вызовет метод __serialize(), если класс реализует интерфейс Serializable.

Назначение метода __serialize() заключается в определении удобного для сериализации произвольного представления объекта. Элементам массива разрешается соответствовать свойствам объекта, но это не обязательно.

И наоборот, функция unserialize() проверяет доступность магического метода __unserialize(). PHP передаст методу массив, который восстановил и вернул метод __serialize(), если метод определили в классе. А затем, если потребуется, метод восстановит свойства объекта из этого массива.

> Замечание:

> При определении в классе обоих методов — и __unserialize(), и __wakeup(), PHP вызовет только метод __unserialize(), а метод __wakeup() проигнорируется.

> Замечание:

> Метод доступен с PHP 7.4.0.

Пример #1 Пример сериализации и десериализации

    <?php

    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __serialize(): array
        {
            return [
              'dsn' => $this->dsn,
              'user' => $this->username,
              'pass' => $this->password,
            ];
        }

        public function __unserialize(array $data): void
        {
            $this->dsn = $data['dsn'];
            $this->username = $data['user'];
            $this->password = $data['pass'];

            $this->connect();
        }
    }

    ?>

### Методы __sleep() и __wakeup()

public function __sleep(): array
public function __wakeup(): void

Функция serialize() проверяет, определили ли в классе магический метод с названием __sleep(). Магический метод, если его определили, выполняется перед сериализацией. В методе очищают сериализуемый объект, если требуется, и возвращают из метода массив с названиями переменных объекта, которые требуется сериализовать. При невозврате из магического метода значения сериализуется константа `null` и выдаётся предупреждение `E_NOTICE`.

> Замечание:

> Методу __sleep() нельзя возвращать названия закрытых свойств родительских классов. Это сгенерирует ошибку уровня `E_NOTICE`. Для сериализации закрытых родительских свойств вместо магического метода __sleep вызывают магический метод __serialize().

> Замечание:

> Начиная с PHP 8.0.0 при возврате из метода __sleep() значения кроме массива генерируется предупреждение. Раньше выдавалось уведомление.

Назначение метода __sleep() — зафиксировать отложенные данные или выполнить аналогичные задачи очистки. Метод также будет полезным, когда требуется сохранить только часть объекта.

И наоборот, функция unserialize() проверяет в классе определение магического метода с названием __wakeup(). Методу пробуждения, если его определили в классе, доступно восстановление любых ресурсов, которые разрешается содержать объекту.

Назначение метода __wakeup() — восстановить соединения с базой данных, которые потерялись при сериализации, и выполнить другие задачи повторной инициализации.

Пример #2 Пример засыпания и пробуждения

    <?php

    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __sleep()
        {
            return array('dsn', 'username', 'password');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }

    ?>

### Метод __toString()

public function __toString(): string

Метод __toString() разрешает классу выбирать, как класс будет реагировать, когда с ним обращаются как со строкой. Например, класс решает, что выведет выражение `echo $obj;`.

Внимание

С PHP 8.0.0 возвращаемое значение соответствует стандартной семантике PHP-типов, поэтому значение приводится к строке (string), если возможно и если отключили строгую типизацию.

Объект, который реализует интерфейс Stringable, не будет приниматься объявлением типа string, если включили строгую типизацию. Объявление типа должно принимать интерфейс Stringable и строку (string) через объединение типов, если требуется такое поведение.

С PHP 8.0.0 каждый класс, в котором описали магический метод __toString(), неявно реализует интерфейс Stringable, и поэтому проходит проверку типа для этого интерфейса. В определении класса рекомендуют явно указывать, что класс реализует интерфейс.

В PHP 7.4 значение возврата ДОЛЖНО принадлежать типу string, иначе выбрасывается ошибка Error.

До PHP 7.4.0 значение возврата должно было принадлежать типу string, иначе возникала фатальная ошибка уровня `E_RECOVERABLE_ERROR`.

Внимание

До PHP 7.4.0 возникала фатальная ошибка, если из метода __toString() выбрасывали исключение.

Пример #3 Простой пример

    <?php

    // Объявление простого класса
    class TestClass
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString()
        {
            return $this->foo;
        }
    }

    $class = new TestClass('Привет');
    echo $class;

    ?>

Результат выполнения приведённого примера:

    Привет

### Метод __invoke()

function __invoke( `...$values`): mixed

Метод __invoke() вызывается, когда скрипт пытается выполнить объект как функцию.

Пример #4 Пример вызова объекта класса с методом __invoke()

    <?php

    class CallableClass
    {
        public function __invoke($x)
        {
            var_dump($x);
        }
    }

    $obj = new CallableClass();

    $obj(5);
    var_dump(is_callable($obj));

    ?>

Результат выполнения приведённого примера:

    int(5)
    bool(true)

Пример #5 Пример вызова объекта класса с методом __invoke()

    <?php

    class Sort
    {
        private $key;

        public function __construct(string $key)
        {
            $this->key = $key;
        }

        public function __invoke(array $a, array $b): int
        {
            return $a[$this->key] <=> $b[$this->key];
        }
    }

    $customers = [
        ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
        ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
        ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
    ];

    // Сортировка клиентов по имени
    usort($customers, new Sort('first_name'));
    print_r($customers);

    // Сортировка клиентов по фамилии
    usort($customers, new Sort('last_name'));
    print_r($customers);

    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

    )
    Array
    (
        [0] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

    )

### Метод __set_state()

static function __set_state(array `$properties`): object

Этот статический метод вызывается для тех классов, которые экспортируются функцией var_export().

Единственный параметр метода — массив, который содержит экспортируемые свойства в виде `['property' => value, ...]`.

Пример #6 Пример использования метода __set_state()

    <?php

    class A
    {
        public $var1;
        public $var2;

        public static function __set_state($an_array)
        {
            $obj = new A;
            $obj->var1 = $an_array['var1'];
            $obj->var2 = $an_array['var2'];
            return $obj;
        }
    }

    $a = new A();
    $a->var1 = 5;
    $a->var2 = 'foo';

    $b = var_export($a, true);
    var_dump($b);
    eval('$c = ' . $b . ';');
    var_dump($c);

    ?>

Результат выполнения приведённого примера:

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> Замечание: При экспорте объекта функция var_export() не проверяет, реализует ли класс объекта метод __set_state(), поэтому повторный импорт объектов выбросит исключение Error, если метод __set_state() не реализовали. В частности, это относится к ряду внутренних классов. Программист несёт ответственность повторный импорт только тех объектов, класс которых реализует метод __set_state().

### Метод __debugInfo()

function __debugInfo(): array

Этот метод вызывается функцией var_dump(), когда требуется вывести список свойств объекта. Функция выведет каждое объектное свойство c модификаторами public, protected и private, если метод не определили.

Пример #7 Пример вывода отладочной информации методом __debugInfo()

    <?php

    class C
    {
        private $prop;

        public function __construct($val)
        {
            $this->prop = $val;
        }

        public function __debugInfo()
        {
            return [
                'propSquared' => $this->prop ** 2,
            ];
        }
    }

    var_dump(new C(42));

    ?>

Результат выполнения приведённого примера:

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## Ключевое слово final

Ключевое слово `final` указывают в начале объявлений. Окончательные методы, свойства и константы невозможно переопределить в дочернем классе, а окончательный класс становится недоступным для расширения.

Пример #1 Пример окончательных методов

    <?php

    class BaseClass
    {
       public function test()
       {
           echo "Вызван метод BaseClass::test()\n";
       }

       final public function moreTesting()
       {
           echo "Вызван метод BaseClass::moreTesting()\n";
       }
    }

    class ChildClass extends BaseClass
    {
       public function moreTesting()
       {
           echo "Вызван метод ChildClass::moreTesting()\n";
       }
    }
    // Переопределение финального метода вызовет ошибку Fatal error: Cannot override final method BaseClass::moreTesting()

Пример #2 Пример окончательного класса

    <?php

    final class BaseClass
    {
        public function test()
        {
            echo "Вызвали метод BaseClass::test()\n";
        }

        // Поскольку класс уже окончательный, ключевое слово final избыточно
        final public function moreTesting()
        {
            echo "Вызвали метод BaseClass::moreTesting()\n";
        }
    }

    class ChildClass extends BaseClass {}
    // Наследование финального класса вызовет ошибку Fatal error: Class ChildClass may not inherit from final class (BaseClass)

Пример #3 Пример финального свойства, которые появились с PHP 8.4.0

    <?php

    class BaseClass
    {
       final protected string $test;
    }

    class ChildClass extends BaseClass
    {
        public string $test;
    }

    // Переопределение финального свойства вызовет ошибку Fatal error: Cannot override final property BaseClass::$test

Пример #4 Пример финальной константы, которые появились с PHP 8.1.0

    <?php

    class Foo
    {
        final public const X = "foo";
    }

    class Bar extends Foo
    {
        public const X = "bar";
    }

    // Переопределение финальной константы вызовет ошибку Fatal error: Bar::X cannot override final constant Foo::X

> Замечание: С PHP 8.0.0 закрытые методы, за исключением конструкторов , нельзя объявлять финальными.

> Замечание: Свойства, которые объявили c закрытой видимостью области установки значения `private(set)`, неявно получают ключевое слово `final`.

## Клонирование объектов

Создание копии объекта с абсолютно идентичными свойствами не всегда является приемлемым вариантом. Хорошим примером необходимости копирования конструкторов может послужить ситуация, когда у вас есть объект, представляющий собой окно GTK и содержащий ресурс-идентификатор этого окна; когда вы создаёте копию этого объекта, вам может понадобиться, чтобы копия объекта содержала ресурс-идентификатор нового окна. Другим примером может послужить ситуация, когда ваш объект содержит ссылку на какой-либо другой используемый объект и, когда вы создаёте копию родительского объекта, вам нужно также создать новый экземпляр этого другого объекта, так, чтобы копия объекта-контейнера содержала собственный отдельный экземпляр содержащегося объекта.

Копия объекта создаётся с использованием ключевого слова `clone` (который вызывает метод __clone() объекта, если это возможно).

    $copy_of_object = clone $object;

При клонировании объекта, PHP выполняет поверхностную копию всех свойств объекта. Любые свойства, являющиеся ссылками на другие переменные, останутся ссылками.

function __clone(): void

После завершения клонирования, если метод __clone() определён, то будет вызван метод __clone() вновь созданного объекта для возможного изменения всех необходимых свойств.

Пример #1 Клонирование объекта

    <?php
    class SubObject
    {
        static $instances = 0;
        public $instance;

        public function __construct() {
            $this->instance = ++self::$instances;
        }

        public function __clone() {
            $this->instance = ++self::$instances;
        }
    }

    class MyCloneable
    {
        public $object1;
        public $object2;

        function __clone()
        {
            // Принудительно клонируем this->object1, иначе
            // он будет указывать на один и тот же объект.
            $this->object1 = clone $this->object1;
        }
    }

    $obj = new MyCloneable();

    $obj->object1 = new SubObject();
    $obj->object2 = new SubObject();

    $obj2 = clone $obj;

    print "Оригинальный объект:\n";
    print_r($obj);

    print "Клонированный объект:\n";
    print_r($obj2);

    ?>

Результат выполнения приведённого примера:

    Оригинальный объект:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 1
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )
    Клонированный объект:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instance] => 3
            )

        [object2] => SubObject Object
            (
                [instance] => 2
            )

    )

Возможно обращаться к свойствам/методам только что склонированного объекта:

Пример #2 Доступ к только что склонированному объекту

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

Вывод приведённого примера будет похож на:

    2016

## Сравнение объектов

При сравнении объектов через оператор `==` PHP сравнивает переменные, в которых содержатся объекты, в простой манере: два экземпляра объекта равны, если сравнение атрибутов и значений объектов через оператор `==` указывает на равенство, и экземпляры объектов принадлежат одному и тому же классу.

При строгом сравнении объектов через оператор `===` переменные, в которых содержатся объекты, идентичны только тогда, когда переменные ссылаются на один и тот же экземпляр одного и того же класса.

Следующий пример пояснит эти правила.

Пример #1 Пример сравнения объектов

    <?php

    function bool2str($bool)
    {
        return (string) $bool;
    }

    function compareObjects(&$o1, &$o2)
    {
        echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
        echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
        echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
        echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
    }

    class Flag
    {
        public $flag;

        function __construct($flag = true)
        {
            $this->flag = $flag;
        }
    }

    class OtherFlag
    {
        public $flag;

        function __construct($flag = true)
        {
            $this->flag = $flag;
        }
    }

    $o = new Flag();
    $p = new Flag();
    $q = $o;
    $r = new OtherFlag();

    echo "Два экземпляра одного и того же класса\n";
    compareObjects($o, $p);

    echo "\nДве ссылки на один и тот же экземпляр\n";
    compareObjects($o, $q);

    echo "\nЭкземпляры двух разных классов\n";
    compareObjects($o, $r);

    ?>

Результат выполнения приведённого примера:

    Два экземпляра одного и того же класса
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

    Две ссылки на один и тот же экземпляр
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : TRUE
    o1 !== o2 : FALSE

    Экземпляры двух разных классов
    o1 == o2 : FALSE
    o1 != o2 : TRUE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

> Замечание:

> Модули иногда определяют внутренние правила сравнения своих объектов через оператор `==`.

## Позднее статическое связывание

Позднее статическое связывание в PHP — механизм, который разрешает ссылаться на класс вызова в контексте статического наследования.

Точнее, позднее статическое связывание сохраняет класс, название которого указали в последнем «неперенаправленном вызове». При вызове статических методов это тот класс, название которого явно указали слева от оператора `::`; при нестатических вызовах это класс объекта. «Перенаправленным вызовом» называется статический вызов через конструкции `self::`, `parent::`, `static::` или через функцию forward_static_call() при движении вверх по иерархии классов. Строку с названием класса вызова получают функцией get_called_class(), а конструкция `static::` вводит область действия вызываемого класса.

Природа названия «позднее статическое связывание» возникает из внутренней логики работы языка. Связывание называется «поздним», потому что конструкция `static::` разрешается не в тот класс, в котором определили метод, а вычисляется на основе информации в ходе исполнения программы. Связывание также назвали «статическим», поскольку этот механизм в числе прочего умеет вызывать статические методы.

### Ограничения конструкции `self::`

Статические ссылки на текущий класс наподобие конструкции `self::` или константы `__CLASS__` разрешаются в класс, которому принадлежит функция, — в котором функцию определили:

Пример #1 Пример обращения к члену класса через конструкцию `self::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            self::who();
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

Результат выполнения приведённого примера:

    A

### Пример позднего статического связывания

Позднее статическое связывание стремится устранить это ограничение и вводит ключевое слово для ссылки на класс, который изначально вызвали в ходе исполнения программы. По сути, это ключевое слово, которое в предыдущем примере разрешило бы ссылаться на класс `B` из метода `test()`. Вместо введения нового ключевого слова для позднего статического связывания разработчики языка выбрали ключевое слово `static`, которое зарезервировали прежде.

Пример #2 Пример позднего статического связывания через конструкцию `static::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            static::who(); // В этом месте появляется позднее статическое связывание
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

Результат выполнения приведённого примера:

    B

> Замечание:

> В нестатическом контексте классом вызова будет класс экземпляра объекта. Обращение через конструкцию `$this->` попытается вызывать закрытые методы из той же области действия, тогда как результат конструкции `static::` зависит от контекста вызова. Другое отличие состоит в том, что обращение через конструкцию `static::` умеет ссылаться только на статические свойства.

Пример #3 Пример ссылки через конструкцию `static::` в нестатическом контексте

    <?php

    class A
    {
        private function foo()
        {
            echo "Success!\n";
        }

        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
        /* Метод foo() скопируется в класс В из класса A, поэтому областью действия метода
          по-прежнему будет класс А, и вызов будет успешным */
    }

    class C extends A
    {
        private function foo()
        {
            /* Этот метод заменил собой исходный; область действия нового метода — класс С */
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

Результат выполнения приведённого примера:

    Success!
    Success!
    Success!
    Call to private method C::foo() from scope A

> Замечание:

> Разрешение поздних статических связок останавливается на статическом вызове по полному названию класса, без попытки перенаправить вызов в класс, в котором сделали последний неперенаправленный вызов. Между тем, статические вызовы через конструкции `parent::` или `self::` перенаправляют информацию о вызове.

> Пример #4 Пример перенаправленных и неперенаправленных вызовов

>     <?php

>     class A
>     {
>         public static function foo()
>         {
>             static::who();
>         }

>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     class B extends A
>     {
>         public static function test()
>         {
>             A::foo();
>             parent::foo();
>             self::foo();
>         }

>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     class C extends B
>     {
>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     C::test();

>     ?>

> Результат выполнения приведённого примера:

>     A
>     C
>     C

## Объекты и ссылки

Разработчики при обсуждении объектно-ориентированного программирования на языке PHP часто утверждают, что «по умолчанию объекты передаются по ссылке». Это не совсем так. Этот раздел объясняет общую мысль утверждения на примерах.

Ссылка в PHP — псевдоним, который разрешает присвоить двум переменным одно и то же значение. В PHP объектная переменная не содержит сам объект как значение. Такая переменная содержит только идентификатор объекта, который разрешает средствам доступа к объекту найти сам объект. Переменные, через которые объект передаётся как аргумент функции, или возвращается или присваивается другой переменной, — не относятся к псевдонимам: эти переменные содержат копию идентификатора, который указывает на один и тот же объект.

Пример #1 Ссылки и объекты

    <?php

    class A
    {
        public $foo = 1;
    }

    $a = new A();
    $b = $a;     // Переменные $a и $b — копии одного и того же идентификатора
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A();
    $d = &$c;    // Переменные $c и $d — ссылки
                 // ($c, $d) = <id>

    $d->foo = 2;
    echo $c->foo."\n";

    $e = new A();

    function foo($obj)
    {
        // ($obj) = ($e) = <id>
        $obj->foo = 2;
    }

    foo($e);
    echo $e->foo."\n";

    ?>

Результат выполнения приведённого примера:

    2
    2
    2

## Сериализация объектов — сохранение объектов между сессиями

Функция serialize() возвращает строковое представление любого значения, которое может быть сохранено в PHP. Функция unserialize() может использовать эту строку для восстановления исходного значения переменной. Использование сериализации для сохранения объекта сохранит все его переменные. Методы в объекте не будут сохранены, только имя класса.

Чтобы десериализовать объект функцией unserialize(), необходимо заранее определить класс этого объекта. То есть, если есть экземпляр класса А, и он будет сериализован, будет получено его строковое представление, которое содержит значение всех переменных, содержащихся в нем. Чтобы восстановить объект из строки в другом PHP-файле, класс A должен быть определён в этом файле заранее. Это можно сделать, например, путём сохранения определения класса A в отдельном файле и подключения этого файла или вызовом функции spl_autoload_register() для автоматического подключения.

    <?php
    // A.php:

      class A {
          public $one = 1;

          public function show_one() {
              echo $this->one;
          }
      }

    // page1.php:

      include "A.php";

      $a = new A;
      $s = serialize($a);
      // сохраняем $s где-нибудь, откуда page2.php сможет его получить.
      file_put_contents('store', $s);

    // page2.php:

      // это нужно для того, чтобы функция unserialize работала правильно.
      include "A.php";

      $s = file_get_contents('store');
      $a = unserialize($s);

      // теперь можно использовать метод show_one() объекта $a.
      $a->show_one();
    ?>

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

Поэтому, как в примере выше, если переменная $a стала частью сессии путём добавления нового ключа в суперглобальный массив $_SESSION, нужно подключать файл `A.php` на всех страницах, а не только на страницах page1.php и page2.php.

Обратите внимание, что, кроме уже приведённого совета, можно подключиться к событиям сериализации и десериализации объекта через методы __sleep() и __wakeup(). В методе __sleep() можно управлять тем, какие свойства объекта будут сериализованы.

## Ковариантность и контравариантность

В PHP 7.2.0 путём снятия ограничений типа для параметров в дочернем методе добавили частичную контравариантность. Начиная с PHP 7.4.0 добавили полную поддержку ковариантности и контравариантности.

Ковариантность разрешает дочернему методу возвращать более конкретный тип, чем тип значения возврата родительского метода. Контравариантность разрешает определить тип параметра в дочернем методе менее конкретным, чем в родительском.

Объявление типа считают более конкретным в следующем случае:

- Удалили тип из объединения типов
- Добавили тип к пересечению типов
- Тип класса изменили на тип дочернего класса
- Тип iterable изменили на тип array или Traversable

Класс типа считают менее конкретным, если верно обратное.

### Ковариантность

Создадим простой абстрактный родительский класс Animal, чтобы проиллюстрировать работу ковариантности. Класс Animal расширяется дочерними классами Cat и Dog.

    <?php

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function speak();
    }

    class Dog extends Animal
    {
        public function speak()
        {
            echo $this->name . " лает";
        }
    }

    class Cat extends Animal
    {
        public function speak()
        {
            echo $this->name . " мяукает";
        }
    }

    ?>

Обратите внимание, пример не содержит методов, которые возвращают значения. Добавим ряд фабрик, которые возвращают новый объект с типом класса Animal, Cat или Dog.

    <?php

    interface AnimalShelter
    {
        public function adopt(string $name): Animal;
    }

    class CatShelter implements AnimalShelter
    {
        public function adopt(string $name): Cat // Возвращаем тип Cat вместо типа Animal
        {
            return new Cat($name);
        }
    }

    class DogShelter implements AnimalShelter
    {
        public function adopt(string $name): Dog // Возвращаем тип Dog вместо типа Animal
        {
            return new Dog($name);
        }
    }

    $kitty = (new CatShelter())->adopt("Рыжик");
    $kitty->speak();
    echo "\n";

    $doggy = (new DogShelter())->adopt("Бобик");
    $doggy->speak();

    ?>

Результат выполнения приведённого примера:

    Рыжик мяукает
    Бобик лает

### Контравариантность

В продолжение предыдущего примера с классами Animal, Cat и Dog введём новые классы — Food и AnimalFood, и добавим в абстрактный класс Animal новый метод eat(AnimalFood $food).

    <?php

    class Food {}

    class AnimalFood extends Food {}

    abstract class Animal
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function eat(AnimalFood $food)
        {
            echo $this->name . " ест " . get_class($food);
        }
    }

    ?>

Переопределим метод eat в классе Dog так, чтобы метод принимал любой объект с типом Food, чтобы увидеть суть контравариантности. Класс Cat оставим без изменений.

    <?php

    class Dog extends Animal
    {
        public function eat(Food $food)
        {
            echo $this->name . " ест " . get_class($food);
        }
    }

    ?>

Следующий пример покажет поведение контравариантности.

    <?php

    $kitty = (new CatShelter())->adopt("Рыжик");
    $catFood = new AnimalFood();
    $kitty->eat($catFood);
    echo "\n";

    $doggy = (new DogShelter())->adopt("Бобик");
    $banana = new Food();
    $doggy->eat($banana);

    ?>

Результат выполнения приведённого примера:

    Рыжик ест AnimalFood
    Бобик ест Food

Но что произойдёт, если кошка $kitty попробует методом eat() съесть банан $banana?

    $kitty->eat($banana);

Результат выполнения приведённого примера:

    Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given

### Вариативность свойств

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

Начиная с PHP 8.4.0, в котором добавили абстрактные свойства в интерфейсе или абстрактном классе и виртуальные свойства, разрешается объявить свойство, доступное только для операций чтения или записи. Итогом нововведений стало то, что абстрактным свойствам или виртуальным свойствам, для которых требуется только операция "get", доступна ковариантность. Аналогично, абстрактному свойству или виртуальному свойству, для которого требуется только операция "set", доступна контравариантность.

Однако как только для свойства объявили как операцию get, так и операцию set, свойство теряет ковариантность или контравариантность для расширения, и снова становится инвариантным.

Пример #1 Пример вариативности типа свойства

    <?php

    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // Требуется только операция get, поэтому свойству доступна ковариантность
        public Animal $pet {
            get;
        }
    }

    class DogOwner implements PetOwner
    {
        // Свойству возможно указать более ограниченный тип, поскольку со стороны операции get
        // по-прежнему возвращается Animal. Однако, поскольку это внутреннее свойство текущего класса,
        // потомкам класса больше нельзя изменять тип свойства
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // Изменение свойства НЕДОПУСТИМО, поскольку для свойства DogOwner::$pet
        // определили поведение операций get и set, и дочерние классы обязаны соблюдать
        // контракт родительского класса при переопределении свойства
        public Poodle $pet;
    }

    ?>

## Ленивые объекты

Ленивый объект — объект, инициализация которого откладывается до момента отслеживания или изменения состояния. Отдельные примеры работы с ленивыми объектами включают: а) компоненты внедрения зависимостей, которые предоставляют отложенные службы, которые инициализируются на 100 % только когда требуются б) ORM-инструменты, которые предоставляют ленивые объекты, которые гидрируются значениями из базы данных только при обращении к ORM-объекту или в) JSON-парсер, который откладывает разбор до тех пор, пока к элементам не обратятся.

Поддерживаются две стратегии ленивых объектов: объекты-призраки (англ. Ghost Objects) и виртуальные прокси (англ. Virtual Proxies), которые здесь и дальше называются «ленивые призраки» и «ленивые прокси». В обеих стратегиях ленивый объект прикрепляется к инициализатору или фабрике, которая вызывается автоматически, когда состояние объекта начинают отслеживать или изменяют в первый раз. С точки зрения абстракции ленивые объекты-призраки неотличимы от неленивых: с такими объектами работают, не зная, что они ленивые, что разрешает коду передавать и обрабатывать такие объекты без знания о лени объектов. Ленивые прокси тоже прозрачны, но когда потребуется отличить ленивый объекты-прокси от реального экземпляра, соблюдают осторожность, поскольку у объекта-прокси и его реального экземпляра разные идентификаторы.

> Замечание: Сведения о версии
> Ленивые объекты появились в PHP 8.4.

### Создание ленивых объектов

PHP разрешает создавать ленивыми экземпляры пользовательских классов или стандартного PHP-класса stdClass (другие внутренние классы не поддерживаются) или сбрасывать экземпляры этих классов, чтобы сделать объект ленивым. Точки входа, через которые создают ленивые объекты, — методы ReflectionClass::newLazyGhost() и ReflectionClass::newLazyProxy().

Оба метода принимают callback-функцию, которая вызывается, когда требуется инициализация объекта. Поведение, которого ждут от функции обратного вызова, меняется, и зависит от стратегии. Стратегии описывает справочная документация к методам.

Пример #1 Пример создания ленивого призрака

    <?php

    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // Инициализируем объект позже, на месте — по требованию
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Запускаем инициализацию
    var_dump($lazyObject->prop);

Результат выполнения приведённого примера:

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Пример #2 Пример создания ленивого прокси

    <?php

    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // Создаём и возвращаем реальный экземпляр
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Запускаем инициализацию
    var_dump($lazyObject->prop);

Результат выполнения приведённого примера:

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Доступ к свойствам ленивого объекта запускает инициализацию ленивого объекта, включая доступ через класс ReflectionProperty. При этом отдельные свойства иногда известны заранее и требуется предотвратить срабатывание инициализации при доступе:

Пример #3 Пример упреждающей инициализации свойств

    <?php

    class BlogPost
    {
        public function __construct(
            public int $id,
            public string $title,
            public string $content,
        ) {}
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // Без этой строки вызов метода ReflectionProperty::setValue(), который идёт следующим,
    // запустит инициализацию
    $reflector->getProperty('id')->skipLazyInitialization($post);

    $reflector->getProperty('id')->setValue($post, 123);

    // Альтернативный способ установки значения свойства без запуска ленивой инициализации
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // Доступ к свойству id возможен без запуска инициализации.
    var_dump($post->id);

Методы ReflectionProperty::skipLazyInitialization() и ReflectionProperty::setRawValueWithoutLazyInitialization() предлагают способы обхода инициализации ленивых объектов при доступе к свойству.

### О стратегиях ленивых объектов

Ленивые призраки — объекты, которые инициализируются на месте, и после инициализации неотличимы от объекта, который никогда не был ленивым. Стратегию применяют, когда контролируют как создание экземпляра, так и инициализацию объекта, что делает стратегию непригодной, если хотя бы один из этих процессов управляется другой стороной.

Ленивые прокси после инициализации действуют как прокси до реального экземпляра: операции на инициализированном ленивом прокси перенаправляются на реальный экземпляр. Создание реального экземпляра разрешается делегировать другой стороне, что делает эту стратегию полезной, когда ленивые призраки не подходят. Хотя ленивые прокси почти так же прозрачны, как ленивые призраки, потребуется осторожность, когда потребуется отличить ленивый прокси от реального объекта, поскольку объект-прокси и его реальный экземпляр получают разные идентификаторы.

### Жизненный цикл ленивых объектов

Объекты делают ленивыми либо сразу — путём вызова метода ReflectionClass::newLazyGhost() или ReflectionClass::newLazyProxy(), либо создают, а затем передают реальный объект в метод ReflectionClass::resetAsLazyGhost() или ReflectionClass::resetAsLazyProxy(). Следующие операции инициализируют ленивый объект:

- Взаимодействие с объектом, при котором вызывается автоматическая инициализация. См. «Триггеры инициализации».
- Пометка каждого свойства ленивого объекта как неленивое методом ReflectionProperty::skipLazyInitialization() или ReflectionProperty::setRawValueWithoutLazyInitialization().
- Явный вызов метода ReflectionClass::initializeLazyObject() или ReflectionClass::markLazyObjectAsInitialized().

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

### Триггеры инициализации

Ленивые объекты спроектировали на 100 % прозрачными для потребителей, поэтому обычные операции, которые отслеживают или изменяют состояние объекта, автоматически инициализируют ленивый объект перед выполнением операции. Инициализацию запускает следующий неполный список операций:

- Чтение или запись свойства.
- Проверка установки свойства или удаление свойства.
- Доступ к свойству или изменение свойства методами ReflectionProperty::getValue(), ReflectionProperty::getRawValue(), ReflectionProperty::setValue() или ReflectionProperty::setRawValue().
- Получение списка свойств методами ReflectionObject::getProperties() или ReflectionObject::getProperty(), или функцией get_object_vars().
- Итерация по свойствам объекта, который не реализует интерфейс Iterator или IteratorAggregate, конструкцией foreach.
- Сериализация ленивого объекта функциями serialize(), json_encode() или другими.
- Клонирование ленивого объекта.

Вызовы методов, которые не обращаются к состоянию объекта, не инициализируют ленивый объект. Аналогично, взаимодействия с объектом, которые вызывают магические методы или функции хука, не инициализируют ленивый объект, если для этих методов или функций не открыт доступ к состоянию объекта.

#### Нетриггерные операции

Следующие специальные методы или низкоуровневые операции получают доступ к ленивым объектам или изменяют ленивые объекты без запуска инициализации:

- Пометка свойств неленивыми методом ReflectionProperty::skipLazyInitialization() или ReflectionProperty::setRawValueWithoutLazyInitialization().
- Получение внутреннего представления свойств функцией get_mangled_object_vars() или через приведение объекта к массиву.
- Вызов функции serialize() при установке флага `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE`, если только функция __serialize() или __sleep() не запустила инициализацию.
- Вызов магического метода ReflectionObject::__toString().
- Вызов функции var_dump() или debug_zval_dump(), если только магический метод __debugInfo() не запустил инициализацию.

### Последовательность инициализации

Раздел описывает характерные для стратегий последовательности операций, которые выполняются при запуске инициализации.

#### Объекты-призраки

- Ленивый призрак помечается как неленивый.
- Свойствам, которые не инициализировали методом ReflectionProperty::skipLazyInitialization() или ReflectionProperty::setRawValueWithoutLazyInitialization(), устанавливаются значения по умолчанию, если такие определили в классе. На этом этапе объект напоминает объект, который создали методом ReflectionClass::newInstanceWithoutConstructor(), за исключением свойств, которые уже инициализировались.
- Затем вызывается callback-функция инициализатора с объектом в качестве первого аргумента. Ожидается, что функция обратного вызова — хотя это и не обязательно — инициализирует состояние объекта и вернёт `null` или не вернёт никакого значения. На этом этапе объект перестаёт быть ленивым, поэтому функция получает прямой доступ к свойствам реального объекта.

После инициализации объект неотличим от объекта, который никогда не был ленивым.

#### Объекты-прокси

- Ленивый прокси помечается как неленивый.
- В отличие от ленивых призраков, свойства ленивых прокси на этом этапе не изменяются.
- Фабричная callback-функция вызывается с объектом в качестве первого аргумента и возвращает неленивый экземпляр совместимого класса. Смотрите описание метода ReflectionClass::newLazyProxy().
- Экземпляр, который вернула функция обратного вызова, называется реальным экземпляром и прикрепляется к прокси.
- Значения свойств ленивого прокси отбрасываются так, как если бы вызвали языковую конструкцию unset().

После инициализации доступ к свойствам объекта-прокси даст тот же результат, что и доступ к тому же свойству реального экземпляра; обращения к свойствам объекта-прокси перенаправляются на реальный экземпляр, включая объявленные, динамические, несуществующие свойства или свойства, которые пометили методом ReflectionProperty::skipLazyInitialization() или ReflectionProperty::setRawValueWithoutLazyInitialization().

Сам объект-прокси не заменяется и не подменяет собой реальный экземпляр.

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

#### Общее поведение

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

После успешной инициализации объект больше не ссылается на инициализатор или фабричную функцию и доступен для освобождения, если на объект не осталось других ссылок.

Состояние объекта возвращается к состоянию до инициализации, а объект снова помечается как ленивый, если инициализатор генерирует исключение. Другими словами, каждое воздействие на сам объект отменяется. Другие побочные эффекты наподобие воздействия на другие объекты не отменяются. Это предотвращает предоставление частично инициализированного экземпляра при ошибке.

### Клонирование

Клонирование ленивого объекта запускает его инициализацию раньше, чем создаётся клон, поэтому объект инициализируется.

При клонировании объектов-прокси клонируется как прокси, так и его реальный экземпляр, и возвращается клон прокси. Магический метод `__clone` вызывается на реальном экземпляре, не на прокси. Клонированный прокси и реальный экземпляр связываются так, как они связались при инициализации, поэтому доступ к клону объекта-прокси перенаправляется на клон реального экземпляра.

Такое поведение гарантирует, что клон и исходный объект сохраняют разные состояния. Изменения состояния исходного объекта или состояния его инициализатора после клонирования не влияют на клон. Клонирование и прокси, и его реального экземпляра вместо возврата только клона реального экземпляра гарантирует, что операция клонирования стабильно возвращает объект того же класса.

### Деструкторы

Для ленивых призраков деструктор вызывается, только если объект инициализировали. Для прокси деструктор вызывается только для реального экземпляра, если реальный экземпляр существует.

Методам ReflectionClass::resetAsLazyGhost() и ReflectionClass::resetAsLazyProxy() разрешается вызывать деструктор сбрасываемого объекта.

## Журнал изменений ООП

Раздел ведёт журнал изменений ООП-модели PHP. Описания и другие примечания этих функций приводит документация ООП-модели PHP.

Версия | Описание
--- | ---
8.4.0 | Добавили: Поддержка хуков свойств.
8.4.0 | Добавили: Поддержка «Ленивых объектов».
8.1.0 | Добавили: Поддержка модификатора final для констант класса. Кроме того, константы интерфейса по умолчанию становятся переопределяемыми.
8.0.0 | Добавили: Поддержка Null-безопасного оператора ?-> для доступа к свойствам и методам объектов, которые иногда равны null.
7.4.0 | Изменили: В магическом методе __toString() теперь разрешили выбрасывать исключение.
7.4.0 | Добавили: Поддержка ограниченной ковариантности типов возвращаемого значения и типов аргументов. Поддержка полной вариативности доступна только при автозагрузке. Внутри одного файла возможны только нециклические ссылки на типы.
7.4.0 | Добавили: Разрешили задавать тип для свойств класса.
7.3.0 | Несовместимость: Распаковка аргументов объектов, которые реализуют интерфейс Traversable, с нецелочисленными ключами больше не поддерживается. Такое поведение изначально не планировали и теперь удалили.
7.3.0 | Несовместимость: В прошлых версиях разрешали разделить статические свойства путём присваивания по ссылке. Теперь нельзя.
7.3.0 | Изменили: Оператор instanceof теперь принимает литералы в первом операнде. Проверка с литералом в первом аргументе при каждом вызове возвращает `false`.
7.2.0 | Устарело: Метод __autoload() устарел в пользу функции spl_autoload_register().
7.2.0 | Изменили: Нельзя называть классы, интерфейсы и трейты словом `object`.
7.2.0 | Изменили: В конце списка группового use разрешили добавлять висящую запятую.
7.2.0 | Изменили: Типы параметров из переопределённых методов и реализации интерфейсов теперь указывать не обязательно.
7.2.0 | Изменили: Если один абстрактный класс наследует от другого абстрактного класса, то он может переопределять его абстрактные методы.
7.1.0 | Изменили: для имён классов, интерфейсов и трейтов нельзя использовать слова: `void` и `iterable`.
7.1.0 | Добавили: теперь можно задавать область видимости для констант классов.
7.0.0 | Устарело: Статический вызов нестатических методов.
7.0.0 | Устарело: конструктор в стиле PHP 4. Т.е. метод с именем идентичным имени класса, в котором он объявлен.
7.0.0 | Добавили: групповая декларация use: классы, функции и константы, которые надо импортировать из одного и того же пространства имён теперь могут быть сгруппированы в одном выражении use.
7.0.0 | Добавили: добавлена поддержка анонимных классов с помощью `new class`.
7.0.0 | Несовместимость: итерирование объектов не реализующих Traversable теперь ведёт себя аналогично итерированию массива по ссылке.
7.0.0 | Изменили: Определение одинаковых (полностью совпадающих) свойств в двух трейтах больше не вызывает ошибку.
5.6.0 | Добавили: метод __debugInfo().
5.5.0 | Добавили: магическая константа ::class.
5.5.0 | Добавили: finally в обработчик исключений.
5.4.0 | Добавили: трейты.
5.4.0 | Изменили: Если абстрактный класс определяет сигнатуру для конструктора, то она будет принудительно применяться.
5.3.3 | Изменили: Методы с тем же именем, что и последний элемент пространства имён класса больше не будут рассматриваться как конструктор. Это изменение не влияет классы, не использующие пространства имён.
5.3.0 | Изменили: Больше не требуется, чтобы классы, реализующие интерфейсы с методами, которые имеют значения по умолчанию в прототипе, соответствовали значениям по умолчанию в интерфейсе.
5.3.0 | Изменили: Теперь стало возможным ссылаться на класс, используя переменную (например, `echo $classname::constant;`). Значение переменной не может быть ключевым словом (например, `self`, `parent` или `static`).
5.3.0 | Изменили: Ошибка `E_WARNING` происходит, если магические перегруженные методы объявлены как статические. Это также усиливает требование, что эти методы должны быть общедоступными.
5.3.0 | Изменили: До 5.3.0, исключения в функции __autoload() не могли быть перехвачены в блоке catch и приводили к фатальной ошибке. Сейчас исключения в функции __autoload могут быть перехвачены в блоке catch, но с одной оговоркой. Если перехватывается пользовательское исключение, то класс, обрабатывающий это исключение, должен быть доступен. Функция __autoload может быть использована рекурсивно для автозагрузки пользовательского класса обработки исключения.
5.3.0 | Добавили: Метод __callStatic.
5.3.0 | Добавили: Поддержка heredoc и nowdoc для констант и определений свойств класса. Примечание: Значение heredoc должны следовать тем же правилам, что и строки в двойных кавычках (например, без переменных внутри).
5.3.0 | Добавили: Позднее статическое связывание.
5.3.0 | Добавили: метод __invoke().
5.2.0 | Изменили: Метод __toString() вызывался только, когда он напрямую объединён с echo или print. Сейчас он вызывается в любом контексте строки (например, в printf() с модификатором `%s`), но не в других типах контекста (например, с модификатором `%d`). С PHP 5.2.0, преобразование объектов без метода __toString в строку выдаёт ошибку уровня `E_RECOVERABLE_ERROR`.
5.1.3 | Изменили: В предыдущих версиях PHP 5 использование `var` считалось устаревшим и выдавало ошибку `E_STRICT`. Сейчас это не считается устаревшим, поэтому ошибка больше не выдаётся.
5.1.0 | Изменили: Статический метод __set_state() теперь вызывается для классов, экспортируемых функцией var_export().
5.1.0 | Добавлены: методы __isset() и __unset().

# Пространства имён

## Содержание

- Обзор
- Пространства имён
- Подпространства имён
- Несколько пространств имён в одном файле
- Основы
- Пространства имён и динамические особенности языка
- Ключевое слово namespace и константа __NAMESPACE__
- Псевдонимирование и импорт
- Глобальное пространство
- Возврат к глобальному пространству
- Правила разрешения имён
- FAQ

## Обзор пространств имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Пространства имён, в широком смысле, — способ инкапсуляции элементов. Такое абстрактное понятие встречается часто. Например, в каждой операционной системе директории группируют связанные файлы и выступают в роли пространства имён для находящихся в них файлов. Конкретный пример, разрешается размещать файл `foo.txt` сразу в обоих каталогах: `/home/greg` и `/home/other`, но двум копиям файла `foo.txt` нельзя сосуществовать в одной директории. Кроме сказанного, для доступа к файлу `foo.txt` извне каталога `/home/greg` надо через разделитель добавить перед именем файла имя директории, чтобы получить путь `/home/greg/foo.txt`. Этот же принцип распространяется и на пространства имён в программировании.

В PHP пространства имён решают две проблемы, с которыми сталкиваются авторы библиотек и приложений, когда создают переиспользуемые элементы кода, например классы и функции:

1. Устраняют конфликт имён между кодом разработчика и внутренними или внешними классами, функциями, константами PHP.
2. Создают псевдонимы (или сокращения) для Ну_Очень_Длинных_Имён, чтобы сгладить первую проблему и улучшить читаемость исходного кода.

Пространства имён в PHP помогают группировать логически связанные классы, интерфейсы, функции и константы.

Пример #1 Пример синтаксиса с пространством имён

    <?php

    namespace my\name; // Смотрите раздел «Определение пространств имён»

    class MyClass {}
    function myfunction() {}
    const MYCONST = 1;

    $a = new MyClass;
    print $a::class . "\n";
    $c = new \my\name\MyClass; // Смотрите раздел «Глобальное пространство»
    print $c::class . "\n";

    $a = strlen('hi'); // Смотрите раздел «Пространства имён: возврат
                       // к глобальному пространству для функций и констант»
    print $a . "\n";

    $d = namespace\MYCONST; // Смотрите раздел «Ключевое слово namespace и магическая константа __NAMESPACE__»
    print $d . "\n";
    $d = __NAMESPACE__ . '\MYCONST';
    echo constant($d); // Смотрите раздел «Пространства имён и динамические особенности языка»

> Замечание: Имена пространств имён регистронезависимы.

> Замечание:

> Название пространства имён «`PHP`» и составные названия, которые начинаются с этого слова (например, `PHP\Classes`), зарезервированы для внутренних целей языка, их не нужно писать в пользовательском коде.

## Определение пространств имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Хотя любой корректный PHP-код разрешается размещать внутри пространства имён, только классы (включая абстрактные классы, трейты и перечисления), интерфейсы, функции и константы зависят от пространства имён.

Пространства имён объявляют зарезервированным словом `namespace`, за которым идёт название пространства имён. Пространства имён объявляют в начале файла. Другому коду нельзя идти перед объявлением пространства имён, за исключением зарезервированного слова declare.

Пример #1 Объявление единого пространства имён

    <?php

    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

> Замечание: Абсолютные имена, — которые начинаются с обратной косой черты, — нельзя включать в объявления пространств имён, поскольку языковые конструкции с начальным слешем интерпретируются как выражения относительных пространств имён.

Перед объявлением пространства имён разрешается указывать только инструкцию `declare`, чтобы, например, определить кодировку исходного файла. В дополнение, никакой код, кроме PHP-кода, нельзя размещать перед объявлением пространства имён, включая лишние пробелы:

Пример #2 Объявление пространства имён

    <html>
    <?php

    namespace MyProject; // Фатальная ошибка, поскольку объявление пространства имён идёт не первой инструкцией в скрипте

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

## Определение подпространств имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Аналогично каталогам и файлам, пространства имён PHP разрешают указывать иерархию названий пространств имён. Поэтому имя пространства разрешается определять с подуровнями:

Пример #1 Определение пространства имён с иерархией

    <?php

    namespace MyProject\Sub\Level;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

Приведённый пример создаёт константу `MyProject\Sub\Level\CONNECT_OK`, класс `MyProject\Sub\Level\Connection` и функцию `MyProject\Sub\Level\connect`.

## Описание нескольких пространств имён в одном файле

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

В одном файле разрешается объявлять больше одного пространства имён. Многократные пространства имён в одном файле разрешается определять двумя синтаксисами:

Пример #1 Объявление набора пространств имён синтаксисом простой комбинации

    <?php

    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    namespace AnotherProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

Этот синтаксис не рекомендуют для комбинирования пространств имён в одном файле. Вместо него лучше пользоваться альтернативным синтаксисом со скобками.

Пример #2 Объявление набора пространств имён синтаксисом со скобками

    <?php

    namespace MyProject {
        const CONNECT_OK = 1;
        class Connection { /* ... */ }
        function connect() { /* ... */  }
    }

    namespace AnotherProject {
        const CONNECT_OK = 1;
        class Connection { /* ... */ }
        function connect() { /* ... */  }
    }

Практика написания кода настоятельно не рекомендует объединять пространства имён в одном файле. Главный сценарий того, когда это потребуется, — объединение нескольких PHP-файлов в один файл.

Для объединения кода в глобальном пространстве имён с кодом в других пространствах имён пользуются только синтаксисом со скобками. Глобальный код должен быть помещён в конструкцию описания пространства имён без указания имени:

Пример #3 Описание глобального и обычного пространства имён в одном файле

    <?php
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connect() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // Глобальный код
    print strlen("hi") . "\n";
    MyProject\connect();
    MyProject\Connection::start();
    }

Никакой PHP-код нельзя размещать за пределами скобок пространства имён, кроме начального выражения declare.

Пример #4 Описание глобального и обычного пространства имён в одном файле

    <?php
    declare(strict_types=1);
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connect() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // Глобальный код
    print strlen("hi") . "\n";
    MyProject\connect();
    MyProject\Connection::start();
    }

## Основы пространств имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

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

1. Относительное имя файла наподобие `foo.txt` разрешится в `currentdirectory/foo.txt`, где `currentdirectory` — текущая директория, в которой мы находимся. Тогда, если текущая директория — `/home/foo`, то имя преобразуется в `/home/foo/foo.txt`.
2. Относительное имя пути наподобие `subdirectory/foo.txt` разрешится в `currentdirectory/subdirectory/foo.txt`.
3. Абсолютное имя пути наподобие `/main/foo.txt` останется таким же: `/main/foo.txt`.

Тот же принцип сохранится при разрешении элементов из пространств имён PHP. Название класса, например, указывают тремя способами:

1. Неполное имя, или название класса без префикса, наподобие `$a = new foo();` или `foo::staticmethod();`. В текущем пространстве имён `currentnamespace` такое название разрешится в `currentnamespace\foo`. В коде в глобальном пространстве имён название останется прежним: `foo`. Предостережение: неполные названия функций и констант разрешаются в глобальные функции и константы, если их не определили в текущем пространстве имён. Подробнее об этом рассказывает раздел «Пространства имён: возврат к глобальному пространству для функций и констант».
2. Полное имя, или название класса с префиксами наподобие `$a = new subnamespace\foo();` или `subnamespace\foo::staticmethod();`. В текущем пространстве имён `currentnamespace` такое название разрешится в `currentnamespace\subnamespace\foo`. В коде в глобальном пространстве имён название разрешится в `subnamespace\foo`.
3. Абсолютное имя, или название с префиксом в начале, который указывает на глобальное пространство имён наподобие `$a = new \currentnamespace\foo();` или `\currentnamespace\foo::staticmethod();`. Такое название разрешается в буквальное, — которое указали в коде: `currentnamespace\foo`.

Вот пример трёх видов синтаксиса в реальном коде:

file1.php

    <?php

    namespace Foo\Bar\subnamespace;

    const FOO = 1;

    function foo() {}

    class foo
    {
        static function staticmethod() {}
    }

file2.php

    <?php

    namespace Foo\Bar;

    include 'file1.php';

    const FOO = 2;
    function foo() {}

    class foo
    {
        static function staticmethod() {}
    }

    /* Неполные имена */
    foo(); // Разрешается в функцию Foo\Bar\foo
    foo::staticmethod(); // Разрешается в метод staticmethod класса Foo\Bar\foo
    echo FOO; // Разрешается в константу Foo\Bar\FOO

    /* Полные имена */
    subnamespace\foo(); // Разрешается в функцию Foo\Bar\subnamespace\foo
    subnamespace\foo::staticmethod(); // Разрешается в метод staticmethod класса Foo\Bar\subnamespace\foo
    echo subnamespace\FOO; // Разрешается в константу Foo\Bar\subnamespace\FOO

    /* Абсолютные имена */
    \Foo\Bar\foo(); // Разрешается в функцию Foo\Bar\foo
    \Foo\Bar\foo::staticmethod(); // Разрешается в метод staticmethod класса Foo\Bar\foo
    echo \Foo\Bar\FOO; // Разрешается в константу Foo\Bar\FOO

Обратите внимание, что для доступа к глобальным классам, функциям или константам разрешается указывать абсолютное имя, например, \strlen(), \Exception или \`INI_ALL`.

Пример #1 Доступ к глобальным классам, функциям и константам из пространства имён

    <?php

    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    print \strlen('hi') . "\n"; // Вызывает глобальную функцию strlen
    print \INI_ALL . "\n"; // Получает доступ к глобальной константе INI_ALL
    $c = new \Exception('error'); // Создаёт экземпляр глобального класса Exception
    print $c::class . "\n";

## Пространства имён и динамические особенности языка

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

На реализацию пространств имён в PHP повлияли и динамические свойства языка. Поэтому, для преобразования кода наподобие следующего примера в код, который сработает внутри пространства имён:…

Пример #1 Динамически доступные элементы

example1.php:

    <?php

    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }

    function funcname()
    {
        echo __FUNCTION__,"\n";
    }

    const constname = "global";

    $a = 'classname';
    $obj = new $a(); // Выводит classname::__construct

    $b = 'funcname';
    $b(); // Выводит funcname

    echo constant('constname'), "\n"; // Выводит global

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

Пример #2 Динамически доступные элементы пространства имён

    <?php

    namespace namespacename;

    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }

    function funcname()
    {
        echo __FUNCTION__,"\n";
    }

    const constname = "namespaced";

    include 'example1.php';

    $a = 'classname';
    $obj = new $a; // Выводит: classname::__construct
    $b = 'funcname';
    $b(); // Выводит: funcname
    echo constant('constname'), "\n"; // Выводит: global

    /* Обратите внимание, что в двойных кавычках символ обратного слеша потребуется заэкранировать. Например: "\\namespacename\\classname" */
    $a = '\namespacename\classname';
    $obj = new $a; // Выводит: namespacename\classname::__construct
    $a = 'namespacename\classname';
    $obj = new $a; // Тоже выводит: namespacename\classname::__construct
    $b = 'namespacename\funcname';
    $b(); // Выводит: namespacename\funcname
    $b = '\namespacename\funcname';
    $b(); // Тоже выводит: namespacename\funcname
    echo constant('\namespacename\constname'), "\n"; // Выводит: namespaced
    echo constant('namespacename\constname'), "\n"; // Тоже выводит: namespaced

Обязательно прочитайте примечание об экранировании имён пространства имён в строках.

## Ключевое слово namespace и магическая константа __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP поддерживает два способа абстрактного доступа к элементам в текущем пространстве имён: магическая константа `__NAMESPACE__` и ключевое слово `namespace`.

Значение константы `__NAMESPACE__` — строка, которая содержит название текущего пространства имён. В глобальном пространстве, вне пространства имён, константа содержит пустую строку.

Пример #1 Пример записи константы __NAMESPACE__ в коде с пространством имён

    <?php

    namespace MyProject;

    echo '"', __NAMESPACE__, '"'; // Выводит: MyProject

Пример #2 Пример записи константы __NAMESPACE__ в глобальном пространстве

    <?php
    echo '"', __NAMESPACE__, '"'; // Выводит: ""

Константа `__NAMESPACE__` полезна для динамически конструируемых имён, например:

Пример #3 Константа __NAMESPACE__ и динамическое конструирование имени

    <?php

    namespace MyProject;

    function get($classname)
    {
        $a = __NAMESPACE__ . '\\' . $classname;
        return new $a;
    }

Ключевое слово `namespace` разрешается указывать для явного запроса элемента из текущего пространства имён или из подпространства. Это эквивалент ключевого слова `self` для классов в пространстве имён.

Пример #4 Ключевое слово namespace внутри пространства имён

    <?php

    namespace MyProject;

    use blah\blah as mine; // Смотрите «Пространства имён: псевдонимирование и импорт»

    blah\mine(); // Вызывает функцию MyProject\blah\mine()
    namespace\blah\mine(); // Вызывает функцию MyProject\blah\mine()

    namespace\func(); // Вызывает функцию MyProject\func()
    namespace\sub\func(); // Вызывает функцию MyProject\sub\func()
    namespace\cname::method(); // Вызывает статический метод method класса MyProject\cname
    $a = new namespace\sub\cname(); // Создаёт экземпляр класса MyProject\sub\cname
    $b = namespace\CONSTANT; // Присваивает значение константы MyProject\CONSTANT переменной $b

Пример #5 Ключевое слово namespace в глобальном коде

    <?php

    namespace\func(); // Вызывает функцию func()
    namespace\sub\func(); // Вызывает функцию sub\func()
    namespace\cname::method(); // Вызывает статический метод method класса cname
    $a = new namespace\sub\cname(); // Создаёт экземпляр класса sub\cname
    $b = namespace\CONSTANT; // Присваивает значение константы CONSTANT переменной $b

## Пространства имён: псевдонимирование и импорт

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Способность ссылаться на внешнее абсолютное имя по псевдониму или импортировать внешние абсолютные имена — важное свойство пространств имён. Это похоже на способность файловых систем на основе Unix создавать символические ссылки на файл или директорию.

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

Псевдоним имени создают через ключевое слово `use`. Вот пример, который показывает 5 типов импорта:

Пример #1 Импорт или псевдонимирование через ключевое слово use

    <?php

    namespace foo;

    use My\Full\Classname as Another;

    // Это то же, что и My\Full\NSname as NSname
    use My\Full\NSname;

    // Импортирование глобального класса
    use ArrayObject;

    // Импортирование функции
    use function My\Full\functionName;

    // Создание псевдонима функции
    use function My\Full\functionName as func;

    // Импортирование константы
    use const My\Full\CONSTANT;

    $obj = new namespace\Another; // Создаёт экземпляр класса foo\Another
    $obj = new Another; // Создаёт объект класса My\Full\Classname
    NSname\subns\func(); // Вызывает функцию My\Full\NSname\subns\func

    $a = new ArrayObject(array(1)); // Создаёт объект класса ArrayObject
    // без выражения use ArrayObject был бы создан объект класса foo\ArrayObject

    func(); // вызывает функцию My\Full\functionName
    echo CONSTANT; // выводит содержимое константы My\Full\CONSTANT

Обратите внимание, что именам внутри пространства имён (абсолютным именам пространств имён, которые содержат разделитель пространств имён, например `Foo\Bar`, в отличие от глобальных имён, которые его не содержат, например `FooBar`) начальный обратный слеш (\) не нужен и не рекомендован, поскольку импортируемые имена должны быть абсолютными и не обрабатываются относительно текущего пространства имён.

PHP дополнительно поддерживает удобное сокращение для задания нескольких операторов use в одной и той же строке

Пример #2 Импорт или создание псевдонима через ключевое слово use, комбинирование нескольких выражений

    <?php

    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // Создаёт объект класса My\Full\Classname
    NSname\subns\func(); // Вызывает функцию My\Full\NSname\subns\func

Импорт выполняется во время компиляции поэтому не влияет на имена динамических классов, функций или констант.

Пример #3 Импорт и динамические имена

    <?php

    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // Создаёт объект класса My\Full\Classname
    $a = 'Another';
    $obj = new $a;      // Создаёт объект класса Another

В дополнение, импорт распространяется только на неполные и полные имена. На абсолютные имена операция импорта не влияет.

Пример #4 Импортирование и абсолютные имена

    <?php

    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // Создаёт объект класса My\Full\Classname
    $obj = new \Another; // Создаёт объект класса Another
    $obj = new Another\thing; // Создаёт объект класса My\Full\Classname\thing
    $obj = new \Another\thing; // Создаёт объект класса Another\thing

### Обзор правил для импорта

Ключевое слово `use` должно быть указано в самом начале файла (в глобальной области) или внутри объявления пространства имён. Это нужно, потому что импорт выполняется во время компиляции, а не во время исполнения, поэтому его нельзя ограничить блоком кода. Следующий пример показывает недопустимое указание ключевого слова `use`:

Пример #5 Недопустимое правило импорта

    <?php

    namespace Languages;

    function toGreenlandic()
    {
        use Languages\Danish;

        //...
    }

> Замечание:

> Правила импорта задают на каждый файл отдельно. Поэтому присоединяемые файлы НЕ будут наследовать правила импорта из родительского файла.

### Групповые объявления через ключевое слово `use`

Классы, функции и константы, импортируемые из одного и того же пространства имён (`namespace`), разрешается группировать в одном выражении с ключевым словом `use`.

    <?php

    use some\namespace\ClassA;
    use some\namespace\ClassB;
    use some\namespace\ClassC as C;

    use function some\namespace\fn_a;
    use function some\namespace\fn_b;
    use function some\namespace\fn_c;

    use const some\namespace\ConstA;
    use const some\namespace\ConstB;
    use const some\namespace\ConstC;

    // Эквивалентно следующему групповому объявлению с ключевым словом use
    use some\namespace\{ClassA, ClassB, ClassC as C};
    use function some\namespace\{fn_a, fn_b, fn_c};
    use const some\namespace\{ConstA, ConstB, ConstC};

## Глобальное пространство

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Без определения пространства имён определения классов и функций помещаются в глобальном пространстве — так же, как это было в PHP до введения пространств имён. Добавление префикса `\` к именам указывает, что требуется имя из глобального пространства, даже в контексте пространства имён.

Пример #1 Спецификация глобального пространства

    <?php

    namespace A\B\C;

    /* Функция — A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // Вызов глобальной функции fopen
         return $f;
    }

## Пространства имён: возврат к глобальному пространству для функций и констант

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Когда внутри пространства имён PHP встречает неполное имя класса, функции или контекст константы, он разрешает эти имена с разными приоритетами. Имена классов разрешаются в текущее имя пространства имён. Поэтому, чтобы получить доступ ко внутреннему классу или пользовательскому классу вне пространства имён, необходимо обращаться к ним по абсолютному имени. Например:

Пример #1 Доступ к глобальным классам внутри пространства имён

    <?php

    namespace A\B\C;

    class Exception extends \Exception {}

    $a = new Exception('hi'); // Переменная $a — объект класса A\B\C\Exception
    var_dump($a::class);
    $b = new \Exception('hi'); // Переменная $b — объект класса Exception
    var_dump($b::class);

    $c = new ArrayObject; // Фатальная ошибка, класс A\B\C\ArrayObject не найден

PHP будет обращаться к глобальным функциям или константам, если функция или константа не существует в текущем пространстве имён.

Пример #2 Возврат к глобальным функциям или константам внутри пространства имён

    <?php

    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // Выводит 45
    echo INI_ALL, "\n"; // Выводит «7» — возвращается к глобальной константе INI_ALL

    echo strlen('hi'), "\n"; // Выводит «1»
    if (is_array('hi')) { // Выводит строку «это не массив»
        echo "Это массив\n";
    } else {
        echo "Это не массив\n";
    }

## Правила разрешения имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Для целей этих правил разрешения приведём важные определения:

Определения имени пространства имён
Неполное имя

  Идентификатор без разделителя пространств имён, например `Foo`

Полное имя

  Идентификатор с разделителем пространств имён, например `Foo\Bar`

Абсолютное имя

  Идентификатор с разделителем пространств имён, который начинается с разделителя пространств имён, например `\Foo\Bar`. Пространство имён `\Foo` — также абсолютное имя.

Относительное имя

  Идентификатор, который начинается с ключевого слова `namespace`, например `namespace\Foo\Bar`.

Имена разрешаются по следующим правилам:

1. Абсолютные имена разрешаются в имя без ведущего разделителя пространства имён. Например, `\A\B` разрешается в `A\B`.
2. Относительные имена разрешаются в имя с заменой ключевого слова `namespace` текущим пространством имён. Префикс `namespace\` удаляется, если имя встречается в глобальном пространстве имён. Например, имя `namespace\A` внутри пространства имён `X\Y` разрешается в `X\Y\A`. То же имя в глобальном пространстве имён разрешается в `A`.
3. В полных именах первый сегмент имени преобразовывается с учётом текущей таблицы импорта класса или пространства имён. Например, если пространство имён `A\B\C` импортировано как `C`, то имя `C\D\E` преобразуется в `A\B\C\D\E`.
4. В полных именах, если не применялось правило импорта, текущее пространство имён добавляется к имени. Например, имя `C\D\E` внутри пространства имён `A\B` разрешится в `A\B\C\D\E`.
5. Неполные имена преобразовываются с учётом текущей таблицы импорта и типа элемента. То есть имена как у классов преобразовываются с учётом таблицы импорта классов или пространств имён, имена функций — с учётом таблицы импорта функций, а константы — таблицы импорта констант. Например, при записи `use A\B\C;`, вызов `new C()` разрешается в `A\B\C()`. Аналогично, при записи `use function A\B\foo;` вызов `foo()` разрешается в `A\B\foo`.
6. В начало неполных имён, если не применялось правило импорта и имя относится к элементу с именем как у класса, добавляется текущее пространство имён. Например, имя класса в выражении `new C()` внутри пространства имён `A\B` разрешится в имя `A\B\C`.
7. В неполных именах, если не применялось правило импорта и имя относится к функции или константе, а код лежит за пределами глобального пространства имён, имя разрешается при выполнении. Вот как разрешится вызов функции `foo()` в коде в пространстве имён `A\B`:
   1. Выполняется поиск функции из текущего пространства имён: `A\B\foo()`.
   2. PHP пытается найти и вызвать функцию `foo()` из глобального пространства имён.

Пример #1 Примеры разрешения имён

    <?php

    namespace A;

    use B\D, C\E as F;

    // Вызовы функций

    foo();      // Сперва пытается вызвать функцию foo, которую определили в пространстве имён A,
                // затем вызывает глобальную функцию foo

    \foo();     // Вызывает функцию foo, которую определили в глобальном пространстве

    my\foo();   // Вызывает функцию foo, которую определили в пространстве имён A\my

    F();        // Сперва пытается вызвать функцию F, которую определили в пространстве имён A,
                // затем вызывает глобальную функцию F

    // Ссылки на классы

    new B();    // Создаёт объект класса B, который определили в пространстве имён A.
                // Если класс не найден, то пытается автоматически загрузить класс A\B

    new D();    // Следуя правилам импорта, создаёт объект класса D, который определили в пространстве имён B,
                // если класс не найден, то пытается автоматически загрузить класс B\D

    new F();    // Следуя правилам импорта, создаёт объект класса E, который определили в пространстве имён C,
                // если класс не найден, то пытается автоматически загрузить класс класса C\E

    new \B();   // Создаёт объект класса B, который определили в глобальном пространстве,
                // если класс не найден, то пытается автоматически загрузить класс B

    new \D();   // Создаёт объект класса D, который определили в глобальном пространстве,
                // если класс не найден, то пытается автоматически загрузить класс D

    new \F();   // Создаёт объект класса F, который определили в глобальном пространстве,
                // если класс не найден, то пытается автоматически загрузить класс F

    // Статические методы и функции пространства имён из другого пространства имён

    B\foo();    // Вызывает функцию foo из пространства имён A\B

    B::foo();   // Вызывает метод foo из класса B, который определили в пространстве имён A,
                // если класс A\B не найден, то пытается автоматически загрузить класс A\B

    D::foo();   // Следуя правилам импорта, вызывает метод foo класса D, который определили в пространстве имён B,
                // если класс B\D не найден, то пытается автоматически загрузить класс B\D

    \B\foo();   // Вызывает функцию foo из пространства имён B

    \B::foo();  // Вызывает метод foo класса B из глобального пространства,
                // если класс B не найден, то пытается автоматически загрузить класс B

    // Статические методы и функции пространства имён из текущего пространства имён

    A\B::foo();   // Вызывает метод foo класса B из пространства имён A\A,
                  // если класс A\A\B не найден, то пытается автоматически загрузить класс A\A\B

    \A\B::foo();  // Вызывает метод foo класса B из пространства имён A,
                  // если класс A\B не найден, то пытается автоматически загрузить класс A\B

## Часто задаваемые вопросы (FAQ): что нужно знать о пространствах имён

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Этот список вопросов разделён на две части: общие вопросы и некоторые особенности реализации, которые полезны для полного понимания.

Вначале общие вопросы.

1. Если в коде не указаны пространства имён, нужно ли считать что-либо из этого важным?
2. Как обращаться к внутренним или глобальным классам в пространстве имён?
3. Как обращаться к функциям классов в пространствах имён, или константам в их пространстве имён?
4. Как разрешаются имена `\my\name` или `\name`?
5. Как разрешается имя `my\name`?
6. Как разрешается неполное имя класса `name`?
7. Как разрешается неполное имя функции или неполное имя константы наподобие `name`?

Некоторые детали реализации пространств имён, которые полезно понимать.

1. Импортируемые имена не должны конфликтовать с классами, определёнными в том же файле.
2. Вложенные пространства имён недопустимы.
3. Динамические имена пространств имён (идентификаторы, взятые в кавычки) должны экранировать символ обратного слеша.
4. Ссылаться на неопределённые константы, используя обратный слеш, нельзя. Выводится фатальная ошибка
5. Невозможно переопределить специальные константы `null`, `true` или `false`

### Если в коде не указаны пространства имён, нужно ли считать что-либо из этого важным?

Нет, пространства имён не влияют ни на тот код, который уже написали, ни на ещё ненаписанный код без пространств имён. Разрешается писать такой код, если нужно:

Пример #1 Доступ к глобальным классам вне пространства имён

    <?php
    $a = new \stdClass;
    print $a::class;

Функционально это эквивалентно следующему:

Пример #2 Доступ к глобальным классам вне пространства имён

    <?php
    $a = new stdClass;
    print $a::class;

### Как обращаться к внутренним или глобальным классам в пространстве имён?

Пример #3 Доступ ко внутренним классам в пространствах имён

    <?php

    namespace foo;
    $a = new \stdClass;
    print $a::class . "\n";

    function test(?\ArrayObject $parameter_type_example = null) {}

    $a = \FilesystemIterator::CURRENT_AS_FILEINFO;
    print $a . "\n";

    // Расширение внутреннего или глобального класса
    class MyException extends \Exception {}
    print MyException::class . "\n";

### Как использовать функции классов в пространствах имён или константы в их собственном пространстве имён?

Пример #4 Доступ ко внутренним классам, функциям или константам в пространствах имён

    <?php

    namespace foo;

    class MyClass {}

    // Определение класса текущего пространства имён в качестве типа параметра
    function test(?MyClass $parameter_type_example = null) {}
    // Другой способ определить класс из текущего пространства имён в качестве типа параметра
    function test2(?\foo\MyClass $parameter_type_example = null) {}

    // Расширение класса из текущего пространства имён
    class Extended extends MyClass {}
    print Extended::class . "\n";

    // Доступ к глобальной функции
    $a = \strlen("test");
    print $a . "\n";

    // Доступ к глобальной константе
    $b = \INI_ALL;
    print $b . "\n";

### Как разрешаются имена наподобие `\my\name` или `\name`?

Имена, которые начинаются с обратного слеша `\`, разрешаются в названия, на которые сами похожи, поэтому имя `\my\name` разрешается в название `my\name`, а имя `\Exception` — в `Exception`.

Пример #5 Абсолютные имена

    <?php

    namespace foo;

    $a = new \my\name(); // Создаёт экземпляр класса my\name
    echo \strlen('hi'); // Вызывает функцию strlen
    $a = \INI_ALL; // Переменной $a присваивается значение константы INI_ALL

### Как разрешается имя `my\name`?

Имена наподобие `my\name`, — которые содержат обратный слеш, но не начинаются с него, — разрешаются двумя способами.

Уровень `my` в имени `my\name` заменяется псевдонимом, если уровню `my` присвоили псевдоним с другим именем, которое импортировали инструкцией use.

В остальных случаях перед именем `my\name` добавляется название текущего пространства имён.

Пример #6 Полные имена

    <?php

    namespace foo;

    use blah\blah as foo;

    $a = new my\name(); // Создаёт экземпляр класса foo\my\name
    foo\bar::name(); // Вызывает статический метод name, который определили в классе blah\blah\bar
    my\bar(); // Вызывает функцию foo\my\bar
    $a = my\BAR; // Присваивает переменной $a значение константы foo\my\BAR

### Как разрешается неполное имя класса вроде `name`?

Названия классов наподобие `name`, — которые не содержат обратного слеша, — разрешаются двумя способами.

Название класса заменяется псевдонимом, если имени `name` присвоили псевдоним с другим именем, которое импортировали инструкцией use.

В остальных случаях к имени `name` добавляется текущее название пространства имён.

Пример #7 Неполные имена классов

    <?php

    namespace foo;

    use blah\blah as foo;

    $a = new name(); // Создаёт экземпляр класса foo\name
    foo::name(); // Вызывает статический метод name, который определили в классе blah\blah

### Как разрешается неполное название функции или неполное имя константы вроде `name`?

Названия функций или констант наподобие `name`, — которые не содержат обратного слеша, — разрешаются двумя способами.

Вначале перед именем `name` добавляется текущее название пространства имён.

Затем, если текущее пространство имён не содержит названия константы или функции с именем `name`, вызывается глобальная константа или функция с названием `name`, если константу или функцию с таким названием определили в глобальном пространстве имён.

Пример #8 Неполные имена функций или констант

    <?php

    namespace foo;

    use blah\blah as foo;

    const FOO = 1;

    function my() {
        print __FUNCTION__ . "\n";
    }
    function foo() {
        print __FUNCTION__ . "\n";
    }
    function sort(&$a)
    {
        \sort($a); // Вызывает глобальную функцию sort
        $a = array_flip($a);
        return $a;
    }

    my(); // вызывает функцию foo\my
    print strlen('hi') . "\n"; // Вызывает глобальную функцию strlen, потому что функцию foo\strlen не определили
    $arr = array(1,3,2);
    $b = sort($arr); // Вызывает функцию foo\sort
    var_dump($b);
    foo(); // Вызывает функцию foo\foo, без импорта

    $a = FOO; // Присваивает переменной $a значение константы foo\FOO, без импорта
    print $a;
    $b = INI_ALL; // Присваивает переменной $b значение глобальной константы INI_ALL
    print $b;

### Импортируемым именам нельзя конфликтовать с классами, которые определили в том же файле

Следующие комбинации скриптов допустимы:

file1.php

    <?php

    namespace my\stuff;

    class MyClass {}

another.php

    <?php

    namespace another;

    class thing {}

file2.php

    <?php

    namespace my\stuff;

    include 'file1.php';
    include 'another.php';

    use another\thing as MyClass;
    $a = new MyClass; // Создаёт экземпляр класса thing из пространства имён another

Конфликт имён отсутствует, даже несмотря на то что класс `MyClass` существует внутри пространства имён `my\stuff`, потому что определение MyClass находится в отдельном файле. Однако следующий пример приводит к фатальной ошибке с конфликтом имён, потому что класс MyClass определён в том же файле, в котором указано ключевое слово use.

    <?php

    namespace my\stuff;

    use another\thing as MyClass;

    class MyClass {} // Фатальная ошибка: MyClass конфликтует с выражением импорта
    $a = new MyClass();

### Вложенные пространства имён недопустимы.

PHP не разрешает вложение пространств имён

    <?php

    namespace my\stuff {
        namespace nested {
            class foo {}
        }
    }

Однако сымитировать вложенные пространства имён можно так:

    <?php

    namespace my\stuff\nested {
        class foo {}
    }

### Динамические имена пространств имён (идентификаторы, взятые в кавычки) должны экранировать символ обратного слеша.

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

Пример #9 Подводные камни при указании имени пространства имён внутри строки с двойными кавычками

    <?php

    $a = "dangerous\name"; // Символ \n — переход на новую строку внутри строки с двойными кавычками!
    $obj = new $a;

    $a = 'not\at\all\dangerous'; // А тут нет проблем.
    $obj = new $a();

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

### Ссылаться на неопределённые константы, используя обратный слеш, нельзя. Выводится фатальная ошибка

Любая неопределённая константа — неполное имя наподобие `FOO` — будет приводить к выводу сообщения о том, что PHP предположил, что `FOO` было значением константы. Любая константа, с полным или абсолютным именем, которая содержит символ обратного слеша, будет приводить к фатальной ошибке, если не будет найдена.

Пример #10 Неопределённые константы

    <?php

    namespace bar;

    $a = FOO; // Выводит предупреждение: undefined constants "FOO" assumed "FOO";
    $a = \FOO; // Фатальная ошибка: undefined namespace constant FOO
    $a = Bar\FOO; // Фатальная ошибка: undefined namespace constant bar\Bar\FOO
    $a = \Bar\FOO; // Фатальная ошибка: undefined namespace constant Bar\FOO

### Невозможно переопределить специальные константы `null`, `true` или `false`

Любая попытка определить константу пространства имён, которая совпадает с названиями специальных встроенных констант, приведёт к фатальной ошибке.

Пример #11 Неопределённые константы

    <?php

    namespace bar;

    const NULL = 0; // Фатальная ошибка;
    const true = 'stupid'; // Тоже фатальная ошибка;
    // и т. д.

# Перечисления

## Содержание

- Обзор перечислений
- Основы перечислений
- Типизированные перечисления
- Методы перечислений
- Статические методы перечислений
- Константы перечислений
- Трейты
- Значения перечисления в постоянных выражениях
- Отличия от объектов
- Список значений
- Сериализация
- Почему перечисления нерасширяемы
- Примеры

## Обзор перечислений

(PHP 8 >= 8.1.0)

Перечисления, или Enums, разрешают разработчику определять настраиваемый тип, который ограничивается одним значением из дискретного числа возможных. Такое ограничение часто приносит пользу при определении модели предметной области, поскольку разрешает «сделать неверные состояния недопустимыми».

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

Самый популярный пример перечисления — встроенный логический тип, он перечисляем и допускает значения `true` и `false`. Классы enum разрешают разработчикам определять свои перечисления произвольной сложности.

## Основы перечислений

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

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

Это объявление создаёт новый перечислимый тип с именем `Suit`, у которого четыре и только четыре допустимых значения: `Suit::Hearts`, `Suit::Diamonds`, `Suit::Clubs` и `Suit::Spades`. Переменным разрешается присваивать только эти допустимые значения. В функциях разрешается указывать подсказку типа, которая проверит соответствие типа аргумента типу перечисления, чтобы в функцию передавали только значения, которые принадлежат заданному типу перечисления.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function pick_a_card(Suit $suit)
    {
        var_dump($suit);
    }

    $val = Suit::Diamonds;

    // OK
    pick_a_card($val);

    // OK
    pick_a_card(Suit::Clubs);

    // TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
    pick_a_card('Spades');

Перечисления содержат ноль или больше определений `case`, без ограничения максимального количества. Перечисление без вариантов синтаксически корректно, хотя и бесполезно.

Для вариантов перечисления работают те же правила синтаксиса, что и для любой метки в PHP, смотрите раздел «Константы».

По умолчанию варианты не поддерживаются скалярным значением, поэтому `Suit::Hearts` не равно `"0"`. Вместо этого каждый вариант поддерживается одноэлементным объектом с таким именем. Это означает, что:

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    $a = Suit::Spades;
    $b = Suit::Spades;

    if ($a === $b) {
        print "Масти совпадают по ===\n";
    }

    if ($a instanceof Suit) {
        print "Масти совпадают по instanceof\n";
    }

    if ($a !== 'Spades') {
        print "Масть не совпадает со строкой\n";
    }

Это также означает, что значения перечисления не будут `<` или `>` друг с друга, поскольку эти сравнения не имеют смысла для объектов. Сравнения каждый раз будут возвращать `false` при работе с вариантами перечисления.

Тип варианта без связанных данных называется «Чистый вариант» (англ. Pure Case). Перечисление, которое содержит только чистые варианты, называется чистым перечислением (англ. Pure Enum).

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

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

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    print Suit::Spades->name;
    // Вывод: "Spades"

Содержится ли вариант в перечислении, возможно проверить по динамическому названию варианта, которое передают в функцию defined(), а считывают вариант по динамическому имени функцией constant(), но делать так не рекомендуется, поскольку в большей части сценариев работы с вариантами справляются типизированные перечисления.

## Типизированные перечисления

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

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

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

Вариант со скалярным эквивалентом называется типизированным (англ. Backed Case), поскольку «поддерживается» упрощённым значением. Перечисление с типизированными вариантами называется «типизированным перечислением» (англ. Backed Enum). Типизированное перечисление допускает только типизированные варианты, а чистое перечисление — только чистые.

Перечисления допускают поддержку единственным типом — `int` или `string`, поэтому типы нельзя объединять: `int|string`. Для каждого варианта типизированного перечисления потребуется явно определить уникальный скалярный эквивалент. Перечисление не генерирует вариантам скалярные эквиваленты наподобие последовательных целых чисел автоматически. PHP проверит уникальность скалярных значений типизированных вариантов перечисления, поэтому двум вариантам типизированного перечисления нельзя присваивать один и тот же скалярный эквивалент. При этом константам разрешается ссылаться на варианты перечисления, что фактически создаёт псевдоним варианта. Смотрите главу «Константы перечислений».

Эквивалентные значения для вариантов перечисления устанавливаются как константные скалярные выражения. До PHP 8.2.0 варианты перечислений поддерживали только литералы или литеральные выражения. Константы и константные выражения не поддерживались. Поэтому выражения наподобие `1 + 1` работали, а выражения `1 + SOME_CONST` вызывали фатальную ошибку.

У типизированных вариантов есть дополнительное доступное только для чтения свойство `value` — это значение, заданное в определении варианта.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    print Suit::Clubs->value;
    // Конструкция выведет "C"

Переменную нельзя назначать как ссылку на свойство `value`, чтобы свойство оставалось доступным только для чтения. Поэтому следующий код выдаст ошибку:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Fatal Error: Cannot indirectly modify readonly property Suit::$value

Типизированные перечисления реализуют внутренний интерфейс BackedEnum, который даёт два дополнительных метода:

- `from(int|string): self` возьмёт скаляр и вернёт вариант перечисления, которому он принадлежит. Если вариант, который соответствует варианту перечисления, не найден, метод выбросит исключение ValueError. Это в основном полезно тогда, когда входной скаляр надёжен, а отсутствие значения перечисления надо рассматривать как ошибку, останавливающую приложение.
- `tryFrom(int|string): ?self` возьмёт скаляр и вернёт вариант перечисления, которому он принадлежит. Если вариант, который соответствует варианту перечисления, не найден, метод вернёт `null`. Это в основном полезно тогда, когда входной скаляр ненадёжен и вызывающая функция хочет реализовать свою обработку ошибок или логику значения по умолчанию.

Методы `from()` и `tryFrom()` следуют стандартным правилам слабой/строгой типизации. В режиме слабой типизации допустима передача целого числа или строки, система приведёт значение и найдёт вариант, который ему соответствует. Передача числа с плавающей точкой также будет работать и приводиться. В режиме строгой типизации передача целого числа в метод `from()` в перечислении со строковой типизацией (или наоборот) в любом случае приведёт к исключению TypeError, как и передача числа с плавающей точкой. Все остальные типы параметров выбросят исключение TypeError в обоих режимах.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    function get_stuff_from_database($id)
    {
        return [
            'suit' => 'S',
        ];
    }

    $record = get_stuff_from_database(42);
    print $record['suit'] . "\n";

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // Недопустимые данные возвращают значение null, поэтому вместо этого будет использовано Suit::Spades.
    print $suit->value . "\n";

    $suit =  Suit::from('X');
    // Недопустимые данные выбросят исключение ValueError: "X" is not a valid backing scalar value for enum Suit
    print $suit->value . "\n";

Ручное определение метода `from()` или `tryFrom()` в типизированных перечислениях приведёт к фатальной ошибке.

## Методы перечислений

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

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit implements Colorful
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        // Выполняет контракт интерфейса.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Красный',
                Suit::Clubs, Suit::Spades => 'Чёрный'
            };
        }

        // Не часть интерфейса; хорошо.
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    function paint(Colorful $c)
    {
       print $c->color() . "\n";
    }

    paint(Suit::Clubs);  // Работает

    print Suit::Diamonds->shape(); // выведет "Rectangle"

В этом примере каждый из четырёх экземпляров `Suit` имеет два метода: `color()` и `shape()`. В вызывающем коде и при проверке типов экземпляры перечисления ведут себя точно так же, как и любой другой экземпляр объекта.

В типизированных перечислениях объявление интерфейса идёт после объявления типа перечисления.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit: string implements Colorful
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';

        // Выполняет интерфейсный контракт.
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Красный',
                Suit::Clubs, Suit::Spades => 'Чёрный'
            };
        }
    }

Переменная `$this` определена внутри метода и ссылается на экземпляр варианта.

Сложность методов в перечислениях не ограничена, но на практике методы перечислений чаще возвращают статическое значение или результат обработки переменной `$this` выражением match, чтобы результаты обработки отдельных экземпляров перечисления отличались.

Обратите внимание, в этом примере более хорошей практикой построения данных было бы — определить тип перечисления `SuitColor` со значениями Red и Black и возвращать их вместо строковых литералов. Однако это усложнило бы пример.

Иерархия в примере логически похожа на следующую структуру классов (хотя это не настоящий исполняемый код):

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    final class Suit implements UnitEnum, Colorful
    {
        public const Hearts = new self('Hearts');
        public const Diamonds = new self('Diamonds');
        public const Clubs = new self('Clubs');
        public const Spades = new self('Spades');

        private function __construct(public readonly string $name) {}

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Красный',
                Suit::Clubs, Suit::Spades => 'Чёрный'
            };
        }

        public function shape(): string
        {
            return "Прямоугольник";
        }

        public static function cases(): array
        {
            // Недопустимый метод, поскольку определение метода cases() в перечислениях вручную запрещено.
            // Смотрите также раздел "Список значений".
        }
    }

В перечислениях разрешено объявлять общедоступные, закрытые и защищённые методы, хотя на практике закрытые и защищённые методы эквивалентны, поскольку наследование не разрешено.

## Статические методы перечислений

В перечислениях разрешено объявлять статические методы. Статические методы в самом перечислении в первую очередь выступают в роли альтернативных конструкторов. Например:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public static function fromLength(int $cm): self
        {
            return match(true) {
                $cm < 50 => self::Small,
                $cm < 100 => self::Medium,
                default => self::Large,
            };
        }
    }

    var_dump(Size::fromLength(50));

Статические методы разрешено объявлять общедоступными, закрытыми или защищёнными, хотя на практике закрытые и защищённые методы эквивалентны, поскольку наследование не разрешено.

## Константы перечислений

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

Константе перечисления разрешено ссылаться на вариант перечисления:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public const Huge = self::Large;
    }

    var_dump(Size::Huge);

## Трейты

Перечисления поддерживают включение трейтов, которые ведут себя так же, как в классе. Предостережение состоит в том, что во включаемых (`use`) в перечисление трейтах нельзя объявлять свойства. Во включаемом в перечисление трейте разрешается объявлять только методы, статические методы и константы. Трейт со свойствами вызовет фатальную ошибку.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    trait Rectangle
    {
        public function shape(): string
        {
            return "Прямоугольник";
        }
    }

    enum Suit implements Colorful
    {
        use Rectangle;

        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Красный',
                Suit::Clubs, Suit::Spades => 'Чёрный',
            };
        }
    }

    $suit = Suit::Spades;
    var_dump($suit->color());
    var_dump($suit->shape());

## Значения перечисления в постоянных выражениях

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

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

    <?php

    // Это на 100 % корректное определение перечисления.
    enum Direction implements ArrayAccess
    {
        case Up;
        case Down;

        public function offsetExists($offset): bool
        {
            return false;
        }

        public function offsetGet($offset): mixed
        {
            return null;
        }

        public function offsetSet($offset, $value): void
        {
            throw new Exception();
        }

        public function offsetUnset($offset): void
        {
            throw new Exception();
        }
    }

    class Foo
    {
        // Это разрешено.
        const DOWN = Direction::Down;

        // Это запрещено, так как не может быть детерминированным.
        const UP = Direction::Up['short'];
        // Fatal error: Cannot use [] on enums in constant expression
    }

    // Это совершенно законно, потому что это не постоянное выражение.
    $x = Direction::Up['short'];
    var_dump("\$x – это " . var_export($x, true));

    $foo = new Foo();

## Отличия от объектов

Хотя перечисления построены на классах и объектах, они не поддерживают полную объектно-связанную функциональность. В качестве примера, вариантам перечислений не разрешены состояния.

- Конструкторы и деструкторы запрещены.
- Наследование не поддерживается. Перечислениям нельзя наследовать или наследоваться.
- Статические свойства или свойства объекта не допускаются.
- Клонирование варианта перечисления не поддерживается, так как варианты должны быть одноэлементными экземплярами.
- Магические методы, кроме перечисленных ниже, запрещены.
- Перечисления должны быть объявлены до начала работы с ними.

Перечислениям доступны следующие функциональные возможности объекта с аналогичным поведением:

- Методы public, private и protected.
- Статические методы public, private и protected.
- Константы public, private и protected.
- Перечислениям разрешено реализовывать любое количество интерфейсов.
- К перечислениям и вариантам разрешено добавлять атрибуты. Целевой фильтр `TARGET_CLASS` включает сами перечисления. Целевой фильтр `TARGET_CLASS_CONST` включает варианты перечислений.
- Магические методы __call, __callStatic, и __invoke.
- Константы `__CLASS__` и `__FUNCTION__` ведут себя как обычно.

Магическая константа `::class` для типа перечисления оценивается как название перечисления, включая любое пространство имён, точно так же, как объект. Магическая константа `::class` в экземпляре варианта также оценивается как тип перечисления, поскольку она — экземпляр этого типа.

Кроме того, варианты перечисления нельзя создавать через ключевое слово `new` или методом ReflectionClass::newInstanceWithoutConstructor(). Оба способа приведут к ошибке.

    <?php

    $clovers = new Suit();
    // Error: Cannot instantiate enum Suit

    $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
    // Error: Cannot instantiate enum Suit

## Список значений

И чистые, и типизированные перечисления реализуют внутренний интерфейс с именем UnitEnum. Интерфейс `UnitEnum` включает статический метод `cases()`. Метод `cases()` возвращает упакованный массив вариантов, которые определили в перечислении. Варианты возвращаются в порядке объявления.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

    enum SuitBacked: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    var_dump(SuitBacked::cases());

Ручное определение метода `cases()` в перечислении приведёт к фатальной ошибке.

## Сериализация

Перечисления сериализуются иначе, чем объекты. В частности, для перечислений ввели новый код сериализации — `"E"`, который обозначает название варианта перечисления. По этому названию процедура десериализации затем находит единственный экземпляр перечисления и присваивает значение переменной. Это гарантирует, что:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";

PHP выдаст предупреждение и вернёт значение `false`, если не найдёт перечисление и вариант для сопоставления сериализованному значению.

Опция `allowed_classes` функции unserialize() не влияет на перечисления.

При попытке сериализовать чистое перечисление в JSON-формат выбрасывается исключение (если только функцию вызвали с флагом JSON_THROW_ON_ERROR — прим. перев.). При сериализации типизированного перечисления в JSON-формат оно представляется только своим скалярным значением того типа, который указали в перечислении. Поведение сериализации как чистых, так и типизированных перечислений переопределяется путём реализации интерфейса JsonSerializable.

Для функции print_r() вывод варианта перечисления незначительно отличается от объектов, чтобы уменьшить путаницу.

    <?php

    enum Foo
    {
        case Bar;
    }

    enum Baz: int
    {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* Выводит

    Foo Enum
    (
        [name] => Bar
    )
    Baz Enum:int
    (
        [name] => Beep
        [value] => 5
    )
    */

## Почему перечисления нерасширяемы

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

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b)
    {
        foo($b);
    }

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

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

    <?php

    enum ErrorCode
    {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // Кажется, что код охватывает каждый вариант перечисления
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

Статический анализ выражения match в функции `quux` показывает, что проверяется каждый вариант перечисления ErrorCode.

Но представьте, что перечисления разрешили бы расширять:

    <?php

    // Код мысленного эксперимента, в котором перечисления не окончательны.
    // Обратите внимание, что этот код не сработает в PHP.
    enum MoreErrorCode extends ErrorCode
    {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode)
    {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

По стандартным правилам наследования класс-наследник пройдёт проверку типа.

Проблема состояла бы в том, что выражение match в функции `quux()` уже не покрывало бы каждый вариант перечисления. И поскольку выражение проверки не знает о варианте `MoreErrorCode::PEBKAC`, сопоставление выбросит исключение.

Поэтому перечисления окончательны и их нельзя расширять.

## Примеры

Пример #1 Базовые ограниченные значения

    <?php

    enum SortOrder
    {
        case Asc;
        case Desc;
    }

    function query($fields, $filter, SortOrder $order = SortOrder::Asc)
    {
         /* ... */
    }

Функция `query()` теперь безопасно выполняется, поскольку знает, что в параметр `$order` гарантированно примет либо вариант `SortOrder::Asc`, либо вариант `SortOrder::Desc`. Другое значение выбросило бы ошибку TypeError, поэтому функция обойдётся без проверки ошибок или тестирования.

Пример #2 Расширенные эксклюзивные значения

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'В ожидании',
                self::Active => 'Активный',
                self::Suspended => 'Приостановленный',
                self::CanceledByUser => 'Отменён пользователем',
            };
        }
    }

    $status = UserStatus::Suspended;
    var_dump($status->label());

В этом примере статус пользователя ограничивается единственным значением и только из следующих вариантов: `UserStatus::Pending`, `UserStatus::Active`, `UserStatus::Suspended` или `UserStatus::CanceledByUser`. Определение в сигнатуре функции параметра с типом `UserStatus` разрешит функции принимать только эти четыре значения, точка.

Каждому из четырёх значений доступен метод `label()`, который возвращает строку, удобную для чтения человеком. Эта строка не зависит от строки со скалярным эквивалентом «машинного имени», который, например, хранят в поле базы данных или выводят как значение элемента выпадающего списка в HTML-форме.

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match($this) {
                self::Pending => 'В ожидании',
                self::Active => 'Активный',
                self::Suspended => 'Приостановленный',
                self::CanceledByUser => 'Отменён пользователем',
            };
        }
    }

    foreach (UserStatus::cases() as $case) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($case->value),
            htmlentities($case->label())
        );
    }

# Ошибки

## Содержание

- Основы
- Ошибки в PHP 7

## Введение

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

## Основы

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

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

### Обработка ошибок

PHP, по умолчанию, может обрабатывать любые ошибки в соответствии со своей конфигурацией, если обработчик ошибок не установлен. О каких ошибках сообщать и какие ошибки игнорировать указывается в параметре `error_reporting` конфигурации php.ini, или во время исполнения программы с помощью вызова error_reporting(). Настоятельно рекомендуется заранее конфигурировать php.ini, так как некоторые ошибки могут произойти до начала выполнения вашего скрипта.

На стадии разработки, обязательно настройте параметр `error_reporting` на значение `E_ALL`, так как вам необходимо знать обо всех ошибках для их решения на этой стадии. Когда продукт готов, вы можете изменить значение на менее подробное, вроде `E_ALL & ~E_NOTICE & ~E_DEPRECATED`, но во многих случаях значение `E_ALL` также желательно, так как оно может предупреждать заранее о других возможных ошибках.

Дальнейшая работа PHP с появившимися ошибками зависит от двух других параметров в php.ini. Параметр `display_errors` определяет, включать ли данные ошибки в вывод скрипта или нет. Когда продукт готов, обязательно выключите этот параметр, так как в описании ошибки может содержаться конфиденциальная информация, вроде паролей базы данных. Во время разработки данный параметр лучше включить для решения проблем, провоцирующих ошибки.

Кроме отображения ошибок, их можно записывать в лог с помощью включённого параметра `log_errors`. Файл лога указывается в параметре `error_log`. Данная функция незаменима на стадии конечного продукта, так как позволяет видеть информацию об ошибках и составлять основанные на них отчёты вдали от глаз пользователя.

### Пользовательская обработка ошибок

Если вас не устраивает работа предустановленного обработчика ошибок, вы также можете обрабатывать множество видов ошибки с помощью своего обработчика, который можно установить вызовом функции set_error_handler(). Некоторые ошибки не могут обрабатываться пользовательским обработчиком, но те, которые могут, обрабатываются по вашему желанию: например, ваш скрипт может выдавать пользователю любую отдельную страницу ошибки, а подробную информацию записывать в лог или отсылать по почте.

## Ошибки в PHP 7

В PHP 7 механизм сообщения об ошибках был сильно изменён. Традиционное оповещение об ошибке в PHP 5 было заменено новым механизмом, в котором большинство ошибок вызываются с помощью исключений класса Error.

Как и обычные исключения, исключения Error вызываются до появления первого соответствующего блока `catch`. Если соответствующие блоки не предусмотрены, то будет вызван любой обработчик исключений, установленный с помощью set_exception_handler(). В случае отсутствия обработчика по умолчанию, исключение будет конвертировано в фатальную ошибку и будет обработано как традиционная ошибка.

Поскольку класс Error не наследуется от класса Exception, блок `catch (Exception $e) { ... }` для обработки неперехваченных исключений PHP 5 не может перехватить исключения Error. Для их перехвата используйте блок `catch (Error $e) { ... }` или установите обработчик исключений с помощью set_exception_handler().

### Иерархия Error

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# Исключения

## Содержание

- Наследование исключений

> Замечание: Смотрите также класс Exception

Модель исключений PHP напоминает модель исключений других языков программирования. PHP умеет выбрасывать — `throw` — и ловить — `catch` — исключения. Код заключают в блок `try`, чтобы упростить обработку вероятных исключений. Каждому блоку `try` указывают как минимум один блок `catch` или `finally`.

Исключение будет «всплывать» по стеку вызовов функций, пока не найдёт блок `catch`, если функция выбросила исключение, а в текущей области видимости функции, которая её вызвала, нет блока `catch`. PHP выполнит каждый блок `finally`, который встретит по пути. Программа завершается фатальной ошибкой, когда стек вызовов не встречает блок `catch` и разворачивается до глобальной области видимости, если разработчик не установил глобальный обработчик исключений.

В коде допустимо выбрасывать только объект исключения, тип которого при проверке оператором `instanceof` соответствует интерфейсу Throwable. Попытка выбросить объект, который не выполняет это условие, приведёт к фатальной ошибке PHP.

С PHP 8.0.0 ключевое слово `throw` стало выражением, которое разрешили записывать в контексте выражения. В предыдущих версиях это слово было инструкцией и её записывали в отдельной строке.

## `catch`

Блок `catch` определяет, как реагировать на исключение, которое выбросил код. Блок `catch` определяет один или больше типов исключений или ошибок, которые он обрабатывает, и необязательную переменную, которой блок присвоит исключение. До PHP 8.0.0 переменную требовалось указывать. Объект исключения обработает первый блок `catch`, с которым столкнутся исключение или ошибка того типа или подтипа, который ожидает блок.

Блоки `catch` записывают один за другим, чтобы перехватывать исключения разных классов. Нормальное выполнение, когда блок `try` не выбросил исключение, продолжится после последнего блока `catch`, который определили в последовательности. Внутри блока `catch` допустимо выбрасывать, а точнее — повторно выбрасывать исключения через ключевое слово `throw`. PHP продолжит выполнение кода после блока `catch`, который сработал, если внутри блока не выбросили исключение.

При появлении исключения PHP не выполнит код, который идёт за инструкцией, а попытается найти первый подходящий блок `catch`. PHP выдаст фатальную ошибку с сообщением `Uncaught Exception ...`, если исключение не поймали и через функцию set_exception_handler() не определили обработчик исключений.

С PHP 7.1.0 в блоке `catch` допустимо указывать исключения через символ вертикальной черты `|`. Это полезно, когда разные исключения из разных иерархий классов обрабатывают одинаково.

С PHP 8.0.0 имя переменной для исключения, которое поймал блок, необязательно. PHP выполнит блок `catch`, но у блока не будет доступа к объекту, который выбросил код, если переменную не указали.

## `finally`

Блок `finally` также допустимо указывать после или вместо блоков `catch`. PHP выполнит код в блоке `finally` после блоков `try` и `catch`, независимо от того, выбросил ли код исключение, и до возобновления нормального выполнения.

Заслуживает внимания взаимодействие между блоком `finally` и инструкцией `return`. PHP выполнит блок `finally`, даже если встретит внутри блоков `try` или `catch` инструкцию `return`. Больше того, когда PHP встречает инструкцию `return`, он вычисляет её, но вернёт результат после выполнения блока `finally`. Кроме того, PHP вернёт значение из блока `finally`, если блок `finally` тоже содержит инструкцию `return`.

Другое примечательное взаимодействие встречается между исключениями, которые сгенерировали и блок `try`, и блок `finally`. При генерации исключения обоими блоками исключение блока `finally` продолжит всплывать, а исключение блока `try` станет предыдущим исключением для исключения финального блока.

## Глобальный обработчик исключений

Глобальный обработчик исключений, если обработчик установили, перехватит исключение, если исключению разрешили всплывать до глобальной области видимости. Функция set_exception_handler() устанавливает callback-функцию, которую PHP вызовет вместо блока `catch`, если в коде не вызвали другие блоки. Эффект по существу такой же, как если бы всю программу обернули в блок `try`-`catch` с этой функцией в качестве `catch`.

## Примечания

> Замечание:

> Внутренние функции PHP чаще сообщают об ошибках через отчёт об ошибках, только современные объектно-ориентированные модули работают с исключениями. При этом ошибки легко переводятся в исключения через класс ErrorException. Эта техника, однако, работает только с нефатальными ошибками.

> Пример #1 Преобразование отчётов об ошибках в исключения

>     <?php

>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');

Подсказка

Стандартная библиотека PHP (SPL) предлагает много встроенных исключений.

## Примеры

Пример #2 Выброс исключения

    <?php

    function inverse($x) {
        if (!$x) {
            throw new Exception('Деление на ноль.');
        }
        return 1 / $x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'PHP перехватил исключение: ',  $e->getMessage(), "\n";
    }

    // Продолжить выполнение
    echo "Привет, мир\n";

Результат выполнения приведённого примера:

    0.2
    PHP перехватил исключение: Деление на ноль.
    Привет, мир

Пример #3 Обработка исключений в блоке `finally`

    <?php

    function inverse($x) {
        if (!$x) {
            throw new Exception('Деление на ноль.');
        }
        return 1 / $x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'PHP перехватил исключение: ',  $e->getMessage(), "\n";
    } finally {
        echo "Первый блок finally.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'PHP перехватил исключение: ',  $e->getMessage(), "\n";
    } finally {
        echo "Второй блок finally.\n";
    }

    // Продолжить выполнение
    echo "Привет, мир\n";

Результат выполнения приведённого примера:

    0.2
    Первый блок finally.
    PHP перехватил исключение: Деление на ноль.
    Второй блок finally.
    Привет, мир

Пример #4 Взаимодействие между блоками `finally` и `return`

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();

Результат выполнения приведённого примера:

    finally

Пример #5 Вложенные исключения

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // Повторный выброс исключения
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

Результат выполнения приведённого примера:

    string(4) "foo!"

Пример #6 Обработка нескольких исключений в одном блоке catch

    <?php

    class MyException extends Exception { }

    class MyOtherException extends Exception { }

    class Test {
        public function testing() {
            try {
                throw new MyException();
            } catch (MyException | MyOtherException $e) {
                var_dump(get_class($e));
            }
        }
    }

    $foo = new Test;
    $foo->testing();

Результат выполнения приведённого примера:

    string(11) "MyException"

Пример #7 Пример блока `catch` без переменной

Разрешено только в PHP 8.0.0 и более поздних версиях.

    <?php

    class SpecificException extends Exception {}

    function test() {
        throw new SpecificException('Ой!');
    }

    try {
        test();
    } catch (SpecificException) {
        print "Функция выбросила исключение SpecificException, но детали исключения неважны.";
    }

Результат выполнения приведённого примера:

    Функция выбросила исключение SpecificException, но детали исключения неважны.

Пример #8 Throw как выражение

Разрешено только в PHP 8.0.0 и более поздних версиях.

    <?php

    function test()
    {
        do_something_risky() or throw new Exception('Функция завершилась ошибкой');
    }

    function do_something_risky()
    {
        return false; // Имитация сбоя
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

Результат выполнения приведённого примера:

    Функция завершилась ошибкой

Пример #9 Исключение в блоках try и finally

    <?php

    try {
        try {
            throw new Exception(message: 'Третье', previous: new Exception('Четвёртое'));
        } finally {
            throw new Exception(message: 'Первое', previous: new Exception('Второе'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

Результат выполнения приведённого примера:

    string(12) "Первое"
    string(12) "Второе"
    string(12) "Третье"
    string(18) "Четвёртое"

## Наследование исключений

Пользовательский класс исключения определяют путём расширения встроенного класса Exception. Ниже показаны методы и свойства класса Exception, которые доступны дочерним классам.

Пример #1 Встроенный класс Exception

    <?php

    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // Сообщение исключения
        private   $string;                          // Кеш метода __toString
        protected $code = 0;                        // Пользовательский код исключения
        protected $file;                            // Файл, в котором код выбросил исключение
        protected $line;                            // Строка, в которой код выбросил исключение
        private   $trace;                           // Трассировка вызовов методов и функций
        private   $previous;                        // Предыдущее исключение, если исключение вложенное

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // Запрещает клонирования исключения

        final public  function getMessage();        // Сообщение исключения
        final public  function getCode();           // Код исключения
        final public  function getFile();           // Файл, в котором код выбросил исключение
        final public  function getLine();           // Строка, на которой код выбросил исключение
        final public  function getTrace();          // Массив функции backtrace()
        final public  function getPrevious();       // Предыдущее исключение
        final public  function getTraceAsString();  // Отформатированная строка трассировки

        // Переопределяемый
        public function __toString();               // Отформатированная строка для отображения
    }

В конструкторе класса-наследника нужно также вызвать конструктор родительского класса — parent::__construct(), когда класс расширяет класс Exception и переопределяет конструктор, чтобы гарантировать, что родительский класс правильно присвоил значения доступным данным. Метод __toString() допустимо переопределять, чтобы настроить пользовательский вывод, когда с объектом исключения работают как со строкой.

> Замечание:

> Исключения нельзя клонировать. Попытка клонировать исключение приведёт к фатальной ошибке `E_ERROR`.

Пример #2 Наследование класса Exception

    <?php

    /**
     * Определим класс исключения
     */
    class MyException extends Exception
    {
        // Переопределим исключение так, что параметр message станет обязательным
        public function __construct($message, $code = 0, ?Throwable $previous = null)
        {
            // Какой-то код

            // Убедимся, что родительский класс правильно присвоил значения
            parent::__construct($message, $code, $previous);
        }

        // Переопределим строковое представление объекта
        public function __toString()
        {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction()
        {
            echo "Пользовательская функция для этого типа исключения\n";
        }
    }

    /**
     * Создадим класс для тестирования исключения
     */
    class TestException
    {
        public $var;

        const THROW_NONE    = 0;
        const THROW_CUSTOM  = 1;
        const THROW_DEFAULT = 2;

        function __construct($avalue = self::THROW_NONE)
        {

            switch ($avalue) {
                case self::THROW_CUSTOM:
                    // Выбрасываем своё исключение
                    throw new MyException('1 — неправильный параметр', 5);
                    break;

                case self::THROW_DEFAULT:
                    // Выбрасываем встроенное исключение
                    throw new Exception('2 — недопустимый параметр', 6);
                    break;

                default:
                    // Без исключения, PHP создаст объект
                    $this->var = $avalue;
                    break;
            }
        }
    }

    echo "# Пример 1\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // Перехватится
        echo "Блок catch перехватил пользовательское переопределённое исключение\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Пропускается
        echo "Поймано встроенное исключение\n", $e;
    }

    // Продолжить выполнение
    var_dump($o); // Null

    echo "\n\n# Пример 2\n";
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      // Тип исключения не совпадёт
        echo "Блок catch перехватил пользовательское переопределённое исключение\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Перехватится
        echo "Блок catch перехватил встроенное исключение\n", $e;
    }

    // Продолжить выполнение
    var_dump($o); // Null

    echo "\n\n# Пример 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // Перехватится
        echo "Блок catch перехватил встроенное исключение\n", $e;
    }

    // Продолжить выполнение
    var_dump($o); // Null

    echo "\n\n# Пример 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        // Пропускается, поскольку исключение не выбрасывается
        echo "Блок catch перехватил встроенное исключение\n", $e;
    }

    // Продолжить выполнение
    var_dump($o); // TestException

# Fibers

### Обзор файберов

(PHP 8 >= 8.1.0)

Файберы — механизм управления функциями, который умеет прерывать выполнение функций с сохранением полного внутреннего стека вызовов. Файберы разрешается приостанавливать в произвольном месте внутреннего стека вызовов, при этом выполнение кода внутри файбера приостанавливается, пока файбер не возобновит работу.

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

Выполнение файбера разрешается прерывать методом Fiber::suspend() в произвольном месте стека вызовов, вызвать метод Fiber::suspend() можно в глубоко вложенной функции или не вызывать вовсе.

В отличие от бесстековых Generator'ов, под каждый Fiber внутренне выделяется отдельный стек вызовов, что разрешает приостанавливать стеки внутри глубоко вложенных вызовов функций. Функция, которая вызовом метода Fiber::suspend() объявляет точку прерывания файбера, не изменяет тип значения, которое она возвращает, в отличие от функций, которые содержат ключевое слово `yield` и потому возвращают экземпляр класса Generator.

Приостановка файберов доступна как в пользовательских функциях, так и в функциях, которые вызываются внутри виртуальной машины языка PHP, наподобие callback-функции, которую передают как аргумент функции array_map(), или методов, которые цикл `foreach` вызывает на объекте класса Iterator.

Выполнение приостановленного файбера возобновляют либо вызовом метода Fiber::resume(), который умеет передавать в точку приостановки файбера произвольное значение, либо вызовом метода Fiber::throw(), который передаёт исключение в ту же точку. При возобновлении работы файбера с передачей значения это значение возвращается в точке прерывания файбера как результат вызова метода Fiber::suspend(), а при передаче исключения — файбер возобновляет выполнение в той же точке и выбрасывает это исключение.

> Замечание: До PHP 8.4.0 запрещалось переключать файбер в деструкторе объекта.

Пример #1 Стандартный пример работы с файбером

    <?php

    $fiber = new Fiber(function (): void {
        $value = Fiber::suspend('fiber');
        echo "Значение возобновлённого файбера: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Значение приостановленного файбера: ", $value, PHP_EOL;

    $fiber->resume('test');

    ?>

Результат выполнения приведённого примера:

    Значение приостановленного файбера: fiber
    Значение возобновлённого файбера: test

# Генераторы

## Содержание

- Знакомство с генераторами
- Синтаксис генераторов
- Сравнение генераторов с объектами класса Iterator

## Знакомство с генераторами

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Генераторы — легкий способ реализации простых итераторов без дополнительных ресурсов или сложностей, которые связаны с написанием класса, который реализует интерфейс Iterator.

Генератор поддерживает удобную передачу данных в циклы `foreach` без предварительной загрузки массива в память, что иногда вызывает превышение программой предела памяти или значительно увеличивает время обработки, которое уходит на генерацию результата. Вместо этого пишут функцию-генератор, которая аналогична стандартной функции, за исключением того, что вместо возврата единого значения с результатом работы цикла, генератор через ключевое слово `yield` умеет выдавать результат столько раз, сколько значений требуется перебрать. Как и итераторы, генераторы не поддерживают произвольный доступ к элементам массива.

Простой пример этого — переопределение функции range() как генератора. Стандартная функция range() генерирует массив, который состоит из значений, и возвращает его, что приводит к генерации больших массивов: например, вызов range(0, 1000000) займёт более 100 МБ оперативной памяти.

В качестве альтернативы можно создать генератор `xrange()`, который использует память только чтобы создать объект Iterator и сохранить текущее состояние, что потребует не больше 1 килобайта памяти.

Пример #1 Реализация функции range() как генератора

    <?php

    function xrange($start, $limit, $step = 1)
    {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('Шаг должен быть положительным');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('Шаг должен быть отрицательным');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /* Обратите внимание, что и range() и xrange() дадут один и тот же вывод */

    echo 'Нечётные однозначные числа через функцию range():  ';
    foreach (range(1, 9, 2) as $number) {
        echo "$number ";
    }
    echo "\n";

    echo 'Нечётные однозначные числа через функцию xrange(): ';
    foreach (xrange(1, 9, 2) as $number) {
        echo "$number ";
    }

Результат выполнения приведённого примера:

    Нечётные однозначные числа через функцию range():  1 3 5 7 9
    Нечётные однозначные числа через функцию xrange(): 1 3 5 7 9

### Объект Generator

Когда функция-генератор вызывается, она возвращает объект встроенного класса Generator. Этот объект реализует интерфейс Iterator, станет однонаправленным объектом итератора и предоставит методы, с помощью которых можно управлять его состоянием, включая передачу в него и возвращения из него значений.

## Синтаксис генераторов

Функция-генератор выглядит как обычная функция, за исключением того, что вместо возврата значения генератор выдаёт столько значений, столько ему необходимо. Каждая функция с оператором `yield` — функция-генератор.

Когда вызывается генератор, он возвращает объект, который можно итерировать. При итерации по этому объекту (например, в цикле `foreach`), PHP вызывает методы итерации объекта каждый раз, когда ему требуется значение, а затем сохраняет состояние генератора и при следующем вызове возвращает следующее значение.

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

> Замечание:

> Генераторы умеют возвращать значения, которые можно получить методом Generator::getReturn().

### Ключевое слово yield

Сердце функции-генератора — ключевое слово yield. В простейшей форме инструкция yield похожа на инструкцию return, за исключением того, что вместо остановки выполнения функции и возврата, yield отдаёт значение коду, который выполняет цикл над генератором, и приостанавливает выполнение функции генератора.

Пример #1 Простой пример выдачи значений

    <?php

    function gen_one_to_three()
    {
        for ($i = 1; $i <= 3; $i++) {
            // Обратите внимание, что переменная $i сохраняет значение между вызовами
            yield $i;
        }
    }

    $generator = gen_one_to_three();

    foreach ($generator as $value) {
        echo "$value\n";
    }

Результат выполнения приведённого примера:

    1
    2
    3

> Замечание:

> Внутренне последовательные целочисленные ключи свяжутся с полученными значениями, как и в случае с неассоциативным массивом.

#### Получение значений с ключами

PHP также поддерживает ассоциативные массивы, и генераторы — не исключение. Помимо получения простых значений, как показывает пример, разрешается также одновременно получить ключ.

Синтаксис получения пары ключ и значение очень похож на синтаксис определения ассоциативных массивов, как показывает следующий пример.

Пример #2 Получение пар ключ/значение

    <?php

    /* Переменная $input содержит пары ключ и значение, которые разделили точкой с запятой */

    $input = <<<'EOF'
    1;PHP;Любит знаки доллара
    2;Python;Любит пробелы
    3;Ruby;Любит блоки
    EOF;

    function input_parser($input)
    {
        foreach (explode("\n", $input) as $line) {
            $fields = explode(';', $line);
            $id = array_shift($fields);

            yield $id => $fields;
        }
    }

    foreach (input_parser($input) as $id => $fields) {
        echo "$id:\n";
        echo "    $fields[0]\n";
        echo "    $fields[1]\n";
    }

Результат выполнения приведённого примера:

    1:
        PHP
        Любит знаки доллара
    2:
        Python
        Любит пробелы
    3:
        Ruby
        Любит блоки

#### Получение значений null

Чтобы получить значение `null`, нужно вызвать yield без аргументов. Ключ сгенерируется автоматически.

Пример #3 Получение `null`

    <?php

    function gen_three_nulls()
    {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(gen_three_nulls()));

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### Получение значения по ссылке

Функции-генераторы умеют возвращать значения как по ссылке, так и по значению. Это делается так же, как и возврат ссылок из функций: добавлением амперсанда (&) к имени функции.

Пример #4 Получение значений по ссылке

    <?php

    function &gen_reference()
    {
        $value = 3;

        while ($value > 0) {
            yield $value;
        }
    }

    /* Обратите внимание, что можно изменять значение переменной $number в цикле,
     * и поскольку генератор возвращает ссылку, переменная $value
     * в функции gen_reference() также изменится. */
    foreach (gen_reference() as &$number) {
        echo (--$number).'... ';
    }

Результат выполнения приведённого примера:

    2... 1... 0...

#### Делегирование генератора через yield from

Делегирование генератора позволяет получать значения из другого генератора, объекта Traversable или массива через ключевые слова yield from. Внешний генератор будет возвращать значения из внутреннего генератора, объекта или массива до тех пор, пока они не перестанут действовать, после чего выполнение продолжится во внешнем генераторе.

Если генератор используется с ключевыми словами yield from, выражение yield from также будет возвращать значения из внутреннего генератора.

Предостережение

# Сохранение в массив (например, через функцию iterator_to_array())

Ключевые слова yield from не сбрасывают ключи. Ключи, которые вернул объект Traversable или массив, сохранятся. Поэтому некоторые значения могут пересекаться по ключам с другими выражениями yield или yield from, что при записи в массив перезапишет прежние значения этим ключом.

Распространенный случай, когда это имеет значение, — функция iterator_to_array(), которая возвращает массив с ключом по умолчанию, что иногда приводит к неожиданным результатам. У функции iterator_to_array() есть второй параметр `preserve_keys`, которому можно присвоить значение `false` для генерации собственных ключей и игнорирования ключей, которые передаются из объекта Generator.

Пример #5 Выражение yield from с функцией iterator_to_array()

    <?php

    function inner()
    {
        yield 1; // Ключ 0
        yield 2; // Ключ 1
        yield 3; // Ключ 2
    }

    function gen()
    {
        yield 0; // Ключ 0
        yield from inner(); // Ключи 0-2
        yield 4; // Ключ 1
    }

    // Задайте false вторым параметром для получения массива [0, 1, 2, 3, 4]
    var_dump(iterator_to_array(gen()));

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      int(1)
      [1]=>
      int(4)
      [2]=>
      int(3)
    }

Пример #6 Основы работы с выражением yield from

    <?php

    function count_to_ten()
    {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        yield 9;
        yield 10;
    }

    function seven_eight()
    {
        yield 7;
        yield from eight();
    }

    function eight()
    {
        yield 8;
    }

    foreach (count_to_ten() as $num)
    {
        echo "$num ";
    }

Результат выполнения приведённого примера:

    1 2 3 4 5 6 7 8 9 10

Пример #7 Выражение yield from и возвращаемые значения

    <?php

    function count_to_ten()
    {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from seven_eight();
        return yield from nine_ten();
    }

    function seven_eight()
    {
        yield 7;
        yield from eight();
    }

    function eight()
    {
        yield 8;
    }

    function nine_ten()
    {
        yield 9;
        return 10;
    }

    $gen = count_to_ten();

    foreach ($gen as $num) {
        echo "$num ";
    }

    echo $gen->getReturn();

Результат выполнения приведённого примера:

    1 2 3 4 5 6 7 8 9 10

## Сравнение генераторов с объектами класса Iterator

Главное преимущество генераторов — простота. Требуется написать гораздо меньше шаблонного кода по сравнению с реализацией объекта класса Iterator, и этот код гораздо более простой и понятный. Например, эта функция и класс делают одно и то же.

    <?php

    function getLinesFromFile($fileName)
    {
        if (!$fileHandle = fopen($fileName, 'r')) {
            return;
        }

        while (false !== $line = fgets($fileHandle)) {
            yield $line;
        }

        fclose($fileHandle);
    }

    // Против...

    class LineIterator implements Iterator
    {
        protected $fileHandle;

        protected $line;
        protected $i;

        public function __construct($fileName)
        {
            if (!$this->fileHandle = fopen($fileName, 'r')) {
                throw new RuntimeException('Невозможно открыть файл "' . $fileName . '"');
            }
        }

        public function rewind()
        {
            fseek($this->fileHandle, 0);
            $this->line = fgets($this->fileHandle);
            $this->i = 0;
        }

        public function valid()
        {
            return false !== $this->line;
        }

        public function current()
        {
            return $this->line;
        }

        public function key()
        {
            return $this->i;
        }

        public function next()
        {
            if (false !== $this->line) {
                $this->line = fgets($this->fileHandle);
                $this->i++;
            }
        }

        public function __destruct()
        {
            fclose($this->fileHandle);
        }
    }

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

### Смотрите также

- Итераторы объектов

# Атрибуты

## Содержание

- Введение в атрибуты
- Синтаксис атрибутов
- Чтение атрибутов через API-интерфейс модуля Reflection
- Объявление классов атрибутов

## Введение в атрибуты

(PHP 8)

PHP-атрибуты — структурированные машиночитаемые метаданные для классов, методов, функций, параметров, свойств и констант. Атрибуты инспектируют при выполнении кода через API-интерфейс модуля Reflection, добиваясь динамического поведения без изменения кода. Атрибуты — декларативный способ аннотировать код метаданными.

Атрибуты отделяют внутреннюю логику кода от контекста и условий применения этой логики. Интерфейсы жёстко задают структуру класса через обязательные методы, атрибуты же добавляют метаданные множеству элементов: методам, функциям, свойствам и константам. В отличие от интерфейсов, которые заставляют добавлять в класс обязательные методы, атрибуты аннотируют код и не требуют изменять структуру класса.

Атрибуты умеют дополнять класс методами, которые не требует интерфейс, или заменять интерфейсные методы только за счёт добавления метаданных, без изменения структуры интерфейса. Рассмотрим интерфейс `ActionHandler`, который представляет операцию в приложении. Одним реализациям требуется этап настройки, а другим — нет. Не станем заставлять каждый класс, в котором реализуется интерфейс `ActionHandler`, определять метод `setUp()`, а укажем методы, которые требуется выполнить для настройки, атрибутом. Такой подход увеличивает гибкость и разрешает применять атрибуты многократно, когда требуется.

Пример #1 Пример добавления в класс дополнительных неинтерфейсных методов через атрибуты

    <?php

    interface ActionHandler
    {
        public function execute();
    }

    #[Attribute]
    class SetUp {}

    class CopyFile implements ActionHandler
    {
        public string $fileName;
        public string $targetDirectory;

        #[SetUp]
        public function fileExists()
        {
            if (!file_exists($this->fileName)) {
                throw new RuntimeException("Файл не существует");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("Целевой путь $this->targetDirectory не указывает на каталог");
            }
        }

        public function execute()
        {
            copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
        }
    }

    function executeAction(ActionHandler $actionHandler)
    {
        $reflection = new ReflectionObject($actionHandler);

        foreach ($reflection->getMethods() as $method) {
            $attributes = $method->getAttributes(SetUp::class);

            if (count($attributes) > 0) {
                $methodName = $method->getName();

                $actionHandler->$methodName();
            }
        }

        $actionHandler->execute();
    }

    $copyAction = new CopyFile();
    $copyAction->fileName = "/tmp/foo.jpg";
    $copyAction->targetDirectory = "/home/user";

    executeAction($copyAction);

## Синтаксис атрибутов

Синтаксис атрибута состоит из следующих компонентов: объявление атрибута начинается с символов `#[` и заканчивается символом `]`, внутри которых через запятую перечисляют названия атрибутов. Название атрибута указывают как относительное, полное или абсолютное, как описывает раздел «Основы пространств имён». Аргументы атрибута необязательны и указываются в круглых скобках `()`. Аргументы поддерживают только литеральные значения или константные выражения. Поддерживается синтаксис как позиционных, так и именованных аргументов.

При запросе экземпляра атрибута через API-интерфейс модуля Reflection название атрибута разрешается в название класса, а аргументы атрибута передаются в конструктор этого класса. Поэтому для каждого атрибута определяют отдельный класс.

Пример #1 Синтаксис атрибутов

    <?php

    // a.php
    namespace MyExample;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
        const VALUE = 'value';

        private $value;

        public function __construct($value = null)
        {
            $this->value = $value;
        }
    }

    // b.php

    namespace Another;

    use MyExample\MyAttribute;

    #[MyAttribute]
    #[\MyExample\MyAttribute]
    #[MyAttribute(1234)]
    #[MyAttribute(value: 1234)]
    #[MyAttribute(MyAttribute::VALUE)]
    #[MyAttribute(array("key" => "value"))]
    #[MyAttribute(100 + 200)]
    class Thing {}

    #[MyAttribute(1234), MyAttribute(5678)]
    class AnotherThing {}

## Чтение атрибутов через API-интерфейс модуля Reflection

Для доступа к атрибутам классов, методов, функций, параметров, свойств и констант класса в API-интерфейсе модуля Reflection предусмотрели метод getAttributes(). Метод возвращает массив объектов ReflectionAttribute, каждый из которых умеет возвращать название и аргументы атрибута, и создавать объект класса, которым представили атрибут.

Отделение отражённого представления атрибута от экземпляра самого́ атрибутного класса повышает контроль над обработкой ошибок, которые возникают, когда для атрибута не определили класс, допустили опечатку в названии аргумента или пропустили значение аргумента. PHP создаёт объекты атрибутных классов и проверяет корректность аргументов только после вызова метода ReflectionAttribute::newInstance().

Пример #1 Пример чтения атрибутов через API-интерфейс модуля Reflection

    <?php

    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing {}

    function dumpAttributeData($reflection)
    {
        $attributes = $reflection->getAttributes();

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpAttributeData(new ReflectionClass(Thing::class));

Результат выполнения приведённого примера:

    string(11) "MyAttribute"
    array(1) {
      ["value"]=>
      int(1234)
    }
    object(MyAttribute)#3 (1) {
      ["value"]=>
      int(1234)
    }

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

Пример #2 Пример чтения конкретных атрибутов через API-интерфейс модуля Reflection

    <?php
    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpMyAttributeData($reflection) {
        $attributes = $reflection->getAttributes(MyAttribute::class);

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpMyAttributeData(new ReflectionClass(Thing::class));

## Объявление классов атрибутов

Для каждого атрибута рекомендуют определять отдельный класс. В самом простом случае достаточно создать пустой класс и объявить для класса атрибут `#[Attribute]`, который импортируют из глобального пространства имён оператором use.

Пример #1 Пример простого класса с атрибутом

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute {}

Типы объявлений для нацеливания атрибута ограничивают путём передачи битовой маски в первом аргументе объявления `#[Attribute]`.

Пример #2 Спецификация ограничения целей, доступных для присваивания атрибутов

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute {}

Вызов метода ReflectionAttribute::newInstance() теперь выбросит исключение при объявлении атрибута MyAttribute для другого типа, кроме метода или функции.

Атрибутам доступны следующие цели:

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

По умолчанию атрибут разрешается назначить классу, свойству или другому объекту рефлексии только один раз. Назначить одинаковые атрибуты одному объекту рефлексии получится, только если объявить атрибут `#[Attribute]` с флагом `Attribute::IS_REPEATABLE` в битовой маске.

Пример #3 Пример с константой IS_REPEATABLE, которая разрешит назначать атрибут многократно

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute {}

# Объяснение ссылок

## Содержание

- Что такое ссылки
- Что делают ссылки
- Что ссылки собой не представляют
- Передача по ссылке
- Возврат ссылок
- Удаление ссылок
- Неявная работа механизма ссылок

## Что такое ссылки

Ссылки в PHP — средство доступа к одному и тому же содержимому переменной под разными именами. Ссылки в PHP не похожи на указатели языка C; например, нельзя выполнять над ссылками адресную арифметику, они не хранят адрес памяти другой переменной и т. д. Дополнительную информацию даёт раздел «Что ссылки собой не представляют». Напротив, ссылки в PHP — псевдонимы в таблице имён переменных. Обратите внимание, в PHP имя переменной и её содержимое — не одно и то же, поэтому одно и то же значение разрешается хранить под разными именами. Близкое сходство образовывают названия файлов и сами файлы в Unix-системах: имена переменных — записи каталога, а значение переменной — сам файл. Ссылки в PHP — аналогичны жёстким ссылкам в файловых системах Unix.

## Что делают ссылки

Со ссылками выполняют три базовые операции: присваивание по ссылке, передача по ссылке и возврат по ссылке. Глава знакомит читателя с этими операциями и даёт ссылки на дополнительные материалы для изучения.

### Присваивание по ссылке

Первое, что делают ссылки в PHP, — разрешают создавать две переменные, которые ссылаются на одно и то же значение. Когда выражение записывают вот так:

    <?php
    $a =& $b;

переменные $a и $b указывают на одно и то же значение.

> Замечание:

> Переменные $a и $b, которые приводит пример, — эквивалентны. Переменная $a не указывает на переменную $b или наоборот. Переменные $a и $b указывают на одно и то же значение.

> Замечание:

> PHP создаст переменную, если неинициализированную переменную присвоили, передали или вернули по ссылке.

> Пример #1 Пример присваивания ссылок с неопределёнными переменными

>     <?php

>     function foo(&$var) {}

>     foo($a); // PHP создал переменную $a и присвоил ей значение null

>     $b = array();
>     foo($b['b']);
>     var_dump(array_key_exists('b', $b)); // bool(true)

>     $c = new stdClass();
>     foo($c->d);
>     var_dump(property_exists($c, 'd')); // bool(true)

Таким же синтаксисом разрешается пользоваться при вызове функций, из которых возвращаются ссылки на значения:

    <?php
    $foo =& find_var($bar);

Обращение через такой синтаксис к функции, которая не возвращает значение по ссылке, выдаст ошибку, равно как и обращение через такой синтаксис к результату, который возвращает оператор new. Объекты хотя и передаются как указатели, это не то же, что ссылки, как объясняет раздел «Объекты и ссылки».

Внимание

Ссылка будет видна только внутри функции, если присвоить ссылку переменной, которую объявили внутри функции через ключевое слово `global`. Чтобы избежать этого и сделать ссылку видимой в глобальном контексте, ссылку присваивают переменной суперглобального массива $GLOBALS.

Пример #2 Пример присваивания ссылок переменным, которые объявили внутри функции через ключевое слово global

    <?php
    $var1 = "Пример переменной";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // Ссылка $var1 видна только внутри функции
        } else {
            $GLOBALS["var2"] =& $var1; // Ссылка $var1 видна также в глобальном контексте
        }
    }

    global_references(false);
    echo "Переменной \$var2 установили значение '$var2'\n"; // Переменной $var установили значение ''

    global_references(true);
    echo "Переменной \$var2 установили значение '$var2'\n"; // Переменной $var установили значение 'Пример переменной'

Об инструкции `global $var;` думают как о сокращённой записи выражения `$var =& $GLOBALS['var'];`, в котором переменной присваивается ссылка. Поэтому присваивание переменной `$var` другой ссылки изменяет ссылку только локальной переменной.

> Замечание:

> Когда в инструкции `foreach` значение присваивается переменной, которая хранит ссылку, значение ссылки тоже изменяется.

> Пример #3 Пример ссылок в конструкции foreach

>     <?php
>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // Сделать что-нибудь
>     }

>     echo $ref; // 3 — значение последнего элемента массива, который перебирался в цикле

Выражения с языковой конструкцией `array()` умеют вести себя как присваивание по ссылке, хотя и не через строгий синтаксис присваивания по ссылке, а путём добавления префикса `&` к добавляемому элементу массива. Приведём пример:

    <?php
    $a = 1;
    $b = array(2, 3);

    $arr = array(&$a, &$b[0], &$b[1]);

    $arr[0]++;
    $arr[1]++;
    $arr[2]++;
    /* $a == 2, $b == array(3, 4); */
    var_dump($a);
    var_dump($b);

Однако обратите внимание, что ссылки внутри массивов несут опасность. Стандартные (не по ссылке) присваивания со ссылкой в правой части не превращают левую часть в ссылку, но ссылки внутри массивов сохраняются при стандартных присваиваниях. Это также относится к вызовам функций, в которых массив передаётся по значению. Приведём пример:

    <?php

    /* Присваивание скалярных переменных */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // Переменная $c — не ссылка; переменные $a и $b не изменились
    print "a = {$a}; b = {$b}; c = {$c}\n\n";

    /* Присваивание переменных, которые содержат массив */
    $arr = array(1);
    $a =& $arr[0]; // Переменные $a и $arr[0] входят в один набор ссылок
    $arr2 = $arr; // Присваивание по значению, а не по ссылке!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* Содержимое переменной $arr изменяется, даже если это не ссылка! */
    print "a = {$a}\n";
    var_dump($arr);
    var_dump($arr2);

Другими словами, ссылочное поведение массивов определяется поэлементно; ссылочное поведение отдельных элементов массива не зависит от ссылочного статуса контейнера массива.

### Передача по ссылке

Второе, что умеют делать ссылки, — передавать переменные по ссылке. Для этого создают две переменные, которые ссылаются на одно и то же содержимое: одну — в функции, а другую — в области видимости вызова. Следующий пример:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a;

изменит значение, на которое указывает переменная $a, на 6. Причина состоит в том, что в функции foo переменная $var ссылается на то же содержимое, что и переменная $a. Дополнительную информацию об этом даёт раздел о передаче по ссылке.

### Возврат ссылок

Третье, что умеют делать ссылки, — возвращать по ссылке.

## Что ссылки собой не представляют

Как говорилось в предыдущих разделах, ссылки — не указатели. Следующая конструкция не будет делать то, что ожидается:

    <?php
    function foo(&$var)
    {
        $var =& $GLOBALS["baz"];
    }

    foo($bar);

Пример выполняет следующее: в функции foo переменная $var связывается с переменной $bar, которую PHP создал в месте вызова, но затем повторно связывается с переменной $GLOBALS["baz"]. Через механизм ссылок невозможно связать переменную $bar с другим значением в области видимости вызова, поскольку у функции foo нет доступа к переменной $bar, которую представляет только переменная $var, которой доступно только содержимое переменной $bar, но недоступна связка имя-значение, которую хранит таблица символов области видимости вызова. Привязать внешнюю переменную к другому значению помогает механизм возврата ссылок, который связывает ссылки с переменными, которые выбрала функция.

## Передача по ссылке

Переменную по ссылке разрешается передавать в функцию, чтобы функция изменила переменную. Синтаксис выглядит вот так:

    <?php
    function foo(&$var)
    {
        $var++;
    }

    $a = 5;
    foo($a);
    print $a; // В этом месте переменная $a указывает на значение 6

> Замечание: В вызове функции отсутствует знак ссылки — знак указывают только в определении функции. Определения функции достаточно, чтобы правильно передать аргумент по ссылке.

По ссылке разрешается передавать:

- Переменные: `foo($a)`

- Ссылки, которые возвращаются функциями:

      <?php

      function foo(&$var)
      {
          $var++;
          print $var;
      }

      function &bar()
      {
          $a = 5;
          return $a;
      }

      foo(bar());

  Подробнее об этом рассказывает раздел о возврате по ссылке.

Другие выражения не передают по ссылке, поскольку результат будет неопределённым. Следующие примеры передачи по ссылке неправильные:

    <?php

    function foo(&$var)
    {
        return $var++;
    }

    // Обратите внимание, перед названием функции отсутствует знак &
    function bar()
    {
        $a = 5;
        return $a;
    }

    foo(bar()); // Выдаёт предупреждение

    foo($a = 5); // Выражение, а не переменная
    foo(5); // Константа, а не переменная

    class Foobar {}

    foo(new Foobar()); // Вызывает уведомление с PHP 7.0.7
                      // Notice: Only variables should be passed by reference

## Возврат ссылок

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

    <?php

    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // Переменная $myValue — ссылка на переменную $obj->value, значение которой равно 42
    $obj->value = 2;
    echo $myValue;                // Выводит новое значение свойства $obj->value — 2

Пример установит значение свойству объекта, ссылку на которое вернул метод getValue, а не копии свойства, как было бы без синтаксиса ссылок.

> Замечание: Передача аргумента по ссылке отличается от возврата по ссылке тем, что для возврата по ссылке знак `&` придётся указать в двух местах — чтобы указать, что требуется возврат ссылки на свойство, а не копии свойства, и чтобы указать, что переменную $myValue требуется связать со ссылкой, а не присвоить переменной значение стандартным способом.

> Замечание: Возврат ссылки из функции синтаксисом: `return ($this->value);` не сработает, поскольку по ссылке возвращается результат выражения, а не переменная. По ссылке разрешается возвращать только переменные и больше ничего.

Чтобы использовать ссылку, которую вернула функция, потребуется присвоить ссылку переменной:

    <?php

    function &collector()
    {
      static $collection = array();
      return $collection;
    }

    $collection = &collector();
    // Переменная $collection стала ссылкой на статический массив внутри функции

    $collection[] = 'foo';

    print_r(collector());

Результат выполнения приведённого примера:

    Array
    (
        [0] => foo
    )

> Замечание: При присваивании без символа `&` в выражении наподобие `$collection = collector();` переменная $collection получит копию значения, а не ссылку, которую вернула функция.

Ссылку, которую вернула одна функция, передают в другую функцию, которая принимает ссылку, следующим синтаксисом:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    array_push(collector(), 'foo');

> Замечание: Обратите внимание, что вызов `array_push(&collector(), 'foo');` не сработает, а выдаст фатальную ошибку.

## Удаление ссылок

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

    <?php

    $a = 1;
    $b =& $a;
    unset($a);
    var_dump($a);
    var_dump($b);

Пример не удалит переменную $b, удалится только переменная $a.

Опять же, было бы полезно рассматривать это как аналог вызова функции unlink в системе Unix.

## Неявная работа механизма ссылок

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

### Ссылки global

При объявлении переменной синтаксисом global $var фактически создаётся ссылка на глобальную переменную. Такое объявление — то же, что и:

    <?php
    $var =& $GLOBALS["var"];

Удаление переменной $var конструкцией unset() не удалит глобальную переменную.

# Предопределённые переменные

В PHP заранее определили переменные, которые представляют внешние переменные, встроенные переменные окружения и другую информацию о среде выполнения, например количество и значения аргументов, которые передали в скрипт в CLI-окружении.

# Суперглобальные переменные

Суперглобальные переменные — Встроенные переменные, которые всегда доступны во всех областях

### Описание

Некоторые предопределённые переменные в PHP являются "суперглобальными", что означает, что они доступны в любом месте скрипта. Нет необходимости использовать синтаксис global $variable; для доступа к ним в функциях и методах.

Суперглобальными переменными являются:

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### Примечания

> Замечание: Доступность переменных

> По умолчанию все суперглобальные переменные доступны всегда, однако существуют настройки, которые могут на это влиять. За дальнейшей информацией обращайтесь к описанию директивы variables_order.

> Замечание: Переменные переменных

> Суперглобальные переменные не могут быть использованы в качестве переменных переменных внутри функций и методов.

### Смотрите также

- Область видимости переменной
- Директива variables_order
- "Фильтрация данных"

# $GLOBALS

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

$GLOBALS — Ссылается на переменные глобальной области видимости

### Описание

Ассоциативный массив (array), который содержит ссылки на каждую переменную, которую в текущий момент определили в глобальной области видимости скрипта. Имена переменных — ключи массива.

### Примеры

Пример #1 Пример использования суперглобального массива $GLOBALS

    <?php

    function test()
    {
        $foo = "Локальная переменная";

        echo 'Значение переменной $foo в глобальной области видимости: ' . $GLOBALS["foo"] . "\n";
        echo 'Значение переменной $foo в текущей области видимости: ' . $foo . "\n";
    }

    $foo = "Пример содержимого";
    test();

    ?>

Вывод приведённого примера будет похож на:

    Значение переменной $foo в глобальной области видимости: Пример содержимого
    Значение переменной $foo в текущей области видимости: Локальная переменная

Внимание

Начиная с PHP 8.1.0 доступ на запись всего массива $GLOBALS больше не поддерживается:

Пример #2 Пример записи всего массива $GLOBALS выдаёт ошибку

    <?php

    // Присваивания, которые генерируют ошибку во время компиляции:
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...и любая другая операция записи или чтения-записи в массив $GLOBALS

    ?>

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

> Замечание: Доступность переменной

> В противоположность остальным суперглобальным переменным, суперглобальная переменная $GLOBALS доступна в PHP в каждом месте кода.

> Замечание:

> С PHP 8.1.0 суперглобальный массив $GLOBALS стал доступной только для чтения копией глобальной таблицы символов. Поэтому глобальные переменные нельзя изменять через копию массива переменных глобальной области видимости. Раньше массив $GLOBALS исключался из обычного поведения массивов PHP по значению и глобальные переменные разрешалось изменять через копию суперглобального массива.

>     <?php

>     // До PHP 8.1.0
>     $a = 1;

>     $globals = $GLOBALS; // Как будто бы копия по значению
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // Начиная с PHP 8.1.0
>     // такое присваивание больше не изменяет значение переменной $a. Предыдущее поведение нарушало семантику по значению
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // Чтобы восстановить предыдущее поведение, перебирают копию массива и каждое свойство
>     // массива-копии присваивают переменным суперглобального массива $GLOBALS
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — Информация о сервере и среде исполнения

### Описание

Переменная $_SERVER — массив (array), который содержит информацию о заголовках, путях и расположениях скриптов. Записи в этом массиве создаются веб-сервером, поэтому нет гарантии, что каждый веб-сервер будет предоставлять каждую из этих переменных; серверы иногда опускают отдельные переменные или предоставляют другие, которые здесь не указали. Однако большинство из этих переменных учтены в спецификации » CGI/1.1 и, скорее всего, определятся.

> Замечание: При запуске PHP в командной строке бо́льшая часть этих записей недоступна или не содержит никакого значения.

В дополнение к перечисленным ниже элементам PHP создаст дополнительные элементы со значениями из заголовков запросов. Элементам присваивается название с префиксом `HTTP_`, за которым идёт название заголовка, написанное с заглавной буквы и с подчёркиванием вместо дефиса. Например, заголовок `Accept-Language` будет доступен как `$_SERVER['HTTP_ACCEPT_LANGUAGE']`.

### Индексы

'PHP_SELF'
  Название файла скрипта, который выполняется в текущий момент, относительно корня документов. Например, переменная $_SERVER['PHP_SELF'] в скрипте по адресу http://example.com/foo/bar.php примет значение /foo/bar.php. Константа __FILE__ содержит полный путь и название файла текущего (то есть подключённого) файла. Переменная содержит название скрипта, если PHP запустили в командной строке.
'argv'
  Массив аргументов, которые передали скрипту. При запуске скрипта в командой строке это даёт C-подобный доступ к параметрам командной строки. При вызове через метод GET этот массив содержит строку запроса.
'argc'
  Содержит количество параметров, которые передали скрипту, если скрипт запустили в командной строке.
'GATEWAY_INTERFACE'
  Содержит используемую сервером версию спецификации CGI-интерфейса; например `'CGI/1.1'`..
'SERVER_ADDR'
  IP-адрес сервера, по которому выполняется текущий скрипт.
'SERVER_NAME'
  Имя хоста, на котором выполняется текущий скрипт. Переменная содержит имя, которое определили для виртуального хоста, если скрипт выполняется на виртуальном хосте.

  > Замечание: В Apache 2 потребуется установить директивы `UseCanonicalName = On` и `ServerName`, иначе значение отразит имя хоста, которое предоставил клиент и которое подделывают злоумышленники. Небезопасно полагаться на это значение в контексте, который требует безопасности.

'SERVER_SOFTWARE'
  Строка идентификации сервера, указанная в заголовках, когда происходит ответ на запрос.
'SERVER_PROTOCOL'
  Имя и версия информационного протокола, через который запросили страницу; например `'HTTP/1.0'`;
'REQUEST_METHOD'
  Метод, которым запросили страницу; например `'GET'`, `'HEAD'`, `'POST'`, `'PUT'`.

  > Замечание:

  > При запросе методом `HEAD` PHP-скрипт завершается после отправки заголовков — после любого вывода без буферизации вывода.

'REQUEST_TIME'
  Метка времени, когда PHP начал обработку запроса.
'REQUEST_TIME_FLOAT'
  Метка времени, когда PHP начал обработку запроса, с точностью до микросекунд.
'QUERY_STRING'
  Строка запроса, если адрес содержит такую, через которую получили доступ к странице.
'DOCUMENT_ROOT'
  Директория корня документов, в которой выполняется текущий скрипт, в точности та, которую указали в конфигурационном файле сервера.
'HTTPS'
  Принимает непустое значение, если запрос выполнили через протокол HTTPS.
'REMOTE_ADDR'
  IP-адрес, с которого пользователь просматривает текущую страницу.
'REMOTE_HOST'
  Удалённый хост, с которого пользователь просматривает текущую страницу. Обратный поиск DNS основан на значении переменной REMOTE_ADDR.

  > Замечание: Сервер потребуется настроить, чтобы создавать эту переменную. Например, для веб-сервера Apache потребуется указать директиву `HostnameLookups On` в файле httpd.conf, чтобы эта переменная создавалась. Смотрите также описание функции gethostbyaddr().

'REMOTE_PORT'
  Порт на удалённой машине, на котором устанавливается соединение с сервером.
'REMOTE_USER'
  Аутентифицированный пользователь.
'REDIRECT_REMOTE_USER'
  Аутентифицированный пользователь, если запрос перенаправлен изнутри.
'SCRIPT_FILENAME'

  Абсолютный путь к исполняемому скрипту.

  > Замечание:

  > Переменная $_SERVER['SCRIPT_FILENAME'] содержит относительный путь, который указал пользователь, если скрипт запустили в командной строке (CLI) по относительному пути наподобие file.php или ../file.php.

'SERVER_ADMIN'
  Значение директивы SERVER_ADMIN веб-сервера Apache, которое указали в конфигурационном файле сервера. При запуске скрипта на виртуальном хосте значение определяется для этого виртуального хоста.
'SERVER_PORT'
  Порт, на котором сервер принимает запросы. При стандартной конфигурации сервера переменная содержит значение `'80'`; для соединений по протоколу SSL, например, значение переменной соответствует порту, который определили для защищённых HTTP-соединений.

  > Замечание: На веб-сервере Apache 2 потребуется установить директивы установить `UseCanonicalName = On` и `UseCanonicalPhysicalPort = On`, чтобы получить реальный физический порт, иначе значение подделают и переменная не вернёт реальное значение физического порта. В контекстах, которые требуют усиленной безопасности, полагаться на это значение небезопасно.

'SERVER_SIGNATURE'
  Строка, которая содержит версию сервера и имя виртуального хоста. Эта информация добавляются на страницы, которые генерирует сервер, если в конфигурации сервера включили директиву, которая отвечает за добавление такой строки.
'PATH_TRANSLATED'
  Путь к текущему скрипту после выполнения сервером сопоставления virtual-to-real. Путь строится на основе файловой системы, а не на основе корневого каталога сервера.

  > Замечание: Пользователи Apache 2 включают директиву `AcceptPathInfo = On` в конфигурационном файле httpd.conf, чтобы определить значение переменной PATH_INFO.

'SCRIPT_NAME'
  Путь к текущему исполняемому скрипту. Переменная полезна на страницах, которым требуется указывать на самих себя. Полный путь и название текущего включаемого файла содержит константа __FILE__.
'REQUEST_URI'
  URI-идентификатор наподобие '`/index.html`', который указали для доступа к странице.
'PHP_AUTH_DIGEST'
  При HTTP-аутентификации по дайджесту переменной присваивается значение заголовка 'Authorization', который отправил клиент и которое затем проверяют.
'PHP_AUTH_USER'
  При выполнении HTTP-аутентификации переменной присваивается имя пользователя, которое предоставил пользователь.
'PHP_AUTH_PW'
  При выполнении HTTP-аутентификации переменной присваивается пароль, которое предоставил пользователь.
'AUTH_TYPE'
  При выполнении HTTP-аутентификации переменной присваивается тип аутентификации, который сервер устанавливает на основе клиентских данных.
'PATH_INFO'
  Содержит информацию о пути, которую предоставил клиент. Значение идёт после фактического названия скрипта, но до строки запроса, если строку запроса указали. Переменная $_SERVER['PATH_INFO'] получит значение `/some/stuff`, если текущий скрипт запросили по URL-адресу наподобие http://www.example.com/php/path_info.php/some/stuff?foo=bar.
'ORIG_PATH_INFO'
  Исходное значение переменной 'PATH_INFO' перед обработкой PHP.

### Примеры

Пример #1 Пример вывода значения переменной $_SERVER

    <?php

    echo $_SERVER['SERVER_NAME'];

    ?>

Вывод приведённого примера будет похож на:

    www.example.com

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

### Смотрите также

- Фильтрация данных

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — Переменные строки запроса

### Описание

Ассоциативный массив переменных, которые передали скрипту через параметры URL-адреса, в строке запроса. На заполнение массива влияет только состав URL-адреса — содержит ли адрес аргументы в строке запроса, а не HTTP-метод запроса.

### Примеры

Пример #1 Пример работы с переменными массива $_GET

    <?php

    echo 'Привет, ' . htmlspecialchars($_GET["name"]) . '!';

    ?>

Подразумевается, что пользователь ввёл в браузере адрес `http://example.com/?name=Иван`.

Вывод приведённого примера будет похож на:

    Привет, Иван!

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

> Замечание:

> Перед записью в массив $_GET значения автоматически обрабатываются функцией urldecode().

### Смотрите также

- Переменные извне PHP
- Фильтрация данных

# $_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — Данные форм из запросов HTTP-методом POST

### Описание

Ассоциативный массив данных, которые передали скрипту в запросе по протоколу HTTP методом POST со значением `application/x-www-form-urlencoded` или `multipart/form-data` в HTTP-заголовке Content-Type.

### Примеры

Пример #1 Пример работы с переменными массива $_POST

    <?php

    echo 'Привет ' . htmlspecialchars($_POST["name"]) . '!';

    ?>

Подразумевается, что пользователь отправил POST-запрос с данными name=Иван в теле запроса.

Вывод приведённого примера будет похож на:

    Привет, Иван!

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

> Замечание: Обёртка php://input умеет считывать из тела POST-запроса данные, которые при передаче закодировали другим способом, например `application/json` или `application/xml`. Суперглобальный массив $_POST работает только с данными в форматах `application/x-www-form-urlencoded` и `multipart/form-data`, а поток php://input получает прямой доступ к сырым данным из тела запроса.

### Смотрите также

- Обработка внешних переменных
- Фильтрация данных

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — Переменные файлов, загруженных по HTTP

### Описание

Ассоциативный массив (array) элементов, загруженных в текущий скрипт через метод HTTP POST. Структура этого массива описана в разделе Загрузка файлов методом POST.

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

### Смотрите также

- move_uploaded_file() - Перемещает загруженный файл в новое место
- Загрузка файлов на сервер

# $_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — Переменные HTTP-запроса

### Описание

Ассоциативный массив (array), который по умолчанию содержит данные переменных $_GET, $_POST и $_COOKIE.

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

> Замечание:

> При запуске из командной строки записи argv и argc не включаются в этот массив; записи содержит массив (array) $_SERVER.

> Замечание:

> Переменные в массиве $_REQUEST передаются в скрипт через механизмы ввода GET, POST или COOKIE и поэтому удалённый пользователь в состоянии изменить переменные, и им нельзя доверять. Будет ли массив содержать переменные и в каком порядке — определяют директивы конфигурации PHP request_order и variables_order.

### Смотрите также

- "Обработка внешних переменных"
- "Модуль фильтрации данных"

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — Переменные сессии

### Описание

Ассоциативный массив, содержащий переменные сессии, которые доступны для текущего скрипта. Смотрите документацию по функциям сессии для получения дополнительной информации.

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

### Смотрите также

- session_start() - Начинает или возобновляет сессию

# $_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — Переменные окружения

### Описание

Ассоциативный массив (array) значений, переданных скрипту через переменные окружения.

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

Некоторые переменные окружения включают CGI-переменные, причём их наличие не зависит от того, запущен ли PHP как модуль сервера или как препроцессор CGI.

### Примеры

Пример #1 Пример использования $_ENV

    <?php
    echo 'Моё имя пользователя: ' .$_ENV["USER"] . '!';
    ?>

Допустим, скрипт запустил "bjori"

Вывод приведённого примера будет похож на:

    Моё имя пользователя: bjori!

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

### Смотрите также

- getenv() - Получает значение одной или всех переменных окружения
- Фильтрация данных

# $_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — HTTP Cookies

### Описание

Ассоциативный массив (array) значений, переданных скрипту через HTTP Cookies.

### Примеры

Пример #1 Пример использования $_COOKIE

    <?php
    echo 'Привет, ' . htmlspecialchars($_COOKIE["name"]) . '!';
    ?>

Предположим, что значение куки с именем "name" было установлено ранее.

Вывод приведённого примера будет похож на:

    Привет, Иван!

### Примечания

> Замечание: Это «суперглобальная», или автоматическая глобальная, переменная. Поэтому переменная доступна во всех контекстах скрипта. Выполнять global $variable; для доступа к глобальной переменной внутри метода или функции не требуется.

### Смотрите также

- setcookie() - Отправляет cookie
- Обработка внешних переменных
- Фильтрация данных

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — Предыдущее сообщение об ошибке

Внимание

Начиная с PHP 7.2.0 функциональность УСТАРЕЛА, а в PHP 8.0.0 функциональность УДАЛИЛИ. Полагаться на функциональность настоятельно не рекомендуют.

Вместо доступа к переменной вызывают функцию error_get_last().

### Описание

Переменная $php_errormsg содержит текст сообщения о последней об ошибке, которое сгенерировал PHP. Переменная доступна только в той области видимости, в которой возникла ошибка, и только если включили опцию конфигурации track_errors, которая по умолчанию отключена.

Внимание

При установке пользовательского обработчика ошибок функцией set_error_handler() переменная $php_errormsg устанавливается, только если обработчик ошибок возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Директиву track_errors, которая открывала доступ к переменной $php_errormsg, удалили.
7.2.0 | Директива track_errors, которая открывала доступ к переменной $php_errormsg, устарела.

### Примеры

Пример #1 Пример получения сообщения о последней ошибке из переменной $php_errormsg

    <?php

    @strpos();
    echo $php_errormsg;

    ?>

Вывод приведённого примера будет похож на:

    Wrong parameter count for strpos()

### Смотрите также

- error_get_last() - Получает последнюю ошибку

# $http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — Заголовки HTTP-ответа

Внимание

Начиная с PHP 8.5.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

Вместо обращения к переменной вызывают функцию http_get_last_response_headers().

### Описание

Массив (array) $http_response_header похож на функцию get_headers(). При работе с HTTP-обёрткой переменная $http_response_header заполняется заголовками HTTP-ответа. Массив $http_response_header создаётся в локальной области видимости.

### Примеры

Пример #1 Пример получения заголовков HTTP-ответа через переменную $http_response_header

    <?php

    function get_contents()
    {
        file_get_contents("http://example.com");
        var_dump($http_response_header); // Переменная заполняется в локальной области видимости
    }

    get_contents();

    var_dump($http_response_header); // Вызов функции get_contents() не заполняет переменную вне области видимости функции

Вывод приведённого примера будет похож на:

    array(9) {
      [0]=>
      string(15) "HTTP/1.1 200 OK"
      [1]=>
      string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
      [2]=>
      string(29) "Server: Apache/2.2.3 (CentOS)"
      [3]=>
      string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
      [4]=>
      string(27) "ETag: "280100-1b6-80bfd280""
      [5]=>
      string(20) "Accept-Ranges: bytes"
      [6]=>
      string(19) "Content-Length: 438"
      [7]=>
      string(17) "Connection: close"
      [8]=>
      string(38) "Content-Type: text/html; charset=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### Смотрите также

- http_get_last_response_headers() - Получает заголовки последнего HTTP-ответа
- http_clear_last_response_headers() - Очищает сохранённые заголовки HTTP-ответов

# $argc

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

$argc — Количество аргументов, переданных скрипту

### Описание

Содержит количество аргументов, переданных текущему скрипту при запуске из командной строки.

> Замечание: Имя файла скрипта всегда передаётся в качестве первого аргумента, таким образом минимальное значение $argc равно `1`.

> Замечание: Эта переменная недоступна, если register_argc_argv отключён.

### Примеры

Пример #1 Пример использования $argc

    <?php
    var_dump($argc);
    ?>

Запустим пример в командной строке: php script.php arg1 arg2 arg3

Вывод приведённого примера будет похож на:

    int(4)

### Примечания

> Замечание:

> Также доступно как $_SERVER['argc'].

### Смотрите также

- getopt() - Получает параметры из списка аргументов командной строки
- $argv

# $argv

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

$argv — Массив аргументов, которые передали скрипту

### Описание

Переменная содержит массив (array) аргументов, которые передали скрипту при запуске из командной строки.

> Замечание: Первый аргумент $argv[0] содержит название файла запущенного скрипта.

> Замечание: Переменная недоступна при отключённой директиве register_argc_argv.

Внимание

Для проверки того, что скрипт запустили из командной строки, вместо проверки факта установки переменных $argv или $_SERVER['argv'] вызывают функцию php_sapi_name().

### Примеры

Пример #1 Пример сброса переменной $argv в поток вывода

    <?php

    var_dump($argv);

    ?>

Запустим пример в командной строке: php script.php arg1 arg2 arg3

Вывод приведённого примера будет похож на:

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### Примечания

> Замечание:

> Значения также доступны в элементе $_SERVER['argv'].

### Смотрите также

- getopt() - Получает параметры из списка аргументов командной строки
- $argc

## Содержание

- Суперглобальные переменные — Встроенные переменные, которые всегда доступны во всех областях
- $GLOBALS — Ссылается на переменные глобальной области видимости
- $_SERVER — Информация о сервере и среде исполнения
- $_GET — Переменные строки запроса
- $_POST — Данные форм из запросов HTTP-методом POST
- $_FILES — Переменные файлов, загруженных по HTTP
- $_REQUEST — Переменные HTTP-запроса
- $_SESSION — Переменные сессии
- $_ENV — Переменные окружения
- $_COOKIE — HTTP Cookies
- $php_errormsg — Предыдущее сообщение об ошибке
- $http_response_header — Заголовки HTTP-ответа
- $argc — Количество аргументов, переданных скрипту
- $argv — Массив аргументов, которые передали скрипту

# Предопределённые исключения

## Содержание

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

Смотрите также «Исключения SPL».

# Исключение Exception

(PHP 5, PHP 7, PHP 8)

## Введение

Класс Exception — базовый класс для пользовательских исключений.

## Обзор класса

class Exception implements Throwable {
/* Свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Свойства

message

  Текст исключения

code

  Код исключения

file

  Название файла, в котором возникло исключение

line

  Номер строки, в которой возникло исключение

previous

  Ранее выброшенное исключение

string

  Строковое представление трассировки стека

trace

  Трассировка стека в виде массива

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — Создать исключение

### Описание

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Создаёт исключение.

### Список параметров

`message`

  Текст сообщения.

`code`

  Код исключения.

`previous`

  Предыдущее исключение. Используется при создания цепочки исключений.

> Замечание: Вызов конструктора класса Exception из его подкласса, игнорирует аргументы по умолчанию, если свойства $code и $message уже установлены.

### Примечания

> Замечание:

> Параметр `message` не является бинарно-безопасным.

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — Получает сообщение исключения

### Описание

final public function Exception::getMessage(): string

Возвращает сообщение исключения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает сообщение исключения в виде строки.

### Примеры

Пример #1 Пример использования метода Exception::getMessage()

    <?php
    try {
        throw new Exception("Какое-нибудь сообщение об ошибке");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

Вывод приведённого примера будет похож на:

    Какое-нибудь сообщение об ошибке

### Смотрите также

- Throwable::getMessage() - Получает сообщение ошибки

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — Возвращает предыдущий объект, реализующий Throwable

### Описание

final public function Exception::getPrevious(): ?Throwable

Возвращает предыдущий объект, реализующий Throwable (переданный третьим параметром в Exception::__construct()).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает предыдущий объект, реализующий Throwable или `null`, если такового нет.

### Примеры

Пример #1 Пример использования Exception::getPrevious()

Проход и печать цепи исключений.

    <?php
    class MyCustomException extends Exception {}

    function doStuff() {
        try {
            throw new InvalidArgumentException("Ты делаешь это неправильно!", 112);
        } catch(Exception $e) {
            throw new MyCustomException("Что-то случилось", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Exception $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Вывод приведённого примера будет похож на:

    /home/bjori/ex.php:8 Что-то случилось (911) [MyCustomException]
    /home/bjori/ex.php:6 Ты делаешь это неправильно! (112) [InvalidArgumentException]

### Смотрите также

- Throwable::getPrevious() - Возвращает предыдущий Throwable

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — Получает код исключения

### Описание

final public function Exception::getCode(): int

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает код исключения типа int у класса Exception, но у потомков класса Exception может быть другой тип (например, типа string в PDOException).

### Примеры

Пример #1 Пример использования метода Exception::getCode()

    <?php
    try {
        throw new Exception("Какое-нибудь сообщение об ошибке", 30);
    } catch(Exception $e) {
        echo "Код исключения: " . $e->getCode();
    }
    ?>

Вывод приведённого примера будет похож на:

    Код исключения: 30

### Смотрите также

- Throwable::getCode() - Возвращает код исключения

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — Получает файл, в котором возникло исключение

### Описание

final public function Exception::getFile(): string

Получить имя файла, где исключение было создано.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя файла, в котором исключение было создано.

### Примеры

Пример #1 Пример использования метода Exception::getFile()

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

Вывод приведённого примера будет похож на:

    /home/bjori/tmp/ex.php

### Смотрите также

- Throwable::getFile() - Возвращает файл, в котором выброшено исключение

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — Получает строку, в которой возникло исключение

### Описание

final public function Exception::getLine(): int

Получить номер строки, где исключение было создано

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает номер строки, где было создано исключение.

### Примеры

Пример #1 Пример использования метода Exception::getLine()

    <?php
    try {
        throw new Exception("Какое-нибудь сообщение об ошибке");
    } catch(Exception $e) {
        echo "Исключение было создано на строке: " . $e->getLine();
    }
    ?>

Вывод приведённого примера будет похож на:

    Исключение было создано на строке: 3

### Смотрите также

- Throwable::getLine() - Получает строку скрипта, в которой данный объект был выброшен

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — Получает трассировку стека

### Описание

final public function Exception::getTrace(): array

Возвращает трассировку стека исключения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает трассировку стека исключения в виде массива (array).

### Примеры

Пример #1 Пример использования метода Exception::getTrace()

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Смотрите также

- Throwable::getTrace() - Возвращает трассировку стека

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — Получает трассировку стека в виде строки

### Описание

final public function Exception::getTraceAsString(): string

Возвращает трассировку стека исключения в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает трассировку стека исключения в виде строки.

### Примеры

Пример #1 Пример использования метода Exception::getTraceAsString()

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

Вывод приведённого примера будет похож на:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Смотрите также

- Throwable::getTraceAsString() - Получает результаты трассировки стека в виде строки

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — Строковое представление исключения

### Описание

public function Exception::__toString(): string

Возвращает исключение в виде строки (string).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает исключение в виде строки (string).

### Примеры

Пример #1 Пример использования метода Exception::__toString()

    <?php
    try {
        throw new Exception("Какое-нибудь сообщение об ошибке");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

Вывод приведённого примера будет похож на:

    exception 'Exception' with message 'Какое-нибудь сообщение об ошибке' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Смотрите также

- Throwable::__toString() - Получает строковое представление выброшенного объекта

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — Клонировать исключение

### Описание

private function Exception::__clone(): void

Исключения Exception не могут быть клонированы, а попытка сделать это выбросит ошибку Error.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Исключения не поддаются клонированию.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Метод Exception::__clone() больше не является окончательным (final).

## Содержание

- Exception::__construct — Создать исключение
- Exception::getMessage — Получает сообщение исключения
- Exception::getPrevious — Возвращает предыдущий объект, реализующий Throwable
- Exception::getCode — Получает код исключения
- Exception::getFile — Получает файл, в котором возникло исключение
- Exception::getLine — Получает строку, в которой возникло исключение
- Exception::getTrace — Получает трассировку стека
- Exception::getTraceAsString — Получает трассировку стека в виде строки
- Exception::__toString — Строковое представление исключения
- Exception::__clone — Клонировать исключение

# Исключение ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Введение

Исключение выбрасывается, если возникла ошибка.

## Обзор класса

class ErrorException extends Exception {
/* Свойства */
protected int $severity = E_ERROR;
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
public function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

severity

  Серьёзность исключения.

## Примеры

Пример #1 Пример использования функции set_error_handler() для изменения сообщений об ошибках на исключение ErrorException

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // Этот код ошибки не включили в директиве error_reporting
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // Не выбрасывать исключение для предупреждений об устаревании,
            // поскольку новые или неожиданные предупреждения об устаревании
            // иногда ломают приложение
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // Десериализация повреждённых данных вызовет предупреждение,
    // которое обработчик ошибок преобразует в исключение ErrorException
    unserialize('broken data');

    ?>

Вывод приведённого примера будет похож на:

    Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
    Stack trace:
    #0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
    #1 test.php(16): unserialize('broken data')
    #2 {main}
      thrown in test.php on line 16

# ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — Создаёт исключение

### Описание

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

Создаёт исключение.

### Список параметров

`message`

  Текст исключения.

`code`

  Код исключения.

`severity`

  Уровень серьёзности исключения.

  > Замечание:

  > В то время, как уровень серьёзности может быть любым целым числом (int), предполагается, что для её указания будут использованы константы ошибок.

`filename`

  Имя файла, где вызвано исключение.

`line`

  Номер строки, где вызвано исключение.

`previous`

  Предыдущее исключение. Используется для создания цепочки исключений.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `filename` и `line` теперь допускают значение null. Ранее их значениями по умолчанию были `__FILE__` и `__LINE__`, соответственно.

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — Получает серьёзность исключения

### Описание

final public function ErrorException::getSeverity(): int

Возвращает серьёзность исключения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает уровень серьёзности исключения.

### Примеры

Пример #1 Пример использования метода ErrorException::getSeverity()

    <?php
    try {
        throw new ErrorException("Сообщение об исключении", 0, E_USER_ERROR);
    } catch(ErrorException $e) {
        echo "Серьёзность этого исключения равна: " . $e->getSeverity();
        var_dump($e->getSeverity() === E_USER_ERROR);
    }
    ?>

Вывод приведённого примера будет похож на:

    Серьёзность этого исключения равна: 256
    bool(true)

## Содержание

- ErrorException::__construct — Создаёт исключение
- ErrorException::getSeverity — Получает серьёзность исключения

# Исключение ClosedGeneratorException

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Исключение ClosedGeneratorException выбрасывается при попытке получить значение из закрытого итератора, реализованного классом Generator.

## Обзор класса

class ClosedGeneratorException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Ошибка Error

(PHP 7, PHP 8)

## Введение

Класс Error — базовый класс для внутренних ошибок PHP.

## Обзор класса

class Error implements Throwable {
/* Свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Свойства

message

  Сообщение об ошибке

code

  Код ошибки

file

  Название файла, в котором возникла ошибка

line

  Номер строки, в которой возникла ошибка

previous

  Предыдущая ошибка или исключение

string

  Строковое представление трассировки стека

trace

  Трассировка стека в виде массива

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — Создаёт объект класса Error

### Описание

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Создаёт объект класса Error.

### Список параметров

`message`

  Сообщение об ошибке.

`code`

  Код ошибки.

`previous`

  Предыдущий объект, реализующий интерфейс throwable, используется для создания цепочки исключений.

### Примечания

> Замечание:

> Значение `message` НЕ является безопасным для бинарных данных, то есть в тексте сообщения нельзя использовать символ с кодом \0.

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — Получает сообщение об ошибке

### Описание

final public function Error::getMessage(): string

Возвращает сообщение об ошибке.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает сообщение об ошибке в виде строки.

### Примеры

Пример #1 Пример использования метода Error::getMessage()

    <?php
    try {
        throw new Error("Страшная ошибка");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

Вывод приведённого примера будет похож на:

    Страшная ошибка

### Смотрите также

- Throwable::getMessage() - Получает сообщение ошибки

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — Возвращает предыдущий Throwable

### Описание

final public function Error::getPrevious(): ?Throwable

Возвращает предыдущий объект Throwable (третий параметр конструктора Error::__construct()).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает предыдущий объект Throwable, если он есть, и `null`, если его нет.

### Примеры

Пример #1 Пример использования Error::getPrevious()

Проход и печать цепи исключений.

    <?php
    class MyCustomError extends Error {}

    function doStuff() {
        try {
            throw new InvalidArgumentError("Вы делаете это неправильно!", 112);
        } catch(Error $e) {
            throw new MyCustomError("Что-то случилось", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Error $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Вывод приведённого примера будет похож на:

    /home/bjori/ex.php:8 Что-то случилось (911) [MyCustomError]
    /home/bjori/ex.php:6 Вы делаете это неправильно! (112) [InvalidArgumentError]

### Смотрите также

- Throwable::getPrevious() - Возвращает предыдущий Throwable

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — Возвращает код ошибки

### Описание

final public function Error::getCode(): int

Возвращает код ошибки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код ошибки типа int

### Примеры

Пример #1 Пример использованияError::getCode()

    <?php
    try {
        throw new Error("Какое-то сообщение об ошибке", 30);
    } catch(Error $e) {
        echo "Код ошибки: " . $e->getCode();
    }
    ?>

Вывод приведённого примера будет похож на:

    Код ошибки: 30

### Смотрите также

- Throwable::getCode() - Возвращает код исключения

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — Получает файл, в котором произошла ошибка

### Описание

final public function Error::getFile(): string

Получить имя файла, в котором произошла ошибка.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя файла, в котором произошла ошибка.

### Примеры

Пример #1 Пример использования метода Error::getFile()

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

Вывод приведённого примера будет похож на:

    /home/bjori/tmp/ex.php

### Смотрите также

- Throwable::getFile() - Возвращает файл, в котором выброшено исключение

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — Получает номер строки, в которой произошла ошибка

### Описание

final public function Error::getLine(): int

Получить номер строки, в которой произошла ошибка.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает номер строки, в которой произошла ошибка.

### Примеры

Пример #1 Пример использованияError::getLine()

    <?php
    try {
        throw new Error("Какое-то сообщение об ошибке");
    } catch(Error $e) {
        echo "Ошибка создана в строке: " . $e->getLine();
    }
    ?>

Вывод приведённого примера будет похож на:

    Ошибка создана в строке: 3

### Смотрите также

- Throwable::getLine() - Получает строку скрипта, в которой данный объект был выброшен

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — Получает трассировку стека

### Описание

final public function Error::getTrace(): array

Возвращает трассировку стека.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает трассировку стека в виде массива (array).

### Примеры

Пример #1 Пример использования метода Error::getTrace()

    <?php
    function test() {
     throw new Error;
    }

    try {
     test();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Смотрите также

- Throwable::getTrace() - Возвращает трассировку стека

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — Получает трассировку стека в виде строки

### Описание

final public function Error::getTraceAsString(): string

Возвращает трассировку стека в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает трассировку стека в виде строки.

### Примеры

Пример #1 Пример использования метода Error::getTraceAsString()

    <?php
    function test() {
        throw new Error;
    }

    try {
        test();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

Вывод приведённого примера будет похож на:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Смотрите также

- Throwable::getTraceAsString() - Получает результаты трассировки стека в виде строки

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — Строковое представление ошибки

### Описание

public function Error::__toString(): string

Возвращает строковое (string) представление ошибки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строковое (string) представление ошибки.

### Примеры

Пример #1 Пример использования метода Error::__toString()

    <?php
    try {
        throw new Error("Сообщение об ошибке");
    } catch(Error $e) {
        echo $e;
    }
    ?>

Вывод приведённого примера будет похож на:

    Error: Сообщение об ошибке in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Смотрите также

- Throwable::__toString() - Получает строковое представление выброшенного объекта

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — Клонирует ошибку

### Описание

private function Error::__clone(): void

Объект класса Error нельзя клонировать, так что эта функция вызовет фатальную ошибку.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Объект класса Error нельзя клонировать.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Метод Error::__clone() больше не является окончательным (final).

## Содержание

- Error::__construct — Создаёт объект класса Error
- Error::getMessage — Получает сообщение об ошибке
- Error::getPrevious — Возвращает предыдущий Throwable
- Error::getCode — Возвращает код ошибки
- Error::getFile — Получает файл, в котором произошла ошибка
- Error::getLine — Получает номер строки, в которой произошла ошибка
- Error::getTrace — Получает трассировку стека
- Error::getTraceAsString — Получает трассировку стека в виде строки
- Error::__toString — Строковое представление ошибки
- Error::__clone — Клонирует ошибку

# Ошибка ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## Введение

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

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

## Обзор класса

class ArgumentCountError extends TypeError {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка ArithmeticError

(PHP 7, PHP 8)

## Введение

Ошибка ArithmeticError возникает при некорректных математических операциях или недопустимом результате. К таким ошибкам относятся попытки выполнить сдвиг битов на отрицательную величину или вызов функции intdiv(), при котором частное выходит за пределы возможных границ типа int.

## Обзор класса

class ArithmeticError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка AssertionError

(PHP 7, PHP 8)

## Введение

Ошибка AssertionError возникает, когда утверждение, которое проверяют функцией assert(), не проходит проверку.

## Обзор класса

class AssertionError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка DivisionByZeroError

(PHP 7, PHP 8)

## Введение

Ошибка DivisionByZeroError возникает при делении на ноль.

## Обзор класса

class DivisionByZeroError extends ArithmeticError {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка CompileError

(PHP 7 > 7.3.0, PHP 8)

## Введение

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

## Обзор класса

class CompileError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка ParseError

(PHP 7, PHP 8)

## Введение

Ошибка ParseError возникает, когда невозможно разобрать PHP-код, например при вызове функции eval().

> Замечание: С PHP 7.3.0 класс ParseError стал наследником класса CompileError. Раньше класс расширял класс Error.

## Обзор класса

class ParseError extends CompileError {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка TypeError

(PHP 7, PHP 8)

## Введение

Ошибка TypeError возникает, если:

- Значение, которое устанавливают для свойства класса, не соответствует объявленному типу свойства.
- Тип аргумента, который передали в функцию, не соответствует типу, который для этого аргумента объявили в функции.
- Тип значения, которое вернула функция, не соответствует типу возврата, который объявили в функции.

## Обзор класса

class TypeError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Список изменений

Версия | Описание
--- | ---
7.1.0 | Ошибка TypeError больше не возникает в строгом режиме при передаче во встроенную PHP-функцию неправильного количества аргументов. Вместо этого выбрасывается более конкретная ошибка ArgumentCountError, которая расширяет ошибку TypeError.

# Ошибка ValueError

(PHP 8)

## Введение

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

## Обзор класса

class ValueError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка UnhandledMatchError

(PHP 8)

## Введение

Ошибка UnhandledMatchError возникает, если значение, которое поступило в выражение match, не обрабатывается ни одной ветвью выражения match.

## Обзор класса

class UnhandledMatchError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Ошибка FiberError

(PHP 8 >= 8.1.0)

## Введение

Ошибка FiberError возникает при недопустимых операциях на объекте класса Fiber.

## Обзор класса

final class FiberError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
/* Наследуемые методы */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Исключение RequestParseBodyException

(PHP 8 >= 8.4.0)

## Введение

Исключение RequestParseBodyException выбрасывается в функции request_parse_body(), когда тело запроса недопустимо для заголовка `Content-Type`.

## Обзор класса

class RequestParseBodyException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Встроенные интерфейсы и классы

## Содержание

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

Смотрите также Интерфейсы SPL и Предопределённые классы.

# Интерфейс Traversable

(PHP 5, PHP 7, PHP 8)

## Введение

Интерфейс, который определяет, доступен ли обход класса конструкцией `foreach`.

Нельзя реализовать сам абстрактный базовый интерфейс. Вместо этого реализуют либо интерфейс IteratorAggregate, либо интерфейс Iterator.

## Обзор интерфейса

interface Traversable {
}

У интерфейса нет методов. Единственная цель интерфейса — быть базовым интерфейсом для классов, которым доступен обход.

## Список изменений

Версия | Описание
--- | ---
7.4.0 | Реализовывать интерфейс Traversable теперь разрешается абстрактным классам. Расширяющие классы должны реализовывать интерфейс Iterator или IteratorAggregate.

## Примечания

> Замечание:

> Внутренние, или встроенные, классы, которые реализуют этот интерфейс, разрешается обходить конструкцией `foreach`, и такие классы не обязаны реализовывать интерфейс IteratorAggregate или Iterator.

> Замечание:

> До PHP 7.4.0 этот внутренний интерфейс движка нельзя было реализовать в PHP-скриптах. Вместо этого требовалось реализовывать либо IteratorAggregate, либо Iterator.

# Интерфейс Iterator

(PHP 5, PHP 7, PHP 8)

## Введение

Интерфейс для внешних итераторов или объектов, которые умеют итерироваться сами, внутренне.

## Обзор интерфейса

interface Iterator extends Traversable {
/* Методы */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## Предопределённые итераторы

PHP уже предоставляет некоторые итераторы для многих ежедневных задач. Смотрите список итераторов SPL для более детальной информации.

## Примеры

Пример #1 Основы использования

Этот пример демонстрирует в каком порядке вызываются методы, когда используется с итератором оператор `foreach`.

    <?php
    class myIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "firstelement",
            "secondelement",
            "lastelement",
        );

        public function __construct() {
            $this->position = 0;
        }

        public function rewind(): void {
            var_dump(__METHOD__);
            $this->position = 0;
        }

        #[\ReturnTypeWillChange]
        public function current() {
            var_dump(__METHOD__);
            return $this->array[$this->position];
        }

        #[\ReturnTypeWillChange]
        public function key() {
            var_dump(__METHOD__);
            return $this->position;
        }

        public function next(): void {
            var_dump(__METHOD__);
            ++$this->position;
        }

        public function valid(): bool {
            var_dump(__METHOD__);
            return isset($this->array[$this->position]);
        }
    }

    $it = new myIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    string(18) "myIterator::rewind"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(0)
    string(12) "firstelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(1)
    string(13) "secondelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"
    string(19) "myIterator::current"
    string(15) "myIterator::key"
    int(2)
    string(11) "lastelement"

    string(16) "myIterator::next"
    string(17) "myIterator::valid"

## Смотрите также

Смотрите также раздел Итераторы объектов.

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — Возврат текущего элемента

### Описание

public function Iterator::current(): mixed

Возвращает текущий элемент.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Может возвращать любой тип.

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — Возвращает ключ текущего элемента

### Описание

public function Iterator::key(): mixed

Возвращает ключ текущего элемента.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает скалярное значение (scalar) в случае успешного выполнения или `null`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_NOTICE`, если возникла ошибка.

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — Переходит к следующему элементу

### Описание

public function Iterator::next(): void

Передвигает текущую позицию к следующему элементу.

> Замечание:

> Метод вызывается после каждой итерации `foreach`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

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

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — Возвращает итератор на первый элемент

### Описание

public function Iterator::rewind(): void

Возвращает итератор обратно на первый элемент.

> Замечание:

> В начале цикла `foreach` этот метод вызывается первым. Метод не будет вызван после цикла `foreach`.

> Поскольку `foreach` всегда вызывает метод rewind() перед началом итерации, ручное перемещение позиции итератора (например, с помощью метода SplFileObject::seek()) будет сброшено. Для выполнения итерации без перемотки итератора, оберните его в NoRewindIterator.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

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

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — Проверяет корректность текущей позиции

### Описание

public function Iterator::valid(): bool

Метод вызывается после функций Iterator::rewind() и Iterator::next() чтобы проверить, допустима ли текущая позиция.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращаемое значение будет приведено к логическому типу (bool) и затем использовано. Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

## Содержание

- Iterator::current — Возврат текущего элемента
- Iterator::key — Возвращает ключ текущего элемента
- Iterator::next — Переходит к следующему элементу
- Iterator::rewind — Возвращает итератор на первый элемент
- Iterator::valid — Проверяет корректность текущей позиции

# Интерфейс IteratorAggregate

(PHP 5, PHP 7, PHP 8)

## Введение

Интерфейс для создания внешнего итератора.

## Обзор интерфейса

interface IteratorAggregate extends Traversable {
/* Методы */
public function getIterator(): Traversable
}

## Примеры

Пример #1 Базовый пример реализации интерфейса

    <?php

    class myData implements IteratorAggregate
    {
        public function getIterator(): Traversable
        {
            return new ArrayIterator([
                "key one" => "item one",
                "key two" => "item two",
                "key three" => "item three"
            ]);
        }
    }

    $obj = new myData();

    foreach ($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

Вывод приведённого примера будет похож на:

    string(7) "key one"
    string(8) "item one"

    string(7) "key two"
    string(8) "item two"

    string(9) "key three"
    string(10) "item three"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — Получает внешний итератор

### Описание

public function IteratorAggregate::getIterator(): Traversable

Метод возвращает внешний итератор, класс которого реализует интерфейс подтипа Traversable.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает экземпляр объекта, класс которого реализует интерфейс Iterator или другой интерфейс подтипа Traversable.

### Ошибки

Метод выбрасывает исключение Exception, если возникла ошибка.

## Содержание

- IteratorAggregate::getIterator — Получает внешний итератор

# Класс InternalIterator

(PHP 8)

## Введение

Класс для упрощения реализации интерфейса IteratorAggregate для внутренних классов.

## Обзор класса

final class InternalIterator implements Iterator {
/* Методы */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — Закрытый конструктор для запрета прямой инициализации

### Описание

private function InternalIterator::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

# InternalIterator::current

(PHP 8)

InternalIterator::current — Возвращает текущий элемент

### Описание

public function InternalIterator::current(): mixed

Возвращает текущий элемент.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает текущий элемент.

# InternalIterator::key

(PHP 8)

InternalIterator::key — Возвращает ключ текущего элемента

### Описание

public function InternalIterator::key(): mixed

Возвращает ключ текущего элемента.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ключ текущего элемента.

# InternalIterator::next

(PHP 8)

InternalIterator::next — Переходит к следующему элементу

### Описание

public function InternalIterator::next(): void

Перемещает текущую позицию к следующему элементу.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — Перематывает итератор к первому элементу

### Описание

public function InternalIterator::rewind(): void

Возвращается к первому элементу итератора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — Проверяет, действительна ли текущая позиция

### Описание

public function InternalIterator::valid(): bool

Проверяет, действительна ли текущая позиция.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает, действительна ли текущая позиция.

## Содержание

- InternalIterator::__construct — Закрытый конструктор для запрета прямой инициализации
- InternalIterator::current — Возвращает текущий элемент
- InternalIterator::key — Возвращает ключ текущего элемента
- InternalIterator::next — Переходит к следующему элементу
- InternalIterator::rewind — Перематывает итератор к первому элементу
- InternalIterator::valid — Проверяет, действительна ли текущая позиция

# Throwable

(PHP 7, PHP 8)

## Введение

Throwable является родительским интерфейсом для всех объектов, выбрасывающихся с помощью выражения `throw`, включая классы Error и Exception.

> Замечание:

> Классы PHP не могут напрямую реализовать интерфейс Throwable. Вместо этого они могут наследовать подкласс Exception.

## Обзор интерфейса

interface Throwable extends Stringable {
/* Методы */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* Наследуемые методы */
public function Stringable::__toString(): string
}

## Список изменений

Версия | Описание
--- | ---
8.0.0 | Класс Throwable теперь реализует интерфейс Stringable.

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — Получает сообщение ошибки

### Описание

public function Throwable::getMessage(): string

Возвращает сообщение ошибки данного выброшенного объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое сообщение.

### Смотрите также

- Exception::getMessage() - Получает сообщение исключения

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — Возвращает код исключения

### Описание

public function Throwable::getCode(): int

Возвращает код ошибки выброшенного объекта, к которому применена функция.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код исключения в виде целого числа (int) в Exception, но возможен и другой возвращаемый тип в классах, наследующих Exception (например, в виде строки (string), если тип ошибки PDOException).

### Смотрите также

- Exception::getCode() - Получает код исключения

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — Возвращает файл, в котором выброшено исключение

### Описание

public function Throwable::getFile(): string

Возвращает имя файла, в котором данный объект был выброшен.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое значение имени файла.

### Смотрите также

- Exception::getFile() - Получает файл, в котором возникло исключение

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — Получает строку скрипта, в которой данный объект был выброшен

### Описание

public function Throwable::getLine(): int

Возвращает номер строки, в которой данный объект был выброшен.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целочисленное значение строки.

### Смотрите также

- Exception::getLine() - Получает строку, в которой возникло исключение

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — Возвращает трассировку стека

### Описание

public function Throwable::getTrace(): array

Возвращает трассировку стека в виде массива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает трассировку стека в виде массива в таком же формате, что и debug_backtrace().

### Смотрите также

- Exception::getTrace() - Получает трассировку стека

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — Получает результаты трассировки стека в виде строки

### Описание

public function Throwable::getTraceAsString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает результаты трассировки стека в виде строки.

### Смотрите также

- Exception::getTraceAsString() - Получает трассировку стека в виде строки

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — Возвращает предыдущий Throwable

### Описание

public function Throwable::getPrevious(): ?Throwable

Возвращает любой предыдущий Throwable (для примера, переданное третьим параметром в Exception::__construct()).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает предыдущий Throwable, если он доступен, или `null` в противном случае.

### Смотрите также

- Exception::getPrevious() - Возвращает предыдущий объект, реализующий Throwable

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — Получает строковое представление выброшенного объекта

### Описание

public function Throwable::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое (string) представление выброшенного объекта.

### Смотрите также

- Exception::__toString() - Строковое представление исключения

## Содержание

- Throwable::getMessage — Получает сообщение ошибки
- Throwable::getCode — Возвращает код исключения
- Throwable::getFile — Возвращает файл, в котором выброшено исключение
- Throwable::getLine — Получает строку скрипта, в которой данный объект был выброшен
- Throwable::getTrace — Возвращает трассировку стека
- Throwable::getTraceAsString — Получает результаты трассировки стека в виде строки
- Throwable::getPrevious — Возвращает предыдущий Throwable
- Throwable::__toString — Получает строковое представление выброшенного объекта

# Интерфейс Countable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Введение

На объектах, классы которых реализуют интерфейс Countable, доступен вызов функции count().

## Обзор интерфейса

interface Countable {
/* Методы */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — Подсчитывает количество элементов в объекте

### Описание

public function Countable::count(): int

Метод выполняется, когда в параметр `value` функции count() передают объект, класс которого реализует интерфейс Countable.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает пользовательское количество элементов объекта в виде значения с типом int.

### Примеры

Пример #1 Пример подсчёта элементов объекта методом Countable::count()

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter();

    for ($i = 0; $i < 10; ++$i) {
        echo "Вот сколько раз меня посчитали функций count(): ", count($counter), "\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    I have been count()ed 1 times
    I have been count()ed 2 times
    I have been count()ed 3 times
    I have been count()ed 4 times
    I have been count()ed 5 times
    I have been count()ed 6 times
    I have been count()ed 7 times
    I have been count()ed 8 times
    I have been count()ed 9 times
    I have been count()ed 10 times

## Содержание

- Countable::count — Подсчитывает количество элементов в объекте

# Интерфейс ArrayAccess

(PHP 5, PHP 7, PHP 8)

## Введение

Интерфейс разрешает обращаться к объектам как к массивам.

## Обзор интерфейса

interface ArrayAccess {
/* Методы */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function offsetUnset(mixed `$offset`): void
}

## Примеры

Пример #1 Основы использования

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        ];

        public function offsetSet($offset, $value): void {
            if (is_null($offset)) {
                $this->container[] = $value;
            } else {
                $this->container[$offset] = $value;
            }
        }

        public function offsetExists($offset): bool {
            return isset($this->container[$offset]);
        }

        public function offsetUnset($offset): void {
            unset($this->container[$offset]);
        }

        public function offsetGet($offset): mixed {
            return isset($this->container[$offset]) ? $this->container[$offset] : null;
        }
    }

    $obj = new Obj;

    var_dump(isset($obj["two"]));
    var_dump($obj["two"]);
    unset($obj["two"]);
    var_dump(isset($obj["two"]));
    $obj["two"] = "A value";
    var_dump($obj["two"]);
    $obj[] = 'Append 1';
    $obj[] = 'Append 2';
    $obj[] = 'Append 3';
    print_r($obj);

Вывод приведённого примера будет похож на:

    bool(true)
    int(2)
    bool(false)
    string(7) "A value"
    Obj Object
    (
        [container] => Array
            (
                [one] => 1
                [three] => 3
                [two] => A value
                [0] => Append 1
                [1] => Append 2
                [2] => Append 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — Определяет, существует ли заданное смещение (ключ)

### Описание

public function ArrayAccess::offsetExists(mixed `$offset`): bool

Определяет, существует или нет данное смещение (ключ).

Данный метод выполняется при использовании isset() или empty() на объектах, реализующих интерфейс ArrayAccess.

> Замечание:

> При использовании функции empty(), вызывается метод ArrayAccess::offsetGet() и проверка на пустоту произойдёт, только если метод ArrayAccess::offsetExists() вернёт `true`.

### Список параметров

`offset`

  Смещение (ключ) для проверки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

> Замечание:

> Возвращаемое значение будет приведено к логическому типу (bool), если возвращаемое значение не является логическим.

### Примеры

Пример #1 Пример использования метода ArrayAccess::offsetExists()

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $value): void {
            var_dump(__METHOD__);
        }

        public function offsetExists($var): bool {
            var_dump(__METHOD__);
            if ($var == "foobar") {
                return true;
            }
            return false;
        }

        public function offsetUnset($var): void {
            var_dump(__METHOD__);
        }

        #[\ReturnTypeWillChange]
        public function offsetGet($var) {
            var_dump(__METHOD__);
            return "value";
        }
    }

    $obj = new obj;

    echo "Выполняется obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nВыполняется obj::offsetExists() и obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nВыполняется obj::offsetExists(), но *не* obj:offsetGet(), поскольку нечего возвращать\n";
    var_dump(empty($obj["foobaz"]));
    ?>

Вывод приведённого примера будет похож на:

    Выполняется obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Выполняется obj::offsetExists() и obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Выполняется obj::offsetExists(), но *не* obj:offsetGet(), поскольку нечего возвращать
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — Возвращает заданное смещение (ключ)

### Описание

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

Возвращает заданное смещение (ключ).

Данный метод выполняется, когда проверяется смещение (ключ) на пустоту с помощью функции empty().

### Список параметров

`offset`

  Смещение (ключ) для возврата.

### Возвращаемые значения

Может возвращать значение любого типа.

### Примечания

> Замечание:

> Возможна реализация данного метода с возвращением по ссылке. Это делает возможным косвенную модификацию для величин массива перегруженного объекта ArrayAccess.

> Явная модификация - это такая модификация, при которой полностью заменяется значение величины массива, как в случае `$obj[6] = 7`. С другой стороны, при косвенной модификации заменяется только часть величины, или происходит попытка присвоения величины по ссылке другой переменной, как в случае `$obj[6][7] = 7` или `$var =& $obj[6]`. Увеличение с использованием оператора `++` и уменьшение с использованием оператора `--` также реализуются с помощью способа, который требует косвенную модификацию.

> В то время как, явная модификация запускает вызов метода ArrayAccess::offsetSet(), косвенная модификация запускает вызов метода ArrayAccess::offsetGet(). В таком случае, реализация метода ArrayAccess::offsetGet() должна быть в состоянии возвращать результат по ссылке, в противном случае будет вызвано сообщение об ошибке уровня `E_NOTICE`.

### Смотрите также

- ArrayAccess::offsetExists() - Определяет, существует ли заданное смещение (ключ)

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — Присваивает значение заданному смещению

### Описание

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

Присваивает значение указанному смещению (ключу).

### Список параметров

`offset`

  Смещение (ключ), которому будет присваиваться значение.

`value`

  Значение для присвоения.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примечания

> Замечание:

> Параметр `offset` будет установлен в `null`, если другое значение недоступно, как показано в следующем примере.

>     <?php
>     $arrayaccess[] = "первое значение";
>     $arrayaccess[] = "второе значение";
>     print_r($arrayaccess);
>     ?>

> Результат выполнения приведённого примера:

>     Array
>     (
>         [0] => first value
>         [1] => second value
>     )

> Замечание:

> Данный метод не вызывается при присвоениях по ссылке и других косвенных изменений величин массива перегруженного объекта ArrayAccess (косвенные в том смысле, что они произведены не прямой заменой величины, а путём изменения часть элемента или свойства элемента массива, или присвоением элемента массива по ссылке другой переменой). Вместо этого, вызывается метод ArrayAccess::offsetGet(). Данная операция будет успешна только в том случае, если метод возвращает по ссылке.

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — Удаляет смещение

### Описание

public function ArrayAccess::offsetUnset(mixed `$offset`): void

Удаляет смещение (ключ).

> Замечание:

> Этот метод не будет вызван при приведении типа к (unset)

### Список параметров

`offset`

  Смещение (ключ) для удаления.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- ArrayAccess::offsetExists — Определяет, существует ли заданное смещение (ключ)
- ArrayAccess::offsetGet — Возвращает заданное смещение (ключ)
- ArrayAccess::offsetSet — Присваивает значение заданному смещению
- ArrayAccess::offsetUnset — Удаляет смещение

# Интерфейс Serializable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Введение

Интерфейс ввели для пользовательской сериализации.

Классы, которые реализуют этот интерфейс, больше не поддерживают магические методы __sleep() и __wakeup(). При каждой сериализации экземпляра класса вызывается интерфейсный метод serialize. Этот метод не вызывает метод __destruct() и не выполняет побочных действий, кроме тех, которые запрограммировали внутри метода. Механизм сериализации знает класс, представление которого десериализует, и вместо вызова метода __construct() как конструктор вызывается интерфейсный метод unserialize(), который соответствует классу. Стандартный конструктор вызывают в методе десериализации, если требуется.

Внимание

Начиная с PHP 8.1.0 класс, который реализует интерфейс Serializable без реализации методов __serialize() и __unserialize(), выдаст предупреждение об устаревании.

## Обзор интерфейса

interface Serializable {
/* Методы */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## Примеры

Пример #1 Базовый пример реализации интерфейса

    <?php

    class obj implements Serializable
    {
        private $data;

        public function __construct()
        {
            $this->data = "Мои закрытые данные";
        }

        public function serialize()
        {
            return serialize($this->data);
        }

        public function unserialize($data)
        {
            $this->data = unserialize($data);
        }

        public function getData()
        {
            return $this->data;
        }
    }

    $obj = new obj();
    $ser = serialize($obj);

    var_dump($ser);

    $newobj = unserialize($ser);

    var_dump($newobj->getData());

    ?>

Вывод приведённого примера будет похож на:

    Deprecated: obj implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in script on line 2
    string(59) "C:3:"obj":44:{s:36:"Мои закрытые данные";}"
    string(36) "Мои закрытые данные"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — Представляет объект в виде строки

### Описание

public function Serializable::serialize(): ?string

Возвращает строковое представление объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление объекта или `null`.

### Ошибки

Выбрасывает исключение Exception при возвращении типов, отличных от строки или `null`.

### Смотрите также

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — Создаёт объект

### Описание

public function Serializable::unserialize(string `$data`): void

Вызывается во время десериализации объекта.

> Замечание:

> Метод действует как конструктор объекта. Метод __construct() не вызывается после этого метода.

### Список параметров

`data`

  Строковое представление объекта.

### Возвращаемые значения

Возвращаемое значение метода игнорируется.

### Смотрите также

- __wakeup()
- __unserialize()

## Содержание

- Serializable::serialize — Представляет объект в виде строки
- Serializable::unserialize — Создаёт объект

# Класс Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Класс представляет анонимные функции.

Анонимные функции становятся объектами Closure. Класс содержит методы для управления экземпляром анонимной функции.

Кроме списка методов на этой странице, класс замыкания также содержит магический метод `__invoke`, который определили не для вызова анонимной функции — метод не срабатывает при вызове объекта замыкания, — а только для согласованности с другими классами, в которых реализовали магический вызов объекта как функции.

## Обзор класса

final class Closure {
/* Методы */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Вывод метода Closure::__debugInfo() теперь дополнительно включает следующие свойства объекта замыкания: "name", "line" и "file".

## Примечания

> Замечание: Объекты Closure невозможно сериализовать, поскольку замыкания связывают переменные в конкретном контексте выполнения, доступность которых невозможно гарантировать в точке восстановления, например при десериализации замыкания в другой области действия. Попытка сериализовать замыкание выбросит исключение Exception.

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — Конструктор, запрещающий создание экземпляра

### Описание

private function Closure::__construct()

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

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- Анонимные функции

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса статически

### Описание

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Метод представляет статическую версию метода Closure::bindTo(), описание которого даёт дополнительную информацию.

### Список параметров

`closure`

  Анонимная функция, которую метод свяжет с объектом.

`newThis`

  Объект, к которому требуется привязать анонимную функцию, или `null`, если привязка не требуется.

`newScope`

  Название класса, к области видимости которого требуется привязать замыкание, или ключевое слово 'static' для сохранения замыканием текущей области видимости. При передаче объекта контекст класса определяется типом объекта. Параметр определяет видимость защищённых и закрытых членов объекта, к которому привязывается замыкание. Нельзя передавать в параметр название или экземпляр объекта внутреннего PHP-класса.

### Возвращаемые значения

Метод возвращает новый объект класса Closure или `null`, если возникла ошибка.

### Примеры

Пример #1 Пример привязки замыкания методом Closure::bind()

    <?php

    class A
    {
        private static $sfoo = 1;
        private $ifoo = 2;
    }

    $cl1 = static function () {
        return A::$sfoo;
    };

    $cl2 = function () {
        return $this->ifoo;
    };

    $bcl1 = Closure::bind($cl1, null, 'A');
    $bcl2 = Closure::bind($cl2, new A(), 'A');

    echo $bcl1(), "\n";
    echo $bcl2(), "\n";

    ?>

Вывод приведённого примера будет похож на:

    1
    2

### Смотрите также

- Анонимные функции
- Closure::bindTo() - Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса

### Описание

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

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

«Объект привязки» определяет значение переменной `$this`, доступное в теле функции, а «область видимости класса» представляет класс, который определяет, какие защищённые и закрытые члены класса доступны анонимной функции. Анонимная функция увидит те же члены класса, которые видела бы, если бы принадлежала к методам класса, который установили как значение параметра `newScope`.

Статические замыкания невозможно привязать к объекту из-за недоступности контекста объекта в статических замыканиях. Поэтому в параметр `newThis` передают значение `null` при вызове метода на статических замыканиях. Но метод всё-таки умеет изменять область видимости класса для статического замыкания.

Метод гарантирует, что нестатическое замыкание, которое привязали к экземпляру класса, получит доступ к контексту объекта, а без привязки сохранит текущую область видимости. Поэтому нестатические замыкания, для которых указали область видимости, но вместо объекта в первом аргументе передали `null`, становятся статическими, а для которых не указали область видимости, но установили объект привязки, получат доступ только к открытым членам объекта.

> Замечание:

> Вместо этого метода пользуются клонированием, когда требуется только дублировать анонимную функцию.

### Список параметров

`newThis`

  Объект, к которому требуется привязать анонимную функцию, или `null`, если привязка не требуется.

`newScope`

  Название класса, к области видимости которого требуется привязать замыкание, или ключевое слово 'static' для сохранения замыканием текущей области видимости. При передаче объекта контекст класса определяется типом объекта. Параметр определяет видимость защищённых и закрытых членов объекта, к которому привязывается замыкание. Нельзя передавать в параметр название или экземпляр объекта внутреннего PHP-класса.

### Возвращаемые значения

Метод возвращает новый объект класса Closure или `null`, если возникла ошибка.

### Примеры

Пример #1 Пример привязки замыкания методом Closure::bindTo()

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            // Метод возвращает замыкание, привязанное к текущим объекту и области видимости
            return function () {
                return $this->val;
            };
        }
    }

    $ob1 = new A(1);
    $ob2 = new A(2);

    $cl = $ob1->getClosure();
    echo $cl(), "\n";

    $cl = $cl->bindTo($ob2);
    echo $cl(), "\n";

    ?>

Вывод приведённого примера будет похож на:

    1
    2

### Смотрите также

- Анонимные функции
- Closure::bind() - Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса статически

# Closure::call

(PHP 7, PHP 8)

Closure::call — Связывает и запускает замыкание

### Описание

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

Временно связывает замыкание с `newThis` и вызывает его с заданными параметрами.

### Список параметров

`newThis`

  Объект (object) для привязки к замыканию на время его вызова.

`args`

  Ноль или больше параметров, которые передаются замыканию.

### Возвращаемые значения

Возвращает возвращаемое значение замыкания

### Примеры

Пример #1 Пример Closure::call()

    <?php
    class Value {
        protected $value;

        public function __construct($value) {
            $this->value = $value;
        }

        public function getValue() {
            return $this->value;
        }
    }

    $three = new Value(3);
    $four = new Value(4);

    $closure = function ($delta) { var_dump($this->getValue() + $delta); };
    $closure->call($three, 4);
    $closure->call($four, 4);
    ?>

Результат выполнения приведённого примера:

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — Конвертирует callable в замыкание

### Описание

public static function Closure::fromCallable(callable `$callback`): Closure

Создаёт и возвращает новую анонимную функцию из заданного `callback`, используя текущую область видимости. Этот метод проверяет, что `callback` является типом callable в текущей области видимости и выбрасывает исключение TypeError, если это не так.

> Замечание:

> Начиная с PHP 8.1.0, у Callback-функций как объектов первого класса та же семантика, что и у этого метода.

### Список параметров

`callback`

  Объект типа callable.

### Возвращаемые значения

Возвращает новый объект класса Closure или выбрасывает исключение TypeError, если `callback` не является объектом типа callable в текущей области видимости.

### Смотрите также

- Анонимные функции
- Callback-функции как объекты первого класса

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — Возвращает текущее выполняемое замыкание

### Описание

public static function Closure::getCurrent(): Closure

Метод возвращает текущее выполняемое замыкание. Метод в первую очередь полезен для рекурсивных замыканий без обязательного захвата ссылки на переменную замыкания через ключевое слово `use`.

Метод доступен только внутри замыкания; вызов извне контекста замыкания сгенерирует ошибку: `Error: Current function is not a closure.`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает текущий объект Closure.

### Ошибки

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

### Примеры

Пример #1 Пример получения замыкания методом Closure::getCurrent()

Следующая функция вычисляет n-е число Фибоначчи через рекурсивные вызовы замыкания, которое возвращается методом Closure::getCurrent():

    <?php

    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // Выведет: 55

Пример #2 Сравнение с традиционным подходом

До PHP 8.5 для реализации рекурсивных замыканий требовалось захватить ссылку на переменную замыкания через ключевое слово `use`:

    <?php

    // Традиционный подход, который по-прежнему работает в PHP 8.5
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) {
            return 0;
        }

        if ($n === 1) {
            return 1;
        }

        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // Выведет: 55

Метод Closure::getCurrent() не требует объявления переменной со ссылкой в предложении `use`, делает код чище и снижает риск ошибок.

## Содержание

- Closure::__construct — Конструктор, запрещающий создание экземпляра
- Closure::bind — Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса статически
- Closure::bindTo — Дублирует замыкание и привязывает копию замыкания к объекту и области видимости класса
- Closure::call — Связывает и запускает замыкание
- Closure::fromCallable — Конвертирует callable в замыкание
- Closure::getCurrent — Возвращает текущее выполняемое замыкание

# Класс stdClass

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

## Введение

Пустой класс общего назначения с динамическими свойствами.

Объекты стандартного класса создают оператором new или путём приведения к объекту значения другого типа. Ряд PHP-функций тоже создаёт экземпляры этого класса, например, json_decode(), mysqli_fetch_object() или PDOStatement::fetchObject().

Класс поддерживает динамические свойства и не требует атрибута `#[\AllowDynamicProperties]`, хотя не реализует магических методов __get() и __set().

Это не базовый класс, поскольку PHP не включает понятия универсального базового класса. При этом возможно создать пользовательский класс, который расширит класс stdClass и поэтому унаследует поддержку динамических свойств.

## Обзор класса

#[\AllowDynamicProperties]
class stdClass {
}

Класс не содержит методов или свойств по умолчанию.

## Примеры

Пример #1 Приведение к объекту значения другого типа

    <?php

    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

Результат выполнения приведённого примера:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Пример #2 Возврат объекта функцией json_decode()

    <?php

    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

Результат выполнения приведённого примера:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Пример #3 Объявление динамических свойств

    <?php

    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

Результат выполнения приведённого примера:

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# Класс Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Объекты класса Generator возвращаются генераторами.

Предостережение

Объекты Generator нельзя создать через ключевое слово new.

## Обзор класса

final class Generator implements Iterator {
/* Методы */
public function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## Смотрите также

Смотрите также раздел «Итераторы объектов».

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — Получает текущее значение генератора

### Описание

public function Generator::current(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает текущее значение.

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — Получает значение, которое возвращает генератор

### Описание

public function Generator::getReturn(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает значение, которое возвращает генератор после завершения выполнения.

### Примеры

Пример #1 Пример использования метода Generator::getReturn()

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — Получает ключ сгенерированного элемента

### Описание

public function Generator::key(): mixed

Метод получает ключ значения, которое отдал генератор.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает ключ элемента, который отдал генератор.

### Примеры

Пример #1 Пример использования метода Generator::key()

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

    ?>

Результат выполнения приведённого примера:

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — Возобновляет работу генератора

### Описание

public function Generator::next(): void

Вызов метода Generator::next() даёт тот же эффект, что и вызов метода Generator::send() со значением `null` в качестве аргумента.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Выполняет генератор до первого выражения yield

### Описание

public function Generator::rewind(): void

Выполняет генератор до первого выражения `yield` включительно. Если генератор уже находится в первом `yield`, никаких действий не будет выполнено. Если генератор когда-либо продвигался дальше выражения `yield`, метод выбросит ошибку Exception.

> Замечание:

> Это первый метод, который генератор автоматически вызывает при запуске цикла `foreach`. Метод не выполняется после цикла `foreach`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример перемотки генератора методом Generator::rewind()

    <?php

    function generator(): Generator
    {
        echo "Я генератор!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // Инициализируем генератор
    $generator = generator();

    // Перематываем генератор к началу первого выражения yield,
    // если генератор ещё не там
    $generator->rewind(); // Я генератор!

    // В этом месте ничего не произойдёт; генератор уже перемотался к первому yield
    $generator->rewind(); // Ничего не выводит, возвращает NULL

    // Цикл возвращает генератор к первому выражению yield,
    // если генератор ещё не там, и начинает итерацию по генератору
    foreach ($generator as $value) {
        // После выдачи первого значения генератор остается
        // на первом выражении yield, пока не возобновит выполнение и не продвинется к следующем yield
        echo $value, PHP_EOL; // 1

        break;
    }

    // Снова возобновляем работу генератора и «отматываем» к первому выражению yield.
    // Слово «отматываем» в кавычках, потому что генератор уже на первом yield.
    // Ошибка не возникает, поскольку генератор ещё не продвинулся дальше первого yield
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // Ошибка тоже не возникает, генератор всё ещё на первом выражении
    $generator->rewind();

    // Этот вызов продвигает генератор ко второму выражению yield
    $generator->next();

    try {
        // Попытка перемотать генератор выбросит исключение Exception,
        // потому что генератор уже перешёл ко второму выражению yield
        $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

Результат выполнения приведённого примера:

    Я генератор!
    1
    1
    Cannot rewind a generator that was already run

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — Отправляет значение в генератор

### Описание

public function Generator::send(mixed `$value`): mixed

Метод отправляет значение в генератор как результат текущего выражения `yield` и возобновляет выполнение генератора.

Перед отправкой значения генератор сначала перейдёт к первому выражению `yield`, если при вызове метода генератор ещё не дошёл до первого выражения `yield`. Поэтому перед вызовом метода не требуется «подготавливать» работу PHP-генераторов вызовом метода Generator::next(), как это делается в языке Python.

### Список параметров

`value`

  Значение для отправки в генератор, которое вернёт выражение `yield` в точке, до которой дошёл генератор.

### Возвращаемые значения

Метод возвращает значение, которое выдал генератор.

### Примеры

Пример #1 Пример внедрения значений в генератор путём вызова метода Generator::send()

    <?php

    function printer()
    {
        echo "Я — принтер!" . PHP_EOL;

        while (true) {
            $string = yield;
            echo $string . PHP_EOL;
        }
    }

    $printer = printer();

    $printer->send('Привет, мир!');
    $printer->send('Пока, мир!');

Результат выполнения приведённого примера:

    Я — принтер!
    Привет, мир!
    Пока, мир!

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — Бросает исключение в генератор

### Описание

public function Generator::throw(Throwable `$exception`): mixed

Метод бросает исключение в генератор и возобновляет выполнение генератора. Поведение будет таким же, как если бы текущее выражение `yield` заменили выражением `throw $exception`.

Если при вызове этого метода генератор уже закрыт, PHP выбросит исключение в контексте кода, который вызвал этот метод.

### Список параметров

`exception`

  Исключение, которое нужно бросить в генератор.

### Возвращаемые значения

Метод возвращает значение, которое отдал генератор.

### Примеры

Пример #1 Пример пробрасывания исключения в генератор

    <?php

    function gen()
    {
        echo "Foo\n";

        try {
            yield;
        } catch (Exception $e) {
            echo "Exception: {$e->getMessage()}\n";
        }

        echo "Bar\n";
    }

    $gen = gen();
    $gen->rewind();
    $gen->throw(new Exception('Test'));

    ?>

Результат выполнения приведённого примера:

    Foo
    Exception: Test
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — Проверяет, закрыт ли итератор

### Описание

public function Generator::valid(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `false`, если итератор закрыт, иначе возвращает `true`.

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — Играет роль callback-функции при сериализации генератора

### Описание

public function Generator::__wakeup(): void

Метод выбрасывает исключение, поскольку генераторы нельзя сериализовывать.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- Generator::current — Получает текущее значение генератора
- Generator::getReturn — Получает значение, которое возвращает генератор
- Generator::key — Получает ключ сгенерированного элемента
- Generator::next — Возобновляет работу генератора
- Generator::rewind — Выполняет генератор до первого выражения yield
- Generator::send — Отправляет значение в генератор
- Generator::throw — Бросает исключение в генератор
- Generator::valid — Проверяет, закрыт ли итератор
- Generator::__wakeup — Играет роль callback-функции при сериализации генератора

# Класс Fiber

(PHP 8 >= 8.1.0)

## Введение

Файберы — механизм управления функциями, который умеет прерывать выполнение функций с сохранением полного внутреннего стека вызовов. Файберы разрешается приостанавливать в произвольном месте внутреннего стека вызовов, при этом выполнение кода внутри файбера приостанавливается до тех пор, пока файбер не возобновит работу.

## Обзор класса

final class Fiber {
/* Методы */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## Смотрите также

Обзор файберов

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — Создаёт новый экземпляр класса Fiber

### Описание

public function Fiber::__construct(callable `$callback`)

### Список параметров

`callback`

  Значение с типом callable, которое файбер вызовет как функцию в начале выполнения стека вызовов. Файбер передаст в callback-функцию аргументы, которые указали при вызове метода Fiber::start().

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — Начинает выполнение файбера

### Описание

public function Fiber::start(mixed `...$args`): mixed

Метод запускает файбер и передаёт в файбер переменный список аргументов, который файбер передаёт в callback-функцию при вызове конструктора.

Вызов метода на файбере, который уже начал работу, выбрасывает ошибку FiberError.

### Список параметров

`args`

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

### Возвращаемые значения

Метод возвращает значение, которое передали в первом вызове метода Fiber::suspend(), или значение `null`, если файбер вернул результирующее значение. Исключение, которое файбер выбрасывает раньше очередной приостановки, выбрасывается в точке вызова этого метода.

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — Возобновляет выполнение файбера с передачей значения

### Описание

public function Fiber::resume(mixed `$value` = `null`): mixed

Метод возобновляет выполнение файбера и передаёт в файбер значение, которое вернётся в текущей точке прерывания файбера как результат вызова метода Fiber::suspend().

Вызов метода на неприостановленном файбере выбросит ошибку FiberError.

### Список параметров

`value`

  Значение, которое файбер получит при возобновлении выполнения и вернёт в текущей точке прерывания как результат вызова метода Fiber::suspend().

### Возвращаемые значения

Метод возвращает значение, которое передали в очередном вызове метода Fiber::suspend(), или значение `null`, если файбер вернул результирующее значение. Исключение, которое файбер выбрасывает раньше очередной приостановки, выбрасывается в точке вызова этого метода.

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — Возобновляет выполнение файбера с передачей исключения

### Описание

public function Fiber::throw(Throwable `$exception`): mixed

Метод возобновляет выполнение файбера и передаёт в файбер исключение, которое выбрасывается в текущей точке прерывания стека вызовов — месте последнего вызова метода Fiber::suspend().

Вызов метода на неприостановленном файбере выбросит ошибку FiberError.

### Список параметров

`exception`

  Исключение, которое требуется выбросить в текущей точке прерывания файбера — точке вызова метода Fiber::suspend().

### Возвращаемые значения

Метод возвращает значение, которое передали в очередном вызове метода Fiber::suspend(), или значение `null`, если файбер вернул результирующее значение. Исключение, которое файбер выбрасывает раньше очередной приостановки, выбрасывается в точке вызова этого метода.

### Примеры

    <?php

    $fiber = new Fiber(function () {
       try {
           // Приостановка выполнения файбера и объявление точки прерывания
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // Возобновляем выполнение файбера
    // с передачей исключения, которое выбросится в точке прерывания
    $fiber->throw(new Exception('Сообщение исключения, которое выбросилось в текущей точке прерывания'));

Вывод приведённого примера будет похож на:

    Сообщение исключения, которое выбросилось в текущей точке прерывания

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — Получает значение, которое вернул файбер

### Описание

public function Fiber::getReturn(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает значение, которое вернула callback-функция файбера, которую передали как значение с типом callable в метод Fiber::__construct(). Метод выбросит ошибку FiberError, если файбер не вернул значение. Файбер не возвращает значение, если ещё не начал или пока не завершил выполнение стека вызовов, или выбросил исключение.

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — Определяет, запущен ли файбер

### Описание

public function Fiber::isStarted(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` только после того, как файбер был запущен, в противном случае возвращает `false`.

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — Определяет, приостановлен ли файбер

### Описание

public function Fiber::isSuspended(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если файбер в данный момент приостановлен, в противном случае возвращает `false`.

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — Определяет, работает ли файбер

### Описание

public function Fiber::isRunning(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` только если файбер работает. Файбер считается работающим после вызова Fiber::start(), Fiber::resume() или Fiber::throw(), который ещё не был возвращён. Возвращает `false`, если файбер не работает.

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — Определяет, завершён ли файбер

### Описание

public function Fiber::isTerminated(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` только после того, как файбер завершился, либо путём возврата, либо выбросив исключение, в противном случае возвращает `false`.

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — Приостанавливает выполнение текущего файбера

### Описание

public static function Fiber::suspend(mixed `$value` = `null`): mixed

Приостанавливает выполнение текущего файбера. Значение, предоставленное этому методу, будет возвращено из вызова Fiber::start(), Fiber::resume() или Fiber::throw(), который переключил выполнение текущего файбера.

Когда выполнение файбера возобновляется, метод возвращает значение, предоставленное в Fiber::resume(). Если выполнение файбера возобновляется с использованием Fiber::throw, исключение, переданное этому методу, будет выброшено при вызове метода.

Если этот метод вызывается извне файбера, будет выброшена ошибка FiberError.

### Список параметров

`value`

  Значение, возвращаемое при вызове Fiber::start(), Fiber::resume() или Fiber::throw(), которые переключают выполнение текущего файбера.

### Возвращаемые значения

Значение, предоставленное Fiber::resume().

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — Получает текущий выполняющийся экземпляр Fiber

### Описание

public static function Fiber::getCurrent(): ?Fiber

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает выполняющийся в данный момент экземпляр Fiber или `null`, если метод вызывается извне файбера.

## Содержание

- Fiber::__construct — Создаёт новый экземпляр класса Fiber
- Fiber::start — Начинает выполнение файбера
- Fiber::resume — Возобновляет выполнение файбера с передачей значения
- Fiber::throw — Возобновляет выполнение файбера с передачей исключения
- Fiber::getReturn — Получает значение, которое вернул файбер
- Fiber::isStarted — Определяет, запущен ли файбер
- Fiber::isSuspended — Определяет, приостановлен ли файбер
- Fiber::isRunning — Определяет, работает ли файбер
- Fiber::isTerminated — Определяет, завершён ли файбер
- Fiber::suspend — Приостанавливает выполнение текущего файбера
- Fiber::getCurrent — Получает текущий выполняющийся экземпляр Fiber

# Класс WeakReference

(PHP 7 >= 7.4.0, PHP 8)

## Введение

Слабые ссылки разрешают программисту сохранять ссылку на объект только до тех пор, пока исходный объект не уничтожили. Слабые ссылки приносят пользу, когда требуется создать кешеподобную структуру данных. Метод WeakReference::get() вернёт `null`, если исходный объект уничтожили. Сборщик мусора уничтожит исходный объект, если счётчик ссылок на исходный объект сбросится до нуля; слабые ссылки не увеличивают счётчик ссылок `refcount` объекта, на который ссылаются.

Объект класса WeakReference нельзя сериализовать.

## Обзор класса

final class WeakReference {
/* Методы */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## Примеры поведения класса WeakReference

Пример #1 Пример базового поведения класса WeakReference

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#1 (0) {
    }
    NULL

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Вывод метода WeakReference::__debugInfo() теперь включает объект, на который ссылается или `NULL`, если ссылка больше не действительна.

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — Конструктор, который запрещает реализацию

### Описание

public function WeakReference::__construct()

Метод существует только для запрета создания экземпляров класса WeakReference. Слабые ссылки должны быть созданы с помощью фабричного метода WeakReference::create().

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- WeakReference::create() - Создаёт новую слабую ссылку

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — Создаёт новую слабую ссылку

### Описание

public static function WeakReference::create(object `$object`): WeakReference

Метод создаёт новый объект WeakReference, который будет хранить слабую ссылку на исходный объект.

### Список параметров

`object`

  Объект, на который требуется создать слабую ссылку.

### Возвращаемые значения

Метод возвращает новую слабую ссылку WeakReference или прежний экземпляр, если слабую ссылку WeakReference на тот же объект создали раньше.

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — Получает объект по слабой ссылке

### Описание

public function WeakReference::get(): ?object

Метод получает объект, слабую ссылку на который хранит экземпляр класса слабых ссылок. Метод возвращает `null`, если объект, на который указывает слабая ссылка, уже уничтожили.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект (object), на который указывает слабая ссылка, или `null`, если объект уничтожили.

## Содержание

- WeakReference::__construct — Конструктор, который запрещает реализацию
- WeakReference::create — Создаёт новую слабую ссылку
- WeakReference::get — Получает объект по слабой ссылке

# Класс WeakMap

(PHP 8)

## Введение

Класс WeakMap — карта, или словарь, который принимает объекты как ключи. Однако, PHP не учитывает объект в ключе экземпляра класса WeakMap при подсчёте ссылок на объект, в отличие от аналогичного в остальном класса SplObjectStorage. Поэтому как только единственной ссылкой на объект останется ключ экземпляра класса WeakMap, сборщик мусора соберёт и удалит объект из экземпляра WeakMap. Главное назначение класса — создавать кеши данных, которые получили из объекта и которым не требуется жить дольше, чем сам объект.

Класс WeakMap реализует интерфейсы ArrayAccess, Traversable (через интерфейс IteratorAggregate) и Countable, поэтому с объектом класса часто работают так же, как с ассоциативным массивом.

## Обзор класса

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* Методы */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function offsetUnset(object `$object`): void
}

## Примеры

Пример #1 Пример использования класса Weakmap

    <?php

    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Уничтожено!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Сброс...\n";
    unset($o);
    echo "Готово\n";
    var_dump(count($wm));

    ?>

Результат выполнения приведённого примера:

    int(1)
    Сброс...
    Уничтожено!
    Готово
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — Подсчитывает количество живых записей в коллекции (map)

### Описание

public function WeakMap::count(): int

Подсчитывает количество живых записей в коллекции (map).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество живых записей в коллекции (map).

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — Получает внешний итератор

### Описание

public function WeakMap::getIterator(): Iterator

Возвращает внешний итератор.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает экземпляр объекта, который реализует интерфейс Iterator или интерфейс Traversable.

### Ошибки

Метод выбрасывает Exception, если возникла ошибка.

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — Проверяет, есть ли в коллекции (map) определённый объект

### Описание

public function WeakMap::offsetExists(object `$object`): bool

Проверяет, есть ли ссылка на переданный объект в коллекции (map).

### Список параметров

`object`

  Объект для проверки.

### Возвращаемые значения

Возвращает `true`, если объект содержится в коллекции (map) или `false` в противном случае.

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — Возвращает значение, на которое указывает конкретный объект

### Описание

public function WeakMap::offsetGet(object `$object`): mixed

Метод возвращает значение, на которое указывает конкретный объект.

### Список параметров

`object`

  Объект, который карта сождержит как ключ.

### Возвращаемые значения

Метод возвращает значение, которое связано с объектом, который передали как аргумент.

### Ошибки

Метод выбрасывает исключение Error, если возникла ошибка.

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — Обновляет коллекцию (map) новой парой ключ-значение

### Описание

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

Обновляет коллекцию (map) новой парой ключ-значение. Если ключ уже существует в коллекции, старое значение заменяется новым.

### Список параметров

`object`

  Объект, служащий ключом пары ключ-значение.

`value`

  Произвольные данные, служащие значением пары ключ-значение.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — Удаляет запись из коллекции (map)

### Описание

public function WeakMap::offsetUnset(object `$object`): void

Удаляет запись из коллекции (map).

### Список параметров

`object`

  Объект, служащий ключом для записи, которую нужно удалить из коллекции.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- WeakMap::count — Подсчитывает количество живых записей в коллекции (map)
- WeakMap::getIterator — Получает внешний итератор
- WeakMap::offsetExists — Проверяет, есть ли в коллекции (map) определённый объект
- WeakMap::offsetGet — Возвращает значение, на которое указывает конкретный объект
- WeakMap::offsetSet — Обновляет коллекцию (map) новой парой ключ-значение
- WeakMap::offsetUnset — Удаляет запись из коллекции (map)

# Интерфейс Stringable

(PHP 8)

## Введение

Интерфейс Stringable обозначает класс, который реализует метод __toString(). В отличие от большинства интерфейсов, Stringable неявно присутствует в каждом классе, в котором определили магический метод __toString(), хотя интерфейс разрешается и требуется объявлять явно.

Основное значение интерфейса — разрешить функциям выполнять проверку типа на соответствие объединённым типам `string|Stringable`, чтобы принимать либо строковый примитив, либо объект, который можно преобразовать в строку.

## Обзор интерфейса

interface Stringable {
/* Методы */
public function __toString(): string
}

## Примеры работы с интерфейсом Stringable

Пример #1 Пример базовой реализации интерфейса Stringable

В примере применили продвижение параметров конструктора до свойств объекта .

    <?php

    class IPv4Address implements Stringable
    {
        public function __construct(
            private string $oct1,
            private string $oct2,
            private string $oct3,
            private string $oct4,
        ) {}

        public function __toString(): string
        {
            return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
        }
    }

    function showStuff(string|Stringable $value)
    {
        // При выводе значения с типом Stringable неявно вызывается магический метод __toString
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);

    ?>

Вывод приведённого примера будет похож на:

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — Получает строковое представление объекта

### Описание

public function Stringable::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое (string) представление объекта.

### Смотрите также

- __toString()

## Содержание

- Stringable::__toString — Получает строковое представление объекта

# Интерфейс UnitEnum

(PHP 8 >= 8.1.0)

## Введение

Интерфейс UnitEnum автоматически применяется движком ко всем перечислениям. Он не может быть реализован пользовательскими классами. Перечисления не могут переопределять его методы, поскольку реализации по умолчанию предоставляются движком. Доступен только для проверки типа.

## Обзор интерфейса

interface UnitEnum {
/* Методы */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — Возвращает список вариантов перечисления

### Описание

public static function UnitEnum::cases(): array

Метод возвращает упакованный массив всех вариантов перечисления в порядке объявления.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив всех определённых вариантов перечисления в порядке объявления.

### Примеры

Пример #1 Простой пример использования

В следующем примере показано, как возвращаются варианты перечисления.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      enum(Suit::Hearts)
      [1]=>
      enum(Suit::Diamonds)
      [2]=>
      enum(Suit::Clubs)
      [3]=>
      enum(Suit::Spades)
    }

## Содержание

- UnitEnum::cases — Возвращает список вариантов перечисления

# Интерфейс BackedEnum

(PHP 8 >= 8.1.0)

## Введение

Интерфейс BackedEnum автоматически применяется движком к типизированным перечислениям. Он не может быть реализован пользовательскими классами. Перечисления не могут переопределять его методы, поскольку реализации по умолчанию предоставляются движком. Доступен только для проверки типа.

## Обзор интерфейса

interface BackedEnum extends UnitEnum {
/* Методы */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* Наследуемые методы */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — Сопоставляет скаляр с экземпляром перечисления

### Описание

public static function BackedEnum::from(int|string `$value`): static

Метод from() переводит строку (string) или число (int) в соответствующее значение перечисления, если такое имеется. Если соответствующее значение не определено, выбрасывается ValueError.

### Список параметров

`value`

  Скалярное значение для сопоставления с перечислением.

### Возвращаемые значения

Случайный экземпляр этого перечисления.

### Примеры

Пример #1 Простой пример использования

В следующем примере показано, как возвращаются варианты перечисления.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::from('H');

    var_dump($h);

    $b = Suit::from('B');
    ?>

Результат выполнения приведённого примера:

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### Смотрите также

- UnitEnum::cases() - Возвращает список вариантов перечисления
- BackedEnum::tryFrom() - Сопоставляет скаляр с экземпляром перечисления или null

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — Сопоставляет скаляр с экземпляром перечисления или null

### Описание

public static function BackedEnum::tryFrom(int|string `$value`): ?static

Метод tryFrom() переводит строку (string) или число (int) в соответствующее значение перечисления, если такое имеется. Если соответствующее значение не определено, возвращается null.

### Список параметров

`value`

  Скалярное значение для сопоставления с перечислением.

### Возвращаемые значения

Экземпляр перечисления или null, если экземпляр не найден.

### Примеры

Пример #1 Простой пример использования

В следующем примере показано, как возвращаются варианты перечисления.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::tryFrom('H');

    var_dump($h);

    $b = Suit::tryFrom('B') ?? Suit::Spades;

    var_dump($b);
    ?>

Результат выполнения приведённого примера:

    enum(Suit::Hearts)
    enum(Suit::Spades)

### Смотрите также

- UnitEnum::cases() - Возвращает список вариантов перечисления
- BackedEnum::from() - Сопоставляет скаляр с экземпляром перечисления

## Содержание

- BackedEnum::from — Сопоставляет скаляр с экземпляром перечисления
- BackedEnum::tryFrom — Сопоставляет скаляр с экземпляром перечисления или null

# Класс SensitiveParameterValue

(PHP 8 >= 8.2.0)

## Введение

Класс SensitiveParameterValue оборачивает чувствительные значения, чтобы защитить их от случайного раскрытия.

Объект класса SensitiveParameterValue автоматически оборачивает значения параметров с атрибутом SensitiveParameter в трассировках стека.

## Обзор класса

final class SensitiveParameterValue {
/* Свойства */
private readonly mixed $value;
/* Методы */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## Свойства

value

  Чувствительное значение, которое требуется защитить от случайного воздействия.

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — Создаёт новый объект SensitiveParameterValue

### Описание

public function SensitiveParameterValue::__construct(mixed `$value`)

Метод создаёт объект SensitiveParameterValue для параметра, значение которого содержит чувствительное значение.

### Список параметров

`value`

  Произвольное значение, которое требуется хранить внутри объекта SensitiveParameterValue.

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — Защищает чувствительные значения от случайного воздействия

### Описание

public function SensitiveParameterValue::__debugInfo(): array

Метод возвращает пустой массив (array) для защиты чувствительного значения от случайного раскрытия при вызове функции var_dump().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Пустой массив (array).

### Примеры

Пример #1 Пример передачи объекта SensitiveParameterValue в функцию var_dump()

    <?php

    $s = new \SensitiveParameterValue('secret');

    var_dump($s);

    ?>

Результат выполнения приведённого примера:

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — Возвращает чувствительное значение

### Описание

public function SensitiveParameterValue::getValue(): mixed

Метод получает чувствительное значение

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Чувствительное значение.

### Примеры

Пример #1 Пример получения чувствительного значения методом SensitiveParameterValue::getValue()

    <?php

    $s = new \SensitiveParameterValue('secret');

    echo "Защищённое значение: ", $s->getValue(), "\n";

    ?>

Результат выполнения приведённого примера:

    Защищённое значение: secret

## Содержание

- SensitiveParameterValue::__construct — Создаёт новый объект SensitiveParameterValue
- SensitiveParameterValue::__debugInfo — Защищает чувствительные значения от случайного воздействия
- SensitiveParameterValue::getValue — Возвращает чувствительное значение

# Класс __PHP_Incomplete_Class

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## Введение

Объект класса создаётся функцией unserialize() при попытке десериализации неопределённого класса или класса, который не указали в списке `allowed_classes` в параметре `options` функции unserialize().

До PHP 7.2.0 функция is_object(), которую вызывали на объекте класса __PHP_Incomplete_Class, возвращала `false`. С PHP 7.2.0 такой вызов будет возвращать `true`.

## Обзор класса

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

В классе нет свойств или методов по умолчанию. Когда функция unserialize() создаёт объект неполного класса, в дополнение к остальным несериализованным свойствам и значениям объект будет содержать свойство `__PHP_Incomplete_Class_Name`, которое будет содержать название несериализованного класса.

## Список изменений

Версия | Описание
--- | ---
8.0.0 | К определению класса добавили модификатор `final`, который сделал класс окончательным.

## Примеры

Пример #1 Пример того, как функция unserialize() создаёт объект неполного класса

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass();

    $foo = serialize($myObject);

    // Любой объект десериализуется в объект класса __PHP_Incomplete_Class
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // Объекты, которые не принадлежат классам MyClass2 и MyClass3, десериализуются в объект класса __PHP_Incomplete_Class
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // Объект неопределённого класса десериализуется в объект класса __PHP_Incomplete_Class
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

Результат выполнения приведённого примера:

    object(__PHP_Incomplete_Class)#2 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#3 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#4 (1) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(16) "MyUndefinedClass"
    }

# Предопределённые атрибуты

## Содержание

- Attribute
- AllowDynamicProperties
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

В PHP предусмотрели и предопределили ряд атрибутов.

# Атрибут Attribute

(PHP 8)

## Введение

Атрибуты добавляют к объявлениям в коде структурированную машиночитаемую метаинформацию. Атрибуты нацеливают на классы, включая анонимные, методы, функции, параметры, свойства и константы класса. Затем во время выполнения кода метаданные, которые определили атрибутами, инспектируют через API-интерфейс модуля Reflection. Поэтому атрибуты рассматривают как язык конфигурации, который встраивается в код.

## Обзор класса

#[\Attribute]
final class Attribute {
/* Константы */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* Свойства */
public int $flags;
/* Методы */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## Предопределённые константы

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_CONSTANT

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

## Свойства

flags

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавлена константа `Attribute::TARGET_CONSTANT`.

## Смотрите также

Введение в атрибуты

# Attribute::__construct

(PHP 8)

Attribute::__construct — Инициализирует новый экземпляр класса Attribute

### Описание

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

Метод инициализирует объект Attribute.

### Список параметров

`flags`

## Содержание

- Attribute::__construct — Инициализирует новый экземпляр класса Attribute

# Атрибут AllowDynamicProperties

(PHP 8 >= 8.2.0)

## Введение

Атрибут маркирует классы, в которых разрешается объявлять динамические свойства.

> Замечание: Разрешение объявлять динамические свойства, которое устанавливает атрибут `AllowDynamicProperties`, наследуется, хотя сами атрибуты не наследуются. Подкласс разрешит добавлять свойства динамически, если родительский класс разметили атрибутом.

## Обзор класса

#[\Attribute]
final class AllowDynamicProperties {
/* Методы */
public function __construct()
}

## Примеры

Динамические свойства устарели с PHP 8.2.0, поэтому объявление динамического свойства без маркировки класса атрибутом выдаст уведомление об устаревании.

Пример #1 Влияние атрибута AllowDynamicProperties на добавление динамических свойств

    <?php

    class DefaultBehaviour {}

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties {}

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;

Результат выполнения приведённого примера в PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

Пример #2 Влияние атрибута AllowDynamicProperties на добавление динамических свойств в дочерних классах

    <?php

    class DefaultBehaviour {}

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties {}

    class InheritedClassAllowsDynamicProperties extends ClassAllowsDynamicProperties {}

    $o1 = new DefaultBehaviour();
    $o2 = new InheritedClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;

Результат выполнения приведённого примера в PHP 8.2:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 12

## Смотрите также

Введение в атрибуты

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — Создаёт новый экземпляр атрибута AllowDynamicProperties

### Описание

public function AllowDynamicProperties::__construct()

Создаёт новый экземпляр AllowDynamicProperties.

### Список параметров

Сигнатура функции не содержит параметров.

## Содержание

- AllowDynamicProperties::__construct — Создаёт новый экземпляр атрибута AllowDynamicProperties

# Атрибут DelayedTargetValidation

(PHP 8 >= 8.5.0)

## Введение

Атрибут откладывает проверку цели внутренних атрибутов и генерацию ошибок с этапа компиляции до момента создания экземпляра объекта отражения атрибута через API-интерфейс модуля Reflection.

После нацеливания атрибута на объявление недопустимое нацеливание других внутренних атрибутов на той же цели не вызовет ошибку компиляции. Проверка откладывается и выполняется только в момент создания объекта отражения атрибута методом ReflectionAttribute::newInstance().

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

## Обзор класса

#[\Attribute]
final class DelayedTargetValidation {
}

## Примеры

Пример #1 Пример откладывания проверки недопустимой цели атрибута

    <?php

    class Base
    {
        protected function foo(): void {}
    }

    class Child extends Base
    {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

Ошибка компиляции не возникнет в PHP-версиях, в которых нацеливание атрибута Override на константы класса не поддерживается.

Пример #2 Пример выполнения проверки атрибута при интроспекции кода

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // Разметка атрибутом недопустимой цели спровоцирует ошибку
    }

Проверка цели атрибута, который применили к объявлению вместе с атрибутом DelayedTargetValidation, выполняется только в момент вызова метода ReflectionAttribute::newInstance(). При этом для атрибута с несовместимой целью выбрасывается ошибка. Проверка цели самого́ атрибута DelayedTargetValidation не выполняется.

## Примечания

Атрибут влияет на проверку целей только внутренних атрибутов.

Атрибут не подавляет саму функциональную проверку, которую выполняют атрибуты. Например, атрибут Override по-прежнему вызовет ошибку, если метод, на который нацелили атрибут, не переопределяет родительский метод.

## Смотрите также

- Обзор атрибутов
- Override

# Атрибут Deprecated

(PHP 8 >= 8.4.0)

## Введение

Атрибут помечает функциональность устаревшей. Устаревшая функциональность вызывает ошибки уровня `E_USER_DEPRECATED`.

## Обзор класса

#[\Attribute]
final class Deprecated {
/* Свойства */
public readonly ?string $message;
public readonly ?string $since;
/* Методы */
public function __construct(?string `$message` = null, ?string `$since` = null)
}

## Свойства

message

  Необязательное сообщение, которое объясняет причину устаревания и возможную замену функциональности. Текст сообщения включается в предупреждение об устаревании.

since

  Необязательная строка, которая указывает, с какого момента устарела функциональность. PHP не проверяет содержание строки и поэтому иногда строка включает сведения о версии, дате или другие значения, которые считает уместными. Строка включается в предупреждение об устаревании.

  Функциональность самого́ PHP указывает в значении свойства since момент устаревания в виде мажорной и минорной версий, например `'8.4'`.

## Примеры

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "This is unsafe", PHP_EOL;
    }

    unsafe_function();

Результат выполнения приведённого примера в PHP 8.4 аналогичен:

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    This is unsafe

## Смотрите также

- Обзор атрибутов
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — Создаёт новый экземпляр атрибута Deprecated

### Описание

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

Метод создаёт новый экземпляр атрибута Deprecated.

### Список параметров

`message`

  Значение свойства message.

`since`

  Значение свойства since.

## Содержание

- Deprecated::__construct — Создаёт новый экземпляр атрибута Deprecated

# Атрибут NoDiscard

(PHP 8 >= 8.5.0)

## Введение

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

Атрибут полезно нацеливать на функции, результат которых нельзя игнорировать из-за риска пропустить ошибку.

Предупреждение подавляют инструкцией (void), когда требуется преднамеренно проигнорировать обработку результата функции, на которую нацелили атрибут.

> Замечание: В PHP 8.4 или ниже движок проигнорирует атрибут `#[\NoDiscard]`, который добавили к функции или методу, поскольку атрибуты разработали с учётом обратной совместимости. В PHP 8.5 и выше движок выдаст предупреждение, если результат проигнорировали. Присваивание результата переменной наподобие `$_` не нарушит работу кода на прежних версиях PHP, в которых ещё не добавили поддержку инструкции `(void)`, и подавит предупреждение при переносе кода на PHP 8.5.

> Замечание: Атрибут `#[\NoDiscard]` применяется к конкретному объявлению функции или метода, на котором его написали, а предупреждение выдаётся на основе того объявления, которое вызвали на самом деле. Поэтому добавление атрибута `#[\NoDiscard]` к методу интерфейса или абстрактному методу не приводит к предупреждению, поскольку вызывается метод реализации или переопределяющий метод. Аналогично метод, который переопределяет метод с атрибутом `#[\NoDiscard]`, не выдаёт предупреждение, если только его самого не пометили этим атрибутом. Напротив, метод, импортированный из трейта, сохраняет атрибут, поскольку метод трейта копируется в использующий класс, как будто его объявили там.

## Обзор класса

#[\Attribute]
final class NoDiscard {
/* Свойства */
public readonly ?string $message;
/* Методы */
public function __construct(?string `$message` = null)
}

## Свойства

message
  Необязательное сообщение, которое объясняет, почему нельзя игнорировать значение возврата.

## Примеры

Пример #1 Базовый пример

    <?php

    /**
     * Метод возвращает массив, элементы которого содержат результат обработки
     * каждого отдельного значения. Значение null указывает, что обработка элемента завершилась без ошибок,
     * а объект Exception указывает на ошибку. Ключи в массиве с результатами обработки совпадают с ключами массива $items.
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("поскольку вероятна ошибка при обработке отдельного элемента")]
    function bulk_process(array $items): array
    {
        $results = [];

        foreach ($items as $key => $item) {
            if (\random_int(0, 9999) < 9999) {
                // Имитация полезной операции со значением $item
                // с вероятностью успеха 99,99 %.
                echo "Обработка значения {$item}", PHP_EOL;
                $error = null;
            } else {
                $error = new \Exception("Ошибка обработки значения {$item}.");
            }

            $results[$key] = $error;
        }

        return $results;
    }

    bulk_process($items);

Результат выполнения приведённого примера в PHP 8.5 аналогичен:

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), поскольку вероятна ошибка при обработке отдельного элемента

Пример #2 Преднамеренное игнорирование значения возврата

    <?php

    #[\NoDiscard]
    function some_command(): int
    {
        return 1;
    }

    // Подавление предупреждения инструкцией (void) — поддерживается в PHP 8.5+
    (void) some_command();

    // Временная переменная сохранит обратную совместимость с PHP до версии 8.5
    $_ = some_command();

## Смотрите также

- Введение в атрибуты

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — Создаёт новый экземпляр атрибута NoDiscard

### Описание

public function NoDiscard::__construct(?string `$message` = `null`)

Метод создаёт новый экземпляр атрибута NoDiscard.

### Список параметров

`message`
  Значение свойства message.

## Содержание

- NoDiscard::__construct — Создаёт новый экземпляр атрибута NoDiscard

# Атрибут Override

(PHP 8 >= 8.3.0)

## Введение

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

PHP выдаст ошибку времени компиляции, если в родительском классе или реализуемом интерфейсе не определили метод или свойство с таким же названием.

Атрибут нельзя нацеливать на метод __construct(), поскольку PHP не проверяет совместимость сигнатур конструкторов при наследовании.

## Обзор класса

#[\Attribute]
final class Override {
/* Методы */
public function __construct()
}

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Атрибут Override теперь работает со свойствам.

## Примеры

Пример #1 Нацеливание на методы

    <?php

    class Base
    {
        protected function foo(): void {}
    }

    final class Extended extends Base
    {
        #[\Override]
        protected function boo(): void {}
    }

Результат выполнения приведённого примера в PHP 8.3 аналогичен:

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

Пример #2 Нацеливание на свойства

    <?php

    class Base
    {
        protected string $foo;
    }

    final class Extended extends Base
    {
        #[\Override]
        protected string $boo;
    }

Результат выполнения приведённого примера в PHP 8.5 аналогичен:

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## Смотрите также

- Атрибуты

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — Создаёт новый экземпляр атрибута Override

### Описание

public function Override::__construct()

Создаёт новый экземпляр класса Override.

### Список параметров

Сигнатура функции не содержит параметров.

## Содержание

- Override::__construct — Создаёт новый экземпляр атрибута Override

# Атрибут ReturnTypeWillChange

(PHP 8 >= 8.1.0)

## Введение

При переопределении большей части неокончательных методов внутренних классов теперь потребуется указать совместимый тип возвращаемого значения, иначе при проверке наследования PHP выдаст предупреждение об устаревании сигнатуры, которая нарушает правила ковариантности. С PHP 8.1.0 начался предварительный этап перехода к типизации значений, которые возвращаются методами внутренних классов: проверка совместимости типов возврата продолжится в мягком режиме, прежде чем в будущей версии языка введут строгую проверку, и вместо предупреждений движок начнёт выдавать критическую ошибку. Для подавления предупреждения при переопределении метод размечают атрибутом `#[\ReturnTypeWillChange]`, если из-за несовместимости между версиями PHP невозможно объявить тип возвращаемого значения или переопределение метода содержит несовместимый тип.

Внимание

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

## Обзор класса

#[\Attribute]
final class ReturnTypeWillChange {
/* Методы */
public function __construct()
}

## Смотрите также

Введение в атрибуты

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — Создаёт новый экземпляр атрибута ReturnTypeWillChange

### Описание

public function ReturnTypeWillChange::__construct()

Создаёт новый экземпляр ReturnTypeWillChange.

### Список параметров

Сигнатура функции не содержит параметров.

## Содержание

- ReturnTypeWillChange::__construct — Создаёт новый экземпляр атрибута ReturnTypeWillChange

# Атрибут SensitiveParameter

(PHP 8 >= 8.2.0)

## Введение

Атрибутом размечают параметр с чувствительным значением, которое PHP отредактирует, когда значение попадёт в трассировку стека вызовов.

## Обзор класса

#[\Attribute]
final class SensitiveParameter {
/* Методы */
public function __construct()
}

## Примеры

    <?php

    function defaultBehavior(
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    function sensitiveParametersWithAttribute(
        #[\SensitiveParameter]
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    try {
        defaultBehavior('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    try {
        sensitiveParametersWithAttribute('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

Результат выполнения приведённого примера в PHP 8.2 аналогичен:

    Exception: Error! in example.php:7
    Stack trace:
    #0 example.php(19): defaultBehavior('password', 'normal')
    #1 {main}

    Exception: Error! in example.php:15
    Stack trace:
    #0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
    #1 {main}

## Смотрите также

- Введение в атрибуты
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — Создаёт новый экземпляр атрибута SensitiveParameter

### Описание

public function SensitiveParameter::__construct()

Создаёт новый экземпляр SensitiveParameter.

### Список параметров

Сигнатура функции не содержит параметров.

## Содержание

- SensitiveParameter::__construct — Создаёт новый экземпляр атрибута SensitiveParameter

# Опции и параметры контекста

PHP предлагает ряд опций и параметров контекста, которые разрешается использовать со всеми файловыми системами и обёртками потоков. Контекст создаётся функцией stream_context_create(). Опции устанавливаются функцией stream_context_set_option(), а параметры — функцией stream_context_set_params().

# Контекстные опции сокета

Контекстные опции сокета — Список контекстных опций сокета

### Описание

Контекстные опции доступны для всех обёрток, которые работают через сокеты, например: `tcp`, `http` и `ftp`.

### Опции

`bindto`

  Указывает IP-адрес (IPv4 или IPv6) и (или) номер порта, которые PHP будет использовать для подключения к сети. Синтаксис выглядит следующим образом: `ip:port` для адреса IPv4, и `[ip]:port` для адреса IPv6. Установка для IP-адреса и (или) порта значения `0` разрешит системе самой выбрать нужный IP и (или) порт.

  > Замечание:

  > Поскольку во время обычной работы FTP-сервер создаёт 2 соединения с сокетами, этой опцией нельзя задать номер порта.

`backlog`

  Ограничивает исходящие соединения в очереди соединений сокета.

  > Замечание:

  > Опция работает только с функцией stream_socket_server().

`ipv6_v6only`

  Переопределяет значение ОС по умолчанию для сопоставления IPv4-адресов с IPv6-адресами.

  > Замечание:

  > Это важно, в частности, при попытке прослушивать IPv4-адреса отдельно, пока существует привязка к адресу `[::]`.

  > Применимо только к функции stream_socket_server().

`so_reuseport`

  Разрешает множественную привязку к одной и той же паре IP:порт, даже из разных процессов.

  > Замечание:

  > Применимо только к функции stream_socket_server().

`so_broadcast`

  Разрешает посылать и принимать данные в/от широковещательных адресов.

  > Замечание:

  > Применимо только к функции stream_socket_server().

`tcp_nodelay`

  Установка для этой опции значения `true` установит `SOL_TCP,NO_DELAY=1` и тем самым отключит алгоритм TCP Nagle.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Добавлено `tcp_nodelay`.
7.0.1 | Добавлено `ipv6_v6only`.

### Примеры

Пример #1 Пример использования опции `bindto`

    <?php

    // Соединение с сетью через IP-адрес 192.168.0.100
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // Соединение с сетью через IP-адрес 192.168.0.100 и порт 7000
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // Соединение с сетью через IPv6-адрес 2001:db8::1
    // и порт 7000
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // Соединение с сетью через порт 7000
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // Создаём контекст...
    $context = stream_context_create($opts);

    // ...и получаем через него данные
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# Опции HTTP-контекста

Опции HTTP-контекста — Список опций HTTP-контекста

### Описание

Опции контекста для транспортных протоколов `http://` и `https://`.

### Опции

`method` string

  Методы `GET`, `POST` или любой другой HTTP-метод, который поддерживает удалённый сервер.

  По умолчанию — `GET`.

`header` array или string

  Дополнительные заголовки для отправки в запросе. Значения в этой опции переопределяют другие значения наподобие `User-Agent:`, `Host:` и `Authentication:`, даже при следовании перенаправлениям заголовка `Location:`. Поэтому лучше не устанавливать заголовок `Host:`, если включили опцию `follow_location`.

  Строковые значения указывают как пары `Ключ: значение` и разделяют последовательностью символов `\r\n`, например: `"Content-Type: application/json\r\nConnection: close"`. В массиве значения указывают как список пар `Ключ: значение`, например: `["Content-Type: application/json", "Connection: close"]`.

`user_agent` string

  Значение для отправки в заголовке `User-Agent:`. Значение учитывается, только если заголовок User-Agent не указали в опции контекста `header` выше.

  По умолчанию извлекается значение директивы user_agent из файла php.ini.

`content` string

  Дополнительные данные для отправки после заголовков. Параметр часто указывают с POST- и PUT-запросами.

`proxy` string

  URI-идентификатор, который указывает адрес прокси-сервера, например: `tcp://proxy.example.com:5100`.

`request_fulluri` bool

  Со значением `true` при формировании запроса запрашивается весь URI, например: `GET http://www.example.com/path/to/file.html HTTP/1.0`. Некоторые прокси-серверы требуют указывать весь идентификатор, хотя это нестандартный формат запроса.

  По умолчанию `false`.

`follow_location` int

  Опция указывает, следовать ли перенаправлениям заголовка `Location`. Чтобы отключить, устанавливают значение `0`.

  По умолчанию — `1`.

`max_redirects` int

  Максимальное количество перенаправлений, которым можно следовать. Значение `1` или меньше означает, что перенаправления не выполняются.

  По умолчанию `20`.

`protocol_version` float

  Версия HTTP-протокола.

  С PHP 8.0.0 значение по умолчанию — `1.1`; до этой версии значение по умолчанию равнялось `1.0`.

`timeout` float

  Время ожидания на чтение в секундах в виде числа с плавающей точкой (float), например: `10.5`.

  По умолчанию извлекается значение директивы default_socket_timeout из файла php.ini.

`ignore_errors` bool

  Опция указывает, извлекать ли содержимое даже при неуспешных статусах завершения.

  По умолчанию — `false`.

### Примеры

Пример #1 Пример получения страницы и отправки данных методом POST

    <?php

    $postdata = http_build_query(
        [
            'var1' => 'некоторое содержимое',
            'var2' => 'doh',
        ]
    );

    $opts = [
        'http' => [
            'method'  => 'POST',
            'header'  => 'Content-type: application/x-www-form-urlencoded',
            'content' => $postdata,
        ]
    ];

    $context = stream_context_create($opts);

    $result = file_get_contents('http://example.com/submit.php', false, $context);

    ?>

Пример #2 Пример игнорирования перенаправлений, но с получением заголовков и контента

    <?php

    $url = "http://www.example.org/header.php";

    $opts = [
        'http' => [
            'method'        => 'GET',
            'max_redirects' => '0',
            'ignore_errors' => '1',
        ]
    ];

    $context = stream_context_create($opts);
    $stream = fopen($url, 'r', false, $context);

    // Информация о заголовках
    // и метаданные о потоке
    var_dump(stream_get_meta_data($stream));

    // Фактические данные в переменной $url
    var_dump(stream_get_contents($stream));
    fclose($stream);

    ?>

### Примечания

> Замечание: Опции контекста потока нижележащего сокета
> Нижележащий транспортный протокол может поддерживать дополнительные опции контекста. Для потоков `http://` смотрите описание опций контекста для транспортного протокола `tcp://`. Для потоков `https://` смотрите описание опций контекста для транспортного протокола `ssl://`.

> Замечание: Строка HTTP-статуса
> Когда эта обёртка потока следует перенаправлениям, элемент `wrapper_data`, который возвращает функция stream_get_meta_data(), необязательно содержит строку HTTP-статуса, которая на самом деле относится к содержанию данных в индексе `0`.

>     array (
>       'wrapper_data' =>
>       array (
>         0 => 'HTTP/1.0 301 Moved Permanently',
>         1 => 'Cache-Control: no-cache',
>         2 => 'Connection: close',
>         3 => 'Location: http://example.com/foo.jpg',
>         4 => 'HTTP/1.1 200 OK',
>         ...

> Первый запрос вернул код `301` (постоянное перенаправление), поэтому обёртка потока автоматически последовала перенаправлению, чтобы получить ответ с кодом `200` (индекс = `4`).

### Смотрите также

- http://
- Контекстные опции сокета
- Опции SSL-контекста

# Параметры FTP-контекста

Параметры FTP-контекста — Список параметров FTP-контекста

### Описание

Параметры контекста для транспортных протоколов `ftp://` и `ftps://`.

### Опции

`overwrite` bool

  Разрешает перезаписывать существующие файлы на удалённом сервере. Работает только в режиме записи (uploading).

  По умолчанию `false`.

`resume_pos` int

  Смещение в файле, с которого начинается передача. Работает только в режиме чтения (downloading).

  По умолчанию `0` (начало файла).

`proxy` string

  FTP-запрос через прокси-сервер HTTP. Применяется только при операции чтения файла. Пример: `tcp://squid.example.com:8000`.

### Примечания

> Замечание: Опции контекста потока нижележащего сокета
> Нижележащий транспортный протокол может поддерживать дополнительные опции контекста. Для потоков `ftp://` смотрите описание опций контекста для транспортного протокола `tcp://`. Для потоков `ftps://` смотрите описание опций контекста для транспортного протокола `ssl://`.

### Смотрите также

- ftp://
- Контекстные опции сокета
- Опции SSL-контекста

# Опции SSL-контекста

Опции SSL-контекста — Список опций SSL-контекста

### Описание

Опции контекста для протоколов `ssl://` и `tls://`.

### Опции

`peer_name` string

  Имя узла. Если значение параметра не задали, имя подставляется на основе имени хоста, который использовался при открытии потока.

`verify_peer` bool

  Требовать проверки SSL-сертификата.

  По умолчанию `true`.

`verify_peer_name` bool

  Требовать проверки имени узла.

  По умолчанию `true`.

`allow_self_signed` bool

  Разрешить самоподписанные сертификаты. Требуется опция `verify_peer`.

  По умолчанию `false`

`cafile` string

  Расположение файла центра сертификации в локальной файловой системе, который следует использовать с опцией контекста `verify_peer` для проверки подлинности удалённого узла.

`capath` string

  Если опцию `cafile` не определили или функция не смогла найти сертификат, выполняется поиск в директории, которую указали в опции `capath`. Путь `capath` должен указывать на корректную директорию, которая содержит сертификаты, имена которых — хеш от поля subject, указанного в сертификате.

`local_cert` string

  Путь к локальному сертификату в файловой системе. Требуется файл, который закодировали в формате PEM, который содержит ваш сертификат и закрытый ключ. Файл дополнительно может содержать открытый ключ эмитента. Закрытый ключ также может содержаться в отдельном файле, который задали опцией `local_pk`.

`local_pk` string

  Путь к локальному файлу с приватным ключом в случае отдельных файлов сертификата (`local_cert`) и приватного ключа.

`passphrase` string

  Идентификационная фраза, с которой закодировали ваш файл `local_cert`.

`verify_depth` int

  Прервать, если цепочка сертификата слишком длинная.

  По умолчанию проверка отсутствует.

`ciphers` string

  Устанавливает список доступных алгоритмов шифрования. Формат этой строки описывает страница » шифры(1).

  По умолчанию принимает значение `DEFAULT`.

`capture_peer_cert` bool

  Если для опции установили значение `true`, будет создана опция контекста `peer_certificate`, которая содержит сертификат удалённого узла.

`capture_peer_cert_chain` bool

  Если для опции установили значение `true`, будет создана опция контекста `peer_certificate_chain`, которая содержит цепочку сертификатов.

`SNI_enabled` bool

  Если для опции установили значение `true`, включится индикация имени сервера. Включение SNI разрешает использовать разные сертификаты на одном IP-адресе.

`disable_compression` bool

  Отключает TLS-сжатие, что помогает предотвратить атаки типа CRIME.

`peer_fingerprint` string | array

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

  Если указали строку (string), её длина определяет, какой алгоритм хеширования будет использоваться: «md5» (32) или «sha1» (40).

  Если указали массив (array), ключи определяют алгоритм хеширования, а каждое соответствующее значение представляет собой требуемым хешем.

`security_level` int

  Устанавливает уровень безопасности. Если не указали, используется стандартный уровень безопасности, указанный в библиотеке. Уровни безопасности описывает страница » SSL_CTX_get_security_level(3).

  Доступна с PHP 7.2.0 и OpenSSL 1.1.0.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Добавили опцию `security_level`. Требуется OpenSSL >= 1.1.0.

### Примечания

> Замечание: Поскольку `ssl://` — нижележащий транспортный протокол для обёрток `https://` и `ftps://`, любые опции контекста, которые применяются к транспорту `ssl://`, будут также применяться к обёрткам `https://` и `ftps://`.

> Замечание: Чтобы указание имени сервера (SNI, Server Name Indication) было доступно, требуется скомпилировать PHP с OpenSSL 0.9.8j или более поздней. Чтобы определить, поддерживается ли SNI, указывают константу `OPENSSL_TLSEXT_SERVER_NAME`.

### Смотрите также

- Контекстные опции сокета

# Опции Phar-контекста

Опции Phar-контекста — Список опций контекста модуля Phar

### Описание

Опции контекста для обёртки `phar://`.

### Опции

`compress` int

  Одна из констант сжатия модуля Phar.

`metadata` mixed

  Метаданные Phar. Смотрите описание метода Phar::setMetadata().

### Смотрите также

- phar://
- Потоки Phar

# Параметры контекста

Параметры контекста — Список параметров контекста

### Описание

Эти `параметры` устанавливают для контекста через параметр `context` функции stream_context_set_params().

### Список параметров

`notification` callable

  Функция с типом callable, которая будет вызываться при наступлении события в потоке.

  Дополнительную информацию даёт описание функции stream_notification_callback.

# Опции Zip-контекста

Опции Zip-контекста — Список опций Zip-контекста

### Описание

Опции Zip-контекста доступны для обёрток `zip`.

### Опции

`password`

  Указывает пароль для зашифрованных архивов.

### Список изменений

Версия | Описание
--- | ---
7.2.0, PECL zip 1.14.0 | Добавили опцию `password`.

### Примеры

Пример #1 Простой пример использования опции `password`

    <?php

    // Читаем зашифрованный архив
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );

    // Создаём контекст...
    $context = stream_context_create($opts);

    // ...и получаем данные
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Опции Zlib-контекста

Опции Zlib-контекста — Список опций контекста модуля Zlib

### Описание

Опции Zlib-контекста доступны для обёрток `zlib`.

### Опции

`level`

  Указывает уровень сжатия (`0` — `9`).

### Список изменений

Версия | Описание
--- | ---
7.3.0 | Добавили опцию `level`.

## Содержание

- Контекстные опции сокета — Список контекстных опций сокета
- Опции HTTP-контекста — Список опций HTTP-контекста
- Параметры FTP-контекста — Список параметров FTP-контекста
- Опции SSL-контекста — Список опций SSL-контекста
- Опции Phar-контекста — Список опций контекста модуля Phar
- Параметры контекста — Список параметров контекста
- Опции Zip-контекста — Список опций Zip-контекста
- Опции Zlib-контекста — Список опций контекста модуля Zlib

# Протоколы и обёртки

PHP поставляется с набором встроенных обёрток для ряда URL-подобных протоколов. Обёртки указывают при вызове функций, которые работают с файловой системой: fopen(), copy(), file_exists() и filesize(). В дополнение к встроенным обёрткам доступна регистрация пользовательских обёрток функцией stream_wrapper_register().

> Замечание: Синтаксис URL-адресов для описания обёртки поддерживает только схемы в формате `scheme://...`. Варианты синтаксиса `scheme:/` и `scheme:` не поддерживаются.

# file://

file:// — Доступ к локальной файловой системе

### Описание

Обёртка `file://` — PHP-обёртка по умолчанию, которая представляет локальную файловую систему. Когда задают относительный путь (путь, который не начинается с символов `/`, `\`, `\\` или с буквы жёсткого диска в ОС Windows), путь применяется к текущей рабочей директории. В большинстве случаев это директория, в которой находится сценарий, если она не была изменена. При работе через CLI-интерфейс командной строки SAPI-интерфейса директорией по умолчанию будет та, из которой вызвали исполнение скрипта.

В функциях наподобие fopen() и file_get_contents() поиск файла может дополнительно выполняться в списке путей директивы `include_path`.

### Использование

- /path/to/file.ext
- relative/path/to/file.ext
- fileInCwd.ext
- C:/path/to/winfile.ext
- C:\path\to\winfile.ext
- \\smbserver\share\path\to\winfile.ext
- file:///path/to/file.ext

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Чтение | Да
Запись | Да
Добавление | Да
Одновременное чтение и запись | Да
Поддержка stat() | Да
Поддержка unlink() | Да
Поддержка rename() | Да
Поддержка mkdir() | Да
Поддержка rmdir() | Да

# http://

# https://

http:// -- https:// — Доступ к URL-адресам по протоколу HTTP(s)

### Описание

Предоставляет доступ только для чтения файлов или ресурсов через протокол HTTP. По умолчанию используется HTTP 1.0 GET. Для поддержки виртуальных хостов на основе имён вместе с запросом посылается заголовок `Host:`. Если через файл php.ini или контекст потока сконфигурировали строку user_agent, то она также включится в запрос.

Этот поток также разрешает получить доступ к содержимому ресурса; заголовки сохраняются в переменной $http_response_header.

Если важно знать URL-адрес, с которого получили документ (после всех переадресаций, которые были выполнены), то необходимо обработать серию заголовков ответов, которые возвращает поток.

INI-директива from будет использоваться для заголовка `From:`, если установлена и не переопределена в контексте Опции и параметры контекста.

### Использование

- http://example.com
- http://example.com/file.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/file.php?var1=val1&var2=val2
- https://user:password@example.com

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Да
Чтение | Да
Запись | Нет
Добавление | Нет
Одновременное чтение и запись | Недоступно
Поддержка stat() | Нет
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

### Примеры

Пример #1 Определение URL-адреса, с которого забрали документ после переадресаций

    <?php

    $url = 'http://www.example.com/redirecting_page.php';

    $fp = fopen($url, 'r');

    $meta_data = stream_get_meta_data($fp);
    foreach ($meta_data['wrapper_data'] as $response) {
        /* Выполнялась ли переадресация? */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {
            /* Сохранить в переменной $url адрес переадресации */
            $url = substr($response, 10);
        }
    }

    ?>

### Примечания

> Замечание: Протокол HTTPS поддерживается, только когда включили модуль openssl.

HTTP-соединения предназначены только для чтения; запись данных или копирование файлов в HTTP-ресурс не поддерживается.

Отправку, например, POST- и PUT-запросов можно выполнить через HTTP-контекст.

### Смотрите также

- Опции HTTP-контекста
- $http_response_header
- stream_get_meta_data() - Извлекает заголовок или метаданные из потоков или файловых указателей

# ftp://

# ftps://

ftp:// -- ftps:// — Доступ к URL-адресам по протоколу FTP(s)

### Описание

Разрешает читать существующие файлы и создавать новые файлы через FTP-протокол. Если FTP-сервер не поддерживает пассивный режим, соединение будет невозможно.

Можно открыть файл либо для чтения, либо для записи, но не одновременно для того и другого. Если файл на FTP-сервере уже существует, и файл пытаются открыть для записи без указания опцию контекста `overwrite`, соединение будет невозможно. Если необходимо перезаписать существующие файлы на FTP-сервере, указывают опцию `overwrite` в контексте и открывают файл для записи. Кроме того, использовать модуль FTP.

Если установили директиву from в файле php.ini, то это значение будет отправлено как пароль при анонимном подключении к FTP-севрверу.

### Использование

- ftp://example.com/pub/file.txt
- ftp://user:password@example.com/pub/file.txt
- ftps://example.com/pub/file.txt
- ftps://user:password@example.com/pub/file.txt

### Опции

Основная информация
Атрибут | Поддерживается
--- | ---
Ограничение по allow_url_fopen | Да
Чтение | Да
Запись | Да (новые или существующие файлы с опцией `overwrite`)
Добавление | Да
Одновременное чтение и запись | Нет
Поддержка stat() | filesize(), filemtime(), filetype(), file_exists(), is_file() и is_dir().
Поддержка unlink() | Да
Поддержка rename() | Да
Поддержка mkdir() | Да
Поддержка rmdir() | Да

### Примечания

> Замечание:

> Протокол FTPS поддерживается только тогда, когда включили поддержку модуля OpenSSL.

> Если сервер не поддерживает SSL, то соединение переключается обратно на обычный нешифрованный протокол FTP.

> Замечание: Дополнение
> Файлы можно дописать через URL-обёртку `ftp://`.

### Смотрите также

- Параметры FTP-контекста

# php://

php:// — Доступ к различным потокам ввода-вывода

### Описание

В PHP предусмотрели ряд потоков ввода-вывода, которые открывают доступ к собственным потокам ввода-вывода PHP, к стандартным файловым дескрипторам ввода, вывода и ошибок, к временным файловым потокам в памяти и на диске, и фильтрам, которые умеют манипулировать другими файловыми ресурсами по мере их считывания или записи.

#### php://stdin, php://stdout и php://stderr

Потоки php://stdin, php://stdout и php://stderr открывают прямой доступ к соответствующему потоку ввода или вывода PHP-процесса. Поток указывает на копию файлового дескриптора, поэтому, если открыть php://stdin а потом закрыть его, закроется только копия дескриптора — фактический поток, на который ссылается `STDIN`, останется неизменным. Рекомендуется просто использовать константы `STDIN`, `STDOUT` и `STDERR` вместо ручного открытия потоков через эти обёртки.

Поток php://stdin доступен только для чтения, тогда как потоки php://stdout и php://stderr — только для записи.

#### php://input

Поток php://input — поток только для чтения, который разрешает читать необработанные данные из тела запроса. Поток php://input недоступен в POST-запросах с типом кодирования `enctype="multipart/form-data"`, если включили опцию enable_post_data_reading.

#### php://output

Поток php://output — поток только для записи, который разрешает записывать данные в механизм буфера вывода так же, как это делают языковые конструкции print и echo.

#### php://fd

Поток php://fd разрешает прямой доступ к файловому дескриптору. Например, php://fd/3 относится к файловому дескриптору 3.

#### php://memory и php://temp

Потоки php://memory и php://temp — потоки чтения и записи, которые разрешают сохранять временные данные в файлоподобной обёртке. Единственная разница между ними заключается в том, что поток php://memory будет всегда хранить данные в оперативной памяти, тогда как php://temp будет использовать временный файл, как только объем хранимой информации достигнет предопределённого предела (по умолчанию 2 МБ). Расположение этого временного файла определяется аналогично функции sys_get_temp_dir().

Ограничением памяти для потока php://temp управляют путём добавления суффикса `/maxmemory:NN`, где `NN` — максимальный размер данных в байтах для хранения в памяти перед тем как PHP создаст временный файл.

Предостережение

Отдельным PHP-модулям иногда требуется стандартный поток ввода-вывода и модули могут попытаться преобразовать заданный поток в стандартный поток ввода-вывода. Это преобразование может завершиться ошибкой для потоков памяти, поскольку для такого приведения необходима функция fopencookie() языка C. Такая функция языка C недоступна в операционных системах Windows.

#### php://filter

Поток php://filter — вид мета-обёртки, которая разрешает применять фильтры к потоку во время открытия. Это полезно при работе с универсальными файловыми функциями наподобие readfile(), file() и file_get_contents(), где иначе нет возможности применить фильтр к потоку до считывания содержимого.

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

Параметры для php://filter
Название | Описание
--- | ---
`resource=<поток для фильтрации>` | Этот параметр обязателен. Он указывает поток, который необходимо отфильтровать.
`read=<список фильтров для применения к цепочке чтения>` | Этот параметр необязателен. Здесь можно указать одно или несколько имён фильтров через символ вертикальной черты (`|`).
`write=<список фильтров для применения к цепочке записи>` | Этот параметр необязателен. Здесь можно указать одно или несколько имён фильтров через символ вертикальной черты (`|`).
`<список фильтров для применения к обеим цепочкам>` | Любые списки фильтров без префикса `read=` или `write=` будут применяться как к цепочкам чтения, так и к цепочкам записи.

### Опции

Краткое описание обёртки (для потока `php://filter` смотрите информацию по фильтруемой обёртке)
Атрибут | Поддержка
--- | ---
Ограничение по директиве allow_url_fopen | Нет
Ограничение по директиве allow_url_include | только потоки `php://input`, `php://stdin`, `php://memory` и `php://temp`.
Чтение | только потоки `php://stdin`, `php://input`, `php://fd`, `php://memory` и `php://temp`.
Запись | только потоки `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` и `php://temp`.
Добавление | только потоки `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` и `php://temp`. (Эквивалентно записи)
Одновременное чтение и запись | только потоки `php://fd`, `php://memory` и `php://temp`.
Поддержка функции stat() | нет. Тем не менее, потоки `php://memory` и `php://temp` поддерживают функцию fstat().
Поддержка функции unlink() | Нет
Поддержка функции rename() | Нет
Поддержка функции mkdir() | Нет
Поддержка функции rmdir() | Нет
Поддержка функции stream_select() | только потоки `php://stdin`, `php://stdout`, `php://stderr`, `php://fd` и `php://temp`.

### Примеры

Пример #1 php://temp/maxmemory

Этот необязательный параметр устанавливает ограничение памяти перед началом работы потока php://temp с временным файлом.

    <?php

    // Устанавливаем предел в 5 МБ
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // Читаем данные, которые записали на предыдущем шаге
    rewind($fp);
    echo stream_get_contents($fp);

    ?>

Пример #2 php://filter/resource=<поток для фильтрации>

Параметр указывают в конце спецификации php://filter. Значение параметра указывает на поток, который требуется отфильтровать.

    <?php

    /* Это просто эквивалентно:
      readfile("http://www.example.com");
      поскольку на самом деле фильтры не указали */

    readfile("php://filter/resource=http://www.example.com");

    ?>

Пример #3 php://filter/read=<список фильтров для применения к цепочке чтения>

Этот параметр принимает один или более имён фильтров, разделённых вертикальной чертой `|`.

    <?php

    /* Скрипт выведет содержимое ресурса
      www.example.com полностью в верхнем регистре */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* Скрипт выполняет аналогичную работу,
      но также кодирует данные алгоритмом ROT13 */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");

    ?>

Пример #4 php://filter/write=<список фильтров для применения к цепочке записи>

Параметр принимает одно или несколько имён фильтров, разделённых вертикальной чертой `|`.

    <?php

    /* Скрипт отфильтрует строку "Hello World"
      через фильтр rot13, затем запишет результат
      в файл example.txt в текущем каталоге */
    file_put_contents("php://filter/write=string.rot13/resource=example.txt", "Hello World");

    ?>

Пример #5 Недоступность повторного обращения к потокам php://memory и php://temp

Потоки php://memory и php://temp невозможно переиспользовать, поэтому после закрытия потокового ресурса нельзя обратиться к потоку повторно.

    <?php

    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // Ничего не выведет

    ?>

Пример #6 Чтение JSON-данных из тела запроса через обёртку php://input

Пример показывает, как считывать входные данные в формате JSON из тела POST, PUT и PATCH-запросов через обёртку php://input.

    <?php

    $input = file_get_contents("php://input");

    $json_array = json_decode(
        json: $input,
        associative: true,
        flags: JSON_THROW_ON_ERROR
    );

    echo "Поступили JSON-данные: ";
    print_r($json_array);

    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — Сжатые потоки

### Описание

compress.zlib:// и compress.bzip2://

Обёртка zlib: работает как функция gzopen(), за исключением того что с этим потоком сможет работать функция fread() и другие функции, которые работают с файловой системой. Обёртка устарела из-за неоднозначности при наличии файлов, которые содержат ':'; вместо неё пользуются обёрткой compress.zlib://.

Обёртки compress.zlib:// и compress.bzip2:// эквиваленты функциям gzopen() и bzopen() соответственно и работают даже в системах, которые не поддерживают fopencookie.

Модуль ZIP добавляет обёртку zip:. Начиная с PHP 7.2.0 и libzip 1.2.0+ добавили поддержку паролей для зашифрованных архивов, разрешая предоставлять пароли через контексты потоков. Пароли можно установить через контекстную опцию `'password'`.

### Использование

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Чтение | Да
Запись | Да (кроме `zip://`)
Добавление | Да (кроме `zip://`)
Одновременное чтение и запись | Нет
Поддержка stat() | Нет, используйте стандартную обёртку `file://` для получения информации по сжатым файлам.
Поддержка unlink() | Нет, используйте стандартную обёртку `file://` для удаления сжатых файлов.
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

### Смотрите также

- Опции Zlib-контекста

# data://

data:// — Схема Data (RFC 2397)

### Описание

data: (» RFC 2397) — обёртка потоков.

### Использование

- data://text/plain;base64,

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Да
Ограничение по allow_url_include | Да
Чтение | Да
Запись | Нет
Добавление | Нет
Чтение и запись одновременно | Нет
Поддержка stat() | Нет
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

### Примеры

Пример #1 Вывод содержимого data://

    <?php

    // Выводит: I love PHP
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');

    ?>

Пример #2 Получение типа потока

    <?php

    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // Выводит: text/plain
    echo $meta['mediatype'];

    ?>

# glob://

glob:// — Нахождение путей, которые соответствуют шаблону

### Описание

Обёртка потока glob:.

### Использование

- glob://

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Ограничение по allow_url_include | Нет
Чтение | Нет
Запись | Нет
Добавление | Нет
Одновременное чтение и запись | Нет
Поддержка stat() | Нет
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

### Примеры

Пример #1 Основы использования

    <?php

    // Просмотреть все файлы *.php в директории ext/spl/examples/
    // и напечатать имена файлов и их размеры
    $it = new DirectoryIterator("glob://ext/spl/examples/*.php");

    foreach($it as $f) {
        printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
    }

    ?>

    tree.php: 1.0K
    findregex.php: 0.6K
    findfile.php: 0.7K
    dba_dump.php: 0.9K
    nocvsdir.php: 1.1K
    phar_from_dir.php: 1.0K
    ini_groups.php: 0.9K
    directorytree.php: 0.9K
    dba_array.php: 1.1K
    class_tree.php: 1.8K

# phar://

phar:// — PHP-архив

### Описание

Обёртка потока phar://. Подробное описание даёт раздел Обёртка потока Phar.

### Использование

- phar://

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Ограничение по allow_url_include | Нет
Чтение | Да
Запись | Да
Добавление | Нет
Одновременное чтение и запись | Да
Поддержка stat() | Да
Поддержка unlink() | Да
Поддержка rename() | Да
Поддержка mkdir() | Да
Поддержка rmdir() | Да

### Смотрите также

- Опции Phar-контекста

# ssh2://

ssh2:// — Secure Shell 2

### Описание

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> Замечание: Эта обёртка не включена по умолчанию
> Чтобы использовать обёртки ssh2.*://, необходимо установить модуль » SSH2 из репозитория » PECL.

Помимо принятия традиционных данных для входа по URI-идентификатору, обёртки ssh2 также будут повторно использовать открытые соединения, передавая ресурс соединения в хост-часть URL.

### Использование

- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename

### Опции

Основная информация
Атрибут | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
Ограничение по allow_url_fopen | Да | Да | Да | Да | Да
Чтение | Да | Да | Да | Да | Да
Запись | Да | Да | Да | Да | Нет
Добавление | Нет | Нет | Нет | Да (когда поддерживается сервером) | Нет
Одновременная чтение и запись | Да | Да | Да | Да | Нет
Поддержка stat() | Нет | Нет | Нет | Да | Нет
Поддержка unlink() | Нет | Нет | Нет | Да | Нет
Поддержка rename() | Нет | Нет | Нет | Да | Нет
Поддержка mkdir() | Нет | Нет | Нет | Да | Нет
Поддержка rmdir() | Нет | Нет | Нет | Да | Нет

Опции контекста
Имя | Использование | По умолчанию
--- | --- | ---
`session` | Предварительно соединённый ресурс ssh2 для повторного использования |
`sftp` | Предварительно выделенный ресурс sftp для повторного использования |
`methods` | Обмен ключами, ключ хоста, шифр, компрессия и методы MAC для использования |
`callbacks` |  |
`username` | Имя пользователя для соединения |
`password` | Пароль для аутентификации |
`pubkey_file` | Имя файла, в котором находится открытый ключ для аутентификации |
`privkey_file` | Имя файла, в котором находится приватный ключ для аутентификации |
`env` | Ассоциативный массив с переменными окружения, которые необходимо установить |
`term` | Тип эмуляции терминала для запроса, когда выделяется pty |
`term_width` | Ширина терминала, запрашивается когда выделяется pty |
`term_height` | Высота терминала, запрашивается когда выделяется pty |
`term_units` | Единицы, в которых измеряются term_width и term_height | `SSH2_TERM_UNIT_CHARS`

### Примеры

Пример #1 Открытие потока из активного соединения

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
    ?>

Пример #2 Переменная $session должна быть доступна!

Для использования каких-либо из обёрток ssh2.*://$session, необходимо сохранить доступным ресурс, хранящийся в переменной $session. Следующий код не будет иметь желаемого эффекта:

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $connection_string = "ssh2.sftp://$session/";
    unset($session);
    $stream = fopen($connection_string . "path/to/file", 'r');
    ?>

unset() закрывает сессию, потому что $connection_string не является ссылкой на переменную $session, а только её текстовым представлением. Это также происходит и в случае неявного вызова unset() при выходе из области видимости (например, из функции).

# rar://

rar:// — RAR

### Описание

Эта обёртка принимает URL-кодированный путь к RAR-архиву (относительный или абсолютный), необязательный символ звёздочки (`*`), необязательный символ решётки (`#`) и необязательное URL-кодированное имя такое, как хранится в архиве. Для указания имени содержимого требуется символ решётки, начальный обратный слеш в названии содержимого необязателен.

Эта обёртка может открывать файлы и директории. Когда открываются директории, знак звёздочки требует, чтобы имена объектов директории были закодированы unencode. Если такой знак не указан, они будут возвращены в URL-кодировке. Смысл этого в том, чтобы позволить обёртке корректно использовать встроенную функциональность, такую как RecursiveDirectoryIterator когда присутствуют имена файлов, которые кажутся как url-закодированные данные.

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

> Замечание: Эта обёртка не включена по умолчанию
> Для того, чтобы использовать обёртку rar://, необходимо установить модуль » rar, доступный в репозитории » PECL.

rar:// Доступно начиная с PECL rar 3.0.0

### Использование

- rar://<url encoded archive name>[*][#[<url encoded entry name>]]

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Ограничение по allow_url_include | Нет
Чтение | Да
Запись | Нет
Добавление | Нет
Одновременное чтение и запись | Нет
Поддержка stat() | Да
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

Опции контекста
Название | Использование | По умолчанию
--- | --- | ---
`open_password` | Пароль используется для шифрования заголовков архива, если таковые есть. WinRAR будет шифровать все файлы с таким же паролем, как и пароль заголовков, когда последний присутствует. Поэтому для архивов с зашифрованными заголовками опция `file_password` будет проигнорирована. |
`file_password` | Пароль, используемый для шифрования файла, если таковой имеется. Если заголовки также зашифрованы, эта опция будет игнорирована в пользу `open_password`. Причина этого в том, что нет смысла в использовании одновременно двух разных паролей для шифрования отдельно заголовков и отдельно файлов. Нет таких архивов, где бы это пригодилось. Заметим, что если у архива отсутствуют зашифрованные заголовки, то опция `open_password` будет игнорирована и эта опция должна быть использована вместо неё. |
`volume_callback` | Обратный вызов для определения пути недостающих томов архива. Смотрите RarArchive::open() для более детальной информации. |

### Примеры

Пример #1 Обход RAR-архива

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

Пример #2 Открытие зашифрованного файла (шифрование заголовка)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* дата создания и дата последнего доступа включается опционально в WinRAR, поэтому у
     * большинства файлов их нет */
    var_dump(fstat($stream));
    ?>

Вывод приведённого примера будет похож на:

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — Аудиопотоки

### Описание

Файлы, открываемые для чтения с использованием обёртки ogg://, рассматриваются как сжатый аудиопоток, кодируемый с использованием кодека `OGG/Vorbis`. Аналогично, файлы, открытые для записи или добавления через обёртку ogg://, записываются как сжатые звуковые данные. Функция stream_get_meta_data(), когда используется с файлами `OGG/Vorbis` открытыми для чтения, будет возвращать разнообразную информацию о потоке, включая тег производителя `vendor`, комментарии `comments`, число каналов `channels`, частоту дискретизации `rate`, и диапазон частоты кодирования, описываемый: `bitrate_lower`, `bitrate_upper`, `bitrate_nominal` и `bitrate_window`.

ogg:// (PECL)

> Замечание: Данная обёртка не доступна по умолчанию
> Для того чтобы использовать обёртку ogg:// необходимо установить модуль » OGG/Vorbis, доступный в репозитории » PECL.

### Использование

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Чтение | Да
Запись | Да
Добавление | Да
Одновременное чтение и запись | Нет
Поддержка stat() | Нет
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

Установки для контекста
Название | Использование | Значение по умолчанию | Режим
--- | --- | --- | ---
`pcm_mode` | Опция PCM-кодирования, применяемая во время чтения, одна из констант: `OGGVORBIS_PCM_U8`, `OGGVORBIS_PCM_S8`, `OGGVORBIS_PCM_U16_BE`, `OGGVORBIS_PCM_S16_BE`, `OGGVORBIS_PCM_U16_LE` и `OGGVORBIS_PCM_S16_LE`. (8- или 16-битное, со знаком или без него, прямой или обратный порядок байтов) | OGGVORBIS_PCM_S16_LE | Чтение
`rate` | Частота дискретизации входных данных в Гц | 44100 | Запись или добавление
`bitrate` | Когда дано целое число, постоянный битрейт при котором кодировать. (от 16000 до 131072) Когда дано вещественное число, качество переменного битрейта для использования. (от -1.0 до 1.0) | 128000 | Запись или добавление
`channels` | Количество аудиоканалов для кодирования, обычно 1 (моно) или 2 (стерео). Может достигать 16. | 2 | Запись/Добавление
`comments` | Массив строковых значений для кодирования в заголовок трека. |  | Запись или добавление

# expect://

expect:// — Потоки для взаимодействия с процессами

### Описание

Потоки, открытые через обёртку expect://, предоставляют доступ к процессам stdin, stdout и stderr через псевдотерминальную утилиту PTY.

> Замечание: Эта обёртка отключена по умолчанию
> Чтобы использовать обёртку expect://, необходимо установить модуль » Expect, доступный в репозитории » PECL.

expect:// (PECL)

### Использование

- expect://command

### Опции

Основная информация
Атрибут | Поддержка
--- | ---
Ограничение по allow_url_fopen | Нет
Чтение | Да
Запись | Да
Добавление | Да
Одновременное чтение и запись | Нет
Поддержка stat() | Нет
Поддержка unlink() | Нет
Поддержка rename() | Нет
Поддержка mkdir() | Нет
Поддержка rmdir() | Нет

## Содержание

- file:// — Доступ к локальной файловой системе
- http:// — Доступ к URL-адресам по протоколу HTTP(s)
- ftp:// — Доступ к URL-адресам по протоколу FTP(s)
- php:// — Доступ к различным потокам ввода-вывода
- zlib:// — Сжатые потоки
- data:// — Схема Data (RFC 2397)
- glob:// — Нахождение путей, которые соответствуют шаблону
- phar:// — PHP-архив
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Аудиопотоки
- expect:// — Потоки для взаимодействия с процессами

- Основы синтаксиса
  - PHP-теги
  - Выход из режима HTML-разметки
  - Разделение инструкций
  - Комментарии
- Типы
  - Введение
  - Система типов
  - NULL
  - Логические значения
  - Целые числа
  - Числа с плавающей точкой
  - Строки
  - Числовые строки
  - Массивы
  - Объекты
  - Перечисления
  - Ресурсы
  - Вызываемые выражения
  - Mixed
  - Void
  - Never
  - Относительные типы классов
  - Одноэлементные типы
  - Итерируемые значения
  - Объявления типов
  - Жонглирование типами
- Переменные
  - Основы
  - Предопределённые переменные
  - Область видимости переменной
  - Переменные переменных
  - Переменные из внешних источников
- Константы
  - Синтаксис
  - Предопределённые константы
  - Магические константы
- Выражения
- Операторы
  - Приоритет — Приоритет оператора
  - Арифметика — Арифметические операторы
  - Инкремент и декремент — Операторы инкремента и декремента
  - Присваивание — Операторы присваивания
  - Побитовые операторы
  - Сравнение — Операторы сравнения
  - Управление ошибками — Оператор управления ошибками
  - Выполнение — Операторы выполнения
  - Логика — Логические операторы
  - Строки — Строковые операторы
  - Массивы — Операторы для работы с массивами
  - Проверка типа — Оператор проверки принадлежности типу
  - Функциональность — Функциональный оператор
- Управляющие конструкции
  - Введение
  - if
  - else
  - elseif/else if
  - Альтернативный синтаксис управляющих структур
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- Функции
  - Пользовательские функции
  - Параметры и аргументы функции
  - Возврат значений
  - Функции переменных
  - Внутренние, или встроенные, функции
  - Анонимные функции
  - Стрелочные функции
  - Синтаксис создания первоклассных callable-значений
- Классы и объекты
  - Введение
  - Основы
  - Свойства
  - Хуки свойств
  - Константы классов
  - Автоматическая загрузка классов
  - Конструкторы и деструкторы
  - Область видимости
  - Наследование
  - Оператор разрешения области действия ::
  - Ключевое слово static
  - Абстракция класса
  - Интерфейсы объектов
  - Трейты
  - Анонимные классы
  - Перегрузка
  - Итераторы объектов
  - Магические методы
  - Ключевое слово final
  - Клонирование объектов
  - Сравнение объектов
  - Позднее статическое связывание
  - Объекты и ссылки
  - Сериализация объектов — Сериализация объектов — сохранение объектов между сессиями
  - Ковариантность и контравариантность
  - Ленивые объекты
  - Журнал изменений ООП
- Пространства имён
  - Обзор — Обзор пространств имён
  - Пространства имён — Определение пространств имён
  - Подпространства имён — Определение подпространств имён
  - Несколько пространств имён в одном файле — Описание нескольких пространств имён в одном файле
  - Основы — Основы пространств имён
  - Пространства имён и динамические особенности языка
  - Ключевое слово namespace и константа __NAMESPACE__ — Ключевое слово namespace и магическая константа __NAMESPACE__
  - Псевдонимирование и импорт — Пространства имён: псевдонимирование и импорт
  - Глобальное пространство
  - Возврат к глобальному пространству — Пространства имён: возврат к глобальному пространству для функций и констант
  - Правила разрешения имён
  - FAQ — Часто задаваемые вопросы (FAQ): что нужно знать о пространствах имён
- Перечисления
  - Обзор перечислений
  - Основы перечислений
  - Типизированные перечисления
  - Методы перечислений
  - Статические методы перечислений
  - Константы перечислений
  - Трейты
  - Значения перечисления в постоянных выражениях
  - Отличия от объектов
  - Список значений
  - Сериализация
  - Почему перечисления нерасширяемы
  - Примеры
- Ошибки
  - Основы
  - Ошибки в PHP 7
- Исключения
  - Наследование исключений
- Fibers
- Генераторы
  - Знакомство с генераторами
  - Синтаксис генераторов
  - Сравнение генераторов с объектами класса Iterator
- Атрибуты
  - Введение в атрибуты
  - Синтаксис атрибутов
  - Чтение атрибутов через API-интерфейс модуля Reflection
  - Объявление классов атрибутов
- Объяснение ссылок
  - Что такое ссылки
  - Что делают ссылки
  - Что ссылки собой не представляют
  - Передача по ссылке
  - Возврат ссылок
  - Удаление ссылок
  - Неявная работа механизма ссылок
- Предопределённые переменные
  - Суперглобальные переменные — Встроенные переменные, которые всегда доступны во всех областях
  - $GLOBALS — Ссылается на переменные глобальной области видимости
  - $_SERVER — Информация о сервере и среде исполнения
  - $_GET — Переменные строки запроса
  - $_POST — Данные форм из запросов HTTP-методом POST
  - $_FILES — Переменные файлов, загруженных по HTTP
  - $_REQUEST — Переменные HTTP-запроса
  - $_SESSION — Переменные сессии
  - $_ENV — Переменные окружения
  - $_COOKIE — HTTP Cookies
  - $php_errormsg — Предыдущее сообщение об ошибке
  - $http_response_header — Заголовки HTTP-ответа
  - $argc — Количество аргументов, переданных скрипту
  - $argv — Массив аргументов, которые передали скрипту
- Предопределённые исключения
  - Exception — Исключение Exception
  - ErrorException — Исключение ErrorException
  - ClosedGeneratorException — Исключение ClosedGeneratorException
  - Error — Ошибка Error
  - ArgumentCountError — Ошибка ArgumentCountError
  - ArithmeticError — Ошибка ArithmeticError
  - AssertionError — Ошибка AssertionError
  - DivisionByZeroError — Ошибка DivisionByZeroError
  - CompileError — Ошибка CompileError
  - ParseError — Ошибка ParseError
  - TypeError — Ошибка TypeError
  - ValueError — Ошибка ValueError
  - UnhandledMatchError — Ошибка UnhandledMatchError
  - FiberError — Ошибка FiberError
  - RequestParseBodyException — Исключение RequestParseBodyException
- Встроенные интерфейсы и классы
  - Traversable — Интерфейс Traversable
  - Iterator — Интерфейс Iterator
  - IteratorAggregate — Интерфейс IteratorAggregate
  - InternalIterator — Класс InternalIterator
  - Throwable
  - Countable — Интерфейс Countable
  - ArrayAccess — Интерфейс ArrayAccess
  - Serializable — Интерфейс Serializable
  - Closure — Класс Closure
  - stdClass — Класс stdClass
  - Generator — Класс Generator
  - Fiber — Класс Fiber
  - WeakReference — Класс WeakReference
  - WeakMap — Класс WeakMap
  - Stringable — Интерфейс Stringable
  - UnitEnum — Интерфейс UnitEnum
  - BackedEnum — Интерфейс BackedEnum
  - SensitiveParameterValue — Класс SensitiveParameterValue
  - __PHP_Incomplete_Class — Класс __PHP_Incomplete_Class
- Предопределённые атрибуты
  - Attribute — Атрибут Attribute
  - AllowDynamicProperties — Атрибут AllowDynamicProperties
  - DelayedTargetValidation — Атрибут DelayedTargetValidation
  - Deprecated — Атрибут Deprecated
  - NoDiscard — Атрибут NoDiscard
  - Override — Атрибут Override
  - ReturnTypeWillChange — Атрибут ReturnTypeWillChange
  - SensitiveParameter — Атрибут SensitiveParameter
- Опции и параметры контекста
  - Контекстные опции сокета — Список контекстных опций сокета
  - Опции HTTP-контекста — Список опций HTTP-контекста
  - Параметры FTP-контекста — Список параметров FTP-контекста
  - Опции SSL-контекста — Список опций SSL-контекста
  - Опции Phar-контекста — Список опций контекста модуля Phar
  - Параметры контекста — Список параметров контекста
  - Опции Zip-контекста — Список опций Zip-контекста
  - Опции Zlib-контекста — Список опций контекста модуля Zlib
- Протоколы и обёртки
  - file:// — Доступ к локальной файловой системе
  - http:// — Доступ к URL-адресам по протоколу HTTP(s)
  - ftp:// — Доступ к URL-адресам по протоколу FTP(s)
  - php:// — Доступ к различным потокам ввода-вывода
  - zlib:// — Сжатые потоки
  - data:// — Схема Data (RFC 2397)
  - glob:// — Нахождение путей, которые соответствуют шаблону
  - phar:// — PHP-архив
  - ssh2:// — Secure Shell 2
  - rar:// — RAR
  - ogg:// — Аудиопотоки
  - expect:// — Потоки для взаимодействия с процессами

# Безопасность

# Вступление

PHP — мощный язык программирования и интерпретатор. Независимо от того, включается ли PHP в состав веб-сервера как модуль или исполняется как отдельное бинарное CGI-приложение, PHP умеет получать доступ к файлам, исполнять команды и открывать сетевые соединения на сервере. Эти свойства по умолчанию делают всё, что выполняется на веб-сервере, небезопасным. PHP разрабатывался как более безопасный язык для CGI-программ, чем языки программирования Perl или C, и при правильных настройках конфигурации времени компиляции и выполнения, а также правильных практиках программирования PHP даёт сочетание свободы и безопасности, которое требуется разработчикам.

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

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

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

# Общие соображения

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

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

Пословица, которую лучше бы запомнить: где тонко, там и рвётся — надёжность системы зависит от надёжности самого слабого звена. Связь записей лога транзакций с пользователями сильно снижается, если тщательно логируется время каждой транзакции, место, тип операции и другая информация о транзакции, но пользователь проверяется только на основе одного блока cookie.

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

В интернете часто ищут славы за счёт взлома кода, разрушения сайта, публикации неуместного материала или другими способами делают день разработчика «интереснее». Неважно, идёт речь о маленьком сайте или о портале, сервер становится мишенью только потому что доступен для подключений. Программы-взломщики не смотрят на размер, а слепо перебирают IP-адреса в поисках жертвы. Разработчики следят за безопасностью кода, чтобы предотвратить попытки злоумышленников обойти защиту.

# О безопасности PHP в режиме CGI-программы

## Содержание

- Возможные атаки
- Вариант 1: обслуживание только общедоступных файлов
- Вариант 2: включение директивы cgi.force_redirect
- Вариант 3: включение директив doc_root или user_dir
- Вариант 4: PHP вне дерева веб-документов

## Возможные атаки

Установка PHP в виде двоичного файла, который взаимодействует с веб-сервером по протоколу CGI, представляет альтернативу интегрированию PHP в серверное ПО наподобие веб-сервера Apache в виде модуля и альтернативу установкам, которым придётся использовать PHP с набором CGI-обёрток, чтобы сделать окружения для скриптов безопасными в части установки утилитами chroot и setuid корневого каталога и идентификатора пользователя, от имени которого выполнится скрипт. При установке PHP в виде CGI-программы исполняемый двоичный файл php часто устанавливают в каталог веб-сервера cgi-bin. Компьютерная группа реагирования на чрезвычайные ситуации (англ. Computer Emergency Response Team, CERT) подготовила рекомендацию » CA-96.11, в которой не советует располагать интерпретаторы в каталоге cgi-bin. Двоичный файл php спроектировали так, чтобы даже при работе в качестве автономного интерпретатора файл защищал от атак, риск которых появляется при установке PHP в режиме CGI:

- Доступ к системным файлам через запрос вида: http://my.host/cgi-bin/php?/etc/passwd. Информация в query-компоненте, который URL-адрес запроса содержит после вопросительного знака (`?`), передаётся интерпретатору через CGI-интерфейс как аргументы командной строки. Стандартное поведение интерпретатора — открыть и исполнить в командной строке файл, который указали как первый аргумент запроса. В режиме CGI-обработчика php не станет интерпретировать аргументы командной строки.
- Доступ к произвольному документу на сервере: http://my.host/cgi-bin/php/secret/doc.html. Информация в path-части URL-адреса наподобие /secret/doc.html, которая идёт после названия двоичного файла PHP, указывает название файла, который CGI-программа откроет и интерпретирует. Отдельные директивы конфигурации наподобие директивы `Action` в конфигурации веб-сервера Apache указывают, чтобы перенаправить запрос к документам вида http://my.host/secret/script.php к интерпретатору PHP. При такой настройке веб-сервер сначала проверяет права доступа к каталогу /secret, а затем создаёт и перенаправляет запрос к файлу http://my.host/cgi-bin/php/secret/script.php. К сожалению, веб-сервер проверит права доступа только к файлу /cgi-bin/php, но не проверит права доступа к файлу /secret/script.php, если запрос в самом начале задали в полной форме. Поэтому пользователи с доступом к файлу /cgi-bin/php получат доступ к защищённым документам на сервере. Для предотвращения атак, которые направляют на каталоги с ограничениями доступа, если такие содержит дерево документов сервера, в PHP пользуются директивами конфигурации cgi.force_redirect, doc_root и user_dir, которые PHP учитывает при выполнении кода. Подробнее опции и их комбинации рассматривают следующие главы раздела.

## Вариант 1: обслуживание только общедоступных файлов

Опциями, которые упоминает предыдущая глава раздела, не пользуются, если на сервере нет файлов, доступ к которым ограничили паролем или фильтром по IP-адресам. В ситуации, при которой веб-сервер не разрешает выполнять перенаправления или у сервера нет способа сообщить исполняемому PHP-файлу о безопасном перенаправлении запроса, включают ini-директиву cgi.force_redirect. Но при этом по-прежнему требуется убедиться, что альтернативные способы вызова скрипта наподобие непосредственного вызова файла http://my.host/cgi-bin/php/dir/script.php или вызова с переадресацией к файлу http://my.host/dir/script.php недоступны.

На веб-сервере Apache перенаправление конфигурируют через директивы `AddHandler` и `Action`, которые описывает следующая глава раздела.

## Вариант 2: включение директивы `cgi.force_redirect`

Конфигурационная директива cgi.force_redirect запрещает прямой вызов php по URL-адресу, похожему на http://my.host/cgi-bin/php/secretdir/script.php. В этом режиме вместо прямого вызова PHP разберёт поступивший запрос, только если запрос перенаправил веб-сервер.

Перенаправление в конфигурации Apache чаще настраивают через следующие директивы:

    Action php-script /cgi-bin/php
    AddHandler php-script .php

Опцию конфигурации протестировали только с веб-сервером Apache/ При установке нестандартной переменной CGI-окружения REDIRECT_STATUS для перенаправленных запросов опция полагается на веб-сервер Apache. Нельзя пользоваться этой опцией конфигурации, если веб-сервер не поддерживает способы определения прямых и перенаправленных запросов, и лучше запускать CGI-версии PHP другими способами, которые описывает раздел.

## Вариант 3: включение директив doc_root или user_dir

Включение в каталоги документов веб-сервера активного содержимого наподобие скриптов и исполняемых файлов ослабляет безопасность. Из-за ошибок в конфигурации сервера, когда скрипты не выполняются, а отображаются в браузере как HTML-документы, утекает интеллектуальная собственность или конфиденциальная информация наподобие паролей. Поэтому системные администраторы отдают преимущество настройке другой структуры каталогов хранения скриптов, к которым открывают доступ только через CGI-интерфейс PHP, который гарантирует интерпретацию, а не вывод кода скриптов.

Потребуется установить через директиву doc_root корневой каталог, который отличается от корневого каталога веб-документов, если метод, который проверяет запросы на перенаправление, как описывает предыдущая глава, недоступен.

Корневой каталог для PHP-скриптов устанавливают в файле конфигурации PHP через директиву doc_root или через переменную окружения PHP_DOCUMENT_ROOT. При установке корневого каталога для PHP-скриптов CGI-версия двоичного файла PHP сформирует путь к файлу, который требуется открыть, на основе значения директивы `doc_root` и пути, который указали в запросе. Это гарантирует, что скрипты за пределами этого каталога, за исключением каталога `user_dir`, не выполнятся.

Другая директива, которая помогает создавать безопасные пути к файлам, — user_dir. Путём к файлу, который требуется открыть, управляет только директива `doc_root`, если директиву `user_dir` не установили. При запросе URL-адреса наподобие http://my.host/~user/doc.php обработчик откроет файл с названием ~user/doc.php (да, название каталога начинается с символа `~`) в каталоге, который установили в директиве `doc_root`, а не файл в домашнем каталоге пользователей.

Но если для директивы `user_dir` установили значение наподобие public_php, то запрос URL-адреса http://my.host/~user/doc.php откроет файл doc.php, который лежит в домашнем каталоге пользователя в директории public_php. Приведём пример. Обработчик выполнит файл /home/user/public_php/doc.php, если домашний каталог пользователя /home/user.

PHP разворачивает значение директивы `user_dir` независимо от настройки директивы `doc_root`, поэтому управлять корневым каталогом документов веб-сервера и каталогом пользователя разрешается по отдельности.

## Вариант 4: PHP вне дерева веб-документов

Безопасность значительно повышается за счёт переноса двоичного файла PHP-парсера за пределы дерева веб-файлов, в каталог наподобие /usr/local/bin. Единственный недостаток такого способа состоит в том, в первую строку каждого файла с PHP-тегами придётся вставить аргумент:

    #!/usr/local/bin/php

Аналогично другим CGI-скриптам, которые написали на языке Perl, sh или другом скриптовом языке общего назначения, который использует символы `#!` — механизм shell-экранирования для запуска самого себя, потребуется сделать каждый файл скрипта исполняемым.

Для корректной обработки PHP-интерпретатором переменных окружения PATH_INFO и PATH_TRANSLATED потребуется включить ini-директиву cgi.discard_path.

# Если PHP установлен как модуль Apache

Если PHP используется как модуль Apache, он наследует права пользователя, с которыми был запущен веб-сервер (обычно это пользователь "nobody"). Это влияет на обеспечение безопасности и реализацию авторизации. Например, если вы используете PHP для доступа к базе данных, которая не имеет встроенного механизма разграничения доступа, вам придётся обеспечить доступ к БД для пользователя 'nobody'. В таком случае вредоносный скрипт может получить доступ к базе данных и модифицировать её, даже не зная логина и пароля. Вполне возможна ситуация, при которой веб-паук неверными запросами на страницу администратора базы данных может уничтожить все ваши базы данных. Вы можете избежать такой ситуации при помощи авторизации Apache или разработав собственную модель доступа, используя LDAP, файлы .htaccess или любые другие технологии, внедряя соответствующий код в ваши PHP-скрипты.

Достаточно часто используются такие настройки безопасности, при которых PHP (имеется в виду пользователь, с правами которого выполняется Apache) имеет минимальные привилегии, например, отсутствует возможность записи в пользовательские директории с помощью PHP. Или, например, отсутствует возможность работать с базой данных. При этом система безопасности не позволяет записывать как "хорошие", так и "плохие" файлы, или провести "хорошие" или "плохие" транзакции.

Распространённой ошибкой является запуск Apache с правами суперпользователя или любое другое расширение полномочий веб-сервера.

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

Существует несколько простых решений. Используя open_basedir, вы можете ограничить дерево доступных директорий для PHP. Вы так же можете определить область доступа Apache, ограничив все действия, совершаемые из веба не пользовательскими или несистемными файлами.

# Безопасность сессий

Поддерживать безопасность при управлении HTTP-сессиями — важный фактор защиты конфиденциальных данных. О защите сессий рассказывает раздел «Безопасность сессий» руководства к модулю Session.

# Безопасность файловой системы

## Содержание

- Нулевые байты и безопасность

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

Поскольку PHP разработали для доступа к файловой системе на уровне пользователя, можно написать PHP-скрипт, который разрешит читать системные файлы наподобие /etc/passwd, изменять Ethernet-соединения, отправлять большие задания на печать и т. д. У этого есть ряд последствий, и поэтому нужно убедиться, что не возникла ошибка с выбором файла, который разработчик читает и в который записывает данные.

Рассмотрим следующий скрипт, в котором пользователь указывает, что хотел бы удалить файл из пользовательского домашнего каталога. Это предполагает, что управление файлами регулярно использует веб-интерфейс PHP, поэтому пользователю веб-сервера Apache разрешается удалять файлы в домашних каталогах пользователя.

Пример #1 Недостаточная проверка переменных приводит к…

    <?php

    // Удаление файла из домашней директории пользователя
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "Скрипт удалил файл!";

    ?>

Поскольку имя пользователя и название файла приходят из пользовательской формы, не исключается риск подмены и удаления данных, которые принадлежат другому пользователю, даже если у пользователя не было разрешения на удаление данных. Тогда требуется аутентификация. Посмотрим, что произойдёт, если отправить значения `"../etc/"` и `"passwd"`. Тогда код будет выглядеть вот так:

Пример #2 …атаке на файловую систему

    <?php

    // Удаляем файл из произвольного места на жестком диске,
    // к которому у пользователя PHP-скрипта есть доступ. Если PHP работает с правами суперпользователя:
    $username = $_POST['user_submitted_name']; // В переменной передали значение "../etc"
    $userfile = $_POST['user_submitted_filename']; // В переменной передали значение "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "Скрипт удалил файл!";

    ?>

Атаки предотвращают двумя способами.

- Ограничивают права доступа на двоичный файл веб-пользователя PHP.
- Проверяют каждую переменную, которую передают пользователи.

Вот улучшенный вариант кода:

Пример #3 Более безопасная проверка имени файла

    <?php

    // Удаляем файл из произвольного места на жестком диске,
    // к которому у пользователя PHP-скрипта есть доступ.
    $username = $_SERVER['REMOTE_USER']; // Проверяем, прошёл ли пользователь аутентификацию
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
        $logstring = "Функция удалила файл $filepath\n";
    } else {
        $logstring = "Не удалось удалить файл $filepath\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);

    ?>

Однако даже такая проверка не лишена недостатков. Если система аутентификации разрешает пользователям создавать произвольные логины, и взломщик выбрал логин `"../etc/"`, система снова становится уязвимой. Поэтому предпочитают более строгую проверку:

Пример #4 Более строгая проверка имени файла

    <?php

    $username     = $_SERVER['REMOTE_USER']; // Проверяем, прошёл ли пользователь аутентификацию
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
        die("Неправильное имя пользователя или файл");
    }

    // и т. д.

    ?>

Набор файлов, за которыми придётся следить разработчику, определяет операционная система, и включает системные файлы устройств /dev/ или COM1, конфигурационные файлы /etc/ и файлы с расширением `.ini`, хорошо известные области хранения файлов /home/, Мои документы и так далее. Поэтому обычно проще создать политику безопасности, которая запрещает всё, кроме того, что явно разрешили.

## Нулевые байты и безопасность

Поскольку для работы с файловой системой PHP внутренне вызывает функции языка C, он иногда обрабатывает нулевые байты неожиданным образом. Поскольку в C нулевые байты обозначают конец строки, PHP не принимает всю строку с NUL-байтом, а только до позиции перед нулевым байтом. Следующий пример содержит уязвимый код, который показывает проблему:

Пример #1 Пример уязвимого скрипта с NUL-байтом

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"

    if (file_exists('/home/wwwrun/' . $file . '.php')) {
        // Функция file_exists() вернёт true, поскольку путь /home/wwwrun/../../etc/passwd существует
        include '/home/wwwrun/' . $file . '.php';

        // PHP подключит файл /etc/passwd
    }

    ?>

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

Пример #2 Корректная проверка входных данных

    <?php

    $file = $_GET['file'];

    // Белый список возможных значений
    switch ($file) {
        case 'main':
        case 'foo':
        case 'bar':
            include '/home/wwwrun/include/' . $file . '.php';
            break;
        default:
            include '/home/wwwrun/include/main.php';
    }

    ?>

# Безопасность баз данных

## Содержание

- Проектирование баз данных
- Соединение с базой данных
- Шифрование хранилища базы данных
- SQL-инъекции

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

Чтобы получить или сохранить информацию, необходимо подключиться к базе данных, отправить законный запрос, получить результат и закрыть соединение. Наиболее распространённый язык запросов в таком взаимодействии — язык структурированных запросов SQL. Подробнее о подделке SQL-запросов рассказывает раздел «SQL-инъекции».

Нетрудно догадаться, что сам PHP не защищает базу данных. Этот раздел документации вводит основы безопасного доступа и управления базами данных в PHP-скриптах.

Требуется помнить простое правило: глубокая защита. Чем шире меры по защите базы данных, тем меньше вероятность того, что злоумышленник раскроет или злоупотребит сохранённой информацией. Хороший проект структуры базы данных и приложения помогает справиться с опасениями.

## Проектирование баз данных

Первый шаг — создать базу данных или выбрать готовую БД, которую предоставила третья сторона. При этом БД назначается владельцу, который выполнил запрос, который создал базу данных. Обычно только владельцу или суперпользователю разрешается выполнять действия с объектами в базе данных, а чтобы разрешить эти действия другим пользователям, пользователей наделяют привилегиями.

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

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

## Соединение с базой данных

Возможно, для повышения безопасности потребуется устанавливать соединения по SSL-протоколу, чтобы зашифровать сообщения между клиентом и сервером, или подключаться по SSH-протоколу, чтобы зашифровать сетевое соединение между клиентами и сервером базы данных. Каждый из этих способов связи затруднит злоумышленнику отслеживание трафика и получение информации о базе данных.

## Шифрование хранилища базы данных

Протоколы SSL и SSH защищают данные, которые передаются от клиента к серверу: эти протоколы не защищают постоянные данные, которые хранятся в базе данных. Протокол SSL — протокол шифрования на уровне сеанса передачи данных.

Злоумышленник сможет раскрыть или использовать конфиденциальные данные не по назначению, как только получит прямой (в обход веб-сервера) доступ к базе данных, если только база данных не защищает информацию. Шифрование данных снижает риск угрозы, но немногие базы данных предлагают такой тип шифрования данных.

Простейший способ защитить информацию — вначале установить пакет для шифрования данных, а затем использовать этот пакет в PHP-скриптах. PHP помогает в этом и предлагает модули вроде OpenSSL и Sodium, которые покрывают широкий круг алгоритмов шифрования. Скрипт шифрует данные перед вставкой в базу данных и расшифровывает данные при извлечении. В следующих параграфах документация приводит примеры шифрования.

### Хеширование

При работе со скрытыми данными, которые требуют повышенного внимания, данные хешируют, если не требуется необработанное представление данных, — то, которое не требуется показывать. Популярный пример данных, которые требуют хеширования, — хранение криптографического хеша пароля в БД вместо хранения самого пароля.

Функции, которые работают с паролями, помогают удобно хешировать конфиденциальные данные и работать с этими хешами.

Функция password_hash() хеширует заданную строку самым стойким из доступных алгоритмом, а функция password_verify() проверяет, совпадает ли заданный пароль с хешем, который хранится в базе данных.

Пример #1 Хеширование полей с паролями

    <?php

    // Сохраняем хеш пароля
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($username),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // Проверяем правильность пароля, который ввёл пользователь
    $query = sprintf("SELECT pwd FROM users WHERE name='%s';",
                pg_escape_string($username));
    $row = pg_fetch_assoc(pg_query($connection, $query));

    if ($row && password_verify($password, $row['pwd'])) {
        echo 'Добро пожаловать, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'Ошибка авторизации, ' . htmlspecialchars($username) . '.';
    }

    ?>

## SQL-инъекции

SQL-инъекция — техника, при которой злоумышленник пользуется недостатками в коде приложения, который отвечает за построение динамических SQL-запросов. Злоумышленник получает доступ к привилегированным разделам приложения, получает информацию из базы данных, подменяет данные или даже выполняет опасные команды системного уровня на узле базы данных. Уязвимость возникает, когда разработчики конкатенируют или интерполируют произвольные входные данные в SQL-запросах.

Пример #1 Постраничный вывод результата и… создание суперпользователя в СУБД PostgreSQL

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

    <?php

    $offset = $_GET['offset']; // Осторожно, нет валидации ввода!
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);

    ?>

В стандартном сценарии пользователи нажимают на ссылки «Вперёд» и «Назад», в URL-адресах которых закодировано смещение, значение которого получает переменная $offset. Скрипт ожидает, что входящее значение для переменной $offset — число. Однако, что если взломщик выполнит попытку взломать систему и добавит к URL-адресу следующее значение:

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
      select 'crack', usesysid, 't','t','crack'
      from pg_shadow where usename='postgres';
    --

Если бы это случилось, скрипт предоставил бы злоумышленнику доступ суперпользователя. Обратите внимание, что значение `0;` записали, чтобы передать правильное смещение для исходного запроса и завершить запрос.

> Замечание:

> Распространённый приём, который заставляет SQL-парсер игнорировать остальную часть запроса разработчика, — последовательность символов `--`, которая играет в SQL роль синтаксиса комментариев.

Ещё один способ раскрыть пароли учётных записей в БД — атаковать страницы с результатами поиска. Злоумышленнику требуется только проверить, есть ли в запросе к серверу переменные, которые попадут в SQL-запрос и которые не обрабатываются правильно. Эти фильтры обычно устанавливают в форме перед выполнением поиска, чтобы изменить поведение условий `WHERE, ORDER BY, LIMIT` и `OFFSET` в запросе `SELECT`. Если база данных поддерживает конструкцию `UNION`, злоумышленник попробует добавить к оригинальному запросу ещё один, чтобы вывести список паролей из произвольной таблицы. Настоятельно рекомендуется хранить только зашифрованные пароли.

Пример #2 Вывод списка статей… и ряда паролей (любой сервер базы данных)

    <?php

    $query  = "SELECT id, name, inserted, size FROM products
             WHERE size = '$size'";
    $result = odbc_exec($conn, $query);

    ?>

Статическую часть запроса комбинируют с другим `SELECT`-запросом, который раскроет все пароли:

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

Инструкции `UPDATE` и `INSERT` также подвержены таким атакам.

Пример #3 От сброса пароля до… получения дополнительных привилегий (любой сервер баз данных)

    <?php

    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";

    ?>

Если злоумышленник отправляет значение `' or uid like'%admin%'` для переменной $uid, чтобы изменить пароль администратора, или просто присваивает переменной $pwd значение `hehehe', trusted=100, admin='yes`, чтобы получить дополнительные привилегии, тогда запросы переплетаются:

    <?php

    // Значение переменной $uid: ' or uid like '%admin%
    $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

    // Значение переменной $pwd: hehehe', trusted=100, admin='yes
    $query = "UPDATE usertable SET pwd='hehehe', trusted=100, admin='yes' WHERE
    ...;";

    ?>

Хотя остаётся ясным, что для успешной атаки злоумышленнику нужны хотя бы частичные знания об архитектуре базы данных, эту информацию часто получают легко. Например, когда код — часть открытого программного обеспечения и лежит в открытом доступе. Информация также раскрывается и закрытым исходным кодом, даже если код закодировали, обфусцировали или скомпилировали, и даже собственным кодом через отображение сообщений об ошибках. Другие методы включают подстановку типичных имён таблиц и столбцов: форма входа в систему, которая использует таблицу users с именами столбцов id, username и password.

Пример #4 Атака на операционную систему сервера базы данных (MSSQL Server)

Страшный пример получения доступа к командам уровня операционной системы на отдельных хостах баз данных.

    <?php

    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);

    ?>

Если злоумышленник отправит значение `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` для переменной $prod, то переменная $query будет равна:

    <?php

    $query  = "SELECT * FROM products
             WHERE id LIKE '%a%'
             exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
    $result = mssql_query($query);

    ?>

MSSQL Server выполняет пакетные SQL-запросы, включая команду для добавления нового пользователя в базу данных локальных учётных записей. Если бы это приложение запустили от имени суперадминистратора `sa`, а службу MSSQLSERVER запустили бы с достаточными привилегиями, у злоумышленника появилась бы учётная запись с доступом к локальной машине.

> Замечание:

> Часть приведённых примеров привязана к конкретному серверу базы данных, но это не говорит о невозможности похожей атаки на другие продукты. Сервер базы данных подвержен и другим уязвимостям.

Изображение любезно предоставил сайт веб-комиксов » xkcd

### Техники защиты

Рекомендуемый способ избежать SQL-инъекций — связать данные подготовленными инструкциями. Параметризованных запросов недостаточно, чтобы на 100 процентов избежать внедрения SQL-инъекций, но это простейший и безопасный способ передать входные данные SQL-инструкциям. Литералы динамических данных в условиях `WHERE`, `SET` и `VALUES` требуется заменить заполнителями. Сервер базы данных свяжет фактические данные при выполнении и отправит отдельно от SQL-команды.

Сервер применяет связывание параметров только для данных. Другие динамические части SQL-запроса требуется отфильтровать по известному списку разрешённых значений.

Пример #5 Избегание SQL-инъекций средствами подготовленных инструкций модуля PDO

    <?php

    // Динамическая часть SQL-запроса проверяется на соответствие ожидаемым значениям
    $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
    $productId = $_GET['productId'];

    // SQL-запрос подготавливается с заполнителем
    $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");

    // Значение передаётся с подстановочными знаками LIKE
    $stmt->execute(["%{$productId}%"]);

    ?>

Подготовленные инструкции предоставляют модули PDO, MySQLi и другие библиотеки баз данных.

Атаки с внедрением SQL-инъекций обычно основаны на коде, который написали без учёта требований безопасности. Разработчик не должен доверять никаким входным данным, особенно со стороны клиента, даже если входные значения поступают из HTML-блока SELECT, скрытого поля ввода или из cookie. Первый пример показывает, что такой простой запрос легко приводит к катастрофе.

Стратегия глубокой защиты включает набор практик хорошего кода:

- Не подключайтесь к базе данных как суперпользователь или владелец базы данных. Используйте только пользователей с минимальными привилегиями.
- Проверяйте входные данные на соответствие типу, который ожидался. В PHP содержится много функции для проверки входных данных, от простейших функций для работы с переменными наподобие функции is_numeric() и функций проверки типа символов наподобие функции ctype_digit() и далее к поддержке Perl-совместимых регулярных выражений.
- Если приложение ожидает числовые входные данные, рассмотрите применимость проверки данных функцией ctype_digit(), незаметно измените тип входных данных функцией settype() или получите числовое представление входных данных функцией sprintf().
- Если на уровне базы данных не поддерживается связывание переменных, возьмите в кавычки каждое пользовательское нечисловое значение, которое передаётся в БД через характерную для конкретной базы данных функцию экранирования строки: mysql_real_escape_string(), sqlite_escape_string() и т. д. Общие функции наподобие addslashes() полезны только в конкретных средах (например, СУБД MySQL в однобайтовой кодировке с отключённым режимом NO_BACKSLASH_ESCAPES), поэтому при работе с БД лучше избегать таких функций.
- Ни в каком случае не выводите информации о БД, особенно о структуре. Дополнительную информацию дают разделы «Сообщения об ошибках» и «Функции обработки и логирования ошибок».

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

# Сообщения об ошибках

С точки зрения PHP-безопасности вывод ошибок несёт как вред, так и пользу.

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

Пример #1 Атака на переменные в HTML-странице

    <form method="post" action="attacktarget?username=badfoo&amp;password=badfoo">
        <input type="hidden" name="username" value="badfoo" />
        <input type="hidden" name="password" value="badfoo" />
    </form>

При отладке сообщения об ошибках в PHP-коде возвращают полезную для разработчика информацию: показывают функцию, номер строки в файле или PHP-файл, в которых произошёл сбой. Эта информация помогает злоумышленнику во взломе. PHP-разработчик часто пользуется функциями show_source(), highlight_string() и highlight_file() как методами отладки, но на живых сайтах это раскрывает скрытые переменные, непроверенный синтаксис и другую опасную информацию. Повышенную опасность несёт запуск в публичных частях сайта открытого исходного кода со встроенными механизмами и методами отладки. Злоумышленник попытается взломать страницу методом перебора, или «грубой силы» (англ. brute force), путём отправки общих строк отладки, если узнает, какой техникой отладки пользуется разработчик:

Пример #2 Пример стандартных отладочных переменных

    <form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
        <input type="hidden" name="errors" value="Y" />
        <input type="hidden" name="showerrors" value="1" />
        <input type="hidden" name="debug" value="1" />
    </form>

Открытость системы к проверке ошибок снабжает злоумышленника дополнительной информацией независимо от метода обработки ошибок.

Сам стиль стандартной информации о PHP-ошибке указывает, что система работает на PHP. При просмотре `.html`-страницы и исследовании бэкенда в поиске слабых мест в системе, взломщик вводит неверные данные и узнаёт, что систему построили на PHP.

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

Вывод информации об ошибках в файловой системе или стандартных PHP-ошибок сообщает, с какими привилегиями запустили веб-сервер, и как организовали каталоги сервера. Коды ошибок в отладочной информации, которые записал разработчик, усугубляют проблему и упрощают доступ к информации, которая раньше была «скрыта».

Проблему решают тремя базовыми способами. Первый способ — тщательно изучить каждую функцию и компенсировать бо́льшую часть ошибок. Второй — отключить вывод сообщений об ошибках в запущенном коде. И третий способ — использовать функции, которые устанавливают пользовательский обработчик PHP-ошибок. Иногда защищаются всеми тремя способами, в зависимости от политики безопасности, которую принял для себя разработчик.

Способ заранее обнаружить проблему вывода конфиденциальной информации — изменить уровень сообщений об ошибках в PHP-коде функцией error_reporting(), которая помогает защитить код и выявить опасные переменные. На время тестирования кода, перед развёртыванием в рабочей среде, вывод сообщений об ошибках устанавливают на уровень `E_ALL`, с которым быстро находят области, в которых переменные открываются для «заражения» — подмены или модификации. С момента готовности кода к развёртыванию требуется вызывать функцию error_reporting() со значением 0, чтобы отключить вывод сообщений об ошибках, либо отключить вывод ошибок в файле php.ini — через директиву `display_errors`, чтобы изолировать код от проверки. Разработчику потребуется также определить путь к файлу лога через директиву `error_log` и включить директиву `log_errors`.

Пример #3 Поиск опасных переменных с выводом ошибок уровня E_ALL

    <?php

    if ($username) {  // Переменную $username не инициализировали — не установили начальное значение — и не проверили
        $good_login = 1;
    }

    if ($good_login == 1) { // Переменная $good_login не проинициализируется, а проверка не пройдёт,
                            // если предыдущая проверка провалится
        readfile ("/highly/sensitive/data/index.html");
    }

    ?>

# Данные пользовательского ввода

Наиболее опасные уязвимости в PHP-скриптах часто возникают не столько из-за самого языка, сколько из-за кода, который написали с нарушением требований безопасности. Поэтому лучше потратить время на исследование разрабатываемого участка кода, чтобы оценить потенциальную угрозу от ввода переменной с нестандартным значением.

Пример #1 Потенциально опасная обработка переменных

    <?php

    // Удалить файлы из домашней директории пользователя...
    // а может, и ещё из какой-то?
    unlink($evil_var);

    // Записать в лог-файл выполняемое действие...
    // а может, в файл /etc/passwd?
    fwrite($fp, $evil_var);

    // Выполнение тривиальных действий... или команды rm -rf *?
    system($evil_var);
    exec($evil_var);

    ?>

Требуется тщательно проверять код и быть на 100 % уверенным в правильной проверке данных, которые передаёт браузер. Ответьте на следующие вопросы:

- Влияет ли скрипт только на предполагаемые данные?
- Обрабатываются ли некорректные или нестандартные данные?
- Получится ли использовать скрипт способом, который не предусмотрели?
- Возможно ли использовать скрипт в сочетании с другими скриптами в негативных целях?
- Правильно ли логируется каждая транзакция?

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

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

Директива `register_globals` и директивы механизма `magic_quotes`, которые удалили в PHP 5.4.0, когда-то способствовали этим рискам, поскольку автоматически создавали переменные из пользовательского ввода и экранировали данные непоследовательно. Хотя директивы удалили из PHP, аналогичные риски сохраняются, когда входные данные обрабатывают неправильно.

Вызов error_reporting(E_ALL) включает режим сообщения об ошибках всех уровней и помогает определять неинициализированные переменные и проверять входные данные. Инструкция declare(strict_types=1) включает режим строгой типизации, который появился в PHP 7 и который повышает безопасность за счёт строгой проверки типов, предотвращает непреднамеренное преобразование типов и повышает общую безопасность.

# Сокрытие PHP

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

Несколько несложных методик могут помочь вам скрыть PHP, что усложняет работу потенциального взломщика, который пытается найти брешь в вашей системе. Установив опцию expose_php в `off` в конфигурационном файле php.ini, вы уменьшите количество доступной хакеру информации.

Ещё одна методика заключается в настройке веб-сервера таким образом, чтобы он обрабатывал файлы с различными расширениями как PHP-скрипты. Это можно указать как в .htaccess файлах, так и конфигурационном файле Apache. В таком случае вы сможете использовать при написании кода нестандартные расширения:

Пример #1 Маскировка PHP под другие языки программирования

    # Теперь PHP-скрипты могут иметь те же расширения, что и другие языки программирования
    AddType application/x-httpd-php .asp .py .pl

Или скрыть его совсем:

Пример #2 Использование неизвестных расширений для PHP-скриптов

    # Теперь PHP-скрипты могут иметь неизвестные типы файлов
    AddType application/x-httpd-php .bop .foo .133t

Также можно спрятать его под видом HTML-кода, что приведёт к потере производительности, так как все HTML-файлы будут обрабатываться PHP:

Пример #3 Маскировка PHP-файлов под HTML

    # Теперь PHP-скрипты выглядят как обыкновенный HTML
    AddType application/x-httpd-php .htm .html

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

# Необходимость обновлений

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

Как и в других программах и языках программирования, рекомендуется регулярно обновлять PHP и быть в курсе изменений, сделанных в последних версиях.

- Вступление
- Общие соображения
- О безопасности PHP в режиме CGI-программы
  - Возможные атаки
  - Вариант 1: обслуживание только общедоступных файлов
  - Вариант 2: включение директивы cgi.force_redirect
  - Вариант 3: включение директив doc_root или user_dir
  - Вариант 4: PHP вне дерева веб-документов
- Если PHP установлен как модуль Apache
- Безопасность сессий
- Безопасность файловой системы
  - Нулевые байты и безопасность
- Безопасность баз данных
  - Проектирование баз данных
  - Соединение с базой данных
  - Шифрование хранилища базы данных
  - SQL-инъекции
- Сообщения об ошибках
- Данные пользовательского ввода
- Сокрытие PHP
- Необходимость обновлений

# Особенности

# HTTP-аутентификация в PHP

Функция header() умеет отправлять в браузер сообщение «`Требуется аутентификация`» и при этом заставляет браузер показывать всплывающее окно ввода имени пользователя и пароля. Как только пользователь заполнит логин и пароль, браузер снова вызовет URL-адрес с названием PHP-скрипта, но уже с предопределёнными переменными: для переменной PHP_AUTH_USER PHP установит значение имени пользователя, для переменной PHP_AUTH_PW — пароль, а для AUTH_TYPE — тип аутентификации. Эти предопределённые переменные содержит суперглобальный массив $_SERVER. PHP поддерживает только Basic-метод аутентификации. Дополнительную информацию даёт описание функции header().

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

Пример #1 Пример HTTP-аутентификации с типом Basic

    <?php

    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Basic realm="My Realm"');

        echo 'Текст, который скрипт отправит,
        если пользователь нажмёт кнопку «Отмена»';
        exit;
    } else {
        echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>Вы ввели пароль: {$_SERVER['PHP_AUTH_PW']}.</p>";
    }

    ?>

> Замечание: Совместимость

> При определении HTTP-заголовков соблюдают осторожность. Слово "Basic" требуется писать с заглавной буквы "B", значение для ключа realm берут в двойные, но не одинарные кавычки, а перед кодом 401 в строке заголовка HTTP/1.1 401 указывают ровно один пробел, чтобы гарантировать максимальную совместимость с клиентами. Параметры аутентификации разделяют запятыми.

Вместо простого вывода значений переменных PHP_AUTH_USER и PHP_AUTH_PW, как это сделал приведённый пример, программист может проверить правильность имени пользователи и пароля через базу данных или через поиск пользователя в dbm-файле.

> Замечание: Настройка Apache

> PHP использует директиву `AuthType`, чтобы определить, действует ли внешняя аутентификация.

Однако обратите внимание, что это не мешает тому, кто контролирует неаутентифицированный URL-адрес, воровать пароли от аутентифицированных URL-адресов на том же сервере.

> Замечание: Поведение браузеров
> Basic-аутентификация по HTTP действительно простая (basic) и не была рассчитана на поддержку выхода из системы. Поскольку HTTP — это протокол без сохранения состояния, большинство браузеров кешируют переданные учётные данные сразу же, как только получат код состояния `2xx`, и отправляют их в каждом запросе, пока браузер не закроют. Определённого способа, которым сервер мог бы запросить повторный ввод учётных данных, не существует. За прошедшие годы в интернете в качестве советов разошлись разные обходные приёмы, но все они зависят от того, как разные браузеры решили обрабатывать неопределённые крайние случаи (или даже нарушения стандарта HTTP). Лучше избегать таких приёмов и не использовать Basic-аутентификацию для чего-либо серьёзного.

> Замечание: Настройка IIS
> Чтобы HTTP-аутентификация работала на IIS-сервере с CGI-версией PHP, для php.ini-директивы cgi.rfc2616_headers требуется установить значение `0` (значение по умолчанию), а также отредактировать опцию конфигурации IIS-сервера "`Directory Security`". Щёлкните «`Изменить`» и поставьте галочку только в поле «`Анонимный доступ`», остальные поля остаются неотмеченными.

# Cookies

PHP прозрачно поддерживает cookies при обмене данными по HTTP-протоколу. Cookies — механизм хранения данных браузером удалённой машины, который отслеживает или идентифицирует посетителей, которые вернулись на сайт. Блоки данных cookies устанавливают функцией setcookie() или setrawcookie(). Cookies — часть HTTP-заголовка, поэтому функцию setcookie() требуется вызывать перед отправкой данных вывода в браузер. Это то же ограничение, которое касается функции header(). Функции буферизации вывода откладывают вывод скрипта, пока не решилось, нужно ли устанавливать cookies или отправлять заголовки.

Cookies, которые браузер клиента отправит на сервер, PHP автоматически включит в суперглобальный массив $_COOKIE, если директива variables_order содержит букву «C». Имена cookie записывают в нотации массивов: `[]`, когда одному блоку данных требуется назначить список значений.

Дополнительную информацию, включая примечания об ошибках браузеров, приводят описания функций setcookie() и setrawcookie().

# Сессии

Поддержка сессий в PHP состоит в сохранении набора данных для повторного обращения к ним. Это помогает повысить индивидуальность разрабатываемого приложения и улучшает привлекательность сайта. Подробнее об этом рассказывает раздел «Управление сессиями».

# Загрузка файлов на сервер

## Содержание

- Загрузка файлов методом POST
- Объяснение сообщений об ошибках
- Распространённые подводные камни
- Загрузка нескольких файлов
- Поддержка метода PUT
- Смотрите также

## Загрузка файлов методом POST

Через этот механизм загружают как текстовые, так и бинарные файлы. Через PHP-функции аутентификации и работы с файлами программист получает полный контроль над доступом к загрузке файлов на сервер и обработкой файла после загрузки.

PHP умеет принимать загруженные файлы из браузеров, которые совместимы со стандартом RFC-1867.

> Замечание: Смежные замечания по конфигурации

> Ознакомьтесь также с описанием директив конфигурационного файла php.ini: file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size и max_input_time.

PHP также поддерживает загрузку файлов методом PUT, через который загружают файлы на сервер клиенты Netscape Composer и Amaya консорциума W3C. Подробнее об этом методе рассказывает раздел «Поддержка метода PUT».

Пример #1 Форма для загрузки файлов

Страница загрузки файлов на сервер реализуется через форму, которая выглядит примерно так:

    <!-- Тип кодирования данных, enctype, требуется указывать только так, как показывает пример -->
    <form enctype="multipart/form-data" action="__URL__" method="POST">
        <!-- Поле MAX_FILE_SIZE требуется указывать перед полем загрузки файла -->
        <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
        <!-- Название элемента input определяет название элемента в суперглобальном массиве $_FILES -->
        Отправить файл: <input name="userfile" type="file" />
        <input type="submit" value="Отправить файл" />
    </form>

В приведённом примере значение `__URL__` нужно заменить ссылкой на PHP-файл.

Скрытое поле `MAX_FILE_SIZE` (значение требуется указывать в байтах) должно идти перед полем выбора файла. Значение поля указывает максимальный размер файла, который принимает PHP. Рекомендуется добавлять этот элемент в форму, поскольку он не заставляет пользователя ждать окончания передачи большого файла, а только потом узнавать, что файл оказался слишком большим и передача не состоялась. Имейте в виду: обойти это ограничение на стороне браузера легко, поэтому не рассчитывайте, что эта функция заблокирует файлы большего размера. Это только удобная функция для пользователей клиентской части приложения. Однако серверные PHP-настройки, которые касаются максимального размера, обойти невозможно.

> Замечание:

> Проверьте, что форма загрузки содержит атрибут `enctype="multipart/form-data"`, иначе загрузка файлов на сервер не будет работать.

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

$_FILES['userfile']['name']

  Исходное название файла на компьютере клиента.

$_FILES['userfile']['type']

  MIME-тип файла, если браузер отправил такую информацию. Пример MIME-типа: «`image/gif`». MIME-тип не проверяется на стороне PHP, поэтому значение не принимают без проверки.

$_FILES['userfile']['size']

  Размер принятого файла в байтах.

$_FILES['userfile']['tmp_name']

  Временное имя файла, под которым PHP хранил файл, который загрузили на сервер.

$_FILES['userfile']['error']

  Код ошибки, которая возникает при загрузке файла.

$_FILES['userfile']['full_path']

  Полный путь, который отправил браузер. Это значение не всегда содержит реальную структуру каталогов и ему нельзя доверять. Поле доступно с PHP 8.1.0.

По умолчанию PHP сохраняет принятые файлы на сервере в стандартной вре́менной папке до тех пор, пока через директиву upload_tmp_dir конфигурационного файла php.ini не зададут другой каталог. На сервере директорию по умолчанию можно изменить через переменную TMPDIR того окружения, в котором работает PHP. Установка переменной функцией putenv() внутри PHP-скрипта работать не будет. Через эту переменную окружения также проверяют, что другие операции тоже работают с принятыми файлами.

Пример #2 Проверка файлов, которые загрузили на сервер

Дополнительную информацию дают описания функций is_uploaded_file() и move_uploaded_file(). Следующий пример принимает и обрабатывает файл, который загрузили на сервер через форму.

    <?php

    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "Файл не содержит ошибок и успешно загрузился на сервер.\n";
    } else {
        echo "Возможная атака на сервер через загрузку файла!\n";
    }

    echo 'Дополнительная отладочная информация:';
    print_r($_FILES);

    print "</pre>";

    ?>

PHP-скрипт, который принимает файл, должен реализовывать логику определения того, что требуется сделать с файлом, который загрузили на сервер. Можно, например, проверить переменную $_FILES['userfile']['size'], чтобы отсечь чрезмерно большие или слишком мелкие файлы. Можно также использовать переменную $_FILES['userfile']['type'], чтобы выбросить файлы, которые не соответствуют заданным критериям типа файла. Но выполняйте такую проверку только как первую в серии проверок, потому что это значение контролируется клиентом и не проверяется на стороне PHP. Кроме того, можно использовать переменную $_FILES['userfile']['error'] и планировать логику поведения кода с учётом кодов ошибок. При любой логике требуется либо удалить файл из временного каталога, либо переместить файл в другую директорию.

Если при отправке формы файл не выбрали, PHP установит для переменной $_FILES['userfile']['size'] значение 0, а переменной $_FILES['userfile']['tmp_name'] — none.

PHP удалит файл из временного каталога в конце запроса, если файл не переместили или не переименовали.

Пример #3 Загрузка массива файлов

PHP поддерживает передачу массива из HTML-формы даже с файлами.

    <form action="" method="post" enctype="multipart/form-data">
        <p>Изображения:
            <input type="file" name="pictures[]" />
            <input type="file" name="pictures[]" />
            <input type="file" name="pictures[]" />
            <input type="submit" value="Отправить" />
        </p>
    </form>

    <?php

    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];

            // Функция basename() помогает защититься от атак на файловую систему;
            // иногда требуется дополнительная проверка или очистка имени файла
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }

    ?>

Полосу прогресса загрузки файлов можно реализовать через «Отслеживание прогресса загрузки файлов через сессии».

## Объяснение сообщений об ошибках

PHP наряду с другими атрибутами принятого файла возвращает код ошибки. Код ошибки хранится в массиве, который PHP создаёт при загрузке файла, и доступен при обращении по ключу `error`. Другими словами, код ошибки находят в переменной $_FILES['userfile']['error'].

Значение кода ошибки определяется константой семейства `UPLOAD_ERR_*`.

## Распространённые подводные камни

Элементу `MAX_FILE_SIZE` нельзя указывать размер файла, который превышает предел, который установили в директиве upload_max_filesize файла php.ini. Ограничение по умолчанию составляет 2 мегабайта.

Если установили ограничения памяти, может потребоваться увеличение значения опции memory_limit. Убедитесь, что значение директивы memory_limit достаточно.

Время, которое потребуется для работы скрипта, может превысить значение опции max_execution_time, если для директивы установили маленькое значение. Убедитесь, что значение директивы `max_execution_time` достаточно.

> Замечание: Директива max_execution_time влияет только на время выполнения самого скрипта. Время, которое заняли действия за пределами скрипта, — системные вызовы функций system() или sleep(), запросы к базе данных, время, которое заняла загрузка файла на сервер, и т. д. — не учитывается при определении максимального времени работы скрипта.

Внимание

Директива max_input_time устанавливает максимальное время в секундах, в течение которого скрипту разрешается получать входные данные; время загрузки файла тоже включается. Загрузка больших файлов, набора файлов или обработка запросов пользователей с медленными соединениями может превысить значение по умолчанию в `60` секунд.

Сервер не загрузит большие файлы, если для директивы post_max_size установили слишком маленькое значение. Проверьте, что значение директивы `post_max_size` достаточно.

Опция max_file_uploads контролирует максимальное количество файлов, которые загружают на сервер в течение одного запроса. Суперглобальный массив $_FILES прекратит обработку файлов, как только достигнет ограничения, если загружается больше файлов, чем в ограничении. Например, если значение директивы max_file_uploads равняется `10`, массив $_FILES не будет содержать больше 10 элементов.

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

Из-за многообразия стилей, в которых файловые системы ведут список каталогов, PHP не гарантирует правильную обработку файлов с экзотическими именами, например файлов с пробелами в именах.

Разработчикам нельзя смешивать обычные `input`-поля и поля загрузки файлов в одной и той же переменной формы (например, нельзя указывать в имени `input`-элемента значение `foo[]`).

## Загрузка нескольких файлов

Набор файлов загружают через разные значения атрибута `name` в `input`-элементах формы.

Возможно также загружать набор файлов одновременно и автоматически получать файлы в виде массива. Для этого в HTML-форме пользуются тем же синтаксисом отправки массива, что и для отправки списка значений через HTML-элементы SELECT или поля ввода с типом checkbox:

Пример #1 Загрузка нескольких файлов

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
        Файлы:<br />
        <input name="userfile[]" type="file" /><br />
        <input name="userfile[]" type="file" /><br />
        <input type="submit" value="Отправить" />
    </form>

При отправке приведённой формы PHP инициализирует массивы $_FILES['userfile'], $_FILES['userfile']['name'] и $_FILES['userfile']['size'].

Предположим, что отправили файлы /home/test/review.html и /home/test/xwp.out. Тогда переменная $_FILES['userfile']['name'][0] будет содержать значение review.html, а переменная $_FILES['userfile']['name'][1] — xwp.out. Аналогично, переменная $_FILES['userfile']['size'][0] будет содержать размер файла review.html и так далее.

PHP также инициализирует переменные $_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0] и $_FILES['userfile']['type'][0].

Внимание

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

Пример #2 Загрузка каталога

В HTML-полях выбора файла для загрузки указывают атрибут `webkitdirectory`, чтобы загрузить весь каталог. Бо́льшая часть браузеров поддерживает эту функцию.

Информация, которую хранит элемент `full_path`, помогает сохранить относительные пути или воссоздать такой же каталог на сервере.

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
        Загрузка каталога:<br />
        <input name="userfile[]" type="file" webkitdirectory multiple />
        <input type="submit" value="Загрузить файлы" />
    </form>

Внимание

Атрибут `webkitdirectory` нестандартен и не соответствует спецификациям. Не рекомендуется включать атрибут в элементы форм на рабочих сайтах: атрибут работает не у каждого пользователя. Способ обработки атрибута несовместим между браузерами, и поведение могут изменить в будущих выпусках.

PHP анализирует только информацию об относительном пути, которую отправили браузер или пользовательский агент, и передаёт информацию в суперглобальный массив $_FILES. Нет гарантии, что значения в массиве `full_path` содержат реальную структуру каталогов, и PHP-приложение не должно доверять этой информации.

## Поддержка метода PUT

PHP поддерживает HTTP-метод PUT, через который отдельные клиенты отправляют файлы на сервер для хранения. PUT-запросы проще, чем загрузка файлов POST-запросами, а выглядят PUT-запросы примерно так:

    PUT /path/filename.html HTTP/1.1

Обычно такой вызов означает, что удалённый клиент хотел бы сохранить файл /path/filename.html в дереве каталогов веб-сервера. Не сомневаемся, что настраивать веб-сервер Apache или PHP так, чтобы они разрешали каждому автоматически перезаписывать файлы веб-сервера, — плохая идея. Поэтому, чтобы обработать такой запрос, потребуется сначала сообщить веб-серверу, чтобы запрос обрабатывал конкретный PHP-скрипт. На веб-сервере Apache это делается через директиву Script. Обычно директиву записывают в произвольном месте конфигурационного файла веб-сервера Apache внутри блока `<Directory>` или, возможно, внутри блока `<VirtualHost>`. Строка наподобие этой укажет веб-серверу конкретный PHP-файл для обработки запроса:

    Script PUT /put.php

Строка говорит веб-серверу Apache перенаправлять каждый PUT-запрос к URI-идентификаторам, которые соответствуют контексту, в котором записали строку, в файл put.php. Предполагается, что файлы с расширением .php обрабатываются как PHP-скрипты, и что сам PHP активен. Ресурсом назначения для PUT-запросов к этому скрипту должен быть сам скрипт, а не имя, которое требуется дать загружаемому файлу.

Затем внутри файла put.php разработчик мог бы написать код наподобие следующего примера. Пример скопирует содержимое загруженного файла в файл myputfile.ext на сервере. Возможно, потребуются проверки и (или) аутентификация пользователя перед копированием файла.

Пример #1 Сохранение файлов, которые отправили HTTP-методом PUT

    <?php

    /* PUT-данные приходят в стандартный поток входных данных stdin */
    $putdata = fopen("php://input", "r");

    /* Открываем файл для записи */
    $fp = fopen("myputfile.ext", "w");

    /* Читаем 1 KB данных за один раз
       и записываем в файл */
    while ($data = fread($putdata, 1024)) {
        fwrite($fp, $data);
    }

    /* Закрываем потоки */
    fclose($fp);
    fclose($putdata);

    ?>

## Смотрите также

- Безопасность файловой системы

# Работа с удалёнными файлами

В случае, если опция allow_url_fopen включена в конфигурационном файле php.ini, вы можете использовать URL-адреса HTTP и FTP в большинстве функций, принимающих в качестве параметра имя файла. Также вы можете использовать ссылки в операторах include, include_once, require и require_once (для корректной работы этих функций должна быть включена опция allow_url_include). Дополнительную информацию о поддерживаемых в PHP протоколах вы можете найти в Протоколы и обёртки.

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

Пример #1 Получение заголовка удалённой страницы

    <?php
    $file = fopen ("http://www.example.com/", "r");
    if (!$file) {
        echo "<p>Невозможно открыть удалённый файл.\n";
        exit;
    }
    while (!feof ($file)) {
        $line = fgets ($file, 1024);
        /* Сработает, только если заголовок и сопутствующие теги расположены в одной строке */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
            $title = $out[1];
            break;
        }
    }
    fclose($file);
    ?>

Вы также можете работать с удалёнными файлами, расположенными на FTP-сервере (подразумевается, что вы авторизовались с необходимыми для этого привилегиями). Таким образом вы можете только создавать новые файлы, но попытка перезаписать существующий файл при помощи функции fopen() приведёт к ошибке.

Для того, чтобы авторизоваться под пользователем, отличным от 'anonymous', вам необходимо указать логин (и, возможно, пароль) в адресной строке, например так: '`ftp://user:password@ftp.example.com/path/to/file`'. (Вы можете использовать этот же синтаксис для доступа к удалённым файлам по HTTP-протоколу, если необходима Basic-аутентификация.)

Пример #2 Сохранение данных на удалённом сервере

    <?php
    $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$file) {
        echo "<p>Невозможно перезаписать удалённый файл.\n";
        exit;
    }
    /* Запись данных. */
    fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($file);
    ?>

> Замечание:

> Глядя на приведённый выше пример, у вас может возникнуть идея использовать эту технику для ведения удалённого лог-файла. К сожалению, это нереализуемо, поскольку попытка записи в уже существующий удалённый файл при помощи функции fopen() приведёт к ошибке. В реализации распределённого логирования, возможно, вам поможет функция syslog().

# Работа с соединениями

Статус соединения сохраняется внутренними механизмами PHP. Ниже перечислены четыре возможные состояния:

- 0 - NORMAL
- 1 - ABORTED
- 2 - TIMEOUT
- 3 - ABORTED и TIMEOUT

Во время штатного выполнения PHP-скрипта установлен статус NORMAL. В случае, если удалённый клиент разорвал соединение, статус изменяется на ABORTED. Чаще всего отсоединение удалённого клиента происходит при нажатии кнопки "Stop" в браузере. В случае, если достигается установленный временной лимит (ознакомьтесь с функцией set_time_limit()), будет установлен статус TIMEOUT.

Вы можете решать, приводит ли отключение клиента к завершению вашего скрипта. Иногда бывает необходимо, чтобы скрипт выполнился до конца, даже если отсутствует удалённый браузер, которому адресован весь вывод. По умолчанию скрипт завершает свою работу при отключении клиента. Это поведение может быть изменено при помощи опции ignore_user_abort в конфигурационном файле php.ini. Такого же результата можно добиться, указав `php_value ignore_user_abort` в конфигурационном файле Apache httpd.conf или воспользовавшись функцией ignore_user_abort(). Если вы явно не указали на необходимость игнорировать разрыв соединения с клиентом, выполнение скрипта будет прервано. Исключением является тот случай, если используя register_shutdown_function(), вы указали специальную функцию, вызываемую при завершении скрипта. В таком случае после того, как пользователь нажал кнопку "Stop" в своём браузере, при первой же попытке что-либо вывести PHP обнаруживает, что соединение с клиентом было утеряно, и вызывает завершающую функцию. Эта функция также вызывается при нормальном завершении работы вашего скрипта, поэтому для того, чтобы выполнить некоторые специфические действия при отсоединении клиента, вам понадобится функция connection_aborted(), которая возвращает `true`, если соединение было разорвано.

Выполнение вашего скрипта также может быть прервано встроенным таймером. Стандартное ограничение по времени составляет 30 секунд, изменить его можно при помощи директивы max_execution_time в конфигурационном файле php.ini. Такого же результата можно достичь, добавив `php_value max_execution_time` в конфигурационный файл Apache httpd.conf или воспользовавшись функцией set_time_limit(). При достижении скриптом временного лимита выполнение скрипта прерывается и вызывается завершающая функция, если она была указана. Уточнить причину завершения скрипта вы можете при помощи функции connection_status(), которая возвращает 2, если скрипт был прерван по достижению временного ограничения.

Единственное, что следует заметить - что оба статуса: ABORTED и TIMEOUT, - могут быть установлены одновременно. Это может произойти в том случае, если вы явно указали необходимость игнорировать отсоединение удалённого клиента. В таком случае после разрыва соединения, отметив этот факт, PHP продолжит выполнение скрипта, и при достижении временного лимита будет вызвана завершающая функция, если таковая была указана. В этой точке вы можете обнаружить, что connection_status() вернёт значение 3.

# Постоянные соединения с базами данных

### Что такое постоянные соединения?

Постоянные соединения представляют собой связи с базами данных, которые не закрываются при завершении скрипта. При получении запроса на постоянное соединение PHP вначале проверяет, имеется ли идентичное постоянное соединение (которое было открыто при предыдущих обращениях) и, если таковое было найдено, использует его. В случае если идентичного соединения нет, PHP создаёт новое. Под "идентичным" подразумевается соединение, открытое на том же хосте с таким же именем пользователя и паролем (если они указаны).

Нет способа запросить конкретное соединение или гарантировать, что вернётся существующее соединение или совершенно новое (если все существующие соединения заняты или запрос обслуживается другим процессом, у которого есть отдельный пул соединений).

Поэтому постоянные соединения PHP нельзя использовать, например, для:

- назначения определённой сессии базы данных конкретному веб-пользователю
- создания крупной транзакции, охватывающей несколько запросов
- инициализации запроса для одного запроса и собирания результатов по другому

Постоянные соединения не предоставляют никакой функциональности, которая была бы недоступна при использовании непостоянных соединений.

### Веб-запросы

Существует два основных способа использования PHP сервером для генерации веб-страниц.

Первый способ заключается в том, чтобы использовать PHP как CGI-обёртку. При этом PHP-интерпретатор создаётся и уничтожается при каждом обращении к странице (PHP-скрипту). Поскольку интерпретатор уничтожается после каждого запроса к серверу, все используемые им ресурсы (в том числе и соединение с базой данных) закрываются. Следовательно, в этом случае от использования постоянных соединений ничего не выигрывается: они просто не сохраняются.

Второй и наиболее популярный метод заключается в запуске PHP-FPM или PHP в качестве модуля в многопроцессорном веб-сервере, которым в настоящее время является только Apache. В таких конфигурациях обычно можно выделить один процесс (родительский), который координирует работу всех остальных процессов (дочерних), которые фактически и выполняют работу по обслуживанию веб-страниц. При каждом обращении клиента к серверу запрос перенаправляется одному из дочерних процессов, который в данный момент не занят обслуживанием другого клиента. Это означает, что когда тот же самый клиент выполняет повторный запрос к серверу, он может быть обработан другим дочерним процессом, отличным от того, который был при первом обращении. После открытия постоянного соединения каждая последующая страница, требующая соединения с базой данных, может использовать уже установленное ранее соединение с SQL-сервером.

> Замечание:

> Чтобы проверить, какой метод используют веб-запросы, посмотрите значение «Server API» в выводе функции phpinfo() или значение константы `PHP_SAPI`, полученное из веб-запроса.

> Если API сервера является «Apache 2 Handler» или «FPM/FastCGI», то постоянные соединения будут использоваться для всех запросов, обслуживаемых одним и тем же рабочим процессом. Для любого другого значения постоянные соединения не будут сохраняться после каждого запроса.

### Процессы командной строки

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

### Зачем их использовать?

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

### Возможные недостатки: ограничения подключения

Следует заметить, что этот подход имеет некоторые недостатки: при использовании базы данных с ограниченным количеством возможных подключений оно может быть превышено количеством запрашиваемых дочерними процессами постоянных соединений. Например, если база данных позволяет 16 одновременных соединений, и во время нагрузки на сервер 17 дочерних процессов попробуют открыть соединение, одна из попыток потерпит неудачу. Если в коде содержатся ошибки, не позволяющие закрывать соединение (например, бесконечные циклы), база данных с 16 одновременными подключениями вскоре может оказаться заблокированной.

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

Убедитесь, что максимальное количество подключений, разрешённое сервером базы данных, превышает максимальное количество рабочих процессов веб-запросов (плюс любое другое использование, такое как задания Cron или административные подключения).

Проверьте документацию по базе данных для получения информации об обработке заброшенных или неактивных соединений (время ожидания). Длительное время ожидания может значительно увеличить количество постоянных соединений, открытых в любой момент времени.

### Возможные недостатки: поддержание состояния соединения

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

- Выбранная / базовая база данных
- Блокировка таблиц
- Незавершённые транзакции
- Временные таблицы
- Настройки или функции, специфичные для подключения, такие как профилирование

Блокировки таблиц и транзакции, которые не очищаются или не закрываются, могут привести к бесконечной блокировке других запросов и/или к неожиданным изменениям при повторном использовании соединения.

Выбор неправильной базы данных приведёт к тому, что при последующем повторном использовании соединения запросы не будут выполняться должным образом (или будут выполняться в неправильной базе данных, если схемы достаточно похожи).

Если временные таблицы не очищаются, последующие запросы не смогут воссоздать ту же таблицу.

Очистку можно реализовать с помощью деструкторов классов или функции register_shutdown_function(). Также можно рассмотреть возможность использования специальных прокси-серверов для пула подключений, которые включают функцию в свой набор возможностей.

### Заключительные слова

Учитывая их поведение и потенциальные недостатки, описанные выше, не следует использовать постоянные соединения без тщательного обдумывания. Их не следует использовать без внесения дополнительных изменений в приложение и тщательной настройки сервера базы данных и веб-сервера и/или PHP-FPM.

Рассмотрите альтернативные решения, такие как исследование и устранение причин накладных расходов на создание соединений (например, отключение обратного DNS-поиска на сервере базы данных) или использование специальных прокси-серверов для объединения соединений.

Для веб API с большим объёмом данных рассмотрите возможность использования альтернативных сред выполнения или серверов приложений с длительным временем работы.

### Смотрите также

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- Модуль MySQLi и постоянные соединения
- Подключения и управление подключениями

# Работа с PHP из командной строки

## Содержание

- Основные отличия от остальных реализаций SAPI
- Опции
- Использование
- Потоки ввода-вывода
- Интерактивная консоль
- Встроенный веб-сервер
- Опции конфигурации

## Введение

Основная цель CLI SAPI — разработка консольных приложений на PHP. CLI SAPI содержит много отличий от других видов SAPI, которые объясняет эта глава. Обратите внимание, что CLI SAPI и CGI — разные SAPI-интерфейсы, хотя в их поведении много общего.

CLI SAPI включается по умолчанию опцией --enable-cli, а отключается опцией --disable-cli при запуске команды ./configure.

Имя, расположение и доступность бинарных модулей CLI или CGI-интерфейса различаются в зависимости от способа установки PHP в систему. По умолчанию при выполнении команды make внутри директории с исходным кодом PHP в каталоге sapi/cgi/php-cgi создаётся модуль CGI, а в каталоге sapi/cli/php модуль CLI. Обратите внимание, что оба файла модулей называются одинаково: php. Что произойдёт при выполнении make install, зависит от того, какие опции указали на стадии конфигурирования. Команда make install скопирует в каталог {PREFIX}/bin/php CLI-модуль, если во время конфигурирования выбрали модуль SAPI наподобие apxs или указали опцию --disable-cgi, иначе команда скопирует в эту директорию CGI-модуль. Например, с опцией --with-apxs команда make install скопирует в каталог {PREFIX}/bin/php CLI-версию. После команды make install запускают команду make install-cli, когда требуется переопределить установку двоичного файла CGI-модуля, или как альтернативу указывают в строке конфигурации опцию --disable-cgi.

> Замечание:

> Опция --enable-cli в строке конфигурации не означает, что команда make install скопирует CLI в каталог {PREFIX}/bin/php, поскольку опции --enable-cli и --enable-cgi включены по умолчанию.

Бинарный файл CLI лежит в главном каталоге PHP-дистрибутива для Windows в виде файла php.exe, а CGI-версия — в виде файла php-cgi.exe. Кроме того, в дистрибутив входит файл php-win.exe, если PHP сконфигурировали с опцией --enable-cli-win32. Этот файл эквивалентен CLI-версии, за исключением того, что ничего не выводит, и поэтому при запуске файла не открывает окно Командной строки.

> Замечание: Как узнать версию SAPI-интерфейса

> Вызов в командной оболочке команды php -v выведет информацию о том, запускается двоичный php-файл как CGI- или CLI-версия SAPI-интерфейса. Информацию о SAPI-версии возвращают также функция php_sapi_name() и константа `PHP_SAPI`.

> Замечание:

> В Unix-системах страница руководства к интерфейсу CLI доступна при вызове команды `man` в командной оболочке: man php.

## Основные отличия от остальных реализаций SAPI

Основные отличия CLI-версии SAPI-интерфейса от остальных реализаций SAPI:

- В отличие от CGI-версии SAPI-интерфейса, заголовки не пишутся в поток вывода.

  Хотя в CGI-версии SAPI-интерфейса предусмотрели способ подавления HTTP-заголовков, в CLI SAPI заголовки включить нельзя.

  CLI по умолчанию запускается в тихом режиме, тем не менее, ключи -q и --no-header сохранили для обратной совместимости, что разрешает запускать старые CGI-скрипты.

  Текущая директория не изменяется на рабочую директорию скрипта. Ключи -C и --no-chdir сохранили для обратной совместимости.

  Сообщения об ошибках выдаются в текстовом режиме — без HTML-форматирования.

- Отдельные настройки файла php.ini переопределяются CLI SAPI, поскольку в них нет смысла при работе в командной строке:

  Переопределяемые директивы php.ini
  Директива | Значение по умолчанию в CLI-версии SAPI-интерфейса | Комментарий
  --- | --- | ---
  html_errors | `false` | Значение по умолчанию равно `false`, поскольку в консоли неудобно читать сообщения об ошибке с нагромождением неинтерпретируемых HTML-тегов.
  implicit_flush | `true` | В консоли часто требуется, чтобы вывод функции print или языковой конструкции echo сбрасывался сразу, а не хранился в буфере. При этом буферизация вывода по-прежнему поддерживается для отложенного вывода или манипуляций с данными буфера.
  max_execution_time | 0 (без ограничений) | В консольном режиме средствами PHP часто выполняют расширенный, по сравнению со стандартными веб-скриптами, диапазон задач, и поскольку консольные скрипты часто выполняются долго, для директивы устанавливается значение 0 — бесконечное время выполнения скрипта.
  register_argc_argv | `true` | При установке значения `true` скрипты, которые выполняются через CLI SAPI, получают доступ к переменной argc, которая содержит количество переданных приложению аргументов, и к переменной argv с массивом текущих аргументов. При работе в CLI SAPI переменные $argc и $argv автоматически заполняются значениями. Эти значения также доступны в массиве $_SERVER, например: $_SERVER['argv']. Внимание Переменные $argv и $_SERVER['argv'] не относятся к надёжному признаку запуска скрипта из командной строки, поскольку при включённой директиве register_argc_argv переменные могли установить в других контекстах. Вместо этого проверяют значение, которое вернула функция php_sapi_name().
      <?php

      if (php_sapi_name() === 'cli') {
          echo "Код запускается из командной строки!\n";
      }
  Внимание Начиная с PHP 8.5.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
  output_buffering | `false` | Хотя для этой опции файла php.ini жёстко установили значение `false`, функции буферизации вывода по-прежнему доступны.
  max_input_time | `false` | PHP CLI не поддерживает GET, POST или загрузку файлов.

  > Замечание:

  > Эти директивы нельзя инициализировать другими значениями из конфигурационного файла php.ini или любого другого, если другой файл указали. Это ограничение связано с тем, что значения применяются после обработки конфигурационных файлов. Тем не менее, эти значения могут быть изменены во время работы скрипта (хотя это не имеет особого смысла для всех них, например register_argc_argv).

  > Замечание:

  > Рекомендуется установить опцию ignore_user_abort для скриптов, используемых из командной строки. За подробностями обращайтесь к функции ignore_user_abort().

- Для облегчения работы в окружении оболочки определили несколько констант для потоков ввода-вывода.

- CLI SAPI не изменяет текущую директорию на директорию исполняемого скрипта.

  Пример #1 Пример, который показывает разницу с CGI-режимом SAPI-интерфейса:

      <?php

      // Базовый тестовый скрипт с названием test.php
      echo getcwd(), "\n";

  При работе в CGI-режиме результат работы будет таким:

      $ pwd
      /tmp

      $ php -q another_directory/test.php
      /tmp/another_directory

  Это наглядно демонстрирует, что PHP изменяет текущую директорию на директорию исполняемого скрипта.

  Работа через CLI SAPI даёт другой результат:

      $ pwd
      /tmp

      $ php -f another_directory/test.php
      /tmp

  Это обеспечивает большую гибкость при написании консольных скриптов на PHP.

  > Замечание:

  > При запуске из командной строки с ключом -C CGI-режим SAPI-интерфейса разрешает получить поведение, которое аналогично поведению при работе через CLI SAPI.

## Список опций командной строки

Список опций командной строки, которые предоставляет PHP, доступны для получения в любой момент при запуске PHP с ключом -h:

    Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

      -a               Run interactively
      -c <path>|<file> Look for php.ini file in this directory
      -n               No php.ini file will be used
      -d foo[=bar]     Define INI entry foo with value 'bar'
      -e               Generate extended information for debugger/profiler
      -f <file>        Parse and execute <file>.
      -h               This help
      -i               PHP information
      -l               Syntax check only (lint)
      -m               Show compiled in modules
      -r <code>        Run PHP <code> without using script tags <?..?>
      -B <begin_code>  Run PHP <begin_code> before processing input lines
      -R <code>        Run PHP <code> for every input line
      -F <file>        Parse and execute <file> for every input line
      -E <end_code>    Run PHP <end_code> after processing all input lines
      -H               Hide any passed arguments from external tools.
      -S <addr>:<port> Run with built-in web server.
      -t <docroot>     Specify document root <docroot> for built-in web server.
      -s               Output HTML syntax highlighted source.
      -v               Version number
      -w               Output source with stripped comments and whitespace.

      args...          Arguments passed to script. Use -- args when first argument
                       starts with - or script is read from stdin

      --ini            Show configuration file names

      --rf <name>      Show information about function <name>.
      --rc <name>      Show information about class <name>.
      --re <name>      Show information about extension <name>.
      --rz <name>      Show information about Zend extension <name>.
      --ri <name>      Show configuration for extension <name>.

Опции, которые доступны из командной строки
Опция | Полное название | Описание
--- | --- | ---
-a | --interactive | Запустить PHP в интерактивном режиме. Дополнительную информацию даёт раздел «Интерактивная консоль».
-b | --bindpath | Путь связывания библиотек (Bind Path) для внешнего режима FASTCGI Server (параметр работает только в CGI-версии).
-C | --no-chdir | Не менять текущую директорию на директорию скрипта (параметр работает только в CGI-версии).
-q | --no-header | Тихий режим. Подавляет вывод заголовков HTTP (параметр работает только в CGI-версии).
-T | --timing | Измерить время выполнения скрипта, повторенного count раз (параметр работает только в CGI-версии).
-c | --php-ini | Указывает, либо директорию, в которой требуется искать конфигурационный файл php.ini, либо пользовательский `INI`-файл (название которого может отличаться от стандартного php.ini), например:
    $ php -c /custom/directory/ my_script.php

    $ php -c /custom/directory/custom-file.ini my_script.php
Если эта опция не указана, поиск php.ini будет осуществлён в местах по умолчанию.
-n | --no-php-ini | Полностью игнорировать php.ini.
-d | --define | Устанавливает пользовательское значение для каждой из конфигурационных опций, доступных в php.ini. Синтаксис выглядит следующим образом:
     -d configuration_directive[=value]
Пример #1 Пример команды с параметром `-d` для установки INI-настройки
    # Если значение опустили, соответствующей опции присвоится значение "1"
    $ php -d max_execution_time
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # Указание пустого значения установит соответствующую опцию значением ""
    php -d max_execution_time=
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # Конфигурационная переменная будет установлена любым значением, указанным после символа '='
    $  php -d max_execution_time=20
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(2) "20"
    $  php
            -d max_execution_time=doesntmakesense
            -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(15) "doesntmakesense"
-e | --profile-info | Включить режим расширенной информации для отладчика или профайлера.
-f | --file | Разбирает и исполняет файл, который указали в параметре -f. Параметр необязателен — достаточно указать только название файла для запуска.
-h и -? | --help и --usage | Выводит список опций командной строки с однострочным описанием того, что они делают.
-i | --info | Вызывает функцию phpinfo() и выводит результат работы функции. При некорректной работе PHP рекомендуют выполнить команду php -i и посмотреть, выводятся ли сообщения об ошибках до или вместо информационных таблиц. При работе CGI-модуля учитывают, что команда выведет данные в HTML-формате и поэтому вывод будет большим.
-l | --syntax-check | Проверяет синтаксис, но не выполняет PHP-код. Обработаются входные данные стандартного входного потока, если название файла не указали, иначе проверится каждое название файла. При выполнении без ошибок в стандартный поток вывода записывается текст `No syntax errors detected in <filename>`. Вместе с внутренней информацией об ошибке парсера в станадртный поток вывода записывается текст `Errors parsing <filename>`, если возникла ошибка. Опция присвоит коду возврата командной оболочки значение `-1`, если в заданных файлах или данных стандартного потока ввода возникли ошибки, иначе опция присвоит коду возврата командной оболочки значение `0`. Опция не обнаружит фатальные ошибки в коде, который требует выполнения, наподобие вызова функций, которые не объявили. Замечание: До PHP 8.3.0 для проверки разрешалось указывать только одно название файла. Замечание: Опция не работает с опцией -r.
-m | --modules | Пример #2 Вывод списка PHP- и Zend-модулей ядра, которые загрузили
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | Разрешает выполнять PHP-код, который указали в командной строке. Открывающие и закрывающие PHP-теги (`<?php` и `?>`) не нужны и вызовут синтаксическую ошибку. Замечание: С этим ключом работают очень осторожно и избегают недоразумений, которые связаны с автоматической подстановкой переменных окружения. Пример #3 Ошибка синтаксиса при двойных кавычках
>     $ php -r "$foo = get_defined_constants();"
>     PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

>     Parse error: syntax error, unexpected '=' in Command line code on line 1
> Проблема здесь заключается в том, что командная оболочка bash выполняет автоматическую подстановку переменных в sh-командах, если указали двойные кавычки `"`. Поскольку маловероятно, что переменную $foo определили, переменная заменяется пустой строкой, что изменяет PHP-код, который передали для выполнения, вот так:
>     $ php -r " = get_defined_constants();"
> Правильное решение в таких ситуациях состоит в указании одинарных кавычек `'`, поскольку автоматическая подстановка переменных, которые обернули в одинарные кавычки, в sh-командах оболочки bash не происходит. Пример #4 Одинарные кавычки, которые предотвращают подстановку переменных в консоли
>     $ php -r '$foo = get_defined_constants(); var_dump($foo);'
>     array(370) {
>       ["E_ERROR"]=>
>       int(1)
>       ["E_WARNING"]=>
>       int(2)
>       ["E_PARSE"]=>
>       int(4)
>       ["E_NOTICE"]=>
>       int(8)
>       ["E_CORE_ERROR"]=>
>       [...]
В оболочках, которые отличаются от оболочки bash и которые запускают sh-команды, иногда возникают другие проблемы. Тогда требуется создать отчёт о ошибке, которая возникла, на сайте » https://github.com/php/php-src/issues. С проблемами иногда сталкиваются при попытке получить доступ к переменным оболочки или при работе с экранирующими обратными слешами. Теперь вы предупреждены! Замечание: Ключ -r доступен в CLI SAPI, но недоступен в CGI SAPI. Замечание: Опция предназначена только для самого простого кода. Поэтому некоторые конфигурационные директивы наподобие auto_prepend_file и auto_append_file в этом режиме проигнорируются.
-B | --process-begin | PHP-код, который требуется выполнить перед обработкой стандартного потока ввода stdin.
-R | --process-code | PHP-код, который требуется выполнить для каждой строки ввода. В этом режиме предусмотрели две специальные переменные: $argn и $argi. Переменная $argn содержит строку, которую PHP обрабатывает в текущий момент, а переменная $argi содержит номер этой строки.
-F | --process-file | PHP-файл, который требуется выполнить для каждой строки ввода.
-E | --process-end | PHP-код, который требуется выполнить после обработки ввода. Пример #5 Подсчёт количества строк в проекте опциями -B, -R и -E
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Всего строк: $l\n";'
    Всего строк: 37328
-S | --server | Запускает встроенный веб-сервер.
-t | --docroot | Указывает корень документа для встроенного веб-сервера.
-s | --syntax-highlight и --syntax-highlighting | Показывает исходный код с подсветкой синтаксиса. Эта опция использует внутренний механизм для разбора файла и записи в стандартный поток вывода подсвеченной версии этого файла. Учтите, что опция только генерирует блок `<code> [...] </code>` HTML-тегов, без HTML-заголовков. Замечание: Опция несовместима с опцией -r.
-v | --version | Пример #6 Получение информации о названия SAPI, PHP- и Zend-версии через опцию -v
    $ php -v
    PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
    Copyright (c) 1997-2009 The PHP Group
    Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
-w | --strip | Показывает исходный код без комментариев и пробелов. Замечание: Опция несовместима с опцией -r.
| --ini | Показывает имена файлов конфигурации и просканированные каталоги. Дополнительно можно передать `--ini=diff`, чтобы показать различия между загруженными файлами конфигурации и конфигурацией по умолчанию. Пример #7 Пример `--ini`
    $ php --ini
    Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
    Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed:      (none)
Замечание: Опция `--ini=diff` недоступна до PHP 8.5.0.
--rf | --rfunction | Показывает информацию о функции или методе класса (например, количество и названия параметров). Опция доступна, только если PHP скомпилировали с поддержкой интерфейса Reflection. Пример #8 Пример базового поведения опции `--rf`
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | Показывает информацию об классе; выводит список констант, свойств и методов. Опция доступна, только если PHP скомпилировали с поддержкой интерфейса Reflection. Пример #9 Пример вывода опции `--rc`
    $ php --rc Directory
    Class [ <internal:standard> class Directory ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [0] {
      }

      - Methods [3] {
        Method [ <internal> public method close ] {
        }

        Method [ <internal> public method rewind ] {
        }

        Method [ <internal> public method read ] {
        }
      }
    }
--re | --rextension | Показывает информацию о модуле; выводит список опций файла php.ini, функций, которые объявили, констант и классов. Опция доступна, только если PHP скомпилировали с поддержкой интерфейса Reflection. Пример #10 Пример вывода опции `--re`
    $ php --re json
    Extension [ <persistent> extension #19 json version 1.2.1 ] {

      - Functions {
        Function [ <internal> function json_encode ] {
        }
        Function [ <internal> function json_decode ] {
        }
      }
    }
--rz | --rzendextension | Показывает информацию о конфигурации Zend-модуля — та же информация, которая возвращается функцией phpinfo().
--ri | --rextinfo | Показывает информацию о конфигурации указанного модуля (та же информация, которая возвращается phpinfo()). Конфигурацию ядра можно узнать, указав в качестве имени модуля значение "main". Пример #11 Пример `--ri`
    $ php --ri date

    date

    date/time support => enabled
    "Olson" Timezone Database Version => 2009.20
    Timezone Database => internal
    Default timezone => Europe/Oslo

    Directive => Local Value => Master Value
    date.timezone => Europe/Oslo => Europe/Oslo
    date.default_latitude => 59.930972 => 59.930972
    date.default_longitude => 10.776699 => 10.776699
    date.sunset_zenith => 90.583333 => 90.583333
    date.sunrise_zenith => 90.583333 => 90.583333

> Замечание:

> Опции `-rBRFEH`, `--ini` и `--r[fcezi]` доступны только в CLI.

## Выполнение PHP-файлов

В CLI SAPI есть три различных способа запуска PHP-кода:

1. Указание конкретного файла для запуска.

       $ php my_script.php

       $ php -f my_script.php

   Оба способа — с опцией -f или без — запустят файл my_script.php. Нет ограничений, какой файл запускать; в частности, файлам даже не требуется содержать расширение `.php`.

2. Передача PHP-кода для выполнения в командной строке.

       $ php -r 'print_r(get_defined_constants());'

   При работе в этом режиме соблюдают осторожность из-за риска подстановки значений переменных оболочки в переменные в двойных кавычках.

   > Замечание:

   > Внимательно прочтите пример: код не содержит открывающих и закрывающих тегов! Опции -r теги не требуются, и даже вызовут ошибку разбора.

3. Передать запускаемый PHP-код через стандартный поток ввода (`stdin`).

   Это даёт мощную возможность создавать PHP-код и передавать его запускаемому файлу, как показано в этом (вымышленном) примере:

       $ some_application | some_filter | php | sort -u > final_output.txt

Вы не можете комбинировать любой из этих трёх способов запуска кода.

Как и любое другое консольное приложение бинарный файл PHP принимает аргументы, но PHP-скрипт также получает аргументы. PHP не ограничивает количество аргументов, передаваемых в скрипт (оболочка консоли устанавливает некоторый порог количества символов, которые могут передать; обычно этого лимита хватает). Переданные аргументы доступны в глобальном массиве $argv. Первый индекс — ноль — содержит название скрипта, который вызвали из командной строки. Учтите, что если код вызывается из командной строки на лету с опцией -r, значением элемента $argv[0] будет `«Стандартный поток»` (Standard input code); до PHP 7.2.0 это был дефис (`"-"`). То же самое верно и для кода, переданного через конвейер из `STDIN`.

Вторая зарегистрированная глобальная переменная — $argc, которая содержит количество элементов в массиве $argv, а не количество аргументов, которые передали скрипту.

В режиме командной строки PHP поддерживает передачу аргументов скрипту без символа `-`. При передаче в скрипт аргумента, перед которым указали символ `-`, возникнет ошибка, поскольку PHP-интерпретатор попытается обработать аргумент до выполнения скрипта как параметр команды. Аргументы скрипта указывают после разделителя списка аргументов `--`, чтобы не возникали ошибки интерпретации команды. После разбора разделителя PHP-интерпретатором следующие аргументы передаются в скрипт нетронутыми.

    # Команда не запустит код, а выведет информацию о параметрах командной строки, которые поддерживает PHP
    $ php -r 'var_dump($argv);' -h
    Usage: php [options] [-f] <file> [args...]
    [...]

    # Команда передаст аргумент '-h' в скрипт вместо вывода справки по параметрам PHP
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

При этом в Unix-системах доступен ещё один способ запуска PHP-скриптов из консоли. В первой строке такого скрипта указывают шебанг #! (от англ. hashbang) и корректный путь к бинарному файлу PHP CLI: `#!/usr/bin/php`. После этой строки записывают стандартный PHP-код, обрамлённый открывающим и закрывающим PHP-тегами. Сразу после установки корректных атрибутов запуска на файл, например chmod +x test), скрипт станет готов к запуску как стандартный консольный или perl-скрипт:

Пример #1 Запуск PHP-скрипта как консольного

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

Предполагая, что этот файл назван test и находится в текущей директории, можно сделать следующее:

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
      [0]=>
      string(6) "./test"
      [1]=>
      string(2) "-h"
      [2]=>
      string(2) "--"
      [3]=>
      string(3) "foo"
    }

Как можно увидеть, в этом случае не нужно заботиться о передаче параметров, которые начинаются с `-`.

Исполняемый PHP-файл может использоваться для запуска PHP-скриптов независимо от веб-сервера. В случае работы в Unix-подобной системе, необходимо добавить в первую строку файла `#!` (называемый также "shebang") чтобы указать, какая из программ должна запускать скрипт. На Windows-платформах можно назначить обработчик php.exe для файлов с расширениями `.php` или создать пакетный (.bat) файл для запуска скриптов посредством PHP. Строка, добавляемая в начале скрипта для Unix-систем, не влияет на их работу в ОС Windows, таким образом можно создавать кросс-платформенные скрипты. Ниже приведён простой пример скрипта, который выполняется из командной строки:

Пример #2 Скрипт для запуска из командной строки (script.php)

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    Это консольный PHP-скрипт, принимающий один аргумент.

      Использование:
      <?php echo $argv[0]; ?> <option>

      <option> Любое слово, которое вы хотели бы
      напечатать. Опции  --help, -help, -h,
      или -? покажут текущую справочную информацию.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

В приведённом скрипте первая строка содержит шебанг, который указывает, что файл запускается PHP. Работа ведётся с CLI-версией, поэтому не будет выведено ни одного HTTP-заголовка.

Скрипт сначала проверяет наличие обязательного одного аргумента (в дополнение к имени скрипта, который также подсчитывается). Если их нет, или если переданный аргумент был --help, -help, -h или -?, выводится справочное сообщение с использованием $argv[0], которое содержит имя выполняемого скрипта. В противном случае просто выводится полученный аргумент.

Для запуска приведённого примера в Unix-системе, нужно сделать его исполняемым и просто выполнить в консоли script.php echothis или script.php -h. В Windows-системе можно создать пакетный файл:

Пример #3 Пакетный файл для запуска PHP-скрипта из командной строки (script.bat)

    @echo OFF
    "C:\php\php.exe" script.php %*

Предполагая, что вышеприведённый скрипт называется script.php, а полный путь к CLI php.exe находится в C:\php\php.exe, этот пакетный файл запустит его с переданными параметрами: script.bat echothis или script.bat -h.

Также можно ознакомиться с модулем Readline для получения дополнительных функций, которые можно использовать для улучшения консольного PHP-скрипта.

В Windows запуск PHP можно настроить без необходимости указывать C:\php\php.exe или расширение `.php`. Подробнее эта тема описана в разделе Запуск PHP из командной строки в Microsoft Windows.

> Замечание:

> В Windows рекомендуется запускать PHP под актуальной учётной записью пользователя. При работе в сетевой службе отдельные операции не выполняются, поскольку «сопоставление имён учётных записей и идентификаторов безопасности не выполнено».

## Потоки ввода-вывода

Модуль CLI SAPI определяет набор констант для потоков ввода-вывода, чтобы упростить работу с командной строкой.

Константы, специфичные для модуля CLI
Константа | Описание
--- | ---
`STDIN` | Уже открытый поток ввода (`stdin`). Это предотвращает необходимость его открывать следующим способом:
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
Если вы хотите прочесть одну строку из `stdin`, можно использовать следующий код:
    <?php
    $line = trim(fgets(STDIN)); // читает одну строку из STDIN
    fscanf(STDIN, "%d\n", $number); // читает число из STDIN
    ?>
`STDOUT` | Уже открытый поток вывода (`stdout`). Это предотвращает необходимость его открывать следующим способом:
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | Уже открытый поток ошибок (`stderr`). Это предотвращает необходимость его открывать следующим способом:
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

Учитывая вышесказанное, нет необходимости самому открывать поток, например, `stderr`, а можно просто использовать уже определённую константу ресурса потока:

    php -r 'fwrite(STDERR, "stderr\n");'

PHP закроет поток автоматически при завершении работы скрипта, поэтому закрывать поток вручную не требуется.

> Замечание:

> Эти константы недоступны, если PHP-скрипт считывается из потока `stdin`.

## Интерактивная консоль

Модуль CLI SAPI поддерживает интерактивную консоль, которую запускает опция -a, если PHP скомпилировали с параметром --with-readline. Начиная с PHP PHP 7.1.0 интерактивная консоль также доступна в ОС Windows, если модуль readline включили.

Интерактивная консоль умеет принимать и выполнять сам PHP-код.

Пример #1 Запуск кода в интерактивной консоли

    $ php -a
    Interactive shell

    php > echo 5+8;
    13
    php > function addTwo($n)
    php > {
    php { return $n + 2;
    php { }
    php > var_dump(addtwo(2));
    int(4)
    php >

Интерактивная консоль при нажатии клавиши Tab также автодополняет названия функций, констант, классов, переменных, вызовы статических методов и константы классов.

Пример #2 Автодополнение по клавише Tab

Двойное нажатие клавиши Tab покажет список вариантов, если доступно больше одного варианта дополнения:

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

Когда есть только одно дополнение, одиночное нажатие Tab дополнит оставшийся текст на той же самой строке:

    php > strpt[TAB]ime(

Дополнение также работает для имён, которые объявили в течение текущей интерактивной сессии:

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

Интерактивная оболочка хранит историю команд, для доступа к которой нажимают стрелки вверх и вниз. История хранится в файле ~/.php_history. Начиная с PHP 8.4.0 установить путь к файлу с историей команд можно в переменной окружения PHP_HISTFILE.

Модуль CLI SAPI поддерживает две новые настройки в файле php.ini: `cli.pager` и `cli.prompt`. Директива `cli.pager` разрешает использовать внешнюю программу наподобие less для постраничного просмотра, а не прямого вывода данных на экран. Настройка `cli.prompt` разрешает задавать приглашение `php >` на ввод команды.

В интерактивной консоли также разрешается устанавливать настройки файла php.ini через специальное сокращение.

Пример #3 Установка настройки файла php.ini в интерактивной консоли

Настройка `cli.prompt`:

    php > #cli.prompt=hello world :>
    hello world :>

Обратными кавычками задают PHP-код, который выполнится в приглашении на ввод команды:

    php > #cli.prompt=`echo date('H:i:s');` php >
    15:49:35 php > echo 'hi';
    hi
    15:49:43 php > sleep(2);
    15:49:45 php >

Установка less для постраничного вывода данных:

    php > #cli.pager=less
    php > phpinfo();
    (output displayed in less)
    php >

Настройка `cli.prompt` поддерживает несколько управляющих последовательностей:

Управляющие последовательности `cli.prompt`
Управляющая последовательность | Описание
--- | ---
`\e` | Используется для добавления цветов в приглашение на ввод команды. Пример: `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | Версия PHP.
`\b` | Отображает в какой части PHP мы находимся. Для примера `/*` показывает, что мы находимся в многострочном комментарии. Внешняя область видимости обозначается как `php`.
`\>` | Указывает символ приглашения. По умолчанию это символ `>`, но можно изменить, когда оболочка находится внутри незакрытого блока или строки. Возможные символы: `' " { ( >`

> Замечание:

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

## Интерактивный режим

До PHP 8.1.0 при недоступности модуля readline вызов файла CLI SAPI с параметром -a запускал интерактивный режим. В этом режиме предполагается, что PHP-скрипт передадут целиком через стандартный входной поток STDIN, затем завершат ввод комбинацией клавиш ``CTRL` +`D`` (в POSIX-системах) или комбинацией ``CTRL` +`Z`` , за которой идёт клавиша `ENTER` (в ОС Windows), после чего скрипт обработается. По сути это то же самое, что и вызов CLI SAPI без параметра -a. option.

Начиная с PHP 8.1.0 при недоступности модуля readline вызов CLI SAPI с параметром -a завершается ошибкой.

## Встроенный веб-сервер

Внимание

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

Модуль CLI SAPI содержит встроенный веб-сервер.

Веб-сервер выполняет только один однопоточный процесс, поэтому приложения PHP остановятся при блокировке запроса.

URI-запросы обслуживаются из текущей директории, в которой запустили PHP, если не указали опцию -t для переназначения корневого документа. При запросе URI, который не указывает на конкретный файл, возвращается файл index.php или index.html в заданной директории. При недоступности файлов поиск файлов продолжается в родительской директории, и так далее, пока веб-сервер не найдёт файл или не достигнет корня документа. При обнаружении файла index.html веб-сервер возвращает содержимое файла, а при обнаружении файла index.php — возвращается результат обработки. При этом в элемент $_SERVER['PATH_INFO'] записывается последняя часть URL-адреса, иначе возвращается 404-й код ответа.

Если PHP-файл указывается в командной строке, когда запускается веб-сервер, то он рассматривается как скрипт "маршрутизации" (router). Скрипт выполняется в самом начале каждого HTTP-запроса. Если этот скрипт возвращает `false`, то запрашиваемый ресурс возвращается как есть. В противном случае браузеру будет возвращён вывод этого скрипта.

Стандартные MIME-типы возвращаются для файлов со следующими расширениями: `.3gp`, `.apk`, `.avi`, `.bmp`, `.css`, `.csv`, `.doc`, `.docx`, `.flac`, `.gif`, `.gz`, `.gzip`, `.htm`, `.html`, `.ics`, `.jpe`, `.jpeg`, `.jpg`, `.js`, `.kml`, `.kmz`, `.m4a`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.odp`, `.ods`, `.odt`, `.oga`, `.ogg`, `.ogv`, `.pdf`, `.png`, `.pps`, `.pptx`, `.qt`, `.svg`, `.swf`, `.tar`, `.text`, `.tif`, `.txt`, `.wav`, `.webm`, `.wmv`, `.xls`, `.xlsx`, `.xml`, `.xsl`, `.xsd`, `.zip` .

Начиная с PHP 7.4.0 встроенный веб-сервер получил поддержку многопроцессного режима работы для тестирования кода, который требует нескольких одновременных запросов к встроенному веб-серверу. Перед запуском сервера для переменной среды PHP_CLI_SERVER_WORKERS устанавливают количество рабочих процессов, которое требуется для тестирования.

> Замечание: ОС Windows не поддерживает многопроцессный режим.

> Замечание: Информацию о параметрах, которые поддерживает PHP в режиме командной строки, возвращают команды php --help или man php. PHP проигнорирует параметры командной строки, которые не сочетаются с параметром запуска веб-сервера.

Внимание

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

Пример #1 Запуск веб-сервера

    $ cd ~/public_html
    $ php -S localhost:8000

В консоли выведется:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit

После URI-запросов http://localhost:8000/ и http://localhost:8000/myscript.html в консоли выведется примерно следующее:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit.
    [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Обратите внимание, что до PHP 7.4.0 статические ресурсы с символическими ссылками не были доступны в Windows, если только скрипт маршрутизатора не обработал бы их.

Пример #2 Запуск с указанием корневой директории

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

В консоли выведется:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
    Listening on localhost:8000
    Document root is /home/me/public_html/foo
    Press Ctrl-C to quit

Пример #3 Скрипт маршрутизации

В следующем примере при запросе изображений выводится графический файл, а при запросе HTML-файлов возвращается строка "Добро пожаловать в PHP".

    <?php

    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false;    // Сервер возвращает файлы непосредственно
    } else {
        echo "<p>Добро пожаловать в PHP!</p>";
    }

    $ php -S localhost:8000 router.php

Внимание

Встроенный веб-сервер не должен использоваться в общедоступной сети.

Пример #4 Проверка использования веб-сервера CLI

Для совместного использования скрипта маршрутизации при разработке с веб-сервером CLI и в дальнейшем с рабочим (production) веб-сервером:

    <?php

    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* Маршрутизация статических ресурсов и возврат значения false */
    }
    /* Продолжение стандартных операций с файлом index.php */

    $ php -S localhost:8000 router.php

Пример #5 Обработка неподдерживаемых типов файлов

Для обслуживания статического ресурса, MIME-тип которого не обрабатывается веб-сервером CLI, используйте это:

    <?php

    // router.php
    $path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
    if ($path["extension"] == "el") {
        header("Content-Type: text/x-script.elisp");
        readfile($_SERVER["SCRIPT_FILENAME"]);
    } else {
        return FALSE;
    }

    $ php -S localhost:8000 router.php

Пример #6 Доступ к веб-серверу CLI с удалённых машин

Следующая команда откроет доступ к веб-серверу на порту 8000 для всех сетевых интерфейсов:

    $ php -S 0.0.0.0:8000

## Опции конфигурации

Опции конфигурации CLI SAPI
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL` |

Краткое разъяснение конфигурационных директив.

`cli_server.color` bool

  Включает поддержку цветовых кодов ANSI в выводе терминала встроенного веб-сервера.

# Сборка мусора

## Содержание

- Основы подсчёта ссылок
- Сбор циклических ссылок
- Вопросы производительности

Раздел описывает достоинства нового механизма сборки мусора (Garbage Collection, или GC), который появился в PHP 5.3.

## Основы подсчёта ссылок

Переменная PHP хранится в контейнере, который называется zval (англ. сокр.: Zend Value — Zend-значение). Контейнер zval, кроме типа и значения переменной, также содержит два дополнительных бита информации. Первый называется is_ref (англ. сокр.: Is Reference — ссылка ли?) и представляет логическое значение, которое указывает, включил ли PHP переменную в «набор ссылок» или нет. За счёт бита is_ref PHP-движок знает, как отличать обычные переменные от ссылок. Поскольку PHP разрешает пользовательские ссылки, которые создают оператором &, контейнер zval также содержит внутренний механизм подсчёта ссылок для оптимизации работы памяти. Вторая часть дополнительной информации называется refcount (англ. сокр.: Reference Counter — счётчик ссылок) и содержит количество имён переменных, или другое название — символов, которые указывают на этот zval-контейнер. Каждый символ хранится в таблице символов. У каждой области видимости переменных своя таблица символов. PHP создаёт отдельную область видимости для главного скрипта, который срабатывает при запросе из браузера, и отдельную область видимости для каждой функции или метода.

Контейнер zval создаётся при объявлении новой переменной, которой присваивается константное значение, например:

Пример #1 Создание нового контейнера zval

    <?php

    $a = "new string";

    ?>

В примере в текущей области видимости создаётся новый символ с именем "`a`" и новый контейнер переменной с типом string и значением `new string`. Бит is_ref по умолчанию задаётся равным `false`, поскольку не создали ни одной пользовательской ссылки. Значение же бита refcount задаётся равным `1`, поскольку с этим контейнером PHP связал только один символ. Обратите внимание, zval-контейнеры со значением `true` в бите is_ref и значением `1` в бите refcount движок преобразовывает в контейнеры стандартных переменных путём установки для бита is_ref значения `false`. Модуль » Xdebug умеет выводить эту информацию через функцию xdebug_debug_zval().

Пример #2 Вывод информации о zval-контейнере

    <?php

    $a = "new string";
    xdebug_debug_zval('a');

    ?>

Результат выполнения приведённого примера:

    a: (refcount=1, is_ref=0)='new string'

Присваивание одной переменной другому имени переменной увеличивает счётчик ссылок.

Пример #3 Увеличение счётчика ссылок контейнера zval

    <?php

    $a = "new string";
    $b = $a;
    xdebug_debug_zval('a');

    ?>

Результат выполнения приведённого примера:

    a: (refcount=2, is_ref=0)='new string'

Значение счётчика ссылок здесь равно `2`, поскольку с одним и тем же контейнером переменной PHP связал как символ a, так и символ b. PHP достаточно умён, чтобы не копировать сам контейнер, пока этого не требуется. Как только счётчик ссылок refcount становится равным нулю, контейнеры переменных уничтожаются. Счётчик ссылок refcount уменьшается на единицу, когда символ, который PHP связал с контейнером переменной, выходит из области видимости (например, в конце функции), или при удалении символа (например, при вызове языковой конструкции unset()).

Пример #4 Уменьшение счётчика ссылок контейнера zval

    <?php

    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval('a');

    $b = 42;
    xdebug_debug_zval('a');

    unset( $c );
    xdebug_debug_zval('a');

    ?>

Результат выполнения приведённого примера:

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

Вызов `unset($a);` в этом месте удалит контейнер переменной из памяти, включая тип и значение.

### Составные типы данных

Хранение составных типов данных наподобие массивов (array) и объектов (object) усложняется. Каждый элемент массива или каждое свойство объекта хранится в отдельной таблице символов, в противоположность хранению скалярных (scalar) значений одной и той же области видимости в одной таблице символов. Следующий пример создаст сразу три zval-контейнера:

Пример #5 Создание zval-контейнера для массива (array)

    <?php

    $a = array('meaning' => 'life', 'number' => 42);
    xdebug_debug_zval('a');

    ?>

Вывод приведённого примера будет похож на:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

Графически:

PHP создаёт три zval-контейнера для символов: a, meaning и number. Аналогичные правила применяются для увеличения и уменьшения количества ссылок. В следующем примере в массив добавляется ещё один элемент, которому устанавливается значение другого элемента массива:

Пример #6 Добавление уже существующего элемента в массив

    <?php

    $a = array('meaning' => 'life', 'number' => 42);
    $a['life'] = $a['meaning'];
    xdebug_debug_zval('a');

    ?>

Вывод приведённого примера будет похож на:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=2, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42,
       'life' => (refcount=2, is_ref=0)='life'
    )

Графически:

Из вывода модуля Xdebug видно, что как старый, так и новый элемент массива теперь указывает на zval-контейнер, значение refcount которого равно `2`. Хотя вывод модуля Xdebug показывает два zval-контейнера со значением `'life'`, контейнеры одинаковы. Функция xdebug_debug_zval() не показывает, что контейнеры одинаковы, но добавление в вывод указателей памяти покажет.

Элемент удаляется из массива аналогично удалению символа из области видимости: счётчик ссылок refcount того контейнера, на который указывает элемент массива, уменьшается. Контейнер переменной удаляется из памяти, когда значение в бите refcount достигает нуля. Пример:

Пример #7 Удаление элемента из массива

    <?php

    $a = array('meaning' => 'life', 'number' => 42);
    $a['life'] = $a['meaning'];
    unset($a['meaning'], $a['number']);
    xdebug_debug_zval('a');

    ?>

Вывод приведённого примера будет похож на:

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

Ситуация станет интереснее, если добавить массив сам в себя. В следующем примере вводится оператор присваивания по ссылке, чтобы PHP не создал копию массива.

Пример #8 Пример добавления массива как элемента самого себя

    <?php

    $a = array('one');
    $a[] =& $a;
    xdebug_debug_zval('a');

    ?>

Вывод приведённого примера будет похож на:

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

Графически:

Видно, что переменная массива a, и второй элемент с индексом 1 теперь указывают на контейнер переменной, значение refcount которого равно `2`. Символы «...» в выводе показывают рекурсию, что в этом примере означает, что символы «...» указывают на исходный массив.

Как и раньше, при удалении переменной символ удаляется, а счётчик ссылок контейнера переменной, на который указывает переменная, уменьшается на единицу. Поэтому, если применить конструкцию unset к переменной $a после запуска приведённого кода, счётчик ссылок контейнера переменной, на который указывают переменная $a и элемент массива с индексом 1, уменьшится на единицу, с 2 до 1:

Пример #9 Удаление переменной массива $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

Графически:

### Проблемы очистки

Хотя ни в одной области видимости больше нет символа, который указывает на структуру массива, структуру нельзя очистить, поскольку элемент массива с ключом 1 по-прежнему указывает на этот же массив. Поскольку на структуру не указывает внешний символ, пользователю недоступна очистка этой структуры; поэтому пользователь получает утечку памяти. К счастью, PHP очистит эту структуру данных в конце запроса, но до того момента данные будут занимать ценное место в памяти. Такая ситуация часто возникает при реализации алгоритмов синтаксического анализа или других вещей, в которых дочерние элементы указывают на родительские. С ещё большей вероятностью такая же ситуация возникает с объектами, поскольку с объектами язык неявно работает «по ссылке».

Не проблема, если такое случается раз или два, но при тысяче или даже миллионе таких случаев утечки памяти уже станут проблемой. Особенно в скриптах, которые работают долго, например, в демонах, в которых запрос не заканчивается, или в крупных наборах модульных тестов. Последний случай вызвал проблемы при запуске модульных тестов для компонента Template библиотеки ez Components. В ряде случаев требовалось больше 2 ГБ памяти, доступа к которой на тестовом сервере не было.

## Сбор циклических ссылок

Традиционно механизмы подсчёта ссылок в памяти вроде тех, которые работали в PHP раньше, не справлялись с утечками памяти, которые вызывали циклические ссылки; однако с PHP 5.3.0 разработчики языка реализовали синхронный алгоритм из исследования » Concurrent Cycle Collection in Reference Counted Systems (англ. «Параллельный сбор циклических ссылок в системах подсчёта ссылок»), который решает эту проблему.

Полное описание работы алгоритма выходит за рамки раздела, но основы раздел объясняет. Вначале установим базовые правила. Первое, PHP продолжает хранить в памяти и не считает мусором контейнеры, значение бита refcount которых увеличилось. Zval-контейнер, количество ссылок в котором уменьшилось до нуля, освобождается из памяти. Поэтому циклические ссылки становятся мусорными, только когда переменных со ссылкой на контейнер не осталось, а значение аргумента refcount в контейнере не обнулилось. Второе, PHP умеет обнаруживать мусорные части в мусорных циклах путём уменьшения количества ссылок в контейнерах на единицу и проверки, в каких zval-контейнерах количество ссылок стало нулевым.

Алгоритм помещает возможные корни — zval-контейнеры — в «корневой буфер» и помечает корни «фиолетовыми», чтобы не вызывать проверку мусорных циклов при каждом уменьшении счётчика ссылок. Алгоритм следит и за тем, чтобы каждый возможный мусорный корень попадал в буфер только один раз. Механизм сборки мусора для каждого zval-контейнера внутри буфера стартует, только когда корневой буфер заполняется. Графически поведение показывает шаг A на рисунке выше.

На шаге B алгоритм выполняет поиск в глубину по каждому возможному корню, чтобы однократно уменьшить количество ссылок в каждом контейнере на единицу, и помечает корни «серыми». На шаге C алгоритм снова выполняет поиск в глубину от каждого корневого узла, чтобы ещё раз проверить количество ссылок для каждого zval-контейнера. Алгоритм помечает корни с нулевым количеством ссылок «белыми» (на рисунке — синим). А если количество ссылок в контейнере больше нуля, начиная с этого корня поиск идёт в глубину с обратным увеличением количества ссылок на единицу и пометкой корней «черными». На последнем шаге, D, алгоритм обходит корневой буфер и удаляет из него корни контейнеров. Алгоритм заодно проверяет, какие zval-контейнеры на предыдущем шаге он пометил «белыми». Каждый «белый» zval-контейнер освобождается из памяти.

Теперь, когда есть базовое представление о работе алгоритма, вернёмся к тому, как алгоритм интегрируется с PHP. По умолчанию сборщик мусора PHP включён. Параметр zend.enable_gc в файле php.ini разрешает отключить сборку мусора.

При включённом сборщике мусора, алгоритм поиска циклических ссылок выполняется после каждого наполнения корневого буфера. Фиксированный размер корневого буфера равняется 10 000 возможных корней, хотя значение изменяется путём изменения значения константы `GC_THRESHOLD_DEFAULT` в файле `Zend/zend_gc.c` исходного кода PHP и пересборки PHP. При выключенном сборщике мусора алгоритм поиска циклических ссылок не запускается. Однако в корневой буфер всё равно записываются возможные корни, независимо от активации механизма сборки мусора через параметр конфигурации.

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

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

Кроме изменения параметра конфигурации zend.enable_gc, доступен запуск механизма сборки мусора через вызов функции gc_enable() и остановка механизма функцией gc_disable(). Вызов этих функций даёт тот же эффект, что и включение или выключение механизма в настройках конфигурации. Возможна также принудительная сборка мусорных циклов, даже если корневой буфер ещё не заполнился. Для этого вызывают функцию gc_collect_cycles(), которая возвращает количество циклических ссылок, которые собрал алгоритм.

Смысл включения и выключения механизма сборки мусора, а также ручного запуска механизма состоит в чувствительности отдельных частей приложения ко времени, когда автоматический запуск механизма сборки мусора не нужен. Отключение сборщика мусора в конкретных частях приложения создаёт риск утечки памяти, поскольку отдельные корни не поместятся в ограниченный корневой буфер. Поэтому лучше перед вызовом функции gc_disable() вызвать функцию gc_collect_cycles(), чтобы освободить память, риск потери которой возникает из-за возможных корней, которые алгоритм уже записал в корневой буфер. Это очистит буфер и даст больше места для хранения корней, пока механизм сбора мусорных циклов будет выключен.

## Вопросы производительности

Предыдущий раздел уже упоминал, что простой сбор корней незначительно влияет на производительность, но это если сравнивать PHP 5.2 с PHP 5.3. Хотя запись корней в буфер по сравнению с отсутствием такой записи в PHP 5.2 замедляет работу приложения, другие изменения в работе PHP 5.3 во время выполнения кода предотвратили даже проявление этой конкретной потери производительности.

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

### Уменьшение размера памяти

Первая причина появления в языке механизма сборки мусора, состоит в уменьшении размера памяти, которую занимает мусор, путём очистки переменных с циклическими ссылками в тот момент, когда выполнятся предварительные условия. В реализации PHP сборка мусора начинается, как только заполняется корневой буфер или при вызове функции gc_collect_cycles(). График ниже показывает, как скрипт под графиком занимает память в PHP 5.2 и PHP 5.3, без учёта памяти, которую занимает сам PHP при запуске.

Пример #1 Пример использования памяти

    <?php

    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    $baseMemory = memory_get_usage();

    for ($i = 0; $i <= 100000; $i++) {
        $a = new Foo();
        $a->self = $a;
        if ($i % 500 === 0) {
            echo sprintf('%8d: ', $i), memory_get_usage() - $baseMemory, "\n";
        }
    }

    ?>

В этом академическом примере создаётся объект, в котором устанавливается свойство, которое указывает на сам объект. Когда в скрипте переменной $a на следующей итерации цикла повторно присваивается значение, происходит типичная утечка памяти. В примере утекает память для двух zval-контейнеров — контейнера объекта и контейнера свойства объекта, — но алгоритм находит только один корень: переменную, которую удалили. Как только после 10 000 итераций (если PHP-сборка разрешает только 10 000 корней) корневой буфер заполняется, срабатывает механизм сборки мусора и память, которую занимают эти корни, освобождается. Этот процесс хорошо виден на неравномерном графике потребления памяти PHP 5.3: после каждых 10 000 итераций график проседает. Сам механизм в примере совершает не много работы, потому что структура утечек проста. Из графика видно, что максимальное потребление памяти в PHP 5.3 составило около 9 МБ, тогда как в PHP 5.2 потребление памяти продолжает расти.

### Замедление работы

Вторая область, в которой механизм сборки мусора влияет на производительность, — потеря времени, которое требуется сборщику мусора для освобождения «утечки» памяти. Чтобы понять степень влияния, изменим предыдущий скрипт путём добавления количества итераций и удаления промежуточных показателей потребления памяти. После изменения скрипт выглядит вот так:

Пример #2 Влияние на производительность

    <?php

    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    for ($i = 0; $i <= 1000000; $i++) {
        $a = new Foo();
        $a->self = $a;
    }

    echo memory_get_peak_usage(), "\n";

    ?>

Запустим скрипт два раза: с включённой опцией zend.enable_gc и без неё.

Пример #3 Запуск скрипта

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # и
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

На тестовой машине первая команда выполняется примерно 10.7 секунды, а вторая примерно 11.4 секунды. Это примерно на 7 % медленнее. Однако максимальное потребление памяти скриптом уменьшилось на 98 % — с 931 до 10 МБ. Этот тест производительности не научный и даже не представляет реальное приложение, но показывает преимущества в работе с памятью, которые даёт механизм сборки мусора. Хорошо то, что замедление скрипта каждый раз составляет одни и те же 7 %, тогда как экономия памяти постоянно увеличивается по мере того, как алгоритм во время выполнения скрипта обнаруживает всё больше циклических ссылок.

### Внутренняя статистика сборщика мусора

PHP умеет выдавать больше информации о том, как механизм сборки мусора выполняется в PHP. Но для этого потребуется перекомпилировать PHP, чтобы включить код теста производительности и сбора данных. До запуска команды `./configure` с параметрами, которые требуются пользователю, потребуется установить для переменной окружения `CFLAGS` значение `-DGC_BENCH=1`. Следующая последовательность должна сработать:

Пример #4 Пример перекомпиляции PHP для включения теста производительности сборки мусора

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

При повторном запуске приведенного примера кода с двоичным файлом PHP, который только что создали, после завершения выполнения PHP выведет следующее:

Пример #5 Статистика сборки мусора

    GC Statistics
    -------------
    Runs:               110
    Collected:          2072204
    Root buffer length: 0
    Root buffer peak:   10000

          Possible            Remove from  Marked
            Root    Buffered     buffer     grey
          --------  --------  -----------  ------
    ZVAL   7175487   1491291    1241690   3611871
    ZOBJ  28506264   1527980     677581   1025731

Самую информативную статистику показывает первый блок. Видно, что механизм сборки мусора запускался 110 раз, и суммарно освободил больше 2 миллионов записей в памяти. Как только механизм сборки мусора сработал хотя бы один раз, показатель пика корневого буфера (Root buffer peak) будет равняться 10 000.

### Заключение

Сборщик мусора в PHP вызывает замедление работы только во время работы алгоритма сборки циклических ссылок, тогда как в стандартных скриптах меньшего размера производительность не падает.

Когда механизм сборки циклов все-таки запускается для стандартных скриптов, объём памяти, которую экономит механизм, разрешает одновременно запускать на сервере большее количество скриптов, поскольку в целом скрипты занимают не так много памяти.

Преимущества заметнее для скриптов, которые работают долго — большие наборы тестов или демоны. Новый механизм существенно сокращает утечки памяти для приложений, которые работают с расширением » PHP-GTK, которые часто выполняются дольше, чем скрипты для веба.

# Динамическая трассировка DTrace

## Содержание

- Введение в PHP и DTrace
- PHP и DTrace
- Работа средства SystemTap со статическими зондами PHP DTrace
- Работа трассировщика bpftrace со статическими зондами PHP DTrace

## Введение в PHP и DTrace

DTrace — встроенный в ядро системы фреймворк трассировки с низким уровнем накладных расходов. Фреймворк доступен в Solaris, macOS, Oracle Linux, BSD и на других платформах. DTrace отслеживает поведение операционной системы и запущенных пользовательских приложений, показывает значения параметров и выводит статистику производительности. Мониторинг зондов выполняется через пользовательские скрипты на языке DTrace D. Перечисленные свойства и механизмы делают фреймворк эффективным инструментом анализа отдельных показателей.

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

PHP включает в себя зонды «Статически определённой трассировки уровня пользователя» (User-level Statically Defined Tracing, или USDT), которые работают во время исполнения. Например, когда D-скрипт отслеживает зонд `function-entry`, каждый раз при вызове функции этот зонд запускает действие D-скрипта, которое соответствует функции. Это действие, например, печатает аргументы зонда наподобие расположения этой функции в PHP-скрипте. Или же агрегирует данные наподобие количества запусков каждой функции.

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

Статические зонды DTrace в PHP также умеют работать со средством SystemTap в отдельных дистрибутивах ОС Linux.

## PHP и DTrace

PHP конфигурируется со статическими зондами DTrace на платформах, которые поддерживают динамическую трассировку DTrace.

### Конфигурирование PHP со статическими зондами DTrace

Обратитесь к документации платформы, чтобы включить поддержку DTrace в операционной системе. Например, в Oracle Linux требуется загрузить ядро UEK3 и сделать следующее:

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

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

Сборка PHP с ключом `--enable-dtrace`:

    # ./configure --enable-dtrace ...
    # make
    # make install

Сборка PHP с ключом `--enable-dtrace` сделает статические зонды доступными в ядре PHP. Каждый PHP-модуль, который предоставляет свои зонды, потребуется собрать отдельно как разделяемый модуль.

Установите переменную среды USE_ZEND_DTRACE=1 для целевых PHP-процессов, чтобы включить зонды.

### Статические зонды DTrace в ядре PHP

Следующие статические зонды доступны в PHP
Название зонда | Описание зонда | Аргументы зонда
--- | --- | ---
`request-startup` | Срабатывает при начале запроса. | char *file, char *request_uri, char *request_method
`request-shutdown` | Срабатывает при окончании запроса. | char *file, char *request_uri, char *request_method
`compile-file-entry` | Срабатывает, когда начинается компиляция скрипта. | char *compile_file, char *compile_file_translated
`compile-file-return` | Срабатывает, когда заканчивается компиляция скрипта. | char *compile_file, char *compile_file_translated
`execute-entry` | Срабатывает, когда запускается массив байт-кода. К примеру, когда вызываются функции, возобновляется работа генератора или происходит include. | char *request_file, int lineno
`execute-return` | Срабатывает, после отработки массива байт-кода. | char *request_file, int lineno
`function-entry` | Срабатывает, когда движок PHP начинает запуск функции или метода. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | Срабатывает, когда движок PHP возвращается из функции или метода. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | Срабатывает, когда выброшено исключение. | char *classname
`exception-caught` | Срабатывает, когда исключение поймано. | char *classname
`error` | Срабатывает, если возникла ошибка, независимо от уровня error_reporting. | char *errormsg, char *request_file, int lineno

Модули PHP могут содержать дополнительные зонды.

### Список статических зондов DTrace в PHP

Запустите PHP-процесс и выполните следующую команду, чтобы получить список зондов:

    # dtrace -l

Команда выведет примерно следующее:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
        4   php15271               php               dtrace_compile_file compile-file-entry
        5   php15271               php               dtrace_compile_file compile-file-return
        6   php15271               php                        zend_error error
        7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
        8   php15271               php     zend_throw_exception_internal exception-thrown
        9   php15271               php                 dtrace_execute_ex execute-entry
       10   php15271               php           dtrace_execute_internal execute-entry
       11   php15271               php                 dtrace_execute_ex execute-return
       12   php15271               php           dtrace_execute_internal execute-return
       13   php15271               php                 dtrace_execute_ex function-entry
       14   php15271               php                 dtrace_execute_ex function-return
       15   php15271               php              php_request_shutdown request-shutdown
       16   php15271               php               php_request_startup request-startup

Колонка Provider содержит надпись `php` и PID-идентификатор текущего запущенного PHP-процесса.

При работе веб-сервера Apache название модуля выводится как, например, libphp5.so, и выводятся серия блоков списка, по одному на каждый процесс Apache.

Колонка Function ссылается на название внутренней С-функции PHP, которая реализует соответствующий зонд.

Список не будет содержать зонды, которые связаны с PHP, если PHP не запустили.

### Примеры работы DTrace с PHP

Пример показывает базовые возможности скриптового языка DTrace D.

Пример #1 Скрипт all_probes.d — трассировка статических PHP-зондов через DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::compile-file-entry
    {
        printf("PHP compile-file-entry\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::compile-file-return
    {
        printf("PHP compile-file-return\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::error
    {
        printf("PHP error\n");
        printf("  errormsg                  %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
    }

    php*:::exception-caught
    {
        printf("PHP exception-caught\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::exception-thrown
    {
        printf("PHP exception-thrown\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::execute-entry
    {
        printf("PHP execute-entry\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::execute-return
    {
        printf("PHP execute-return\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::function-entry
    {
        printf("PHP function-entry\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::function-return
    {
        printf("PHP function-return\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::request-shutdown
    {
        printf("PHP request-shutdown\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

    php*:::request-startup
    {
        printf("PHP request-startup\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

Для команды dtrace скрипт указывает опцию `-Z` и разрешает работу, даже если ни один PHP-процесс не запущен. Без опции скрипт сразу же завершит выполнение, поскольку не увидит ни одного зонда для отслеживания.

Скрипт отслеживает каждый статический PHP-зонд на всём протяжении работы PHP-скрипта. Запускаем D-скрипт:

    # ./all_probes.d

Запустите скрипт или PHP-приложение. Отслеживающий D-скрипт будет выводить аргументы каждого сработавшего зонда.

После получения информации работу скрипта прерывают комбинацией ``CTRL`+`C``.

На многопроцессорных машинах порядок зондов непоследователен и зависит от процессоров, на которых работают зонды и как мигрируют потоки между процессорами. Отображение временных меток помогает избегать конфузов. К примеру:

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### Смотрите также

- OCI8 и динамическая трассировка DTrace

## Работа средства SystemTap со статическими зондами PHP DTrace

В отдельных дистрибутивах Linux для отслеживания статических зондов DTrace доступен инструмент трассировки SystemTap. Этот вариант доступен в PHP 5.4.20 и PHP 5.5.

### Установка PHP с SystemTap

Установите разработческий пакет SystemTap SDT:

    # yum install systemtap-sdt-devel

Установите PHP с DTrace:

    # ./configure --enable-dtrace ...
    # make

### Получение списка статических зондов через SystemTap

Статические PHP-зонды выводит команда stap:

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

Примерный вывод:

    process("sapi/cli/php").provider("php").mark("compile__file__entry")
    process("sapi/cli/php").provider("php").mark("compile__file__return")
    process("sapi/cli/php").provider("php").mark("error")
    process("sapi/cli/php").provider("php").mark("exception__caught")
    process("sapi/cli/php").provider("php").mark("exception__thrown")
    process("sapi/cli/php").provider("php").mark("execute__entry")
    process("sapi/cli/php").provider("php").mark("execute__return")
    process("sapi/cli/php").provider("php").mark("function__entry")
    process("sapi/cli/php").provider("php").mark("function__return")
    process("sapi/cli/php").provider("php").mark("request__shutdown")
    process("sapi/cli/php").provider("php").mark("request__startup")

### Пример работы SystemTap с PHP

Пример #1 Скрипт all_probes.stp — трассировка статических PHP-зондов

    probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("error") {
        printf("Probe error\n");
        printf("  errormsg %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
    }
    probe process("sapi/cli/php").provider("php").mark("exception__caught") {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("execute__entry") {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("execute__return") {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("function__entry") {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("function__return") {
        printf("Probe function__return: %s\n", user_string($arg1));
        printf(" function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }
    probe process("sapi/cli/php").provider("php").mark("request__startup") {
        printf("Probe request__startup\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }

Приведённый скрипт выводит данные статических PHP-зондов на всём протяжении работы PHP-скрипта:

    # stap -c 'sapi/cli/php test.php' all_probes.stp

## Работа трассировщика bpftrace со статическими зондами PHP DTrace

В дистрибутивах Linux, в которых ядро поддерживает технологию eBPF, трассировщик bpftrace умеет подключаться к зондам PHP DTrace USDT без посредничества инструмента SystemTap.

### Установка bpftrace

Установите bpftrace через менеджер пакетов дистрибутива. Например, в Oracle Linux, RHEL или Fedora:

    # dnf install bpftrace

Или в Debian либо Ubuntu:

    # apt install bpftrace

Следующие примеры предполагают, что целевой исполняемый файл PHP установлен по пути /usr/bin/php.

Те же зонды USDT предоставляют и другие SAPI, которые собрали из того же дерева исходного кода, поэтому целью зондов вместо этого выступает либо модуль Apache (libphp.so), либо исполняемый файл диспетчера процессов FastCGI (php-fpm); подставьте правильный путь или подключитесь по PID-идентификатору через ключ `-p` при необходимости.

Убедитесь, что собрали целевой исполняемый файл с поддержкой фреймворка DTrace и что правильно настроили переменные окружения. Подробности описывает раздел Конфигурирование PHP со статическими зондами DTrace.

Статические зонды PHP выводит команда bpftrace:

    # bpftrace -l 'usdt:/usr/bin/php:php:*'

Команда выводит:

    usdt:/usr/bin/php:php:compile__file__entry
    usdt:/usr/bin/php:php:compile__file__return
    usdt:/usr/bin/php:php:error
    usdt:/usr/bin/php:php:exception__caught
    usdt:/usr/bin/php:php:exception__thrown
    usdt:/usr/bin/php:php:execute__entry
    usdt:/usr/bin/php:php:execute__return
    usdt:/usr/bin/php:php:function__entry
    usdt:/usr/bin/php:php:function__return
    usdt:/usr/bin/php:php:request__shutdown
    usdt:/usr/bin/php:php:request__startup

Пример #1 Скрипт all_probes.bt — трассировка всех статических PHP-зондов через bpftrace

    #!/usr/bin/env bpftrace

    usdt:/usr/bin/php:php:compile__file__entry
    {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:compile__file__return
    {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:error
    {
        printf("Probe error\n");
        printf("  errormsg %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
    }
    usdt:/usr/bin/php:php:exception__caught
    {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:exception__thrown
    {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:execute__entry
    {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:execute__return
    {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:function__entry
    {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:function__return
    {
        printf("Probe function__return\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:request__shutdown
    {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }
    usdt:/usr/bin/php:php:request__startup
    {
        printf("Probe request__startup\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }

Приведённый скрипт трассирует все статические зонды ядра PHP на всём протяжении работы PHP-скрипта. Трассировщику bpftrace требуются привилегии суперпользователя:

    # USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt

Для трассировки уже запущенного PHP-процесса, например, рабочего процесса php-fpm или процесса Apache, который загрузил библиотеку libphp.so, подключитесь по PID:

    # bpftrace -p $PID all_probes.bt

Внутри скрипта после `usdt:` потребуется указать цель — путь до исполняемого файла запущенного процесса: `usdt:/usr/bin/php`; замените путь в строке спецификации зонда на путь до исполняемого файла php-fpm или библиотеки libphp.so, если потребуется.

- HTTP-аутентификация в PHP
- Cookies
- Сессии
- Загрузка файлов на сервер
  - Загрузка файлов методом POST
  - Объяснение сообщений об ошибках
  - Распространённые подводные камни
  - Загрузка нескольких файлов
  - Поддержка метода PUT
  - Смотрите также
- Работа с удалёнными файлами
- Работа с соединениями
- Постоянные соединения с базами данных
- Работа с PHP из командной строки
  - Основные отличия от остальных реализаций SAPI
  - Опции — Список опций командной строки
  - Использование — Выполнение PHP-файлов
  - Потоки ввода-вывода
  - Интерактивная консоль
  - Встроенный веб-сервер
  - Опции конфигурации
- Сборка мусора
  - Основы подсчёта ссылок
  - Сбор циклических ссылок
  - Вопросы производительности
- Динамическая трассировка DTrace
  - Введение в PHP и DTrace
  - PHP и DTrace
  - Работа средства SystemTap со статическими зондами PHP DTrace
  - Работа трассировщика bpftrace со статическими зондами PHP DTrace

# Справочник функций

Подсказка

Смотрите также Список и классификация модулей.

# Изменение поведения PHP

# Пользовательский кеш APC

# Введение

Модуль APCu — хранилище «ключ — значение» для PHP. Ключи и значения хранятся в памяти. Ключи хранятся как строки (string), а значения как произвольные PHP-переменные. Модуль APCu поддерживает кеширование переменных только в пространстве пользователя.

В ОС Windows отдельные процессы работают с отдельными APCu-кешами, поэтому при работе с SAPI-интерфейсами на основе процессов, а не потоков, кеш не будет разделяться между процессами.

Модуль APCu — это модуль APC, из которого удалили кеширование опкода.

Первая кодовая база модуля APCu появилась под версией 4.0.0 как независимая копия, или форк, последних изменений основной ветки модуля APC. Поддержка PHP 7 появилась с APCu 5.0.0. Поддержка PHP 8 появилась с APCu 5.1.19.

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/apcu.

Подсказка

Обратную совместимость PHP 7 с модулем APC поддерживает отдельный модуль — » apcu-bc.

В режиме обратной совместимости модуль APCu регистрирует пригодные функции модуля APC через обратно совместимые прототипы функций.

Если функция модуля APC принимает параметр `cache_type`, обратно совместимая версия функции просто игнорирует и не включает параметр в прототип функции модуля APCu.

Внимание

Начиная с PHP 8.0.0 модуль apcu-bc больше не поддерживается.

> Замечание: В ОС Windows модулю APCu для хранения кеша требуется временный путь, к которому у веб-сервера будет доступ для записи. Модуль по порядку проверяет переменные окружения TMP, TEMP, USERPROFILE, и только если ни одну из переменных не установили, пытается работать с каталогом WINDOWS.

> Замечание: Углублённую высокотехнологичную информацию о реализации модуля даёт » файл TECHNOTES, который предоставил разработчик.

Исходные коды модуля APCu хранятся » на сайте Github.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

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

При настройке APCu необходимо определиться, сколько памяти предоставить в распоряжение APCu. Директива ini-файла, которая отвечает за эту настройку — `apc.shm_size`. Внимательно прочитайте нижеследующий раздел.

После запуска сервера скрипт `apc.php`, который поставляется вместе с модулем, следует скопировать в docroot и просмотреть в браузере, поскольку он предоставляет подробный анализ внутренней работы APCu. Если в PHP включён модуль GD, он даже отобразит некоторые интересные графики.

Если APCu работает, число `Cache full count` (слева) покажет, сколько раз кеш достигал максимальной ёмкости и был вынужден вытеснять записи, чтобы освободить память. Во время вытеснения, если указали значение `apc.ttl`, хранилище APCu сначала попытается удалить записи с истёкшим сроком действия, т. е. записи, TTL которых либо истёк, либо записи, у которых TTL не установлен и к которым не было доступа в течение последних `apc.ttl` секунд. Если значение `apc.ttl` не установили или удаление истёкших записей не освободило достаточно места, APCu очистит весь кеш.

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

Если APCu собрали с поддержкой mmap (Memory Mapping), оно будет использовать только один сегмент памяти, если же наоборот, APCu собрали с поддержкой SHM (SysV Shared Memory), оно будет использовать несколько сегментов. MMAP не имеет максимального ограничения, в отличие от SHM, который ограничивается `/proc/sys/kernel/shmmax`. Обычно рекомендуется использовать MMAP, потому что он гораздо быстрее выделяет память при перезагрузке веб-сервера, что сказывается на скорости запуска сервера.

Опции конфигурации APCu
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
apc.enabled | 1 | `INI_SYSTEM` |
apc.shm_segments | 1 | `INI_SYSTEM` |
apc.shm_size | "32M" | `INI_SYSTEM` |
apc.entries_hint | 512 * apc.shm_size | `INI_SYSTEM` | До APcu 5.1.25 значение по умолчанию равнялось 4096.
apc.ttl | 0 | `INI_SYSTEM` |
apc.gc_ttl | 3600 | `INI_SYSTEM` |
apc.mmap_file_mask | NULL | `INI_SYSTEM` |
apc.slam_defense | 0 | `INI_SYSTEM` |
apc.enable_cli | 0 | `INI_SYSTEM` |
apc.use_request_time | 0 | `INI_ALL` | До APCu 5.1.19 значение по умолчанию равнялось `1`.
apc.serializer | "php" | `INI_SYSTEM` | До APCu 5.1.19 значение по умолчанию равнялось `"default"`.
apc.coredump_unmap | 0 | `INI_SYSTEM` |
apc.preload_path | NULL | `INI_SYSTEM` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`apc.enabled` bool
  Для опцпии `apc.enabled` устанавливают значение 0, чтобы отключить APC. Это в первую очередь полезно, когда APC статически компилируется в PHP, поскольку нет другого способа отключить его (при компиляции как DSO строку `extension` в файле `php.ini` можно просто закомментировать).
`apc.shm_segments` int
  Количество сегментов разделяемой памяти, которые выделили под кеш компилятора. Если APC не хватает разделяемой памяти, но для опции `apc.shm_size` установили настолько максимальное значение, насколько разрешает система, увеличение этого значения может помешать APC исчерпать свою память. система.
`apc.shm_size` string
  Размер сегмента разделяемой памяти, заданный в короткой нотации (смотрите этот FAQ). По умолчанию, некоторые системы (включая большинство вариантов BSD) ограничивают это значение крайне малым значением.
`apc.entries_hint` int
  Это подсказка о количестве уникальных пользовательских переменных, которые надо кешировать. Установите равным нулю или вообще не указывайте, если не уверены.
`apc.ttl` int
  Записи кеша без явного указания TTL считаются истёкшими, если к ним не обращались в течение этого количества секунд. По сути, это позволяет удалять такие записи оппортунистически во время добавления кеша или перед полным удалением. Обратите внимание, что поскольку удаление происходит по обстоятельствам, записи могут быть доступны для чтения, даже если их срок жизни превышает `apc.ttl` секунд. Параметр не влияет на записи кеша, для которых явно задан TTL.
`apc.gc_ttl` int
  Количество секунд, в течение которых запись кеша остаётся в списке сборщика мусора после удаления или инвалидации. Записи подлежат удалению, если количество ссылок на них равно нулю или записи оставались в списке дольше этого ограничения времени. Со значением `0` очистка по времени отключается, а записи удаляются только тогда, когда количество ссылок на них обнуляется.
`apc.mmap_file_mask` string
  Если собран с поддержкой MMAP через опцию `--enable-mmap`, этот параметр должен содержать файловую маску типа mktemp-style для передачи в модуль MMAP, чтобы определить, будет ли MMAP использовать файловую систему или разделяемую память. Для файловой системы опцию устанавливают так: `/tmp/apc.XXXXXX` (ровно 6 `X`). Чтобы использовать shm_open/mmap в стиле POSIX, в любом месте маски добавляют `.shm`, например: `/apc.shm.XXXXXX`. Чтобы использовать для анонимной памяти mmap интерфейс `/dev/zero`, который входит в ядро, для опции устанавливают значение `/dev/zero`. Если опцию оставили неопределённой, mmap будет анонимным.
`apc.slam_defense` bool
  На очень загруженных серверах всякий раз, когда запускается веб-сервер или изменяются файлы, запускается гонка из множества процессов, которые попытаются закешировать один и тот же файл одновременно. Установка для опции `apc.slam_defense` значения `1` помогает предотвратить одновременное кеширование процессами одного и того же файла за счёт введения вероятностного механизма. Если разные процессы пытаются кешировать один и тот же ключ в течение короткого периода времени, кеширование для текущего процесса пропускается, чтобы уменьшить потенциальные сбои в кеше.
`apc.enable_cli` int
  Больше для тестирования и отладки. Эта настройка включает APCu для CLI версии PHP. При обычной работе, запускать APCu, который будет создавать, наполнять и уничтожать кеш при каждом запуске сценария в консоли, будет далеко не лучшей идеей. Но в целях тестирования и отладки, можно легко включить APCu для CLI.
`apc.serializer` string
  Указывает APC использовать сторонний сериализатор.
`apc.coredump_unmap` bool
  Разрешает APC перехватывать сигналы, такие как SIGSEGV, который записывает coredump, когда подан. Когда эти сигналы будут получены, APC попытается освободить всю разделяемую память, чтобы не включать её в coredump. Эта настройка может увеличить стабильность системы, когда критический сигнал был получен, а APC сконфигурирован на использование большого объёма памяти.
  Внимание

  Эта возможность потенциально опасна. Освобождение сегментов разделяемой памяти при получении критического сигнала может привести к непредсказуемому поведению.

  > Замечание: Хотя некоторые ядра предоставляют возможность игнорировать некоторые сегменты разделяемой памяти при записи core-файла, эти реализации могут также игнорировать важные сегменты памяти, такие как Apache scoreboard.

`apc.preload_path` string
  Опционально. Задаёт путь, который используется APC для загрузки кешированных данных во время запуска.
`apc.use_request_time` bool
  Использовать время старта запроса SAPI для TTL.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`APC_ITER_ALL` (int)
`APC_ITER_ATIME` (int)
`APC_ITER_CTIME` (int)
`APC_ITER_DEVICE` (int)
`APC_ITER_DTIME` (int)
`APC_ITER_FILENAME` (int)
`APC_ITER_INODE` (int)
`APC_ITER_KEY` (int)
`APC_ITER_MD5` (int)
`APC_ITER_MEM_SIZE` (int)
`APC_ITER_MTIME` (int)
`APC_ITER_NONE` (int)
`APC_ITER_NUM_HITS` (int)
`APC_ITER_REFCOUNT` (int)
`APC_ITER_TTL` (int)
`APC_ITER_TYPE` (int)
`APC_ITER_VALUE` (int)
`APC_LIST_ACTIVE` (int)
`APC_LIST_DELETED` (int)

# Функции APCu

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — Добавить переменную в кеш

### Описание

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Добавляет переменную в кеш, если её там ещё нет.

> Замечание: В отличие от многих других механизмов PHP, переменные, сохранённые apcu_add(), сохраняются между запросами, пока их не удалят из кеша.

### Список параметров

`key`
  Имя, под которым будет сохранена переменная. Значение `key` является уникальным для кеша, так что попытка использовать apcu_add() для сохранения переменной с ключом, который уже существует, не перезапишет запись, а вернёт `false`. (Это единственное различие между apcu_add() и apcu_store().)
`var`
  Переменная для сохранения
`ttl`
  Время жизни; переменная `var` будет храниться в течение `ttl` секунд. Как только `ttl` секунд пройдут, переменная будет удалена из кеша (при следующем запросе). Если параметр `ttl` не задан (или `ttl` задан как `0`), значение будет храниться пока не будет удалено явно, либо по технической причине (очистка кеша, перезапуск и т.д.)
`values`
  Имена в ключах, переменные в значениях.

### Возвращаемые значения

Возвращает `true`, если удалось занести значение в кеш, в противном случае возвращает `false`. Второй тип синтаксиса возвращает массив с ключами, по которым произошла ошибка.

### Примеры

Пример #1 Пример использования apcu_add()

    <?php
    $bar = 'BAR';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    $bar = 'NEVER GETS SET';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    ?>

Результат выполнения приведённого примера:

    string(3) "BAR"
    string(3) "BAR"

### Смотрите также

- apcu_store() - Кеширует переменную
- apcu_fetch() - Извлекает из кеша сохранённую переменную
- apcu_delete() - Удаляет сохранённое значение из кеша

# apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — Извлекает закешированную информацию из хранилища APCu

### Описание

function apcu_cache_info(bool `$limited` = `false`): array|false

Извлекает закешированную информацию из хранилища APCu.

### Список параметров

`limited`
  Если `limited` задан как `true`, возвращаемое значение не будет содержать индивидуальный список записей кеша. Это полезно при попытках оптимизировать вызовы для получения статистики.

### Возвращаемые значения

Массив кешированных данных (и метаданные) или `false`, если возникла ошибка

> Замечание: apcu_cache_info() вызывает предупреждение, если невозможно получить данные кеша APCu. Обычно это происходит, если APCu не разрешён.

### Список изменений

Версия | Описание
--- | ---
PECL apcu 3.0.11 | Добавлен параметр `limited`.
PECL apcu 3.0.16 | Добавлена опция "`filehits`" для параметра `cache_type`.

### Примеры

Пример #1 Пример использования apcu_cache_info()

    <?php
    print_r(apcu_cache_info());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [num_slots] => 2000
        [ttl] => 0
        [num_hits] => 9
        [num_misses] => 3
        [start_time] => 1123958803
        [cache_list] => Array
            (
                [0] => Array
                    (
                        [filename] => /path/to/apcu_test.php
                        [device] => 29954
                        [inode] => 1130511
                        [type] => file
                        [num_hits] => 1
                        [mtime] => 1123960686
                        [creation_time] => 1123960696
                        [deletion_time] => 0
                        [access_time] => 1123962864
                        [ref_count] => 1
                        [mem_size] => 677
                    )
                [1] => Array (...итерирует для каждого закешированного файла)
    )

### Смотрите также

- Директивы конфигурации APCu
- APCUIterator::getTotalSize() - Общий размер кеша
- APCUIterator::getTotalHits() - Получить общее количество попаданий в кеш
- APCUIterator::getTotalCount() - Получить общее количество записей

# apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — Заменяет старое значение на новое

### Описание

function apcu_cas(string `$key`, int `$old`, int `$new`): bool

apcu_cas() заменяет значение уже существующего целочисленного значения, если оно равно `old` на `new`.

### Список параметров

`key`
  Ключ изменяемого значения.
`old`
  Старое значение (которое в данный момент хранится в кеше).
`new`
  Новое значение.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования apcu_cas()

    <?php
    apcu_store('foobar', 2);
    echo '$foobar = 2', PHP_EOL;
    echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
    echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

    echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

    apcu_store('perfection', 'xyz');
    echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
    ?>

Вывод приведённого примера будет похож на:

    $foobar = 2
    $foobar == 1 ? 2 : 1 = fail
    $foobar == 2 ? 1 : 2 = ok
    $foobar = 1
    $f__bar == 1 ? 2 : 1 = fail
    $perfection == 2 ? 1 : 2 = epic fail
    $foobar = 1

### Смотрите также

- apcu_dec() - Уменьшить сохранённое число
- apcu_store() - Кеширует переменную

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Очистить кеш APCu

### Описание

function apcu_clear_cache(): bool

Очищает кеш APCu.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Всегда возвращает `true`

### Смотрите также

- apcu_cache_info() - Извлекает закешированную информацию из хранилища APCu

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Уменьшить сохранённое число

### Описание

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Уменьшает сохранённое число.

### Список параметров

`key`
  Ключ значения, которое надо уменьшить.
`step`
  Величина, на которую необходимо уменьшить.
`success`
  Необязательный параметр. Если задан, то в него будет записано логическое значение `true` или `false` в зависимости от успешности операции уменьшения.
`ttl`
  TTL(время жизни), используемое если операция вставляет новое значение (а не уменьшает существующее).

### Возвращаемые значения

Возвращает текущее значение `key` в случае успешного выполнения или `false`, если возникла ошибка

### Примеры

Пример #1 Пример использования apcu_dec()

    <?php
    echo "Сделаем что-то без ошибки", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_dec('anumber'), PHP_EOL;
    echo apcu_dec('anumber', 10), PHP_EOL;
    echo apcu_dec('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "А теперь с ошибкой", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_dec('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Вывод приведённого примера будет похож на:

    Сделаем что-то без ошибки
    42
    41
    31
    21
    bool(true)
    А теперь с ошибкой

    bool(false)
    bool(false)

### Смотрите также

- apcu_inc() - Увеличить сохранённое число

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Удаляет сохранённое значение из кеша

### Описание

function apcu_delete(mixed `$key`): mixed

Удаляет сохранённое значение из кеша.

### Список параметров

`key`
  `key` можно задать как строку, для удаления одного значения, либо как массив строк, для удаления нескольких значений, либо как объект APCUIterator.

### Возвращаемые значения

Если `key` является массивом (array), возвращается индексированный массив (array) ключей. В противном случае возвращается `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования apcu_delete()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);

    //Удаляем одну запись.
    apcu_delete('foo');

    // Удаляем несколько записей.
    apcu_delete(['foo', 'bar', 'baz']);

    // Используем итератор с регулярным выражением.
    apcu_delete(new APCUIterator('#^myprefix_#'));
    ?>

### Смотрите также

- apcu_store() - Кеширует переменную
- apcu_fetch() - Извлекает из кеша сохранённую переменную
- apcu_clear_cache() - Очистить кеш APCu
- APCUIterator

# apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — Возможно ли использовать APCu в текущем окружении

### Описание

function apcu_enabled(): bool

Определяет, возможно ли использовать APCu в текущем окружении.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false` в зависимости от возможности использовать APCu.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Атомарно извлекает или генерирует запись в кеше

### Описание

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

Функция атомарно пытается найти запись с ключом `key`, а если не находит, вызывает `callback`-функцию и передаёт в функцию обратного вызова ключ `key` как единственный аргумент. Затем функция кеширует значение, которое вернула callback-функция, опционально устанавливает для записи время жизни `ttl` и возвращает это значение.

> Замечание: Как только функция apcu_entry() получает управление, устанавливается эксклюзивная блокировка кеша, которая снимается при выходе из функции apcu_entry(): тело `callback`-функции становится критической секцией и не разрешает двум процессам выполнять одни и те же ветви кода одновременно. Эта же блокировка устанавливается и для остальных APCu-функций, поэтому параллельное выполнение функций модуля невозможно.

Внимание

Единственная APCu-функция, которая безопасно вызывается в `callback`-функции, — apcu_entry().

### Список параметров

`key`
  Идентификатор записи.
`callback`
  Callback-функция, которая принимает единственный аргумент `key` и возвращает значение для кеширования.
`ttl`
  Время жизни; параметр `ttl` устанавливает интервал времени в секундах, в течение которого значение возврата `callback`-функции хранится в кеше. По истечении количества секунд, которое определили в параметре `ttl`, запись удаляется из кеша при следующем запросе. При пропуске параметра `ttl` или при передаче в параметр `ttl` значения `0` запись хранится, пока не удалится вручную или не исчезнет из кеша из-за автоматической очистки, перезапуска сервера и по другой причине.

### Возвращаемые значения

Функция возвращает значение, которое закешировала.

### Примеры

Пример #1 Пример атомарного извлечения или генерации записи кеша функцией apcu_entry()

    <?php

    $config = apcu_entry("config", function($key) {
     return [
       "fruit" => apcu_entry("config.fruit", function($key){
         return [
           "apples",
           "pears"
         ];
       }),
       "people" => apcu_entry("config.people", function($key){
         return [
          "bob",
          "joe",
          "niki"
         ];
       })
     ];
    });

    var_dump($config);

    ?>

Результат выполнения приведённого примера:

    array(2) {
      ["fruit"]=>
      array(2) {
        [0]=>
        string(6) "apples"
        [1]=>
        string(5) "pears"
      }
      ["people"]=>
      array(3) {
        [0]=>
        string(3) "bob"
        [1]=>
        string(3) "joe"
        [2]=>
        string(4) "niki"
      }
    }

### Смотрите также

- apcu_store() - Кеширует переменную
- apcu_fetch() - Извлекает из кеша сохранённую переменную
- apcu_delete() - Удаляет сохранённое значение из кеша

# apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — Проверяет, существуют ли записи

### Описание

function apcu_exists(string|array `$keys`): bool|array

Проверяет, существуют ли записи.

### Список параметров

`keys`
  Строка или массив строк, содержащие ключи для проверки.

### Возвращаемые значения

Возвращает `true`, если ключ существует или `false`, если нет. Если же был передан массив ключей, то вернётся массив с существующими ключами, либо пустой массив, если ни одного ключа не существует.

### Примеры

Пример #1 Пример использования apcu_exists()

    <?php
    $fruit  = 'apple';
    $veggie = 'carrot';

    apcu_store('foo', $fruit);
    apcu_store('bar', $veggie);

    if (apcu_exists('foo')) {
        echo "Foo с: ";
        echo apcu_fetch('foo');
    } else {
        echo "Foo не существует";
    }

    echo PHP_EOL;
    if (apcu_exists('baz')) {
        echo "Baz существует.";
    } else {
        echo "Baz не существует";
    }

    echo PHP_EOL;

    $ret = apcu_exists(array('foo', 'donotexist', 'bar'));
    var_dump($ret);

    ?>

Вывод приведённого примера будет похож на:

    Foo существует: apple
    Baz не существует
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### Смотрите также

- apcu_cache_info() - Извлекает закешированную информацию из хранилища APCu
- apcu_fetch() - Извлекает из кеша сохранённую переменную

# apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — Извлекает из кеша сохранённую переменную

### Описание

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Функция извлекает из кеша сохранённую переменную.

### Список параметров

`key`
  Ключ `key`, под которым запись была сохранена в кеш (с помощью apcu_store()). Если задан массив, то будет извлечён и возвращён каждый элемент.
`success`
  Устанавливается в `true` в случае успешного выполнения и `false`, если возникла ошибка.

### Возвращаемые значения

Функция возвращает сохранённую переменную или массив переменных в случае успешного выполнения; `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL apcu 3.0.17 | Добавлен параметр `success`.

### Примеры

Пример #1 Пример использования apcu_fetch()

    <?php

    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));

    ?>

Результат выполнения приведённого примера:

    string(3) "BAR"

### Смотрите также

- apcu_store() - Кеширует переменную
- apcu_delete() - Удаляет сохранённое значение из кеша
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Увеличить сохранённое число

### Описание

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Увеличивает сохранённое число.

### Список параметров

`key`
  Ключ значения, которое надо увеличить.
`step`
  Величина, на которую необходимо увеличить.
`success`
  Необязательный параметр. Если задан, то в него будет записано логическое значение `true` или `false` в зависимости от успешности операции увеличения.
`ttl`
  TTL(время жизни), используемое если операция вставляет новое значение (а не увеличивает существующее).

### Возвращаемые значения

Возвращает текущее значение `key` в случае успешного выполнения или `false`, если возникла ошибка

### Примеры

Пример #1 Пример использования apcu_inc()

    <?php
    echo "Сделаем что-то без ошибки", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_inc('anumber'), PHP_EOL;
    echo apcu_inc('anumber', 10), PHP_EOL;
    echo apcu_inc('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "А теперь с ошибкой", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_inc('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Вывод приведённого примера будет похож на:

    Сделаем что-то без ошибки
    42
    43
    53
    63
    bool(true)
    А теперь с ошибкой

    bool(false)
    bool(false)

### Смотрите также

- apcu_dec() - Уменьшить сохранённое число

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Получить детальную информацию о ключе в кеше

### Описание

function apcu_key_info(string `$key`): ?array

Получить детальную информацию о ключе в кеше

### Список параметров

`key`
  Ключ, для которого требуется получить информацию.

### Возвращаемые значения

Массив, содержащий подробную информацию о ключе кеша или `null`, если ключ не существует.

### Примеры

Пример #1 Пример использования apcu_key_info()

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

Результат выполнения приведённого примера:

    array(7) {
      ["hits"]=>
      int(0)
      ["access_time"]=>
      int(1606701783)
      ["mtime"]=>
      int(1606701783)
      ["creation_time"]=>
      int(1606701783)
      ["deletion_time"]=>
      int(0)
      ["ttl"]=>
      int(0)
      ["refs"]=>
      int(0)
    }

### Смотрите также

- apcu_store() - Кеширует переменную
- apcu_fetch() - Извлекает из кеша сохранённую переменную
- apcu_delete() - Удаляет сохранённое значение из кеша

# apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — Извлекает информацию о выделении разделяемой памяти APCu

### Описание

function apcu_sma_info(bool `$limited` = `false`): array|false

Извлекает информацию о выделении разделяемой памяти APCu.

### Список параметров

`limited`
  Если установлен в `false` (по умолчанию), apcu_sma_info() вернёт детальную информацию о каждом сегменте.

### Возвращаемые значения

Массив данных о выделенной разделяемой памяти; `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования apcu_sma_info()

    <?php
    print_r(apcu_sma_info());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### Смотрите также

- Директивы конфигурации APCu

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — Кеширует переменную

### Описание

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Кеширует переменную.

> Замечание: В отличие от многих других механизмов PHP, переменные, сохранённые apcu_store(), сохраняются между запросами, пока их не удалят из кеша.

### Список параметров

`key`
  Имя, под которым будет сохранена переменная. Значение `key` является уникальным для кеша, так что попытка сохранить запись с ключом `key`, который уже существует, приведёт к её перезаписи.
`var`
  Переменная для сохранения
`ttl`
  Время жизни; переменная `var` будет храниться в течение `ttl` секунд. Как только `ttl` секунд пройдут, переменная будет удалена из кеша (при следующем запросе). Если параметр `ttl` не задан (или `ttl` задан как `0`), значение будет храниться пока не будет удалено явно, либо по технической причине (очистка кеша, перезапуск и т.д.)
`values`
  Имена в ключах, переменные в значениях.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Второй тип синтаксиса возвращает массив с ключами, по которым произошла ошибка.

### Примеры

Пример #1 Пример использования apcu_store()

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

Результат выполнения приведённого примера:

    string(3) "BAR"

### Смотрите также

- apcu_add() - Добавить переменную в кеш
- apcu_fetch() - Извлекает из кеша сохранённую переменную
- apcu_delete() - Удаляет сохранённое значение из кеша

## Содержание

- apcu_add — Добавить переменную в кеш
- apcu_cache_info — Извлекает закешированную информацию из хранилища APCu
- apcu_cas — Заменяет старое значение на новое
- apcu_clear_cache — Очистить кеш APCu
- apcu_dec — Уменьшить сохранённое число
- apcu_delete — Удаляет сохранённое значение из кеша
- apcu_enabled — Возможно ли использовать APCu в текущем окружении
- apcu_entry — Атомарно извлекает или генерирует запись в кеше
- apcu_exists — Проверяет, существуют ли записи
- apcu_fetch — Извлекает из кеша сохранённую переменную
- apcu_inc — Увеличить сохранённое число
- apcu_key_info — Получить детальную информацию о ключе в кеше
- apcu_sma_info — Извлекает информацию о выделении разделяемой памяти APCu
- apcu_store — Кеширует переменную

# Класс APCUIterator

(PECL apcu >= 5.0.0)

## Введение

Класс APCUIterator позволяет с лёгкостью итерировать большой APCu кеш. Это полезно, так как позволяет перебирать большой кеш по шагам, забирая заданное количество записей используя одну блокировку, позволяя другим активностям использовать блокировку, а не задерживать весь кеш для чтения ста (по умолчанию) записей. Также, использование регулярных выражений более эффективно, так как выполняется на уровне скомпилированного кода C.

## Обзор класса

class APCUIterator implements Iterator {
/* Методы */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — Создаёт объект итератор класса APCUIterator

### Описание

public function APCUIterator::__construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)

Создаёт объект APCUIterator.

### Список параметров

`search`
  Либо регулярное выражение PCRE, которое соответствует именам ключей APCu, заданным как строки (string). Или массив (array) строк (string) с именами ключей APCu. Или, необязательно, `null` чтобы пропустить поиск.
`format`
  Формат, заданный одной из констант APC_ITER_*.
`chunk_size`
  Размер блока данных. Должно быть больше 0. По умолчанию 100.
`list`
  Тип списка. Задаётся константами `APC_LIST_ACTIVE` или `APC_LIST_DELETED`.

### Примеры

Пример #1 Пример использования APCUIterator::__construct()

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### Смотрите также

- apcu_exists() - Проверяет, существуют ли записи
- apcu_cache_info() - Извлекает закешированную информацию из хранилища APCu

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Получить текущий элемент

### Описание

public function APCUIterator::current(): mixed

Получает текущий элемент стека APCUIterator.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

В случае успешного выполнения возвращает текущий элемент либо `false`, если элементов больше нет или произошла ошибка.

### Смотрите также

- APCUIterator::next() - Перемещает указатель на следующий элемент
- Iterator::current() - Возврат текущего элемента

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Получить общее количество записей

### Описание

public function APCUIterator::getTotalCount(): int

Получить общее количество записей.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Общее количество записей.

### Смотрите также

- APCUIterator::getTotalHits() - Получить общее количество попаданий в кеш
- APCUIterator::getTotalSize() - Общий размер кеша
- apcu_cache_info() - Извлекает закешированную информацию из хранилища APCu

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Получить общее количество попаданий в кеш

### Описание

public function APCUIterator::getTotalHits(): int

Получить общее количество попаданий в кеш.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество попаданий в случае успешного выполнения или `false` в случае возникновения ошибки.

### Смотрите также

- APCUIterator::getTotalCount() - Получить общее количество записей
- APCUIterator::getTotalSize() - Общий размер кеша
- apcu_cache_info() - Извлекает закешированную информацию из хранилища APCu

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Общий размер кеша

### Описание

public function APCUIterator::getTotalSize(): int

Возвращает общий размер кеша.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Общий размер кеша.

### Смотрите также

- APCUIterator::getTotalCount() - Получить общее количество записей
- APCUIterator::getTotalHits() - Получить общее количество попаданий в кеш
- apc_cache_info()

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — Получить ключ итератора

### Описание

public function APCUIterator::key(): string

Возвращает текущий ключ итератора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает ключ в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- APCUIterator::current() - Получить текущий элемент
- Iterator::key() - Возвращает ключ текущего элемента

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Перемещает указатель на следующий элемент

### Описание

public function APCUIterator::next(): bool

Перемещает указатель на следующий элемент.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- APCUIterator::current() - Получить текущий элемент
- APCUIterator::rewind() - Перемотка итератора
- Iterator::next() - Переходит к следующему элементу

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Перемотка итератора

### Описание

public function APCUIterator::rewind(): void

Устанавливает указатель итератора на первый элемент.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- APCUIterator::next() - Перемещает указатель на следующий элемент
- Iterator::next() - Переходит к следующему элементу

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Проверяет, корректна ли текущая позиция итератора

### Описание

public function APCUIterator::valid(): bool

Проверяет, корректна ли текущая позиция итератора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false`, в зависимости от того, корректна ли позиция.

### Смотрите также

- APCUIterator::current() - Получить текущий элемент
- Iterator::valid() - Проверяет корректность текущей позиции

## Содержание

- APCUIterator::__construct — Создаёт объект итератор класса APCUIterator
- APCUIterator::current — Получить текущий элемент
- APCUIterator::getTotalCount — Получить общее количество записей
- APCUIterator::getTotalHits — Получить общее количество попаданий в кеш
- APCUIterator::getTotalSize — Общий размер кеша
- APCUIterator::key — Получить ключ итератора
- APCUIterator::next — Перемещает указатель на следующий элемент
- APCUIterator::rewind — Перемотка итератора
- APCUIterator::valid — Проверяет, корректна ли текущая позиция итератора

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции APCu
  - apcu_add — Добавить переменную в кеш
  - apcu_cache_info — Извлекает закешированную информацию из хранилища APCu
  - apcu_cas — Заменяет старое значение на новое
  - apcu_clear_cache — Очистить кеш APCu
  - apcu_dec — Уменьшить сохранённое число
  - apcu_delete — Удаляет сохранённое значение из кеша
  - apcu_enabled — Возможно ли использовать APCu в текущем окружении
  - apcu_entry — Атомарно извлекает или генерирует запись в кеше
  - apcu_exists — Проверяет, существуют ли записи
  - apcu_fetch — Извлекает из кеша сохранённую переменную
  - apcu_inc — Увеличить сохранённое число
  - apcu_key_info — Получить детальную информацию о ключе в кеше
  - apcu_sma_info — Извлекает информацию о выделении разделяемой памяти APCu
  - apcu_store — Кеширует переменную
- APCUIterator — Класс APCUIterator
  - APCUIterator::__construct — Создаёт объект итератор класса APCUIterator
  - APCUIterator::current — Получить текущий элемент
  - APCUIterator::getTotalCount — Получить общее количество записей
  - APCUIterator::getTotalHits — Получить общее количество попаданий в кеш
  - APCUIterator::getTotalSize — Общий размер кеша
  - APCUIterator::key — Получить ключ итератора
  - APCUIterator::next — Перемещает указатель на следующий элемент
  - APCUIterator::rewind — Перемотка итератора
  - APCUIterator::valid — Проверяет, корректна ли текущая позиция итератора

# Componere

# Введение

Componere (латинский, английский: compose) предназначен для производственных окружений и предоставляет API для составления классов, обезьяньих патчей и приведения.

##### Структура:

Componere\Definition используется для определения (или переопределения) класса во время выполнения; Затем класс может быть зарегистрирован и в случае переопределения он заменяет исходный класс до тех пор, пока существует Componere\Definition.

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

##### Патчинг:

Componere\Patch используется для изменения класса конкретного экземпляра объекта во время выполнения; После применения исправление будет применяться до тех пор, пока существует Componere\Patch и его можно явно отменить.

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

##### Приведение:

Componere\ функции приведения могут приводить среди определённых пользователем совместимых типов; В случае совместимости означает, что Type является подчинённым или супер типом `object`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Для работы модуля требуется Reflection

## Установка

Исходный код Componere и выпуски доступны на » github

# Класс Componere\Abstract\Definition

(Componere 2 >= 2.1.0)

## Введение

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

## Обзор класса

final abstract class Componere\Abstract\Definition {
/* Методы */
public function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Добавляет интерфейс

### Описание

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Реализует данный интерфейс по текущему определению

### Список параметров

`interface`
  Имя интерфейса без учёта регистра

### Возвращаемые значения

The current Definition

### Exceptions

Внимание

Выбрасывает исключение RuntimeException, если Definition был зарегистрирован

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Добавляет метод

### Описание

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Должен создать или переопределить метод в текущем определении.

### Список параметров

`name`
  Нечувствительное к регистру имя метода
`method`
  Componere\Method ранее не добавленный к другому Definition

### Возвращаемые значения

The current Definition

### Exceptions

Внимание

Выбрасывает исключение RuntimeException, если Definition был зарегистрирован

Внимание

Выбрасывает исключение RuntimeException, если метод был добавлен к другому определению

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Добавляет трейт

### Описание

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Использовать данный трейт для текущего определения

### Список параметров

`trait`
  Нечувствительное к регистру имя трейта

### Возвращаемые значения

The current Definition

### Exceptions

Внимание

Выбрасывает исключение RuntimeException, если Definition был зарегистрирован

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### Описание

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Должен создать или вернуть ReflectionClass

### Возвращаемые значения

ReflectionClass для текущего определения (кешируется)

## Содержание

- Componere\Abstract\Definition::addInterface — Добавляет интерфейс
- Componere\Abstract\Definition::addMethod — Добавляет метод
- Componere\Abstract\Definition::addTrait — Добавляет трейт
- Componere\Abstract\Definition::getReflector — Reflection

# Класс Componere\Definition

(Componere 2 >= 2.1.0)

## Введение

Класс Definition позволяет программисту создавать и регистрировать тип во время выполнения.

Если Definition заменит существующий класс, существующий класс будет восстановлен после уничтожения Definition.

## Обзор класса

final class Componere\Definition extends Componere\Abstract\Definition {
/* Конструкторы класса */
public function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* Методы */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Наследуемые методы */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Определяет конструктор

### Описание

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

### Список параметров

`name`
  Регистронезависимое название класса.
`parent`
  Регистронезависимое название класса.
`interfaces`
  Массив регистронезависимых названий интерфейсов.

### Исключения

Внимание

Метод выбрасывает исключение InvalidArgumentException при попытке заменить внутренний класс.

Внимание

Метод выбрасывает исключение InvalidArgumentException при попытке заменить интерфейс.

Внимание

Метод выбрасывает исключение InvalidArgumentException при попытке заменить трейт.

Внимание

Метод выбрасывает исключение RuntimeException, если PHP не нашёл интерфейс, который указали в параметре `interfaces`.

Внимание

Метод выбрасывает исключение RuntimeException, если в параметре `interfaces` указали название класса, а не интерфейса.

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Добавляет константу

### Описание

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Должен объявить константу класса в текущем определении

### Список параметров

`name`
  Регистронезависимое имя константы
`value`
  Значение для константы не должно быть неопределённым (undefined) или статичным

### Возвращаемые значения

Текущее определение

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если Definition уже было зарегистрировано

Внимание

Выбрасывает исключение RuntimeException, если `name` уже объявлено как константа

Внимание

Выбрасывает исключение RuntimeException, если `value` является статичным

Внимание

Выбрасывает исключение RuntimeException, если `value` является неопределённым

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Добавляет свойство

### Описание

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Должен объявить свойство класса в текущем определении

### Список параметров

`name`
  Регистронезависимое имя свойства
`value`
  Значение свойства по умолчанию

### Возвращаемые значения

Текущее определение

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если Definition уже было зарегистрировано

Внимание

Выбрасывает исключение RuntimeException, если `name` уже объявлен как свойство

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Регистрация

### Описание

public function Componere\Definition::register(): void

Регистрирует текущее определение

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если Definition уже был зарегистрирован

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — Определение состояния

### Описание

public function Componere\Definition::isRegistered(): bool

Определяет состояние регистрации этого определения

### Возвращаемые значения

Возвращает true, если определение зарегистрировано

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Получает замыкание

### Описание

public function Componere\Definition::getClosure(string `$name`): Closure

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

### Список параметров

`name`
  Регистронезависимое имя метода

### Возвращаемые значения

Замыкание, привязанное к корректной области

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если Definition уже было зарегистрировано

Внимание

Выбрасывает исключение RuntimeException, если `name` не найдено

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Получает замыкание

### Описание

public function Componere\Definition::getClosures(): array

Возвращает массив замыканий

### Возвращаемые значения

Возвращает все методы в виде массива объектов Closure, привязанных к корректной области

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если Definition уже было зарегистрировано

## Содержание

- Componere\Definition::__construct — Определяет конструктор
- Componere\Definition::addConstant — Добавляет константу
- Componere\Definition::addProperty — Добавляет свойство
- Componere\Definition::register — Регистрация
- Componere\Definition::isRegistered — Определение состояния
- Componere\Definition::getClosure — Получает замыкание
- Componere\Definition::getClosures — Получает замыкание

# Класс Componere\Patch

(Componere 2 >= 2.1.0)

## Введение

Класс Patch позволяет программисту изменять тип экземпляра во время выполнения без регистрации нового Definition.

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

## Обзор класса

final class Componere\Patch extends Componere\Abstract\Definition {
/* Конструкторы класса */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* Методы */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Наследуемые методы */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Создёт объект класса Patch

### Описание

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### Список параметров

`instance`
  Цель для объекта класса Patch.
`interfaces`
  Регистронезависимый массив названий интерфейсов.

### Исключения

Внимание

Метод выбрасывает исключение RuntimeException, если PHP не нашёл интерфейс, который указали в параметре `interfaces`.

Внимание

Метод выбрасывает исключение RuntimeException, если в параметре `interfaces` указали название класса, а не интерфейса.

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Приложение

### Описание

public function Componere\Patch::apply(): void

Применяет текущий патч

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Отмена

### Описание

public function Componere\Patch::revert(): void

Отменяет текущий патч

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — Определение состояния

### Описание

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Получение патча

### Описание

public function Componere\Patch::derive(object `$instance`): Patch

Должен получить Patch для заданного экземпляра `instance`

### Список параметров

`instance`
  Назначение для полученного патча

### Возвращаемые значения

Patch для `instance` получается из текущего Patch

### Исключения

Внимание

Выбрасывает исключение InvalidArgumentException если `instance` не совместим

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Получает замыкание

### Описание

public function Componere\Patch::getClosure(string `$name`): Closure

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

### Список параметров

`name`
  Регистронезависимое имя метода

### Возвращаемые значения

Замыкание, привязанное к правильной области и объекту

### Исключения

Внимание

Выбрасывает исключение RuntimeException если `name` не найден

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Получает замыкания

### Описание

public function Componere\Patch::getClosures(): array

Должен вернуть массив замыканий

### Возвращаемые значения

Должен вернуть все методы в виде массива объектов Closure, привязанных к правильной области и объекту

## Содержание

- Componere\Patch::__construct — Создёт объект класса Patch
- Componere\Patch::apply — Приложение
- Componere\Patch::revert — Отмена
- Componere\Patch::isApplied — Определение состояния
- Componere\Patch::derive — Получение патча
- Componere\Patch::getClosure — Получает замыкание
- Componere\Patch::getClosures — Получает замыкания

# Класс Componere\Method

(Componere 2 >= 2.1.0)

## Введение

Method представляет функцию с изменяемыми флагами доступности

## Обзор класса

final class Componere\Method {
/* Конструктор класса */
public function __construct(Closure `$closure`)
/* Методы */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Конструктор класса Method

### Описание

public function Componere\Method::__construct(Closure `$closure`)

### Список параметров

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Изменение доступности

### Описание

public function Componere\Method::setPrivate(): Method

### Возвращаемые значения

Текущий метод

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если уровень доступа был ранее установлен

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Изменение доступности

### Описание

public function Componere\Method::setProtected(): Method

### Возвращаемые значения

Текущий метод

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если уровень доступа был ранее установлен

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Изменение доступности

### Описание

public function Componere\Method::setStatic(): Method

### Возвращаемые значения

Текущий метод

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### Описание

public function Componere\Method::getReflector(): ReflectionMethod

Должен создать и вернуть ReflectionMethod

### Возвращаемые значения

ReflectionMethod для текущего метода (кешируется)

## Содержание

- Componere\Method::__construct — Конструктор класса Method
- Componere\Method::setPrivate — Изменение доступности
- Componere\Method::setProtected — Изменение доступности
- Componere\Method::setStatic — Изменение доступности
- Componere\Method::getReflector — Reflection

# Класс Componere\Value

(Componere 2 >= 2.1.0)

## Введение

Value представляет переменную PHP всех типов, включая неопределённую (undefined)

## Обзор класса

final class Componere\Value {
/* Конструктор класса */
public function __construct(mixed `$default` = ?)
/* Методы */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Конструктор класса Value

### Описание

public function Componere\Value::__construct(mixed `$default` = ?)

### Список параметров

`default`

### Исключения

Внимание

Выбрасывает исключение InvalidArgumentException, если `default` не имеет подходящего значения

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Изменение доступности

### Описание

public function Componere\Value::setPrivate(): Value

### Возвращаемые значения

Текущее значение

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если уровень доступа был ранее установлен

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Изменение доступности

### Описание

public function Componere\Value::setProtected(): Value

### Возвращаемые значения

Текущее значение

### Исключения

Внимание

Выбрасывает исключение RuntimeException, если уровень доступа был ранее установлен

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Изменение доступности

### Описание

public function Componere\Value::setStatic(): Value

### Возвращаемые значения

Текущее значение

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Определение доступности

### Описание

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Определение доступности

### Описание

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Определение доступности

### Описание

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Взаимодействие с классом Value

### Описание

public function Componere\Value::hasDefault(): bool

## Содержание

- Componere\Value::__construct — Конструктор класса Value
- Componere\Value::setPrivate — Изменение доступности
- Componere\Value::setProtected — Изменение доступности
- Componere\Value::setStatic — Изменение доступности
- Componere\Value::isPrivate — Определение доступности
- Componere\Value::isProtected — Определение доступности
- Componere\Value::isStatic — Определение доступности
- Componere\Value::hasDefault — Взаимодействие с классом Value

# Функции Componere

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Приведение к типу

### Описание

function Componere\cast(string `$type`, object `$object`): object

### Список параметров

`type`
  Пользовательский тип
`object`
  Объект с пользовательским типом, совместимый с Type

### Возвращаемые значения

object типа Type, приведённый из `object`

### Ошибки

Внимание

Выбрасывает исключение InvalidArgumentException, если тип `object` является производным от внутреннего класса

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является интерфейсом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является трейтом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является абстрактным классом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type не совместим с типом `object`

### Смотрите также

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Приведение к типу

### Описание

function Componere\cast_by_ref(string `$type`, object `$object`): object

### Список параметров

type
  Пользовательский тип
`object`
  Объект с пользовательским типом, совместимым с Type

### Возвращаемые значения

object типа Type, приведённый из `object`, где элементы являются ссылками на элементы `object`

### Ошибки

Внимание

Выбрасывает исключение InvalidArgumentException, если тип `object` является производным от внутреннего класса

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является интерфейсом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является трейтом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type является абстрактным классом

Внимание

Выбрасывает исключение InvalidArgumentException, если Type не совместим с типом `object`

### Смотрите также

- Componere\cast

## Содержание

- Componere\cast — Приведение к типу
- Componere\cast_by_ref — Приведение к типу

- Установка и настройка
  - Требования
  - Установка
- Componere\Abstract\Definition — Класс Componere\Abstract\Definition
  - Componere\Abstract\Definition::addInterface — Добавляет интерфейс
  - Componere\Abstract\Definition::addMethod — Добавляет метод
  - Componere\Abstract\Definition::addTrait — Добавляет трейт
  - Componere\Abstract\Definition::getReflector — Reflection
- Componere\Definition — Класс Componere\Definition
  - Componere\Definition::__construct — Определяет конструктор
  - Componere\Definition::addConstant — Добавляет константу
  - Componere\Definition::addProperty — Добавляет свойство
  - Componere\Definition::register — Регистрация
  - Componere\Definition::isRegistered — Определение состояния
  - Componere\Definition::getClosure — Получает замыкание
  - Componere\Definition::getClosures — Получает замыкание
- Componere\Patch — Класс Componere\Patch
  - Componere\Patch::__construct — Создёт объект класса Patch
  - Componere\Patch::apply — Приложение
  - Componere\Patch::revert — Отмена
  - Componere\Patch::isApplied — Определение состояния
  - Componere\Patch::derive — Получение патча
  - Componere\Patch::getClosure — Получает замыкание
  - Componere\Patch::getClosures — Получает замыкания
- Componere\Method — Класс Componere\Method
  - Componere\Method::__construct — Конструктор класса Method
  - Componere\Method::setPrivate — Изменение доступности
  - Componere\Method::setProtected — Изменение доступности
  - Componere\Method::setStatic — Изменение доступности
  - Componere\Method::getReflector — Reflection
- Componere\Value — Класс Componere\Value
  - Componere\Value::__construct — Конструктор класса Value
  - Componere\Value::setPrivate — Изменение доступности
  - Componere\Value::setProtected — Изменение доступности
  - Componere\Value::setStatic — Изменение доступности
  - Componere\Value::isPrivate — Определение доступности
  - Componere\Value::isProtected — Определение доступности
  - Componere\Value::isStatic — Определение доступности
  - Componere\Value::hasDefault — Взаимодействие с классом Value
- Функции Componere
  - Componere\cast — Приведение к типу
  - Componere\cast_by_ref — Приведение к типу

# Обработка и логирование ошибок

# Введение

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

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

Функции логирования позволяют настраивать тип и детализацию информации об ошибках того или иного типа от простых уведомлений до трассировки функций, вызвавших ошибку.

# Установка и настройка

## Содержание

- Настройка во время выполнения

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Настройки конфигурации протоколирования событий и ошибок
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | Доступно, начиная с PHP 8.5.0
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | До PHP 8.0.0 значение по умолчанию было `"0"`.
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | Не имеет смысла в версии PHP 8.0.0, удалено в версии PHP 8.1.0.
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` | Объявлена устаревшей с PHP 8.5.0
track_errors | "0" | `INI_ALL` | Объявлено устаревшим в PHP 7.2.0, удалено в PHP 8.0.0.
html_errors | "1" | `INI_ALL` |
xmlrpc_errors | "0" | `INI_SYSTEM` |
xmlrpc_error_number | "0" | `INI_ALL` |
docref_root | "" | `INI_ALL` |
docref_ext | "" | `INI_ALL` |
error_prepend_string | NULL | `INI_ALL` |
error_append_string | NULL | `INI_ALL` |
error_log | NULL | `INI_ALL` |
error_log_mode | 0o644 | `INI_ALL` | Доступно, начиная с PHP 8.2.0
syslog.facility | "LOG_USER" | `INI_SYSTEM` | Доступно, начиная с PHP 7.3.0.
syslog.filter | "no-ctrl" | `INI_ALL` | Доступно, начиная с PHP 7.3.0.
syslog.ident | "php" | `INI_SYSTEM` | Доступно, начиная с PHP 7.3.0.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`error_reporting` int

  Задаёт уровень протоколирования ошибки. Параметр может быть либо числом, представляющим битовое поле, либо именованной константой. Соответствующие уровни и константы приведены в разделе Предопределённые константы, а также в php.ini. Для установки настройки во время выполнения используйте функцию error_reporting(). Смотрите также описание директивы display_errors.

  Значение по умолчанию равно `E_ALL`.

  До PHP 8.0.0 значение по умолчанию было: ``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``. При этой настройке не отображаются уровни ошибок `E_NOTICE`, `E_STRICT` и `E_DEPRECATED`.

  > Замечание: PHP-константы за пределами PHP

  > PHP-константы не работают за пределами PHP, поэтому в файлах наподобие httpd.conf указывают не названия, а целочисленные (int) значения констант. По мере добавления новых уровней ошибок значение константы `E_ALL` возрастает, поэтому вместо текущего значения константы `E_ALL` лучше сразу указать число `2147483647`, которое установит тридцать одно битовое поле вместо текущих пятнадцати и включит вывод всех текущих и будущих ошибок.

`fatal_error_backtraces` bool
  Определяет, должны ли фатальные ошибки включать обратную трассировку. Фатальными ошибками являются `E_ERROR`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`, `E_RECOVERABLE_ERROR` и `E_PARSE`.
`display_errors` string

  Настройка определяет, требуется ли выводить ошибки на экран вместе с остальным выводом или скрывать ошибки от пользователя.

  - `Off` — скрывать ошибки.
  - `On` или `stdout` — выводить ошибки в поток `stdout`. Это значение по умолчанию.
  - `stderr` — выводить ошибки в поток `stderr`. Вывод ошибок в стандартный поток ошибок полезен только при работе с SAPI-интерфейсами `CLI`, `phpdbg` и `CGI`.
  В файлах конфигурации, которые входят в дистрибутив PHP, для директивы устанавливаются следующие значения: в `php.ini-development` — `On`; в `php.ini-production` — `Off`.

  > Замечание: Вывод ошибок включают только в целях разработки. В производственных системах с доступом к интернету вывод ошибок включать нельзя.

  > Замечание:

  > Включение директивы display_errors функцией ini_set() не сработает и сообщение об ошибке не появится в выводе, если скрипт содержит синтаксическую ошибку или другую критическую ошибку, которая возникла до этапа выполнения.

`display_startup_errors` bool

  Настройка управляет выводом ошибок, которые возникают на этапе запуска PHP; директива display_errors не влияет на вывод ошибок инициализации. Директиву display_startup_errors включают только для отладки.

`log_errors` bool

  Указывает, записывать ли сообщения об ошибках скрипта в лог ошибок сервера или в место, которое определяет директива error_log. Место, в которое будут отправляться ошибки, зависит от сервера.

  > Замечание:

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

`log_errors_max_len` int

  Устанавливает максимальную длину сообщения об ошибке скрипта в байтах. Логирование ошибок включают директивой log_errors. В журнал ошибок, путь к которому определяет директива error_log, добавляется информация об источнике. Значение по умолчанию равно 1024 байтам, а значение 0 снимает ограничение на длину сообщения. Ограничение длины распространяется на ошибки, которые записываются в журнал ошибок или выводятся на экран, и последнюю ошибку, которую PHP генерирует и записывает в переменную $php_errormsg, но не на явный вызов функций наподобие error_log().

  Объём измеряется в байтах, если значение параметра указали как целое число (int). Параметр также принимает значения в сокращённой нотации, которую описывает раздел FAQ.
`ignore_repeated_errors` bool

  Отключает запись в журнал ошибок, которые повторяются. PHP считает ошибку повторной, если она возникает в том же файле и в той же строке, и если включили опцию ignore_repeated_source.

`ignore_repeated_source` bool

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

`report_memleaks` bool
  Если настройка включена (по умолчанию), будет формироваться отчёт об утечках памяти, зафиксированных менеджером памяти Zend. На POSIX платформах этот отчёт будет направляться в поток stderr. На Windows платформах он будет посылаться в отладчик функцией OutputDebugString(), просмотреть отчёт в этом случае можно с помощью утилит, вроде » DbgView. Эта настройка имеет смысл в сборках, предназначенных для отладки. При этом `E_WARNING` должна быть включена в список error_reporting.
  Внимание

  Начиная с PHP 8.5.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

`track_errors` bool

  Если включена, последняя произошедшая ошибка будет первой в переменной $php_errormsg.

`html_errors` bool

  Если директиву включили, сообщения об ошибках будут включать HTML-теги. Формат для HTML-ошибок создаёт интерактивные сообщения, которые направляют пользователя на страницу, которая описывает ошибку или функцию, которая вызвала ошибку. На такие ссылки влияют директивы docref_root и docref_ext.

  Если директиву выключили, ошибки будут выдаваться простым текстом, без форматирования.

`xmlrpc_errors` bool

  Если включена, то нормальное оповещение об ошибках отключается и, вместо него, ошибки выводятся в формате XML-RPC.

`xmlrpc_error_number` int

  Используется в качестве значения XML-RPC элемента faultCode.

`docref_root` string

  Новый формат ошибок содержит ссылку на страницу с описанием ошибки или функции, вызвавшей эту ошибку. Можно разместить копию описаний ошибок и функций локально и задать ini директиве значение URL этой копии. Если, например, локальная копия описаний доступна по адресу `"/manual/"`, достаточно прописать `docref_root=/manual/`. Дополнительно, необходимо задать значение директиве docref_ext, отвечающей за соответствие расширений файлов файлам описаний вашей локальной копии, `docref_ext=.html`. Также возможно использование внешних ссылок. Например, `docref_root=http://manual/en/` или `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"`

  В большинстве случаев вам потребуется, чтобы значение docref_root оканчивалось слешем `"/"`. Тем не менее, бывают случаи, когда это не требуется (смотрите выше, второй пример).

  > Замечание:

  > Эта функциональность предназначена только для разработки, так как он облегчает поиск описаний функций и ошибок. Не используйте его в готовых производственных системах (например, имеющих доступ в интернет).

`docref_ext` string

  Смотрите docref_root.

  > Замечание:

  > Значение docref_ext должно начинаться с точки `"."`.

`error_prepend_string` string

  Строка, которая будет выводиться непосредственно перед сообщением об ошибке. Используется только тогда, когда на экране отображается сообщение об ошибке. Основная цель - добавить дополнительную HTML-разметку к сообщению об ошибке.

`error_append_string` string

  Строка, которая будет выводиться после сообщения об ошибке. Используется только тогда, когда на экране отображается сообщение об ошибке. Основная цель - добавить дополнительную HTML-разметку к сообщению об ошибке.

`error_log` string

  Имя файла, в который будут добавляться сообщения об ошибках. Файл должен быть открыт для записи пользователем веб-сервера. Если используется специальное значение `syslog`, то сообщения будут посылаться в системный журнал. На Unix-системах это syslog(3), на Windows NT - журнал событий. Смотрите также: syslog(). Если директива не задана, ошибки будут направляться в SAPI журналы. Например, это могут быть журналы ошибок Apache или поток `stderr` командной строки CLI. Смотрите также функцию error_log().

`error_log_mode` int

  Режим файла, описанного в error_log.

`syslog.facility` string

  Указывает, какой тип программы регистрирует сообщение. Действует только в том случае, если опция error_log установлена в "syslog".

`syslog.filter` string

  Указывает тип фильтра для фильтрации регистрируемых сообщений. Разрешённые символы передаются без изменений; все остальные записываются в шестнадцатеричном представлении с префиксом `\x`.

  - `all` – строка будет разделена на символы новой строки и все символы будут переданы без изменений
  - `ascii` – строка будет разделена на символы новой строки, а любые непечатаемые 7-битные символы ASCII будут экранированы
  - `no-ctrl` – строка будет разделена на символы новой строки, а любые непечатаемые символы будут экранированы
  - `raw` – все символы передаются в системный журнал без изменений, без разделения на новые строки (идентично PHP до 7.3)
  Параметр влияет на ведение журнала через error_log установленного в "syslog" и вызовы syslog().

  > Замечание:

  > Тип фильтра `raw` доступен начиная с PHP 7.3.8 и PHP 7.4.0.

  Директива не поддерживается в Windows.
`syslog.ident` string

  Определяет строку идентификатора, которая добавляется к каждому сообщению. Действует только в том случае, если опция error_log установлена в "syslog".

# Предопределённые константы

Следующие константы доступны как часть ядра PHP.

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

Подсказка

В файле php.ini вместо буквальных числовых значений разрешается указывать названия констант с эквивалентными значениями. В файле php.ini распознаются только побитовые операторы `|`, `~`, `^`, `&` и оператор отрицания `!`.

Внимание

Символические имена констант не поддерживаются вне PHP-среды, например, в файле httpd.conf вместо констант потребуется указать вычисленное значение битовой маски.

`E_ERROR` (int)
  Фатальные ошибки времени выполнения. Значение указывает на неустранимые ошибки наподобие проблемы выделения памяти. При критической ошибке выполнение скрипта прерывается. Значение константы: `1`
`E_WARNING` (int)
  Предупреждения времени выполнения, некритические ошибки. Выполнение скрипта не прерывается. Значение константы: `2`
`E_PARSE` (int)
  Синтаксические ошибки на этапе компиляции. Ошибки разбора генерирует только синтаксический анализатор. Значение константы: `4`
`E_NOTICE` (int)
  Уведомления времени выполнения. Значение указывает, что скрипт не нарушает формальные правила синтаксиса и не ломает выполнение программы, но содержит возможную ошибку, которая делает результат работы программы непредсказуемым. Значение константы: `8`
`E_CORE_ERROR` (int)
  Фатальные ошибки при запуске и инициализации PHP. Ошибки этого уровня аналогичны ошибкам уровня `E_ERROR`, но генерируются ядром PHP. Значение константы: `16`
`E_CORE_WARNING` (int)
  Предупреждения при запуске и инициализации PHP, некритические ошибки. Ошибки этого уровня аналогичны ошибкам уровня `E_WARNING`, но генерируются ядром PHP. Значение константы: `32`
`E_COMPILE_ERROR` (int)
  Фатальные ошибки на этапе компиляции. Ошибки этого уровня аналогичны ошибкам уровня `E_ERROR`, но генерируются движком Zend. Значение константы: `64`
`E_COMPILE_WARNING` (int)
  Предупреждения на этапе компиляции, некритические ошибки. Ошибки этого уровня аналогичны ошибкам уровня `E_WARNING`, но генерируются движком Zend. Значение константы: `128`
`E_DEPRECATED` (int)
  Уведомления времени выполнения об устаревании. Ошибки этого уровня предупреждают о коде, который перестанет работать в следующих версиях PHP. Значение константы: `8192`
`E_USER_ERROR` (int)
  Пользовательские сообщения об ошибках. Ошибки этого уровня аналогичны ошибкам уровня `E_ERROR`, но генерируются в PHP-коде вызовом функции trigger_error(). Значение константы: `256`
  Внимание

  С PHP 8.4.0 передача константы в функцию trigger_error() устарела. Альтернатива — ключевое слово `throw` и исключения Exception или вызов функции exit().

`E_USER_WARNING` (int)
  Пользовательские предупреждения. Ошибки этого уровня аналогичны ошибкам уровня `E_WARNING`, но генерируются в PHP-коде вызовом функции trigger_error(). Значение константы: `512`
`E_USER_NOTICE` (int)
  Пользовательские уведомления. Ошибки этого уровня аналогичны ошибкам уровня `E_NOTICE`, но генерируются в PHP-коде вызовом функции trigger_error(). Значение константы: `1024`
`E_USER_DEPRECATED` (int)
  Пользовательские сообщения об устаревании. Ошибки этого уровня аналогичны ошибкам уровня `E_DEPRECATED`, но генерируются в PHP-коде вызовом функции trigger_error(). Значение константы: `16384`
`E_STRICT` (int)
  Ошибки времени выполнения. На этом уровне PHP выдаёт предложения об изменениях кода, которые повысят совместимость кода с новыми версиями PHP. Значение константы: `2048`
  Внимание

  С PHP 8.4.0 ошибки этого уровня устарели, PHP перестал выдавать рекомендации.

`E_RECOVERABLE_ERROR` (int)
  Устаревшие «исключения» движка, которые соответствуют перехватываемым фатальным ошибкам. Ошибки этого уровня похожи на ошибки Error, но отлавливаются пользовательским обработчиком ошибок: set_error_handler(). Поведение необработанной ошибки этого уровня аналогично поведению ошибок уровня `E_ERROR`. Значение константы: `4096`

  > Замечание: PHP фактически не выдаёт ошибки этого уровня, единственный пример — ошибка при интерпретации внутреннего объекта (object) как значения с типом bool. До PHP 8.4.0 такую ошибку, например, генерировало включение объекта GMP в условное выражение.

`E_ALL` (int)
  Битовая маска, которая включает отчёт обо всех ошибках, предупреждениях и уведомлениях. Значение константы: `30719`
  Внимание

  Значение константы до PHP 8.4: `32767`

# Примеры

Ниже представлен пример использования возможностей обработки ошибок в PHP. Мы определим функцию для обработки ошибок, которая будет записывать информацию об ошибках в файл (используя формат XML), а в случае возникновения критических ошибок, будем дополнительно отправлять разработчикам письмо с уведомлением.

Пример #1 Обработка ошибок в скрипте

    <?php
    // мы будем делать нашу собственную обработку ошибок
    error_reporting(0);

    // пользовательская функция для обработки ошибок
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // временная метка возникновения ошибки
        $dt = date("Y-m-d H:i:s (T)");

        // определим ассоциативный массив соответствия всех
        // констант уровней ошибок с их названиями, хотя
        // в действительности мы будем рассматривать только
        // следующие типы: E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING и E_USER_NOTICE
        $errortype = array (
                    E_ERROR              => 'Ошибка',
                    E_WARNING            => 'Предупреждение',
                    E_PARSE              => 'Ошибка разбора исходного кода',
                    E_NOTICE             => 'Уведомление',
                    E_CORE_ERROR         => 'Ошибка ядра',
                    E_CORE_WARNING       => 'Предупреждение ядра',
                    E_COMPILE_ERROR      => 'Ошибка на этапе компиляции',
                    E_COMPILE_WARNING    => 'Предупреждение на этапе компиляции',
                    E_USER_ERROR         => 'Пользовательская ошибка',
                    E_USER_WARNING       => 'Пользовательское предупреждение',
                    E_USER_NOTICE        => 'Пользовательское уведомление',
                    E_STRICT             => 'Уведомление времени выполнения',
                    E_RECOVERABLE_ERROR  => 'Отлавливаемая фатальная ошибка'
                    );
        // определим набор типов ошибок, для которых будет сохранён стек переменных
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $dt . "</datetime>\n";
        $err .= "\t<errornum>" . $errno . "</errornum>\n";
        $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
        $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
        $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

        if (in_array($errno, $user_errors)) {
            $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Переменные") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // для тестирования
        // echo $err;

        // сохраняем в журнал ошибок, а если произошла пользовательская критическая ошибка, то отправляем письмо
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($errno == E_USER_ERROR) {
            mail("phpdev@example.com", "Пользовательская критическая ошибка", $err);
        }
    }

    function distance($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Некорректные параметры функции, ожидаются массивы в качестве параметров", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Векторы должны быть одинаковой размерности", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Координата $i в векторе 1 не является числом, будет использовать ноль",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Координата $i в векторе 2 не является числом, будет использовать ноль",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // использование неопределённой константы, будет генерироваться предупреждение
    $t = I_AM_NOT_DEFINED;

    // определим несколько "векторов"
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // генерируем пользовательскую ошибку
    $t1 = distance($c, $b) . "\n";

    // генерируем ещё одну пользовательскую ошибку
    $t2 = distance($b, "я не массив") . "\n";

    // генерируем пользовательское предупреждение
    $t3 = distance($a, $b) . "\n";

    ?>

# Функции обработки ошибок

# Смотрите также

Смотрите также функцию syslog().

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — Генерирует обратную трассировку вызовов функций

### Описание

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

Функция debug_backtrace() генерирует обратный стек вызовов PHP-функций.

### Список параметров

`options`

  Параметр принимает битовую маску из следующих опций:

  Опции функции debug_backtrace()
  DEBUG_BACKTRACE_PROVIDE_OBJECT | Опция устанавливает бит, который определяет, заполнять ли ключ "object" в выходном массиве.
  DEBUG_BACKTRACE_IGNORE_ARGS | Опция устанавливает бит, который определяет, исключать ли ключ "args" из выходного массива и вместе с ним аргументы функций и методов, чтобы уменьшить расход памяти.

  > Замечание:

  > Объединение опций даёт четыре возможные комбинации:

  > Комбинации опций функции debug_backtrace()
  > `debug_backtrace()` | Заполняются оба ключа.
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT)` | Не включается ключ `"object"` и заполняется ключ `"args"`.
  > `debug_backtrace(0)`
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | Опускаются оба ключа `"object"` и `"args"`.
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT | DEBUG_BACKTRACE_IGNORE_ARGS)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | Заполняется ключ `"object"` и опускается ключ `"args"`.

`limit`

  Параметр ограничивает количество кадров стека в выходном массиве. Со значением по умолчанию — `limit`=`0` — возвращается весь стек вызовов функций.

### Возвращаемые значения

Функция возвращает массив вложенных ассоциативных массивов (array). Следующая таблица приводит список возможных элементов выходного массива:

Возможные элементы массивов в результатах функции debug_backtrace()
Имя | Тип | Описание
--- | --- | ---
function | string | Название текущей функции. Смотрите также описание константы __FUNCTION__.
line | int | Текущий номер строки. Смотрите также описание константы __LINE__.
file | string | Название текущего файла. Смотрите также описание константы __FILE__.
class | string | Название текущего класса. Смотрите также описание константы __CLASS__.
object | object | Текущий объект, если задан флаг `DEBUG_BACKTRACE_PROVIDE_OBJECT`.
type | string | Текущий тип вызова функции. При вызове метода объекта функция возвращает значение "->". При вызове статического метода класса возвращается "::". При вызове функции ничего не возвращается.
args | array | При вызове этой функции внутри другой функции элементы с этим ключом содержат списки аргументов функций. При вызове внутри включаемого файла элемент содержит названия включённых файлов. За исключением случая, когда задан флаг `DEBUG_BACKTRACE_IGNORE_ARGS`.

### Примеры

Пример #1 Пример генерации обратной трассировки вызовов функцией debug_backtrace()

    <?php

    // Файл: /tmp/a.php
    function a_test($str)
    {
        echo "\nПривет, $str";
        var_dump(debug_backtrace());
    }

    a_test('друг');

    ?>

    <?php

    // Файл: /tmp/b.php
    include_once '/tmp/a.php';

    ?>

При выполнении файла /tmp/b.php PHP выведет результат наподобие такого:

    Привет, друг
    array(2) {
    [0]=>
    array(4) {
        ["file"] => string(10) "/tmp/a.php"
        ["line"] => int(10)
        ["function"] => string(6) "a_test"
        ["args"]=>
        array(1) {
          [0] => &string(8) "друг"
        }
    }
    [1]=>
    array(4) {
        ["file"] => string(10) "/tmp/b.php"
        ["line"] => int(2)
        ["args"] =>
        array(1) {
          [0] => string(10) "/tmp/a.php"
        }
        ["function"] => string(12) "include_once"
      }
    }

### Смотрите также

- trigger_error() - Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
- debug_print_backtrace() - Выводит обратную трассировку вызовов функций

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — Выводит обратную трассировку вызовов функций

### Описание

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

Функция debug_print_backtrace() выводит обратный стек вызовов PHP-функций. Функция выводит вызовы функций, названия файлов, которые подключили выражениями include или require, и другую информацию, которую вычислили функции, например eval().

### Список параметров

`options`

  Параметр принимает битовую маску из следующих опций:

  Опции функции debug_print_backtrace()
  DEBUG_BACKTRACE_IGNORE_ARGS | Опция устанавливает бит, который определяет, исключать ли ключ "args" из выходного массива и вместе с ним аргументы функций и методов, чтобы уменьшить расход памяти.

`limit`

  Параметр ограничивает количество кадров стека в выходном массиве. Со значением по умолчанию — `limit`=`0` — возвращается весь стек вызовов функций.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример вывода обратной трассировки вызовов функцией debug_print_backtrace()

    <?php

    // Файл: include.php
    function a()
    {
        b();
    }

    function b()
    {
        c();
    }

    function c()
    {
        debug_print_backtrace();
    }

    a();

    ?>

    <?php

    // Файл test.php
    // Это файл, который потребуется запустить
    include 'include.php';

    ?>

Вывод приведённого примера будет похож на:

    #0  c() called at [/tmp/include.php:10]
    #1  b() called at [/tmp/include.php:6]
    #2  a() called at [/tmp/include.php:17]
    #3  include(/tmp/include.php) called at [/tmp/test.php:3]

### Смотрите также

- debug_backtrace() - Генерирует обратную трассировку вызовов функций

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — Очищает последнюю ошибку

### Описание

function error_clear_last(): void

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция очищает последнюю ошибку, что делает невозможным получение ошибки функцией error_get_last().

### Примеры

Пример #1 Пример использования функции error_clear_last()

    <?php

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    @$a = $b;

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    ?>

Вывод приведённого примера будет похож на:

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### Смотрите также

- Константы ошибок

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — Получает последнюю ошибку

### Описание

function error_get_last(): ?array

Функция получает информацию о последней ошибке.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает ассоциативный массив, который описывает последнюю ошибку и содержит ключи: type, message, file и line. Элемент с ключом message будет начинаться с имени функции, если ошибку вызвала внутренняя функция PHP. Функция возвращает `null`, если ошибка ещё не возникала.

### Примеры

Пример #1 Пример использования функции error_get_last()

    <?php

    echo $a;
    print_r(error_get_last());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### Смотрите также

- Константы ошибок
- Переменная $php_errormsg
- error_clear_last() - Очищает последнюю ошибку
- Директива `display_errors`
- Директива `html_errors`
- Директива `xmlrpc_errors`

# error_log

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

error_log — Отправляет сообщение об ошибке заданному обработчику ошибок

### Описание

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

Функция отправляет сообщение об ошибке в журнал ошибок веб-сервера или в файл.

### Список параметров

`message`

  Сообщение об ошибке, которое требуется записать.

`message_type`

  Определяет, куда отправлять ошибку. Параметр принимает следующие типы сообщений об ошибках:

  Типы журналов функции error_log()
  0 | Сообщение `message` отправляется в системный регистратор PHP, который перенаправляет ошибку в механизм системного логирования операционной системы или записывает в файл, в зависимости от значения директивы error_log в конфигурационном файле. Параметр принимает это значение по умолчанию.
  1 | Сообщение `message` отправляется по электронной почте на адрес, который установили в параметре `destination`. Это единственный тип сообщения, который использует четвёртый параметр — `additional_headers`.
  2 | Параметр больше не принимает это значение.
  3 | Сообщение `message` добавляется в файл, путь к которому указали в параметре `destination`. Символ новой строки не добавляется автоматически в конец строки сообщения `message`.
  4 | Сообщение `message` отправляется непосредственно в SAPI-обработчик сообщений, которые требуется записать в журнал.

`destination`

  Назначение. Значение зависит от параметра `message_type`.

`additional_headers`

  Дополнительные заголовки. Функция использует параметр, когда значение параметра `message_type` устанавливают равным `1`. Тип сообщения использует ту же внутреннюю функцию, что и функция mail().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Функция возвращает логическое значение `true` независимо от результата логирования ошибки, если тип сообщения `message_type` равен 0.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `destination` и `additional_headers` теперь принимают значение null.

### Примеры

Пример #1 Примеры использования функции error_log()

    <?php

    // Отправляет уведомление через лог сервера, если не получается
    // подключиться к базе данных
    if (!Ora_Logon($username, $password)) {
        error_log("База данных Oracle недоступна!", 0);
    }

    // Уведомляет администратора по электронной почте, если закончились FOO
    if (!($foo = allocate_new_foo())) {
        error_log("Большая беда, у нас закончились FOO!", 1,
                   "operator@example.com");
    }

    // Другой способ вызвать функцию error_log():
    error_log("Вы ошиблись!", 3, "/var/tmp/my-errors.log");

    ?>

### Примечания

Внимание

Функция error_log() не бинарно-безопасна. Сообщение `message` обрезается по null-символу.

Подсказка

Параметру `message` нельзя содержать null-символ. Обратите внимание, сообщение `message` разрешается отправлять в файл, по почте, в syslog и т. д. Перед вызовом функции error_log() сообщение преобразовывают или экранируют функциями, которые соответствуют типу сообщения: base64_encode(), rawurlencode() или addslashes().

# error_reporting

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

error_reporting — Определяет, о каких PHP-ошибках сообщать

### Описание

function error_reporting(?int `$error_level` = `null`): int

Функция error_reporting() устанавливает значение директивы error_reporting во время выполнении PHP-кода. В PHP предусмотрели много уровней ошибок и функция устанавливает этот уровень на время, пока выполняется скрипт. Функция error_reporting() просто вернёт текущий уровень сообщений об ошибках, если необязательный параметр `error_level` не установили.

### Список параметров

`error_level`

  Новый уровень сообщений об ошибках, который функция установит для директивы error_reporting. Параметр принимает либо битовую маску, либо именованные константы. Лучше предпочесть именованные константы, чтобы поддерживать совместимость кода с будущими версиями языка. Диапазон целых чисел — значений констант — увеличивается, когда разработчики языка добавляют новые уровни ошибок, поэтому старые уровни ошибок на основе целых чисел будут вести себя непредсказуемо.

  Доступные константы уровней ошибок и значения уровней описывает раздел «Предопределённые константы».

### Возвращаемые значения

Функция возвращает уровень сообщений об ошибках на основе значения директивы error_reporting, которое директива хранила до изменения на уровень `error_level`.

> Замечание: Оператор управления ошибками `@` изменяет уровень `error_level` во время обработки ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `error_level` теперь принимает значение null.

### Примеры

Пример #1 Примеры использования функции error_reporting()

    <?php

    // Отключить сообщения об ошибках
    error_reporting(0);

    // Сообщать о простых ошибках при запуске
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // Сообщения об ошибках уровня E_NOTICE тоже бывают полезны: сообщают о неинициализированных
    // переменных или отлавливают ошибки в именах переменных
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // Сообщать о каждой ошибке, кроме ошибок уровня E_NOTICE
    error_reporting(E_ALL & ~E_NOTICE);

    // Сообщать о каждой PHP-ошибке
    error_reporting(E_ALL);

    // Сообщать о каждой PHP-ошибке
    error_reporting(-1);

    // То же, что и error_reporting(E_ALL);
    ini_set('error_reporting', E_ALL);

    ?>

### Примечания

Подсказка

Передача значения `-1` покажет каждую возможную ошибку, даже если в будущих версиях языка PHP добавятся новые уровни или константы; поведение эквивалентно передаче константы `E_ALL`.

### Смотрите также

- Директива display_errors
- Директива html_errors
- Директива xmlrpc_errors
- Оператор управления ошибками
- Функция ini_set() - Устанавливает значение параметра конфигурации — Устанавливает значение параметра конфигурации

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — Получает пользовательскую функцию обработчика ошибок

### Описание

function get_error_handler(): ?callable

Функция возвращает текущую функцию обработчика ошибок, если такую функцию определили.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает текущий обработчик ошибок, если такой определили в коде, или значение `null`, если за текущую обработку ошибок отвечает встроенная функция.

Функция возвращает непосредственно ту callback-функцию, которую передали в функцию set_error_handler(), когда устанавливали пользовательский обработчик.

### Примеры

Пример #1 Пример получения пользовательского обработчика ошибок функцией get_error_handler()

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Ошибка: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### Примечания

Подсказка

До PHP 8.5.0 действие функции заменяет следующий полифил:

    <?php

    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {}

        function get_error_handler(): ?callable
        {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }

    ?>

### Смотрите также

- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- set_error_handler() - Устанавливает пользовательский обработчик ошибок
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- trigger_error() - Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
- Константы уровней ошибок

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — Получает пользовательскую функцию обработчика исключений

### Описание

function get_exception_handler(): ?callable

Функция возвращает текущую функцию обработчика исключений, если такую функцию определили.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает текущий обработчик исключений, если такой определили в коде, или значение `null`, если за текущую обработку исключений отвечает встроенная функция.

Функция возвращает непосредственно ту callback-функцию, которую передали в функцию set_exception_handler(), когда устанавливали пользовательский обработчик.

### Примеры

Пример #1 Пример получения пользовательского обработчика исключений функцией get_exception_handler()

    <?php

    $handler = function (Throwable $ex) {
         echo "Исключение: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### Примечания

Подсказка

До PHP 8.5.0 действие функции заменяет следующий полифил:

    <?php

    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {}

        function get_exception_handler(): ?callable
        {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }

    ?>

### Смотрите также

- set_exception_handler() - Устанавливает пользовательскую функцию обработчика исключений
- restore_exception_handler() - Восстанавливает предыдущую функцию обработчика исключений
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- Исключения

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — Восстанавливает предыдущую функцию обработчика ошибок

### Описание

function restore_error_handler(): true

Функцию вызывают после изменения обработчика ошибок функцией set_error_handler(), чтобы вернуться к предыдущему обработчику, которым станет или пользовательская функция обработки ошибок, если такую определили, или встроенный обработчик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Пример восстановления предыдущего обработчика ошибок функцией restore_error_handler()

Пример определяет, вызвала ли ошибку функция unserialize(), а затем восстанавливает исходный обработчик ошибок.

    <?php

    function unserialize_handler($errno, $errstr)
    {
        echo "Недопустимое сериализованное значение.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();

    ?>

Результат выполнения приведённого примера:

    Недопустимое сериализованное значение.

### Смотрите также

- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- set_error_handler() - Устанавливает пользовательский обработчик ошибок
- get_error_handler() - Получает пользовательскую функцию обработчика ошибок
- restore_exception_handler() - Восстанавливает предыдущую функцию обработчика исключений
- trigger_error() - Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — Восстанавливает предыдущую функцию обработчика исключений

### Описание

function restore_exception_handler(): true

Функцию вызывают после изменения обработчика исключений функцией set_exception_handler(), чтобы вернуться к предыдущему обработчику, которым станет или пользовательская функция обработки исключений, если такую определили, или встроенный обработчик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Пример восстановления предыдущего обработчика исключений функцией restore_exception_handler()

    <?php

    function exception_handler_1(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    function exception_handler_2(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    set_exception_handler('exception_handler_1');
    set_exception_handler('exception_handler_2');

    restore_exception_handler();

    throw new Exception('Эта инструкция запустит первый обработчик исключений...');

    ?>

Результат выполнения приведённого примера:

    [exception_handler_1] Эта инструкция запустит первый обработчик исключений...

### Смотрите также

- set_exception_handler() - Устанавливает пользовательскую функцию обработчика исключений
- get_exception_handler() - Получает пользовательскую функцию обработчика исключений
- set_error_handler() - Устанавливает пользовательский обработчик ошибок
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- error_reporting() - Определяет, о каких PHP-ошибках сообщать

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Устанавливает пользовательский обработчик ошибок

### Описание

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

Функция устанавливает пользовательскую `callback`-функцию обработки ошибок, которые возникают в скрипте.

Функция определяет пользовательские обработчики ошибок, которые возникают во время выполнения кода. Обработчики устанавливают в приложениях, которым требуется очистить файлы или данные при критичной для приложения ошибке или при ошибке, которую сгенерировали функцией trigger_error() в ответ на конкретные условия.

Важно помнить: PHP-движок передаст ошибки, типы которых указали в параметре `error_levels`, в стандартный обработчик ошибок, только если callback-функция вернёт значение `false`. Движок вызовет пользовательский обработчик ошибок, даже если уровень ошибки не соответствует настройкам, которые установили функцией error_reporting(). При этом текущее значение директивы error_reporting остаётся доступным для чтения, чтобы выполнить операции, которые соответствуют ситуации.

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

Пользовательской функцией невозможно обработать ошибки следующих типов: `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR`, `E_COMPILE_WARNING` независимо от места, в котором возникла ошибка, и бо́льшую часть ошибок уровня `E_STRICT`, которые возникли в файле вызова функции set_error_handler().

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

### Список параметров

`callback`

  При передаче значения `null` обработчик сбрасывается в состояние по умолчанию, иначе обработчиком становится callback-функция со следующей сигнатурой:

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    В первый параметр — `errno` передаётся целое число, которое указывает на уровень ошибки.
  `errstr`
    Во второй параметр — `errstr` передаётся строка с сообщением об ошибке.
  `errfile`
    В третий параметр — `errfile` передаётся строка с названием файла, в котором возникла ошибка, если параметр определили в функции обратного вызова.
  `errline`
    В четвёртный параметр — `errline` передаётся целочисленный номер строки, в которой возникла ошибка, если параметр определили в функции обратного вызова.
  `errcontext`
    В пятый параметр — `errcontext` передаётся массив, который указывает на активную таблицу символов в точке, в которой возникла ошибка, если параметр определили в функции обратного вызова. Другими словами, параметр `errcontext` будет содержать массив переменных той области действия, в которой возникла ошибка. Контекст ошибки не модифицируют в пользовательском обработчике ошибок, чтобы при возврате управления сохранить согласованность данных.
    Внимание

    С PHP 7.2.0 параметр УСТАРЕЛ, а в PHP 8.0.0 параметр УДАЛИЛИ. Обработчик выдаст ошибку "too few arguments", если в callback-функции параметр определили, но не установили значение по умолчанию.

  При возврате из функции значения `false` управление передаётся стандартному обработчику ошибок.

`error_levels`

  Параметр устанавливает маску уровней ошибок, при которых сработает `callback`-функция. Параметр управляет срабатыванием пользовательского обработчика ошибок так же, как ini-настройка error_reporting управляет отображением ошибок. Без установки маски движок вызывает `callback`-функцию для каждой ошибки и игнорирует настройку директивы error_reporting.

### Возвращаемые значения

Функция возвращает предыдущий обработчик ошибок как значение с типом callable, если такой обработчик определили, или значение `null`, если за текущую обработку ошибок отвечает встроенный обработчик.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `errcontext` удалили. Контекст ошибки больше не передаётся в пользовательскую callback-функцию.
7.2.0 | Параметр `errcontext` устарел. При определении параметра в пользовательском обработчике функция выдаст ошибку уровня `E_DEPRECATED`.

### Примеры

Пример #1 Обработка ошибок функциями set_error_handler() и trigger_error()

Пример ниже демонстрирует обработку внутренних исключений путём вызова ошибок разных типов и их обработки пользовательской функцией:

    <?php

    // Функция обработки ошибок
    function myErrorHandler($errno, $errstr, $errfile, $errline)
    {
        if (!(error_reporting() & $errno)) {
            // Директива error_reporting не включает этот код ошибки,
            // поэтому пусть ошибку обрабатывает стандартный обработчик ошибок PHP
            return false;
        }

        // Переменной $errstr требуется экранирование:
        $errstr = htmlspecialchars($errstr);

        switch ($errno) {
            case E_USER_ERROR:
                echo "<b>Пользовательская ОШИБКА</b> [$errno] $errstr<br />\n";
                echo "  Фатальная ошибка в строке $errline файла $errfile";
                echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
                echo "Завершение работы...<br />\n";
                exit(1);

            case E_USER_WARNING:
                echo "<b>Пользовательское ПРЕДУПРЕЖДЕНИЕ</b> [$errno] $errstr<br />\n";
                break;

            case E_USER_NOTICE:
                echo "<b>Пользовательское УВЕДОМЛЕНИЕ</b> [$errno] $errstr<br />\n";
                break;

            default:
                echo "Неизвестная ошибка: [$errno] $errstr<br />\n";
                break;
        }

        /* Не запускаем внутренний обработчик ошибок PHP */
        return true;
    }

    // Функция тестирования обработчика ошибок
    function scale_by_log($vect, $scale)
    {
        if (!is_numeric($scale) || $scale <= 0) {
            trigger_error("log(x) для x <= 0 не определён, вы используете: scale = $scale", E_USER_ERROR);
        }

        if (!is_array($vect)) {
            trigger_error("Некорректный входной вектор, пропущен массив значений", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach ($vect as $pos => $value) {
            if (!is_numeric($value)) {
                trigger_error("Значение на позиции $pos не относится к числу, присваиваем значение 0 (ноль)", E_USER_NOTICE);
                $value = 0;
            }
            $temp[$pos] = log($scale) * $value;
        }

        return $temp;
    }

    // Переключаемся на пользовательский обработчик
    $old_error_handler = set_error_handler("myErrorHandler");

    // Вызовем ряд ошибок, и вначале определим смешанный массив с нечисловым элементом
    echo "vector a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // Теперь создадим ещё один массив
    echo "----\nvector b - a notice (b = log(PI) * a)\n";
    /* Значение на позиции $pos не относится к числу, присваиваем 0 (ноль)*/
    $b = scale_by_log($a, M_PI);
    print_r($b);

    // Проблема, вместо массива передали строку
    echo "----\nvector c - a warning\n";
    /* Некорректный входной вектор, ожидается массив значений */
    $c = scale_by_log("not array", 2.3);
    var_dump($c); // NULL

    // Критическая ошибка, логарифм нуля или отрицательного числа не определён
    echo "----\nvector d - fatal error\n";
    /* log(x) для x <= 0 не определён, передали: scale = $scale */
    $d = scale_by_log($a, -2.5);

    var_dump($d); // До этого места никогда не дойдём

    ?>

Вывод приведённого примера будет похож на:

    vector a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vector b - a notice (b = log(PI) * a)
    <b>Пользовательское УВЕДОМЛЕНИЕ</b> [1024] Значение на позиции 2 не относится к числу, присваиваем значение 0 (ноль)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vector c - a warning
    <b>Пользовательское ПРЕДУПРЕЖДЕНИЕ</b> [512] Некорректный входной вектор, пропущен массив значений<br />
    NULL
    ----
    vector d - fatal error
    <b>Пользовательская ОШИБКА</b> [256] log(x) для x &lt;= 0 не определён, вы используете: scale = -2.5<br />
      Фатальная ошибка в строке 44 файла /in/IYIBO, PHP 7.4.33 (Linux)<br />
    Завершение работы...<br />

### Смотрите также

- ErrorException
- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- get_error_handler() - Получает пользовательскую функцию обработчика ошибок
- trigger_error() - Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
- Константы уровней ошибок

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — Устанавливает пользовательскую функцию обработчика исключений

### Описание

function set_exception_handler(?callable `$callback`): ?callable

Функция устанавливает пользовательскую функцию как обработчик исключений по умолчанию для перехвата исключений, которые не отловили в блоке try-catch. Выполнение скрипта остановится после вызова `callback`-функции.

### Список параметров

`callback`

  Функция, которую требуется вызвать, когда возникнет неперехваченное исключение. В функции-обработчике определяют один параметр с типом Throwable, в который придёт объект выброшенного исключения — Error или Exception, которые реализуют интерфейс Throwable. Сигнатура обработчика:

  function handler(Throwable `$ex`): void

  При передаче вместо callback-функции значения `null` пользовательский обработчик исключений сбрасывается на встроенный обработчик.

### Возвращаемые значения

Функция возвращает предыдущий обработчик исключений или `null`, если возникла ошибка. Функция также возвращает `null`, если предыдущий обработчик не определили.

### Примеры

Пример #1 Пример установки пользовательского обработчика исключений функцией set_exception_handler()

    <?php

    function exception_handler(Throwable $exception)
    {
      echo "Неперехваченное исключение: " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Неперехваченное исключение');
    echo "Не выполняется\n";

    ?>

### Смотрите также

- get_exception_handler() - Получает пользовательскую функцию обработчика исключений
- restore_exception_handler() - Восстанавливает предыдущую функцию обработчика исключений
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- Исключения

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя

### Описание

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

Функция инициирует состояние пользовательской ошибки. Функцию разрешается использовать в сочетании со встроенным обработчиком ошибок или функцией, которую разработчик определил и установил через функцию set_error_handler() как новый обработчик ошибок.

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

### Список параметров

`message`

  Сообщение, которое функция назначит ошибке. Длина сообщения ограничивается 1024 байтами. Функция обрежет символы, которые идут после 1024-го.

`error_level`

  Тип, который функция назначит ошибке. Параметр работает только с константами семейства `E_USER_*`, а значение по умолчанию равно `E_USER_NOTICE`.

  Внимание

  Передача константы `E_USER_ERROR` как значения уровня ошибки в параметр `error_level` устарела. Вместо этого рекомендуют выбрасывать исключение Exception или вызывать функцию exit().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Функция выбрасывает исключение ValueError, если значение параметра `error_level` не соответствует значениям `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE` или `E_USER_DEPRECATED`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Передача константы `E_USER_ERROR` как значения уровня ошибки в параметр `error_level` устарела. Вместо этого рекомендуют выбрасывать исключение Exception или вызывать функцию exit().
8.4.0 | Вместо типа bool функции теперь возвращает тип true.
8.0.0 | Функция выбрасывает ошибку ValueError, если в аргументе `error_level` передали недопустимое значение. Раньше функция возвращала значение `false`.

### Примеры

Пример #1 Пример запуска состояния пользовательской ошибки функцией trigger_error()

Развёрнутый пример приводит описание функции set_error_handler().

    <?php

    if ($divisor == 0) {
        trigger_error("Не могу поделить на ноль", E_USER_ERROR);
    }

    ?>

### Примечания

Внимание

HTML-сущности в параметре `message` не экранируются. Сообщение преобразовывают функцией htmlentities(), если ошибку требуется отобразить в браузере.

### Смотрите также

- error_reporting() - Определяет, о каких PHP-ошибках сообщать
- set_error_handler() - Устанавливает пользовательский обработчик ошибок
- restore_error_handler() - Восстанавливает предыдущую функцию обработчика ошибок
- Константы уровней ошибок

# user_error

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

user_error — Псевдоним trigger_error()

### Описание

Псевдоним функции trigger_error().

## Содержание

- debug_backtrace — Генерирует обратную трассировку вызовов функций
- debug_print_backtrace — Выводит обратную трассировку вызовов функций
- error_clear_last — Очищает последнюю ошибку
- error_get_last — Получает последнюю ошибку
- error_log — Отправляет сообщение об ошибке заданному обработчику ошибок
- error_reporting — Определяет, о каких PHP-ошибках сообщать
- get_error_handler — Получает пользовательскую функцию обработчика ошибок
- get_exception_handler — Получает пользовательскую функцию обработчика исключений
- restore_error_handler — Восстанавливает предыдущую функцию обработчика ошибок
- restore_exception_handler — Восстанавливает предыдущую функцию обработчика исключений
- set_error_handler — Устанавливает пользовательский обработчик ошибок
- set_exception_handler — Устанавливает пользовательскую функцию обработчика исключений
- trigger_error — Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
- user_error — Псевдоним trigger_error

- Установка и настройка
  - Настройка во время выполнения
- Предопределённые константы
- Примеры
- Функции обработки ошибок
  - debug_backtrace — Генерирует обратную трассировку вызовов функций
  - debug_print_backtrace — Выводит обратную трассировку вызовов функций
  - error_clear_last — Очищает последнюю ошибку
  - error_get_last — Получает последнюю ошибку
  - error_log — Отправляет сообщение об ошибке заданному обработчику ошибок
  - error_reporting — Определяет, о каких PHP-ошибках сообщать
  - get_error_handler — Получает пользовательскую функцию обработчика ошибок
  - get_exception_handler — Получает пользовательскую функцию обработчика исключений
  - restore_error_handler — Восстанавливает предыдущую функцию обработчика ошибок
  - restore_exception_handler — Восстанавливает предыдущую функцию обработчика исключений
  - set_error_handler — Устанавливает пользовательский обработчик ошибок
  - set_exception_handler — Устанавливает пользовательскую функцию обработчика исключений
  - trigger_error — Генерирует предупреждение, уведомление или сообщение об ошибке на уровне пользователя
  - user_error — Псевдоним trigger_error

# Интерфейс внешней функции (Foreign Function Interface)

# Введение

Модуль умеет загружать общие библиотеки (.DLL или .so), вызывать C-функции и получать доступ с структурам языка C из PHP без глубокого изучения API модулей Zend и стороннего «промежуточного» языка. Публичный API реализовали как единственный класс FFI с набором статических методов (часть методов вызывается динамически) и переопределёнными методами объекта, которые фактически взаимодействуют с данными языка C.

Предостережение

Модуль FFI довольно опасен, поскольку разрешает взаимодействовать с системой на низком уровне. С модулем FFI должны работать только те разработчики, которые знакомы с языком С и умеют работать с API языка. Чтобы уменьшить риски, модуль запрещают директивой ffi.enable в файле php.ini.

> Замечание: Модуль FFI не делает классический API модулей PHP устаревшим; модуль разработали для взаимодействия с функциями и структурами данных языка C.

Подсказка

Доступ к структурам данных модуля FFI примерно в 2 раза медленнее, чем доступ к объектам и массивам PHP. Поэтому нет повода использовать FFI для ускорения; однако с модулем работают, чтобы сократить потребление памяти.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Для работы модуля необходимо установить библиотеку » libffi.

## Установка

Для включения модуля FFI, PHP надо сконфигурировать с ключом --with-ffi.

Пользователям Windows будет необходимо добавить php_ffi.dll в php.ini.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки FFI
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`ffi.enable` string
  Позволяет разрешить (`"true"`) или запретить (`"false"`) использование FFI API, либо ограничить использование только для CLI SAPI и предзагруженных файлов (`"preload"`). Ограничения FFI API влияют только на класс FFI, но не на перезагруженные функции объекта FFI\CData. Это значит, что можно создать объекты FFI\CData в предзагружаемых файлах и использовать потом напрямую из скриптов PHP.
`ffi.preload` string
  Позволяет предзагружать привязки FFI во время старта, что невозможно с FFI::load(), если включено opcache.preload_user. Эта директива принимает список разделителей имён файлов `DIRECTORY_SEPARATOR`. Предзагруженные привязки доступны с помощью вызова FFI::scope().

# Примеры

## Содержание

- Базовая работа с модулем FFI
- Callback-функции PHP
- Комплексный пример PHP/FFI/preloading

## Базовая работа с модулем FFI

Перед погружением в детали API-интерфейса модуля FFI, давайте рассмотрим несколько примеров упрощённой работы API модуля FFI в стандартных задачах.

> Замечание: Для ряда этих примеров потребуется библиотека libc.so.6. Они не будут работать в системах, где библиотека недоступна.

Пример #1 Вызов функции из общей библиотеки

    <?php

    // Создаём объект FFI, загружаем библиотеку libc и экспортируем функцию printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // Это стандартная декларация в языке C
        "libc.so.6"
    );

    // Вызываем функцию printf()
    $ffi->printf("Привет, %s!\n", "мир");

    ?>

Результат выполнения приведённого примера:

    Привет, мир!

> Замечание: Обратите внимание, что для отдельных функций языка C требуются конкретные соглашения о вызовах, например: `__fastcall`, `__stdcall` или `,__vectorcall`.

Пример #2 Вызов функции и возврат структуры через аргумент

    <?php

    // Создаём привязку gettimeofday()
    $ffi = FFI::cdef(
        "typedef unsigned int time_t;
        typedef unsigned int suseconds_t;

        struct timeval {
            time_t      tv_sec;
            suseconds_t tv_usec;
        };

        struct timezone {
            int tz_minuteswest;
            int tz_dsttime;
        };

        int gettimeofday(struct timeval *tv, struct timezone *tz);",
        "libc.so.6"
    );

    // Создаём структуры данных языка C
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");

    // Вызываем функцию gettimeofday()
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));

    // Получаем доступ к полю структуры данных языка C
    var_dump($tv->tv_sec);

    // Выводим структуру данных
    var_dump($tz);

    ?>

Вывод приведённого примера будет похож на:

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

Пример #3 Доступ к существующим переменным C

    <?php

    // Создаём FFI-объект, загружаем библиотеку libc и экспортируем переменную errno
    $ffi = FFI::cdef(
        "int errno;", // Это стандартная декларация в языке C
        "libc.so.6"
    );

    // Выводим значение переменной errno
    var_dump($ffi->errno);

    ?>

Результат выполнения приведённого примера:

    int(0)

Пример #4 Создание и модификация C-переменной

    <?php

    // Создаём переменную языка C с типом int
    $x = FFI::new("int");
    var_dump($x->cdata);

    // Простое присваивание
    $x->cdata = 5;
    var_dump($x->cdata);

    // Непростое присваивание
    $x->cdata += 2;
    var_dump($x->cdata);

    ?>

Результат выполнения приведённого примера:

    int(0)
    int(5)
    int(7)

Пример #5 Работа с массивами языка C

    <?php

    // Создаём структуру данных
    $a = FFI::new("long[1024]");

    // Работаем с ней как с обычным PHP-массивом
    for ($i = 0; $i < count($a); $i++) {
        $a[$i] = $i;
    }

    var_dump($a[25]);

    $sum = 0;
    foreach ($a as $n) {
        $sum += $n;
    }

    var_dump($sum);
    var_dump(count($a));
    var_dump(FFI::sizeof($a));

    ?>

Результат выполнения приведённого примера:

    int(25)
    int(523776)
    int(1024)
    int(8192)

Пример #6 Работа с перечислениями языка C

    <?php

    $a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
        ZEND_FFI_SYM_TYPE,
        ZEND_FFI_SYM_CONST = 2,
        ZEND_FFI_SYM_VAR,
        ZEND_FFI_SYM_FUNC
    } zend_ffi_symbol_kind;
    ');

    var_dump($a->ZEND_FFI_SYM_TYPE);
    var_dump($a->ZEND_FFI_SYM_CONST);
    var_dump($a->ZEND_FFI_SYM_VAR);

    ?>

Результат выполнения приведённого примера:

    int(0)
    int(2)
    int(3)

## Callback-функции PHP

Можно присвоить замыкание PHP переменной с типом «указатель» (pointer) или передать замыкание как аргумент функции:

Пример #1 Присваивание Closure языка PHP указателю функции языка C

    <?php

    $zend = FFI::cdef("
        typedef int (*zend_write_func_t)(const char *str, size_t str_length);
        extern zend_write_func_t zend_write;
    ");

    echo "Привет, мир 1!\n";

    $orig_zend_write = clone $zend->zend_write;

    $zend->zend_write = function($str, $len) {
        global $orig_zend_write;
        $orig_zend_write("{\n\t", 3);
        $ret = $orig_zend_write($str, $len);
        $orig_zend_write("}\n", 2);
        return $ret;
    };

    echo "Привет, мир 2!\n";
    $zend->zend_write = $orig_zend_write;
    echo "Привет, мир 3!\n";

    ?>

Результат выполнения приведённого примера:

    Привет, мир 1!
    {
            Привет, мир 2!
    }
    Привет, мир 3!

Хоть это и работает, но эта функциональность поддерживается не на каждой платформе с библиотекой libffi, не эффективна и вызывает утечку ресурсов при завершении запросов.
Подсказка

Поэтому рекомендуют минимизировать использование callback-функций PHP.

## Комплексный пример PHP/FFI/preloading

php.ini

    ffi.enable=preload
    opcache.preload=preload.php

preload.php

    <?php

    FFI::load(__DIR__ . "/dummy.h");
    opcache_compile_file(__DIR__ . "/dummy.php");

    ?>

dummy.h

    #define FFI_SCOPE "DUMMY"
    #define FFI_LIB "libc.so.6"

    int printf(const char *format, ...);

dummy.php

    <?php

    final class Dummy
    {
        private static $ffi = null;

        function __construct()
        {
            if (is_null(self::$ffi)) {
                self::$ffi = FFI::scope("DUMMY");
            }
        }

        function printf($format, ...$args)
        {
           return (int) self::$ffi->printf($format, ...$args);
        }
    }

    ?>

test.php

    <?php

    $d = new Dummy();
    $d->printf("Привет, %s!\n", "мир");

    ?>

# Основной интерфейс к коду и данным языка C

(PHP 7 >= 7.4.0, PHP 8)

## Введение

Объекты этого класса создаются фабричными методами FFI::cdef(), FFI::load() и FFI::scope(). Объявленные переменные языка C доступны как свойства экземпляра класса FFI, а функции как методы. Методы FFI::new() и FFI::type() принимают или возвращают объявленные типы языка C, когда создают структуры данных C.

Разбор объявлений FFI и загрузка разделяемой библиотеки может занять значительное время. Не имеет смысла делать это для каждого HTTP-запроса в Web-окружении. Тем не менее можно перезагрузить объявления FFI и библиотеки при старте PHP и инстанциировать объекты класса FFI по необходимости. Заголовочные файлы могут быть расширены специальными объявлениями `FFI_SCOPE` (например, `#define FFI_SCOPE "foo"`; скоуп по умолчанию — «C») и загружены методом FFI::load() во время предзагрузки. Это приведёт к созданию постоянных привязок, которые будут доступны для всех запросов через метод FFI::scope(). Более подробно читайте на странице Простые примеры использования класса FFI.

В один и тот же скоуп можно предзагрузить несколько заголовочных файлов.

## Обзор класса

final class FFI {
/* Константы */
public const int __BIGGEST_ALIGNMENT__;
/* Методы */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## Предопределённые константы

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Создаёт неуправляемый указатель на данные C

### Описание

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

Создаёт неуправляемый указатель на данные C, представленные заданным FFI\CData. Исходный `ptr` должен пережить результирующий указатель. Эта функция используется главным образом для передачи аргументов в функцию C по указателю.

### Список параметров

`ptr`
  Дескриптор неуправляемого указателя на структуру данных.

### Возвращаемые значения

Возвращает новый объект FFI\CData.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Возвращает величину выравнивания

### Описание

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Возвращает величину выравнивания объектов FFI\CData или FFI\CType.

### Список параметров

`ptr`
  Дескриптор указателя на данные или тип C.

### Возвращаемые значения

Возвращает величину выравнивания объектов FFI\CData или FFI\CType.

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Динамически конструирует новый тип С массива

### Описание

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

Динамически конструирует новый тип С массива с элементами типа `type` и размерностями, заданными в `dimensions`. В следующем примере `$t1` и `$t2` определяют массивы одинакового типа:

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### Список параметров

`type`
  Корректная декларация типа С, например string, или заранее созданный объект класса FFI\CType.
`dimensions`
  Массив, определяющий размерность типа.

### Возвращаемые значения

Возвращает новый объект FFI\CType.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Приводит тип C

### Описание

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

Метод FFI::cast() создаёт новый объект класса FFI\CData, который указывает на ту же структуру C, но ассоциирован с другим типом. Полученный объект не становится владельцем данных, так что исходный указатель `ptr` должен оставаться живым дольше полученного объекта. Тип C должен быть задан как строка, которая содержит имя любого корректного типа С, либо как объект FFI\CType. Разрешён любой тип, который объявили для экземпляра.

### Список параметров

`type`
  Строка с именем типа С или объект класса FFI\CType.
`ptr`
  Дескриптор указателя на структуру данных С.

### Возвращаемые значения

Метод возвращает новый объект класса FFI\CData.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Статический вызов метода FFI::cast() устарел.

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Создаёт новый объект FFI

### Описание

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Создаёт новый объект FFI.

### Список параметров

`code`
  Строка, содержащая последовательность деклараций на языке С (типы, структуры, функции, переменные и т.д.). Фактически можно скопировать кусок заголовочного файла С.

  > Замечание: Директивы сопроцессора С не поддерживаются. Т.е. `#include`, `#define` и макросы CPP работать не будут.

`lib`
  Имя файла библиотеки, который будет загружен и связан с заданными декларациями.

  > Замечание: Если параметр `lib` не задан или `null`, то для платформ, поддерживающих `RTLD_DEFAULT`, будет произведён поиск задекларированных в `code` сущностей в глобальной области видимости. Для прочих платформ произвести привязку не получится.

### Возвращаемые значения

Возвращает новый объект FFI.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функции языка Си, возвращающие `void`, возвращают PHP null вместо FFI\CType::TYPE_VOID.
8.0.0 | `lib` теперь допускает значение null.

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Высвобождает неуправляемую структуру данных

### Описание

public static function FFI::free(FFI\CData `&$ptr`): void

Высвобождает созданную ранее неуправляемую структуру данных.

### Список параметров

`ptr`
  Дескриптор неуправляемого указателя на структуру данных.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Проверяет, является ли FFI\CData нулевым указателем

### Описание

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Проверяет, является ли FFI\CData нулевым указателем.

### Список параметров

`ptr`
  Указатель на структуру данных C.

### Возвращаемые значения

Возвращает `true` или `false` в зависимости от того, является ли FFI\CData нулевым указателем.

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Загружает декларации C из заголовочного файла

### Описание

public static function FFI::load(string `$filename`): ?FFI

Метод загружает декларации C из заголовочного файла. Общие библиотеки, которые требуется загрузить, указывают в определениях переменной `FFI_LIB` в загруженном заголовочном файле C.

### Список параметров

`filename`
  Имя заголовочного файла C. Директивы сопроцессора С не поддерживаются. То есть директивы `#include`, `#define` и макросы CPP работать не будут, за исключением особых случаев, которые перечислим ниже. Заголовочный файл должен содержать инструкцию `#define` для переменной `FFI_SCOPE`, например, `#define FFI_SCOPE "MYLIB"`. Подробне об этом рассказывает раздел «Введение в FFI». Заголовочный файл может содержать оператор `#define` для переменной `FFI_LIB`, чтобы указать библиотеку, которую он раскрывает. Если это системная библиотека, требуется только имя файла, например: `#define FFI_LIB "libc.so.6"`. Если это пользовательская библиотека, требуется относительный путь, например: `#define FFI_LIB "./mylib.so"`.

### Возвращаемые значения

Метод возвращает новый объект FFI или `null`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Метод FFI::load() теперь разрешён в скриптах предзагрузки, когда текущий пользователь системы совпадает с пользователем, определённым в директиве конфигурации `opcache.preload_user`.

### Смотрите также

- FFI::scope() - Инстанциирует объект FFI в соответствии с декларацией С, разобранной на этапе предзагрузки

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Сравнивает две области памяти

### Описание

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

Сравнивает полученный в параметре `size` размер байтов из областей памяти по указателям `ptr1` и `ptr2`. И `ptr1`, и `ptr2` могут быть любыми нативными структурами данных (FFI\CData), либо строками PHP.

### Список параметров

`ptr1`
  Указатель на первую область памяти.
`ptr2`
  Указатель на вторую область памяти.
`size`
  Количество байтов для сравнения.

### Возвращаемые значения

Возвращает значение меньше `0`, если содержимое области памяти от указателя в параметре `ptr1` меньше, чем содержимое области памяти от указателя в параметре `ptr2`, значение больше `0`, если содержимое первой области памяти больше второй, и `0`, если если они равны.

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Копирует содержимое одной области памяти в другую

### Описание

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

Копирует `size` байт из области памяти `from` в область памяти `to`.

### Список параметров

`to`
  Целевая область памяти.
`from`
  Область памяти, откуда будет происходить копирование.
`size`
  Количество байт для копирования.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Заполнить область памяти

### Описание

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

Заполняет `size` байт памяти по указателю `ptr` значением `value`.

### Список параметров

`ptr`
  Указатель на начало участка памяти.
`value`
  Значение для заполнения.
`size`
  Количество байт, которые будут заполнены.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Создаёт структуру данных C

### Описание

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

Метод создаёт собственную структуру данных заданного типа. Разрешён любой тип, который объявили для экземпляра.

### Список параметров

`type`
  `type` — допустимое объявление типа С в виде строки (string) или экземпляр класса FFI\CType, которые создали заранее.
`owned`
  Создавать ли управляемые или неуправляемые данные. Управляемые данные живут в связке с возвращённым объектом FFI\CData и высвобождаются, когда стандартный подсчёт ссылок PHP или сборщик мусора GC освободят последнюю ссылку на этот объект. Неуправляемые данные необходимо высвобождать вручную методом FFI::free().
`persistent`
  Располагать ли структуру данных C в системной куче (heap) через функцию malloc() или в куче PHP-запроса через функцию emalloc().

### Возвращаемые значения

Метод возвращает новый объект класса FFI\CData или `null` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Статический вызов метода FFI::new() устарел.

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Инстанциирует объект FFI в соответствии с декларацией С, разобранной на этапе предзагрузки

### Описание

public static function FFI::scope(string `$name`): FFI

Инстанциирует объект FFI в соответствии с декларацией С, разобранной на этапе предзагрузки.

Метод FFI::scope() можно многократно вызывать для одного и того же контекста. Множество ссылок на один и тот же контекст могут быть загружены одновременно.

### Список параметров

`name`
  Имя скоупа, заданного с помощью специальной `#define` директивы `FFI_SCOPE`.

### Возвращаемые значения

Возвращает новый объект FFI.

### Смотрите также

- FFI::load() - Загружает декларации C из заголовочного файла

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Возвращает размер данных или типа C

### Описание

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Возвращает размер объектов FFI\CData или FFI\CType.

### Список параметров

`ptr`
  Дескриптор указателя на тип или данные C.

### Возвращаемые значения

Размер области памяти, на который указывает `ptr`.

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Создаёт строку PHP из области памяти

### Описание

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

Создаёт переменную PHP типа string из `size` байт памяти, начиная с адреса по указателю `ptr`.

### Список параметров

`ptr`
  Начало участка памяти, из которой будет создаваться строка.
`size`
  Количество байт для копирования в строку. Если параметр `size` не задан или `null`, то `ptr` должен указывать на массив C типа `char`, завершающийся нулевым байтом.

### Возвращаемые значения

Строка PHP.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `size` теперь допускает значение null; ранее значением по умолчанию был `0`.

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Создаёт объект класса FFI\CType из объявления С

### Описание

public function FFI::type(string `$type`): ?FFI\CType

Метод создаёт и возвращает объект класса FFI\CType для заданной строки, которая содержит объявление типа С. Разрешён любой тип, который объявили для экземпляра.

### Список параметров

`type`
  Корректное объявление типа C в виде строки (string).

### Возвращаемые значения

Метод возвращает новый объект класса FFI\CType или `null`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Статический вызов метода FFI::type() устарел.

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Получает FFI\CType для FFI\CData

### Описание

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Возвращает объект FFI\CType, представляющий тип объекта FFI\CData.

### Список параметров

`ptr`
  Указатель на структуру данных C.

### Возвращаемые значения

Возвращает объект FFI\CType, представляющий тип объекта FFI\CData.

## Содержание

- FFI::addr — Создаёт неуправляемый указатель на данные C
- FFI::alignof — Возвращает величину выравнивания
- FFI::arrayType — Динамически конструирует новый тип С массива
- FFI::cast — Приводит тип C
- FFI::cdef — Создаёт новый объект FFI
- FFI::free — Высвобождает неуправляемую структуру данных
- FFI::isNull — Проверяет, является ли FFI\CData нулевым указателем
- FFI::load — Загружает декларации C из заголовочного файла
- FFI::memcmp — Сравнивает две области памяти
- FFI::memcpy — Копирует содержимое одной области памяти в другую
- FFI::memset — Заполнить область памяти
- FFI::new — Создаёт структуру данных C
- FFI::scope — Инстанциирует объект FFI в соответствии с декларацией С, разобранной на этапе предзагрузки
- FFI::sizeof — Возвращает размер данных или типа C
- FFI::string — Создаёт строку PHP из области памяти
- FFI::type — Создаёт объект класса FFI\CType из объявления С
- FFI::typeof — Получает FFI\CType для FFI\CData

# Доступ к данным C

(PHP 7 >= 7.4.0, PHP 8)

## Введение

С объектами FFI\CData работают как со стандартными PHP-данными:

- Данные языка C скалярных типов считываются и присваиваются через свойство $cdata: `$x = FFI::new('int'); $x->cdata = 42;`
- К полям структур (struct) и объединений (union) языка C получают доступ как к свойству объекта PHP: `$cdata->field`
- К элементам массива C получают доступ как к элементам массива PHP: `$cdata[$offset]`
- Массивы C перебирают через языковую конструкцию `foreach`.
- На массивах языка C вызывают функцию count().
- Указатели C разыменовывают как массивы: `$cdata[0]`
- Указатели C сравнивают стандартными операторами сравнения (`<`, `<=`, `==`, `!=`, `>=`, `>`).
- Для указателей языка C разрешны операции инкремента и декремента `+`/`-`/ `++`/`--`: `$cdata += 5`
- Указатели C вычитают стандартной операцией `-`.
- Указатели C на функции вызывают как стандартные PHP-замыкания: `$cdata()`
- Данные C клонируют оператором clone: `$cdata2 = clone $cdata;`
- Данные языка C визуализируют через функции var_dump(), print_r(), и т. д.
- Начиная с PHP 8.3.0 объекты класса FFI\CData разрешено присваивать структурам и полям.

> Замечание: Обратите внимание, что экземпляры класса FFI\CData не поддерживают языковые конструкции isset(), empty() и unset(), и что обёрнутые структуры и объединения C не реализуют интерфейс Traversable.

## Обзор класса

namespace FFI;
final class CData {
}

## Список изменений

Версия | Описание
--- | ---
8.3.0 | Объекты класса FFI\CData теперь разрешено присваивать структурам и полям.

# Доступ к типам C

(PHP 7 >= 7.4.0, PHP 8)

## Введение

## Обзор класса

namespace FFI;
final class CType {
/* Константы */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* Методы */
public function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function getStructFieldType(string `$name`): FFI\CType
}

## Предопределённые константы

`FFI\CType::TYPE_VOID`
`FFI\CType::TYPE_FLOAT`
`FFI\CType::TYPE_DOUBLE`
`FFI\CType::TYPE_LONGDOUBLE`
`FFI\CType::TYPE_UINT8`
`FFI\CType::TYPE_SINT8`
`FFI\CType::TYPE_UINT16`
`FFI\CType::TYPE_SINT16`
`FFI\CType::TYPE_UINT32`
`FFI\CType::TYPE_SINT32`
`FFI\CType::TYPE_UINT64`
`FFI\CType::TYPE_SINT64`
`FFI\CType::TYPE_ENUM`
`FFI\CType::TYPE_BOOL`
`FFI\CType::TYPE_CHAR`
`FFI\CType::TYPE_POINTER`
`FFI\CType::TYPE_FUNC`
`FFI\CType::TYPE_ARRAY`
`FFI\CType::TYPE_STRUCT`
`FFI\CType::ATTR_CONST`
`FFI\CType::ATTR_INCOMPLETE_TAG`
`FFI\CType::ATTR_VARIADIC`
`FFI\CType::ATTR_INCOMPLETE_ARRAY`
`FFI\CType::ATTR_VLA`
`FFI\CType::ATTR_UNION`
`FFI\CType::ATTR_PACKED`
`FFI\CType::ATTR_MS_STRUCT`
`FFI\CType::ATTR_GCC_STRUCT`
`FFI\CType::ABI_DEFAULT`
`FFI\CType::ABI_CDECL`
`FFI\CType::ABI_FASTCALL`
`FFI\CType::ABI_THISCALL`
`FFI\CType::ABI_STDCALL`
`FFI\CType::ABI_PASCAL`
`FFI\CType::ABI_REGISTER`
`FFI\CType::ABI_MS`
`FFI\CType::ABI_SYSV`
`FFI\CType::ABI_VECTORCALL`

# FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Описание

### Описание

public function FFI\CType::getAlignment(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Описание

### Описание

public function FFI\CType::getArrayElementType(): FFI\CType

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Описание

### Описание

public function FFI\CType::getArrayLength(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Описание

### Описание

public function FFI\CType::getAttributes(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Описание

### Описание

public function FFI\CType::getEnumKind(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Описание

### Описание

public function FFI\CType::getFuncABI(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Извлекает количество параметров типа функции

### Описание

public function FFI\CType::getFuncParameterCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество параметров для базового типа функции. Метод выбрасывает исключение FFI\Exception, если базовый тип — не функция.

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Получает тип параметра функции

### Описание

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Метод возвращает тип параметра для нижележащего типа функции.

### Список параметров

`index`
  Индекс параметра функции. Отсчёт индексов начинается с нуля.

### Возвращаемые значения

Метод возвращает тип параметра для базового типа функции. Метод выбрасывает исключение FFI\Exception, если базовый тип не соответствует типу «функция» или индекс выходит за пределы диапазона индексов параметров функции.

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Описание

### Описание

public function FFI\CType::getFuncReturnType(): FFI\CType

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Описание

### Описание

public function FFI\CType::getKind(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Описание

### Описание

public function FFI\CType::getName(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Описание

### Описание

public function FFI\CType::getPointerType(): FFI\CType

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Описание

### Описание

public function FFI\CType::getSize(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Описание

### Описание

public function FFI\CType::getStructFieldNames(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Описание

### Описание

public function FFI\CType::getStructFieldOffset(string `$name`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`name`

### Возвращаемые значения

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Описание

### Описание

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`name`

### Возвращаемые значения

## Содержание

- FFI\CType::getAlignment — Описание
- FFI\CType::getArrayElementType — Описание
- FFI\CType::getArrayLength — Описание
- FFI\CType::getAttributes — Описание
- FFI\CType::getEnumKind — Описание
- FFI\CType::getFuncABI — Описание
- FFI\CType::getFuncParameterCount — Извлекает количество параметров типа функции
- FFI\CType::getFuncParameterType — Получает тип параметра функции
- FFI\CType::getFuncReturnType — Описание
- FFI\CType::getKind — Описание
- FFI\CType::getName — Описание
- FFI\CType::getPointerType — Описание
- FFI\CType::getSize — Описание
- FFI\CType::getStructFieldNames — Описание
- FFI\CType::getStructFieldOffset — Описание
- FFI\CType::getStructFieldType — Описание

# Исключения FFI

(PHP 7 >= 7.4.0, PHP 8)

## Введение

## Обзор класса

namespace FFI;
class Exception extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# Исключения парсера FFI

(PHP 7 >= 7.4.0, PHP 8)

## Введение

## Обзор класса

namespace FFI;
final class ParserException extends FFI\Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Примеры
  - Базовая работа с модулем FFI
  - Callback-функции PHP
  - Комплексный пример PHP/FFI/preloading
- FFI — Основной интерфейс к коду и данным языка C
  - FFI::addr — Создаёт неуправляемый указатель на данные C
  - FFI::alignof — Возвращает величину выравнивания
  - FFI::arrayType — Динамически конструирует новый тип С массива
  - FFI::cast — Приводит тип C
  - FFI::cdef — Создаёт новый объект FFI
  - FFI::free — Высвобождает неуправляемую структуру данных
  - FFI::isNull — Проверяет, является ли FFI\CData нулевым указателем
  - FFI::load — Загружает декларации C из заголовочного файла
  - FFI::memcmp — Сравнивает две области памяти
  - FFI::memcpy — Копирует содержимое одной области памяти в другую
  - FFI::memset — Заполнить область памяти
  - FFI::new — Создаёт структуру данных C
  - FFI::scope — Инстанциирует объект FFI в соответствии с декларацией С, разобранной на этапе предзагрузки
  - FFI::sizeof — Возвращает размер данных или типа C
  - FFI::string — Создаёт строку PHP из области памяти
  - FFI::type — Создаёт объект класса FFI\CType из объявления С
  - FFI::typeof — Получает FFI\CType для FFI\CData
- FFI\CData — Доступ к данным C
- FFI\CType — Доступ к типам C
  - FFI\CType::getAlignment — Описание
  - FFI\CType::getArrayElementType — Описание
  - FFI\CType::getArrayLength — Описание
  - FFI\CType::getAttributes — Описание
  - FFI\CType::getEnumKind — Описание
  - FFI\CType::getFuncABI — Описание
  - FFI\CType::getFuncParameterCount — Извлекает количество параметров типа функции
  - FFI\CType::getFuncParameterType — Получает тип параметра функции
  - FFI\CType::getFuncReturnType — Описание
  - FFI\CType::getKind — Описание
  - FFI\CType::getName — Описание
  - FFI\CType::getPointerType — Описание
  - FFI\CType::getSize — Описание
  - FFI\CType::getStructFieldNames — Описание
  - FFI\CType::getStructFieldOffset — Описание
  - FFI\CType::getStructFieldType — Описание
- FFI\Exception — Исключения FFI
- FFI\ParserException — Исключения парсера FFI

# OPcache

# Введение

Модуль OPcache сохраняет предкомпилированный байт-код скриптов в разделяемой памяти. Кеширование операционного PHP-кода повышает производительность и помогает избегать загрузки и анализа скриптов при каждом запросе.

Модуль входит в состав PHP 5.5.0 и более новых версий, а для PHP версий 5.2, 5.3 и 5.4 доступен для скачивания » из репозитория PECL.

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

OPcache можно собирать только как разделяемый модуль. Если вы запретили сборку модулей по умолчанию с помощью --disable-all, то вам будет необходимо компилировать PHP с ключом --enable-opcache для включения OPcache.

Единожды скомпилировав, вы можете использовать директиву конфигурации zend_extension для загрузки OPcache в PHP. Это можно сделать с помощью `zend_extension=/full/path/to/opcache.so` для платформ, отличных от Windows, и `zend_extension=C:\path\to\php_opcache.dll` в Windows.

> Замечание: Если вы хотите использовать OPcache с » Xdebug, то сперва нужно загружать OPcache, а потом Xdebug.

### Рекомендованные настройки php.ini

Данные опции рекомендованы для обеспечения хорошей производительности:

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1 ; до PHP 7.2.0
    opcache.enable_cli=1

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

В Windows должен быть включён параметр opcache.file_cache_fallback и opcache.file_cache должна быть установлена на уже существующий и доступный для записи каталог.

Полный список опций настройки OPcache смотрите тут.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки модуля OPcache
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | Между PHP 7.1.2 и 7.1.6 включительно значение по умолчанию было равно `1`
opcache.memory_consumption | 128 | `INI_SYSTEM` |
opcache.interned_strings_buffer | 8 | `INI_SYSTEM` |
opcache.max_accelerated_files | 10000 | `INI_SYSTEM` |
opcache.max_wasted_percentage | 5 | `INI_SYSTEM` |
opcache.use_cwd | 1 | `INI_SYSTEM` |
opcache.validate_timestamps | 1 | `INI_ALL` |
opcache.revalidate_freq | 2 | `INI_ALL` |
opcache.revalidate_path | 0 | `INI_ALL` |
opcache.save_comments | 1 | `INI_SYSTEM` |
opcache.fast_shutdown | 0 | `INI_SYSTEM` |
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | 0x7FFEBFFF | `INI_SYSTEM` | До PHP 7.3.0 значение равнялось `0x7FFFBFFF`
opcache.inherited_hack | 1 | `INI_SYSTEM` | Удалили в PHP 7.3.0
opcache.dups_fix | 0 | `INI_ALL` |
opcache.blacklist_filename | "" | `INI_SYSTEM` |
opcache.max_file_size | 0 | `INI_SYSTEM` |
opcache.consistency_checks | 0 | `INI_ALL` | Опцию отключили с PHP 8.1.18 и 8.2.5 и удалили в PHP 8.3.0
opcache.force_restart_timeout | 180 | `INI_SYSTEM` |
opcache.error_log | "" | `INI_SYSTEM` |
opcache.log_verbosity_level | "1" | `INI_SYSTEM` |
opcache.record_warnings | 0 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` | Опция доступна только на ОС Windows
opcache.restrict_api | "" | `INI_SYSTEM` |
opcache.file_update_protection | 2 | `INI_ALL` |
opcache.huge_code_pages | 0 | `INI_SYSTEM` |
opcache.lockfile_path | "/tmp" | `INI_SYSTEM` |
opcache.opt_debug_level | 0 | `INI_SYSTEM` | Опция доступна с PHP 7.1.0
opcache.file_cache | `null` | `INI_SYSTEM` |
opcache.file_cache_only | 0 | `INI_SYSTEM` |
opcache.file_cache_consistency_checks | 1 | `INI_SYSTEM` |
opcache.file_cache_fallback | 1 | `INI_SYSTEM` |
opcache.validate_permission | 0 | `INI_SYSTEM` | Опция доступна с PHP 7.0.14
opcache.validate_root | 0 | `INI_SYSTEM` | Опция доступна с PHP 7.0.14
opcache.preload | "" | `INI_SYSTEM` | Опция доступна с PHP 7.4.0
opcache.preload_user | "" | `INI_SYSTEM` | Опция доступна с PHP 7.4.0
opcache.cache_id | "" | `INI_SYSTEM` | Опция доступна с PHP 7.4.0 только на ОС Windows
opcache.jit | "tracing" | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_buffer_size | 0 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_debug | 0 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_bisect_limit | 0 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_prof_threshold | 0.005 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_max_root_traces | 1024 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_max_side_traces | 128 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_max_exit_counters | 8192 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_hot_loop | 61 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0. До PHP 8.5.0 значение по умолчанию было 64
opcache.jit_hot_func | 127 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_hot_return | 8 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_hot_side_exit | 8 | `INI_SYSTEM` | Опция доступна с PHP 8.0.0
opcache.jit_blacklist_root_trace | 16 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_blacklist_side_trace | 8 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_max_loop_unrolls | 8 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_max_recursive_calls | 2 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_max_recursive_returns | 2 | `INI_ALL` | Опция доступна с PHP 8.0.0
opcache.jit_max_polymorphic_calls | 2 | `INI_ALL` | Опция доступна с PHP 8.0.0

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`opcache.enable` bool
  Включает кеш опкодов. Код не оптимизируется и не кешируется, если опцию отключили. Опцию `opcache.enable` нельзя включить во время выполнения функцией ini_set(), но можно отключить. Попытка включить опцию в скрипте выдаст предупреждение.
`opcache.enable_cli` bool
  Включает кеш опкодов для CLI-версии PHP.
`opcache.memory_consumption` int
  Размер разделяемой памяти в мегабайтах для OPcache. Минимально допустимое значение — `8`, которое кеш опкодов займёт, если установили значение меньше.
`opcache.interned_strings_buffer` int
  Количество памяти в мегабайтах для хранения интернированных строк. Максимальное значение — 32 767 на 64-разрядных архитектурах и 4095 на 32-разрядных архитектурах.

  > Замечание: До PHP 8.4.0 максимальное значение составляло 4095 мегабайт на всех архитектурах.

`opcache.max_accelerated_files` int
  Максимальное количество ключей (и, соответственно, скриптов) в хеш-таблице OPcache. Значение, которое кеш опкодов будет использовать в итоге, будет первым числом из набора `{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }`, которое больше или равно значению, которое установили для этого параметра. Минимальное значение составляет 200, а максимальное — 1 000 000. Значения за пределами этого диапазона ограничиваются допустимым диапазоном.
`opcache.max_wasted_percentage` int
  Максимальный процент неиспользуемой памяти, при достижении которого модуль запланирует перезапуск, если свободной памяти недостаточно. Максимально допустимое значение: `50`, которое кеш опкодов займёт, если установили значение больше.
`opcache.use_cwd` bool
  При включении опции OPcache добавляет текущую рабочую директорию к ключу скрипта, чем устраняет возможность коллизий для файлов с одинаковым основным именем. Отключение этой директивы повышает производительность, но иногда приводит к сбоям приложений.
`opcache.validate_timestamps` bool

  При включении опции OPcache будет проверять актуальность закешированных скриптов каждые opcache.revalidate_freq секунд. При отключении директивы требуется сбросить OPcache вручную функциями opcache_reset() и opcache_invalidate() или перезапустить веб-сервер, чтобы изменения в файловой системе вступили в силу.

  > Замечание: OPcache по-прежнему может проверять метку времени файла во время компиляции, если для опций opcache.file_update_protection или opcache.max_file_size установили ненулевые значения.

`opcache.revalidate_freq` int
  Как часто в секундах проверять обновления меток времени скрипта. При значении `0` OPcache будет проверять обновления при каждом запросе. Модуль игнорирует эту директиву конфигурации, если опцию opcache.validate_timestamps отключили.
`opcache.revalidate_path` bool
  При отключении опции модуль переиспользует файлы кеша, пути которых содержат путь из списка include_path. Поэтому модуль не будет искать файл с таким же именем по другим путям списка include_path.
`opcache.save_comments` bool
  При отключении опции модуль отбрасывает комментарии для документации из кеша опкодов, чтобы уменьшить размер оптимизированного кода. Отключение этой директивы конфигурации может спровоцировать сбой в работе приложений и фреймворков, которые полагаются на аннотации в комментариях, включая Doctrine, Zend Framework 2 и PHPUnit.
`opcache.fast_shutdown` bool
  При включении опции используется последовательность быстрого завершения работы, которая не освобождает каждый выделенный блок памяти, а полагается на менеджер памяти движка Zend Engine для массового освобождения всего набора переменных запроса. Эту директиву удалили в PHP 7.2.0. Вариант последовательности быстрого завершения работы интегрировали в PHP и кеш опкодов по возможности будет использовать вариант автоматически.
`opcache.enable_file_override` bool
  При включении опции и вызове функций file_exists(), is_file() и is_readable() модуль будет проверять, содержит ли уже кеш опкодов файл. Опция может повысить производительность приложений, которые проверяют наличие и доступность для чтения PHP-скриптов, но рискует вернуть устаревшие данные, если опцию opcache.validate_timestamps отключили.
`opcache.optimization_level` int
  Битовая маска, которая контролирует, какие шаги оптимизации выполняются. Значением по умолчанию является `0x7FFEBFFF`, которое включает все безопасные оптимизации. Отключение оптимизаций или включение небезопасных оптимизаций в основном полезно для отладки/разработки оптимизатора. Каждый бит в битовой маске включает определённый этап оптимизации:

  Маска битов оптимизации
  Бит | Название | Описание | По умолчанию
  --- | --- | --- | ---
  0 | PASS_1 | Простая оптимизация Peephole | On
  1 | PASS_2 | Не используется (объединён с PASS_1) | On
  2 | PASS_3 | Простая оптимизация JuMP | On
  3 | PASS_4 | Оптимизация Call | On
  4 | PASS_5 | Оптимизация на основе графа управления потоком | On
  5 | PASS_6 | Оптимизация на основе анализа потока данных | On
  6 | PASS_7 | Следует ли использовать график вызовов для оптимизации на основе SSA | On
  7 | PASS_8 | Редкое распространение условных констант | On
  8 | PASS_9 | Оптимизация временных переменных | On
  9 | PASS_10 | Удаление кодов операций NOP | On
  10 | PASS_11 | Сжатие литералов | On
  11 | PASS_12 | Предварительный расчет размера стека вызовов | On
  12 | PASS_13 | Удаление неиспользуемых переменных | On
  13 | PASS_14 | Удаление мёртвого кода | On
  14 | PASS_15 | Сбор и замена объявлений констант (небезопасно) | Off
  15 | PASS_16 | Встраивание тривиальных функций (часть оптимизации вызовов) | On
  16 | (Flag) | Игнорировать возможность перегрузки оператора (небезопасно) | Off

  > Замечание: Безопасные и небезопасные оптимизации
  > Безопасные оптимизации (включены по умолчанию) сохраняют точное поведение кода PHP, одновременно повышая производительность. Включают удаление мёртвого кода, сворачивание констант и оптимизацию переходов. Небезопасные оптимизации (по умолчанию отключено) может изменить поведение в пограничных случаях:

  > - Бит 14: Сбор констант. Константы подставляются во время компиляции, игнорируя порядок объявления во время выполнения:

  >       <?php
  >       echo getA();         // Вывод: "hello" вместо того, чтобы вызывать ошибку
  >       const A = "hello";
  >       function getA() { return A; }

  > - Бит 16: Игнорирование перегрузки операторов. Небезопасно при использовании классов с `do_operation` (например, GMP, BCMath) в арифметических операциях. При объявлении типов оптимизатор может безопасно применять те же оптимизации.

`opcache.inherited_hack` bool
  Эта директива конфигурации игнорируется.
`opcache.dups_fix` bool
  Этот хак требуется только для обхода ошибок «Невозможно повторно объявить класс» (Cannot redeclare class).
`opcache.blacklist_filename` string
  Расположение файла чёрного списка OPcache. Файл чёрного списка — текстовый файл, который содержит имена файлов, которые не нужно ускорять, по одной записи на строку. Допускаются подстановочные знаки, также можно указывать префиксы. Строки, которые начинаются с точки с запятой, игнорируются как комментарии. Пример простого чёрного списка:

      ; Соответствует конкретному файлу.
      /var/www/broken.php
      ; Префикс, который соответствует каждому файлу, который начинается с «x».
      /var/www/x
      ; Соответствует подстановочному знаку.
      /var/www/*-broken.php

`opcache.max_file_size` int
  Максимальный размер файла для кеширования в байтах. Модуль будет кешировать все файлы, если значение равно `0`.
`opcache.consistency_checks` int
  Если значение ненулевое, OPcache будет сверять контрольную сумму кеша каждые N запросов, где N — значение этой директивы конфигурации. Рекомендуется включать директиву только при отладке, поскольку опция снижает производительность.

  > Замечание: Опцию отключили с PHP 8.1.18 и 8.2.5 и удалили в PHP 8.3.0.

`opcache.force_restart_timeout` int
  Время ожидания начала запланированного перезапуска в секундах при неактивном кеше. Если время ожидания истекло, OPcache решает, что что-то не так, и чтобы разрешить перезапуск, завершит процессы, которые удерживают блокировки в кеше. Если для параметра opcache.log_verbosity_level установили значение 2 или больше, то когда возникнет ситуации с превышением времени ожидания, модуль запишет в лог ошибок предупреждение. Директива не поддерживается в ОС Windows.
`opcache.error_log` string
  Путь к логу ошибок OPcache. Пустая строка обрабатывается как `stderr`, и приведёт к отправке логов в стандартный поток ошибок (обычно это лог ошибок веб-сервера).
`opcache.log_verbosity_level` int
  Уровень детализации лога ошибок. По умолчанию регистрируются только фатальные ошибки (уровень 0) и ошибки (уровень 1). Другие доступные уровни: предупреждения (уровень 2), информационные сообщения (уровень 3) и сообщения отладки (уровень 4).
`opcache.record_warnings` bool
  При включении опции OPcache будет записывать предупреждения, которые возникают во время компиляции, и повторять их при следующем включении файла, даже если файл обслуживается из кеша.
`opcache.preferred_memory_model` string
  Предпочитаемая модель памяти для OPcache. Если оставить значение пустым, OPcache сам выберет наиболее подходящую модель, которая будет вести себя корректно практически в любых случаях. Возможные значения включают `mmap`, `shm`, `posix` и `win32`.
`opcache.protect_memory` bool
  Защищает разделяемую память от неожиданной записи во время запуска скриптов. Полезно только для внутренней отладки.
`opcache.mmap_base` string
  Базовое значение для сегмента разделяемой памяти в ОС Windows. Каждый PHP-процесс должен отображать разделяемую память в одинаковое адресное пространство. Эта директива помогает исправить ошибки «Не удается повторно прикрепиться к базовому адресу» (Unable to reattach to base address).
`opcache.restrict_api` string
  Разрешает вызывать API-функции модуля OPcache только из PHP-скриптов, чей путь начинается с заданной строки. Значение по умолчанию равно `""` и означает отсутствие ограничений.
`opcache.file_update_protection` string
  Исключает кеширование файлов, с момента изменения которых прошло меньше секунд, чем указали. Это защищает от кеширования неполностью обновлённых файлов. Если все обновления файлов атомарны, можно повысить производительность, задав для этого параметра значение `0`. Это разрешит закешировать файлы немедленно.
`opcache.huge_code_pages` bool
  Включает или отключает копирование PHP-кода (текстового сегмента) в HUGE PAGES. Опция может повысить производительность, но требует соответствующих системных настроек. Опция доступна в Linux начиная с PHP 7.0.0 и во FreeBSD начиная с PHP 7.4.0.
`opcache.lockfile_path` string
  Абсолютный путь к хранилищу общих файлов блокировок (только для *nix-систем).
`opcache.opt_debug_level` string
  Создаёт сброс опкодов для отладки отдельных этапов оптимизации. Значение 0x10000 будет выводить опкоды в том виде, в каком их создал компилятор, до оптимизации, тогда как значение 0x20000 будет выводить оптимизированные опкоды.
`opcache.file_cache` string
  Включает и устанавливает каталог кеша второго уровня. Опция должна повысить производительность, когда SHM-память заполнилась, при перезапуске сервера или сбросе разделяемой SHM-памяти. Значение по умолчанию `""` отключает кеширование на основе файлов.
`opcache.file_cache_only` bool
  Включает или выключает кеширование опкодов в разделяемой памяти.

  > Замечание: До PHP 8.1.0 отключение этой директивы с уже заполненным файловым кешем требовало ручной очистки файлового кеша.

`opcache.file_cache_consistency_checks` bool
  Включает или выключает проверку контрольной суммы при загрузке скрипта из файлового кеша.
`opcache.file_cache_fallback` bool
  Подразумевает `opcache.file_cache_only=1` для конкретного процесса, которому не удалось повторно подключиться к разделяемой памяти (только для ОС Windows). Требуется явное включение файлового кеша.
  Предостережение

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

`opcache.validate_permission` bool
  Проверяет права доступа к кешированному файлу для текущего пользователя.
`opcache.validate_root` bool
  Предотвращает коллизии имён в chroot-окружении. Опцию необходимо включать для каждого chroot-окружения, чтобы предотвратить доступ к файлам за пределами chroot.
`opcache.preload` string
  Задаёт PHP-скрипт, который модуль скомпилирует и выполнит при старте сервера, а также сможет предзагрузить другие файлы, либо через конструкцию include, либо через функцию opcache_compile_file(). Каждая сущность (например, функции и классы), которую определили в этих файлах, будет автоматически доступна для запросов до момента выключения сервера.

  > Замечание: Предварительная загрузка не поддерживается ОС Windows.

`opcache.preload_user` string
  Позволяет запускать предварительную загрузку от имени заданного пользователя системы. Опция полезна для серверов, которые запускаются от имени root-пользователя перед переключением на непривилегированного пользователя системы. По умолчанию предварительная загрузка от имени root запрещена по соображениям безопасности, если только этой директиве явно не установили значение `root`. Начиная с PHP 8.3.0, эту директиву не нужно устанавливать, чтобы разрешить предварительную загрузку при запуске от имени root при использовании CLI SAPI или phpdbg SAPI.
`opcache.cache_id` string

  В системах Windows процессы, которые запускают один и тот же SAPI-интерфейс PHP под одной и той же учётной записью пользователя с тем же идентификатором кеша, делят между собой один экземпляр OPcache. Значение этой опции разрешается задавать произвольно.

  Подсказка

  На IIS-серверах пулы приложений поддерживают способность работать с отдельными экземплярами OPcache. Чтобы разделить кеши, переменную окружения APP_POOL_ID указывают как идентификатор кеша `opcache.cache_id`.

`opcache.jit` string|int
  В обычном режиме параметр принимает одно из четырёх строковых значений:
  - `disable`: Деактивирован, нельзя включить во время выполнения.
  - `off`: Выключен, но разрешается включить во время выполнения.
  - `tracing`/`on`: Включить JIT с компиляцией трассировок. Включён по умолчанию и рекомендуется для большей части пользователей.
  - `function`: Включить JIT с компиляцией функций.

  В продвинутом режиме параметр принимает 4-значное целое число `CRTO`, в котором цифры означают:

  `C` (флаги оптимизации для процессора)
    - `0`: Отключить оптимизацию для ЦП.
    - `1`: Включить набор инструкций AVX, если поддерживается ЦП.
  `R` (распределение регистров)
    - `0`: Не распределять регистры.
    - `1`: Выделять локальный блочный регистр.
    - `2`: Выделять глобальный регистр.
  `T` (триггер)
    - `0`: Компилировать каждую функцию при загрузке скрипта.
    - `1`: Компилировать функций при первом выполнении.
    - `2`: Профилировать функции при первом запросе и компилировать самые горячие функции.
    - `3`: Профилировать на лету и компилировать горячие функции.
    - `4`: Не используется.
    - `5`: Включить JIT с компиляцией трассировок. Профилировать на лету и компилировать трассировки горячих сегментов кода.
  `O` (уровень оптимизации)
    - `0`: Без JIT-компилятора.
    - `1`: Минимальный уровень JIT-компиляции (вызывать стандартные обработчики виртуальной машины).
    - `2`: Вызывать встроенные обработчики виртуальной машины.
    - `3`: Разрешить компилятору делать выводы о типах значений.
    - `4`: Использовать граф вызовов.
    - `5`: Оптимизировать весь скрипт.
  Режим `tracing` соответствует `CRTO = 1254`, Режим `function` соответствует `CRTO = 1205`.
`opcache.jit_buffer_size` int
  Объем разделяемой памяти, который резервируется для скомпилированного JIT-кода. Нулевое значение отключает JIT. Объём измеряется в байтах, если значение параметра указали как целое число (int). Параметр также принимает значения в сокращённой нотации, которую описывает раздел FAQ.
`opcache.jit_debug` int
  Битовая маска, которая определяет, какой вывод JIT-отладки включить. Возможные значения смотрите в файле » zend_jit.h (ищите определения макросов, которые начинаются с префикса `ZEND_JIT_DEBUG`).
`opcache.jit_bisect_limit` int
  Опция отладки, которая отключает JIT-компиляцию после компиляции конкретного количества функций. Опция помогает разделять источник неправильной JIT-компиляции. Примечание: этот параметр работает, только если для JIT-триггера установили значение 0 (компиляция при загрузке скрипта) или 1 (компиляция при первом выполнении), например `opcache.jit=1215`. Подробнее о значениях рассказывает описание опции opcache.jit.
`opcache.jit_prof_threshold` float
  Когда используется режим триггера «профилирование функций при первом запросе» этот порог определяет, считается ли функция горячей. Количество вызовов функции, разделённое на количество вызовов всех функций, должно быть выше порогового значения. Например, пороговое значение 0,005 означает, что функции, которые составляют более 0,5% всех вызовов, будут компилироваться JIT-компилятором.
`opcache.jit_max_root_traces` int
  Максимальное количество корневых стеков вызовов. Корневой стек вызова — поток выполнения, который сначала проходит по одному пути через код, что является единицей JIT-компиляции. JIT не будет компилировать новый код, если достигнет этого предела.
`opcache.jit_max_side_traces` int
  Максимальное количество боковых стеков вызова, которые могут принадлежать корневому стеку. Боковой стек вызова — другой поток выполнения, который не идёт по пути скомпилированного корневого стека вызова. Боковые стеки вызова, которые принадлежат тому же корневому стеку вызова, не будут компилироваться, если достигнут этого предела.
`opcache.jit_max_exit_counters` int
  Максимальное количество счётчиков выхода бокового стека вызова. Опция ограничивает общее количество возможных боковых стеков вызова для всех корневых стеков.
`opcache.jit_hot_loop` int
  После скольких итераций цикл считается горячим. Допустимый диапазон значений: `[0,255]`; для значений за пределами этого диапазона, например `-1` или `256`, будет использоваться значение по умолчанию. Значение `0` отключит трассировку и компиляцию циклов JIT-компилятором.

  > Замечание: Рекомендуется задавать этому параметру простое число, чтобы оно не было кратно числу итераций цикла.

`opcache.jit_hot_func` int
  После скольких вызовов функция считается горячей. Допустимый диапазон значений: `[0,255]`; для значений за пределами этого диапазона, например `-1` или `256`, будет использоваться значение по умолчанию. Значение `0` отключит трассировку и компиляцию функций JIT-компилятором.
`opcache.jit_hot_return` int
  После скольких возвратов возврат считается горячим. Допустимый диапазон значений: `[0,255]`; для значений за пределами этого диапазона, например `-1` или `256`, будет использоваться значение по умолчанию. Значение `0` отключит трассировку и компиляцию возвратов JIT-компилятором.
`opcache.jit_hot_side_exit` int
  После скольких выходов выход из бокового стека вызова считается горячим. Допустимый диапазон значений: `[0,255]`; для значений за пределами этого диапазона, например `-1` или `256`, будет использоваться значение по умолчанию. Значение `0` отключит трассировку и компиляцию боковых выходов JIT-компилятором.
`opcache.jit_blacklist_root_trace` int
  Максимальное количество попыток компиляции корневого стека вызова, прежде чем компилятор занесёт корневой стек в чёрный список.
`opcache.jit_blacklist_side_trace` int
  Максимальное количество попыток компиляции бокового стека вызова, прежде чем компилятор занесёт боковой стек в чёрный список.
`opcache.jit_max_loop_unrolls` int
  Максимальное количество попыток развернуть цикл в боковом пути при попытке достичь корневого пути и закрыть внешний цикл.
`opcache.jit_max_recursive_calls` int
  Максимальное количество развёрнутых циклов рекурсивных вызовов.
`opcache.jit_max_recursive_returns` int
  Максимальное количество развёрнутых циклов рекурсивных возвратов.
`opcache.jit_max_polymorphic_calls` int
  Максимальное количество попыток встроить полиморфные динамические вызовы или вызовы полиморфных методов. Вызовы, которые превышают этот предел, обрабатываются как мегаморфные и не встраиваются.

# Предзагрузка

Начиная с PHP 7.4.0 разрешили настройку PHP на предварительную загрузку скриптов в память модуля opcache при запуске движка. Доступ к функциям, классам, интерфейсам или трейтам (но не константам) в этих файлах станет глобальным для всех запросов; файлы не потребуется включать явно. Предзагрузка повышает удобство и производительность за счёт постоянной доступности кода для очередных запросов, но увеличивает расход памяти. Одновременно с этим, изменения в предзагруженных скриптах вступят в силу только после перезагрузки PHP-процесса, которая очистит скрипты, которые предварительно загрузили. Поэтому предзагрузку скриптов выполняют только в производственном окружении, а не в среде разработки.

Баланс между ростом производительности и расходом памяти зависит от приложения. «Предзагрузка каждого файла» выглядит как простейшая стратегия, но такая стратегия полезна не в каждом сценарии. Предзагрузка полезна, только когда процесс не изменяется от запроса к запросу. Поэтому, хотя предзагрузка и работает в CLI-скрипте при включённом модуле opcache, это бесполезно. Исключение — предварительная загрузка библиотек FFI.

> Замечание: ОС Windows не поддерживает предзагрузку.

Настройка предзагрузки состоит из двух этапов и работает, только если включили модуль opcache. Сначала устанавливают значение для директивы opcache.preload в файле php.ini:

    opcache.preload=preload.php

Файл preload.php — произвольный файл, который запустится один раз при старте сервера в режиме менеджера процессов PHP-FPM, Apache-модуля mod_php и т. д. и загрузит код в постоянную память. На серверах, которые перед переключением на непривилегированного пользователя системы запускаются от имени root-пользователя, или если PHP запускается от имени root, что делать не рекомендуют, пользователя системы для запуска предварительной загрузки указывают в директиве opcache.preload_user. Запуск предварительной загрузки от имени root по умолчанию запрещён. В файле конфигурации PHP устанавливают значение `opcache.preload_user=root`, чтобы явно разрешить такой запуск.

PHP проанализирует и загрузит в постоянную память каждый файл, который указали в выражениях include, include_once, require, require_once или в аргументе функции opcache_compile_file() в скрипте preload.php. В следующем примере загрузится каждый файл с расширением .php в директории src, если файл не содержат в названии части `Test`.

    <?php

    $directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
    $fullTree = new RecursiveIteratorIterator($directory);
    $phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

    foreach ($phpFiles as $key => $file) {
        require_once $file[0];
    }

    ?>

И выражение include, и функция opcache_compile_file() будут работать, но по-разному влияют на обработку кода.

- Выражение include выполнит код в файле, а функция opcache_compile_file() — нет, поэтому только выражение включения файлов поддерживает условное объявление, при котором функции объявляют в блоках if.
- Поскольку выражение include выполняет код, PHP также разберёт и предзагрузит объявления вложенных файлов, которые включили выражением include.
- Функция opcache_compile_file() загружает файлы в произвольном порядке. Даже если в файле a.php определили класс `A`, а в файле b.php класс `B`, который наследует класс `A`, это не изменит порядок загрузки файлов и функция opcache_compile_file() всё равно загрузит файлы в случайном порядке. А выражение include первым обязательно загрузит файл a.php.
- В любом случае, если более поздний скрипт включает файл, который загрузился прежде, то PHP всё равно выполнит содержимое файла, но не переопределит символы, которые в нём определили. Выражение include_once не предотвратит повторное включение файла. Иногда требуется загрузить файл снова, чтобы включить глобальные константы, которые определили в файле, поскольку они не обрабатываются предварительной загрузкой.

Поведение, которое ждут от кода, определяет, какой подход лучше. Для кода, который иначе использовал бы автозагрузчик, функция opcache_compile_file() даёт больше гибкости. С кодом, который иначе загружался бы вручную, часто надёжнее выражение include.

# Функции OPcache

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — Компилирует и кеширует PHP-скрипт без исполнения

### Описание

function opcache_compile_file(string `$filename`): bool

Функция компилирует PHP-скрипт без исполнения и добавляет скрипт в кеш опкодов. Функцию запускают для прогрева кеша после перезапуска веб-сервера: файл предварительно кешируется и включается в следующие запросы.

### Список параметров

`filename`
  Путь к PHP-скрипту.

### Возвращаемые значения

Функция возвращает `true`, если успешно скомпилировала файл `filename`, или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если файл `filename` невозможно загрузить или скомпилировать. Предупреждение подавляют оператором @.

### Смотрите также

- opcache_invalidate() - Аннулирует закешированный скрипт

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — Получает информацию о конфигурации кеша

### Описание

function opcache_get_configuration(): array|false

Функция возвращает настройки конфигурации экземпляра кеша.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив с информацией, включая INI-настройки, чёрный список и версию.

### Ошибки

Функция выдаст ошибку уровня E_WARNING, если настроили директиву `opcache.restrict_api` и текущий путь подпадает под запрет; информацию о состоянии функция не вернёт.

### Смотрите также

- opcache_get_status() - Получает информацию о состоянии кеша

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — Получает информацию о состоянии кеша

### Описание

function opcache_get_status(bool `$include_scripts` = `true`): array|false

Функция возвращает информацию о состоянии экземпляра кеша в памяти. Она не возвращает никакой информации о файловом кеше.

### Список параметров

`include_scripts`
  Включить информацию о состоянии конкретного скрипта.

### Возвращаемые значения

Возвращает массив, опционально содержащий информацию о состоянии конкретного скрипта или `false`, если возникла ошибка.

### Ошибки

Функция выдаст ошибку уровня E_WARNING, если настроили директиву `opcache.restrict_api` и текущий путь подпадает под запрет; информацию о состоянии функция не вернёт.

### Список изменений

Версия | Описание
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` теперь содержит метку времени Unix о том, когда должна быть произведена следующая ревалидация метки времени скриптов, как указано в INI-директиве `opcache.revalidate_freq`.

### Примеры

Пример #1 Пример использования функции opcache_get_status()

    <?php
    var_dump(opcache_get_status());
    ?>

Вывод приведённого примера будет похож на:

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### Смотрите также

- opcache_get_configuration() - Получает информацию о конфигурации кеша

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — Аннулирует закешированный скрипт

### Описание

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

Функция аннулирует закешированный скрипт. Если параметр `force` не задан или задан как `false`, скрипт аннулируется, только если скрипт был модифицирован после помещения в кеш. Функция аннулирует только кеш в памяти, не затрагивая файловый кеш.

### Список параметров

`filename`
  Путь к скрипту.
`force`
  Если установлено как `true`, кеш скрипта будет принудительно аннулирован независимо от того, требуется ли это или нет

### Возвращаемые значения

Возвращает `true`, если кеш опкодов для `filename` аннулирован, либо если аннулировать нечего. В случае, если кеш опкодов отключён, возвращается `false`.

### Смотрите также

- opcache_compile_file() - Компилирует и кеширует PHP-скрипт без исполнения
- opcache_reset() - Сбрасывает содержимое кеша опкодов

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — Проверяет, закеширован ли скрипт в OPCache

### Описание

function opcache_is_script_cached(string `$filename`): bool

Функция проверяет, закеширован ли указанный скрипт в OPCache. Может быть использована для определения, прогрет ли кеш для конкретного скрипта. Функция проверяет только кеш в памяти, не проверяя файловый кеш. Для проверки файлового кеша используйте функцию opcache_is_script_cached_in_file_cache().

### Список параметров

`filename`
  Путь к файлу скрипта.

### Возвращаемые значения

Возвращает `true`, если `filename` закеширован в OPCache в памяти, `false` если нет.

### Смотрите также

- opcache_compile_file() - Компилирует и кеширует PHP-скрипт без исполнения
- opcache_is_script_cached_in_file_cache() - Проверяет, содержится ли скрипт в файловом кеше модуля OPCache

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — Проверяет, содержится ли скрипт в файловом кеше модуля OPCache

### Описание

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

Функция проверяет, закешировался ли PHP-скрипт в файловом кеше модуля OPCache, и упрощает проверку «прогрева» кеша конкретного скрипта. Функция проверяет только кеш файлов, а не кеширование операционного кода в памяти. Кеширование в памяти проверяют функцией opcache_is_script_cached().

### Список параметров

`filename`
  Путь к PHP-скрипту, кеширование которого требуется проверить.

### Возвращаемые значения

Функция возвращает значение `true`, если модуль OPCache закешировал файл с путём `filename`, иначе возвращается значение `false`.

### Смотрите также

- opcache_compile_file() - Компилирует и кеширует PHP-скрипт без исполнения
- opcache_is_script_cached() - Проверяет, закеширован ли скрипт в OPCache

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — Исключает функцию из JIT-компиляции

### Описание

function opcache_jit_blacklist( Closure `$closure` ): void

Функция запрещает JIT-компиляцию конкретной функции при работе JIT в режиме трассировки. Целевую функцию передают в аргументе в виде замыкания Closure.

Внимание

Запрет не затронет части функции, которые JIT уже скомпилировал — такие участки кода продолжат выполняться в скомпилированном виде.

### Список параметров

`closure`
  Функция, которую требуется исключить из JIT-компиляции. В аргументе передают первоклассное callable-значение или анонимную функцию; при передаче последней исключается сама анонимная функция.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример исключения функции из JIT-компиляции функцией opcache_jit_blacklist()

    <?php

    function foo()
    {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }

    opcache_jit_blacklist(foo(...));

    foo();

### Смотрите также

- opcache_invalidate() - Аннулирует закешированный скрипт
- opcache_reset() - Сбрасывает содержимое кеша опкодов

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — Сбрасывает содержимое кеша опкодов

### Описание

function opcache_reset(): bool

Функция сбрасывает весь кеш. После вызова opcache_reset() все скрипты будут заново загружены, скомпилированы и помещены в кеш после их следующего вызова. Функция сбрасывает только кеш в памяти, не затрагивая файловый кеш.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если кеш опкодов был сброшен или `false`, если кеш отключён, ожидается перезапуск или перезапуск выполняется (смотрите opcache_get_status()).

### Смотрите также

- opcache_invalidate() - Аннулирует закешированный скрипт
- opcache_get_status() - Получает информацию о состоянии кеша

## Содержание

- opcache_compile_file — Компилирует и кеширует PHP-скрипт без исполнения
- opcache_get_configuration — Получает информацию о конфигурации кеша
- opcache_get_status — Получает информацию о состоянии кеша
- opcache_invalidate — Аннулирует закешированный скрипт
- opcache_is_script_cached — Проверяет, закеширован ли скрипт в OPCache
- opcache_is_script_cached_in_file_cache — Проверяет, содержится ли скрипт в файловом кеше модуля OPCache
- opcache_jit_blacklist — Исключает функцию из JIT-компиляции
- opcache_reset — Сбрасывает содержимое кеша опкодов

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предзагрузка
- Функции OPcache
  - opcache_compile_file — Компилирует и кеширует PHP-скрипт без исполнения
  - opcache_get_configuration — Получает информацию о конфигурации кеша
  - opcache_get_status — Получает информацию о состоянии кеша
  - opcache_invalidate — Аннулирует закешированный скрипт
  - opcache_is_script_cached — Проверяет, закеширован ли скрипт в OPCache
  - opcache_is_script_cached_in_file_cache — Проверяет, содержится ли скрипт в файловом кеше модуля OPCache
  - opcache_jit_blacklist — Исключает функцию из JIT-компиляции
  - opcache_reset — Сбрасывает содержимое кеша опкодов

# Operator Overloading for Objects

# Введение

This extension defines and implements operator overloading for objects. It allows defining how an object reacts when an operator is used on it.

One example of this is creating a collection type object that has the addition operator overloaded to allow adding elements to the collection or adding two collections together.

Another example is creating an enhanced string class that has the multiplication operator overloaded to allow repeating the string a certain number of times.

# Установка и настройка

## Содержание

- Установка

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/operator.

Windows users can download prebuilt release binaries from the » PECL website.

operator releases are hosted by PECL and the source code by » github.

# Operator Overloading Magic Methods

The operator overloading extension allows you to define how an object reacts to operators. This is done by implementing the following magic methods:

Arithmetic operators:

- `$a::__add($b)`
- `$a::__sub($b)`
- `$a::__mul($b)`
- `$a::__div($b)`
- `$a::__mod($b)`
- `$a::__pow($b)`

Assignment operators:

- `$a::__assign($b)`
- `$a::__assign_add($b)`
- `$a::__assign_sub($b)`
- `$a::__assign_mul($b)`
- `$a::__assign_div($b)`
- `$a::__assign_mod($b)`
- `$a::__assign_pow($b)`
- `$a::__assign_bw_and($b)`
- `$a::__assign_bw_or($b)`
- `$a::__assign_bw_xor($b)`
- `$a::__assign_sl($b)`
- `$a::__assign_sr($b)`
- `$a::__assign_concat($b)`

Bitwise operators:

- `$a::__bw_and($b)`
- `$a::__bw_or($b)`
- `$a::__bw_xor($b)`
- `$a::__bw_not()`
- `$a::__sl($b)`
- `$a::__sr($b)`

Comparison operators:

- `$a::__is_equal($b)`
- `$a::__is_not_equal($b)`
- `$a::__is_identical($b)`
- `$a::__is_not_identical($b)`
- `$a::__is_smaller($b)`
- `$a::__is_smaller_or_equal($b)`
- `$a::__is_greater($b)`
- `$a::__is_greater_or_equal($b)`
- `$a::__spaceship($b)`

Incrementing and decrementing operators:

- `$a::__pre_inc()`
- `$a::__post_inc()`
- `$a::__pre_dec()`
- `$a::__post_dec()`

String operators:

- `$a::__concat($b)`

## Operator Overloading Examples

The following is the class that is used in the testing of the operator overloading extension. It overloads all of the possible operators that can be overloaded for testing.

Пример #1 Complete class for operator overloading

    <?php
    class OperatorOverloading {
        protected mixed $value;

        //region Standard magic methods
        public function __get(string $name)
        {
            return $this->value;
        }

        public function __set(string $name, mixed $value)
        {
            $this->value = $value;
        }

        public function __construct(mixed $init = null)
        {
            $this->value = $init;
        }
        //endregion

        //region Arithmetic Operators
        public function __add(mixed $val): int|float
        {
            return $this->value + $val;
        }

        public function __div(mixed $val): int|float
        {
            return $this->value / $val;
        }

        public function __mod(mixed $val): int
        {
            return $this->value % $val;
        }

        public function __mul(mixed $val): int|float
        {
            return $this->value * $val;
        }

        public function __pow(mixed $val): int|float
        {
            return $this->value ** $val;
        }

        public function __sub(mixed $val): int|float
        {
            return $this->value - $val;
        }
        //endregion

        //region Assignment Operators
        public function __assign(mixed $val): mixed
        {
            return $this->value = $val;
        }

        public function __assign_add(mixed $val): mixed
        {
            return $this->value += $val;
        }

        public function __assign_bw_and(mixed $val): mixed
        {
            return $this->value &= $val;
        }

        public function __assign_bw_or(mixed $val): mixed
        {
            return $this->value |= $val;
        }

        public function __assign_concat(mixed $val): string
        {
            return $this->value .= $val;
        }

        public function __assign_div(mixed $val): mixed
        {
            return $this->value /= $val;
        }

        public function __assign_mod(mixed $val): mixed
        {
            return $this->value %= $val;
        }

        public function __assign_mul(mixed $val): mixed
        {
            return $this->value *= $val;
        }

        public function __assign_pow(mixed $val): mixed
        {
            return $this->value **= $val;
        }

        public function __assign_sl(mixed $val): mixed
        {
            return $this->value <<= $val;
        }

        public function __assign_sr(mixed $val): mixed
        {
            return $this->value >>= $val;
        }

        public function __assign_sub(mixed $val): mixed
        {
            return $this->value -= $val;
        }
        //endregion

        //region Bitwise Operators
        public function __bw_and(mixed $val): int
        {
            return $this->value & $val;
        }

        public function __bw_not(): int|string
        {
            return ~$this->value;
        }

        public function __bw_or(mixed $val): int
        {
            return $this->value | $val;
        }

        public function __bw_xor(mixed $val): int
        {
            return $this->value ^ $val;
        }

        public function __sl(mixed $val): int
        {
            return $this->value << $val;
        }

        public function __sr(mixed $val): int
        {
            return $this->value >> $val;
        }
        //endregion

        //region Comparison Operators
        public function __is_equal(mixed $val): bool
        {
            return $this->value == $val;
        }

        public function __is_greater(mixed $val): bool
        {
            return $this->value > $val;
        }

        public function __is_greater_or_equal(mixed $val): bool
        {
            return $this->value >= $val;
        }

        public function __is_identical(mixed $val): bool
        {
            return $this->value === $val;
        }

        public function __is_not_equal(mixed $val): bool
        {
            return $this->value != $val;
        }

        public function __is_not_identical(mixed $val): bool
        {
            return $this->value !== $val;
        }

        public function __is_smaller(mixed $val): bool
        {
            return $this->value < $val;
        }

        public function __is_smaller_or_equal(mixed $val): bool
        {
            return $this->value <= $val;
        }

        public function __spaceship(mixed $val): int
        {
            return $this->value <=> $val;
        }
        //endregion

        //region Incrementing/Decrementing Operators
        public function __post_dec(): mixed
        {
            return $this->value--;
        }

        public function __post_inc(): mixed
        {
            return $this->value++;
        }

        public function __pre_dec(): mixed
        {
            return --$this->value;
        }

        public function __pre_inc(): mixed
        {
            return ++$this->value;
        }
        //endregion

        //region String Operators
        public function __concat(mixed $val): string
        {
            return $this->value . $val;
        }
        //endregion

    }

Using the above class, you can overload the operators as follows:

    <?php
    $a = new OperatorOverloading(5);
    var_dump($a + 10);
    var_dump($a - 10);
    $b = new OperatorOverloading("Hello");
    var_dump($b . " World");

The above code will output:

    int(15)
    int(-5)
    string(11) "Hello World"

- Установка и настройка
  - Установка
- Operator Overloading Magic Methods

# Управление буфером вывода

# Введение

Функции управления выводом помогают контролировать вывод данных из скрипта. Управление выводом приносит пользу в ряде ситуаций, особенно тогда, когда требуется отправить заголовки в браузер после начала вывода данных скриптом. Функции управления выводом не влияют на заголовки, которые отправили функцией header() или setcookie(), а только на функции вывода наподобие языковой конструкции echo и данные между блоками PHP-кода.

# Установка и настройка

## Содержание

- Настройка во время выполнения

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Конфигурационные опции управления выводом
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
output_buffering | `«0»` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `«0»` | `INI_ALL` |
url_rewriter.tags | `«form=»` | `INI_ALL` | Начиная с PHP 7.1.0 эта INI-настройка влияет только на функцию output_add_rewrite_var(). До PHP 7.1.0 эта INI-настройка включала поддержку прозрачного идентификатора сеанса (смотрите описание директивы session.trans_sid_tags). функцию .
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` задано значением по умолчанию. | `INI_ALL` | Доступно с PHP 7.1.0

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`output_buffering` bool/integer

  Со значением `"On"` директива включает буферизацию вывода для всех файлов. Вместо значения `"On"` директива поддерживает число — количество байтов, которым ограничится размер буфера: `output_buffering=4096`.

`output_handler` string

  PHP поддерживает перенаправление вывода скриптов в функцию. При установке названия функции mb_output_handler() как значения директивы `output_handler` кодировка символов вывода скрипта прозрачно преобразовывается в кодировку, которую указали для вывода. Установка хотя бы одного обработчика вывода автоматически включает буферизацию вывода.

  > Замечание:

  > Нельзя преобразовывать кодировку вывода одновременно функциями mb_output_handler() и ob_iconv_handler(), а функция ob_gzhandler() и директива zlib.output_compression несовместимы ни с одним компонентом из следующего списка: с функциями mb_output_handler() и ob_gzhandler(), с директивой zlib.output_compression, с обработчиком 'URL-Rewriter'. См. также описания директивы session.use_trans_sid и функции output_add_rewrite_var().

  > Замечание:

  > Директива принимает названия только встроенных функций. Пользовательские обработчики вывода устанавливаются при вызове функции ob_start().

`implicit_flush` bool

  Значение по умолчанию — `false`. Изменение значения на `true` указывает PHP не сохранять данные в буфер, а после каждого отправленного блока автоматически отправлять данные в выходной слой. Это эквивалентно вызову PHP-функции flush() после каждого вызова функции вывода (например, print или echo) и каждого `HTML`-блока.

  При работе PHP в веб-окружении директива снижает производительность, поэтому настройку включают только для отладки. При работе через `CLI SAPI` предустановленное значение директивы равно `true`.

  Сморите также описание функции ob_implicit_flush().

`url_rewriter.tags` string
  Директива `url_rewriter.tags` определяет HTML-теги и атрибуты, в которых URL-адреса перезаписываются значениями функции output_add_rewrite_var(). Значение по умолчанию — `«form=»`. Добавление значения `«form=»` или любого атрибута формы (`form`) добавит скрытый элемент `input` к форме (`form`), с артибутом с указанными именем и значением для каждой пары имя-значение, переданной в функцию output_add_rewrite_var().
  Предостережение

  При перезаписи URL-адресов обработается только первое вхождение, если в директиву `url_rewriter.tags` один и тот же тег добавили больше одного раза.

  > Замечание: До PHP 7.1.0 список HTML-тегов, которые теперь определяет директива session.trans_sid_tags, указывали в директиве url_rewriter.tags.

`url_rewriter.hosts` string
  Директива `url_rewriter.hosts` указывает, какие хосты перезаписываются, чтобы включить в них значения функции output_add_rewrite_var(). По умолчанию директиве установлено значение `$_SERVER['HTTP_HOST']`. Разрешено указывать несколько хостов, перечислив их через запятую без пробелов. Например, `«php.net,wiki.php.net,bugs.php.net»`.

# Предопределённые константы

Следующие константы доступны как часть ядра PHP.

Флаги состояния, которые передают обработчику вывода

Следующие флаги передают как часть битовой маски в параметр `phase` — второй параметр обработчика вывода, который установили функцией ob_start():

`PHP_OUTPUT_HANDLER_START` (int)

  Указывает, что буферизация вывода началась.

`PHP_OUTPUT_HANDLER_WRITE` (int)

  Указывает, что буфер вывода очищается и буфер содержит данные для вывода.

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  Означает, что буфер сбросился — очистился и вывелся.

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  Означает, что буфер очистился.

`PHP_OUTPUT_HANDLER_FINAL` (int)

  Означает, что это последняя операция буферизации.

`PHP_OUTPUT_HANDLER_CONT` (int)

  Означает, что буфер очистился, но буферизация вывода продолжится.

  Это синоним для `PHP_OUTPUT_HANDLER_WRITE`.

`PHP_OUTPUT_HANDLER_END` (int)

  Означает, что буферизация вывода завершилась.

  Это синоним для `PHP_OUTPUT_HANDLER_FINAL`.

Флаги управления буфером вывода

Следующие флаги передают в виде битовой маски в параметр `flags` — третий параметр обработчика вывода, который установили функцией ob_start():

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  Определяет, готов ли буфер вывода, который создали функцией ob_start(), к очистке функцией ob_clean(). Это флаг не управляет поведением функций ob_end_clean() или ob_get_clean().

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  Определяет, готов ли буфер вывода, который создали функцией ob_start(), к сбросу — выводу и очистке — функцией ob_flush(). Это флаг не управляет поведением функций ob_end_flush() или ob_get_flush().

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  Определяет, готов ли буфер вывода, который создали функцией ob_start(), к удалению до завершения скрипта или при вызове функций ob_end_clean(), ob_end_flush(), ob_get_clean() или ob_get_flush().

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  Значение по умолчанию для флагов буфера вывода. Равняется `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

Флаги статуса обработчика вывода

Следующие флаги — часть битовой маски ключа `flags` массива, который возвращает функция ob_get_status():

`PHP_OUTPUT_HANDLER_STARTED` (int)

  Означает, что вызвали обработчик вывода.

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  Указывает, что обработчик вывода выключен. Флаг устанавливается, когда обработчик вывода возвращает `false` или возникает ошибка при обработке буфера. До PHP 8.4.0 флаг разрешали устанавливать при запуске буфера вывода.

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  Указывает, что обработчик вывода успешно обработал буфер. Флаг доступен с PHP 8.4.0.

# Буферизация вывода

Буферизация вывода — временное хранение вывода перед сбросом, перед отправкой и удалением, в браузер в веб-контексте или в командную оболочку в контексте командной строки. Пока буферизация вывода активна, вывод из скрипта не отправляется, вместо этого вывод сохраняется во внутреннем буфере.

## Буферизация, которая влияет на PHP

PHP опирается на базовую программно-аппаратную инфраструктуру при сбросе вывода. Буферизация, которую реализуют консоли в командной строке (например, с буферизацией строк) или веб-серверами и браузером в веб-контексте (например, с полной буферизацией), влияет на то, когда вывод отображается конечному пользователю. Часть этих эффектов получится устранить тонкой настройкой параметров сервера и (или) выравниванием размеров буферов на разных уровнях.

## Контроль буферизации вывода в PHP

Разработчики PHP предусмотрели полностью буферизованный пользовательский буфер вывода с функциями для запуска, манипулирования и отключения буфера (бо́льшая часть ob_*-функций), и две функции для сброса базовых системных буферов (функции flush() и ob_implicit_flush()). Часть этой функциональности также устанавливают и (или) конфигурируют в настройках файла php.ini.

## Когда полезна буферизация

Буферизация вывода полезна в ситуациях, в которых буферизованный вывод изменяется или проверяется, или его переиспользуют в запросе; или когда требуется контролируемая очистка выходных данных. Конкретные сценарии работы с буферами включают:

- Кеширование результатов выполнения скриптов, которые требуют сложных вычислений или времени, например при генерации статических `HTML`-страниц
- Переиспользование сгенерированного вывода путём его отображения, сохранения в файл и (или) отправки по электронной почте
- Сброс элемента `head` — заголовка `HTML`-страницы — до отправки элемента `body` — тела страницы, чтобы разрешить браузерам загружать внешние ресурсы, пока скрипт получает доступ к базе данных или файлу, устанавливает внешнее сетевое соединение или решает другие трудоёмкие задачи. Это полезно только тогда, когда `HTTP`-код состояния нельзя изменить после отправки заголовков
- Извлечение информации из функций, которые иначе выдавали бы вывод, как это делает функция phpinfo()
- Управление выводом стороннего кода путём изменения или включения его частей (например, извлечение данных, замена слов или фраз, добавление недостающих `HTML`-тегов), или полного отказа от этого кода при конкретных условиях, например при ошибках
- Полифиллинг недоступной функциональности веб-сервера наподобие сжатия или кодирования вывода

# Сброс (отправка) системных буферов

PHP предлагает два взаимосвязанных способа сброса (отправки и удаления содержимого) системных буферов: один — вызов функции flush(), другой — включение неявного сброса функцией ob_implicit_flush() или директивой implicit_flush в файле php.ini.

## Поведение сброса (отправки) вывода

Когда неявный сброс выключен, PHP будет сбрасывать вывод, только когда вызвана функция flush() или когда скрипт завершил работу.

При включённом неявном сбросе PHP попытается сбросить вывод после каждого блока кода, который выводит данные. Вывод в этом контексте — данные ненулевой длины, которые:

- написали за пределами тегов `<?php ?>`
- выводятся языковыми конструкциями и функциями, явная цель которых заключается в выводе пользовательских переменных или строк, наподобие: echo, print, printf(), var_dump(), var_export(), vprintf()
- выводятся функциями, цель которых состоит в сборе и выводе данных или информации о запущенном скрипте или PHP, наподобие: debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- выводит PHP при неперехваченном исключении или необработанной ошибке (при условии, что включены директивы display_errors и error_reporting)
- записывают в поток `php://output`

> Замечание: Печать пустых строк или отправка заголовков не рассматривается как вывод и не приведёт к операции сброса.

Внимание

Если неявный сброс включён, управляющие символы (например, `«\n»`, `«\r»`, `«\0»`) также вызовут сброс.

## Ограничения

Функции сброса системных буферов не сбрасывают пользовательские буферы вывода. Чтобы использовать системный и пользовательский буферы вместе, пользовательские буферы вывода сбрасывают перед сбросом системных буферов, чтобы PHP вывел данные.

Внимание

Не исключён риск того, что вызов функции flush() или включённый неявный сброс помешает обработчикам пользовательских буферов вывода, устанавливающим и отправляющим заголовки в веб-контексте (например, функция ob_gzhandler()), отправив заголовки до того, как их отправят обработчики.

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

## Различия в сбросе в интерфейсах SAPI

Хотя реализации сброса в каждом интерфейсе SAPI слегка различаются, эти реализации попадают в одну из категорий:

- Интерфейсы SAPI в веб-контексте вначале сбросят заголовки, а затем вывод. К таким SAPI относятся `Apache2Handler`, `CGI`, `FastCGI` и `FPM`
- другие SAPI, например `CLI` и `embed`, только сбросят вывод

# Пользовательские буферы вывода

## Содержание

- Какой вывод буферизуется?
- Вложенные буферы вывода
- Размер буфера
- Операции, разрешённые для буферов
- Обработчики вывода
- Работа с обработчиками вывода
- Флаги, передаваемые обработчикам вывода
- Значения, которые возвращает обработчик вывода

Пользовательские буферы вывода разрешается запускать, манипулировать ими и завершать из PHP-кода. Каждый из этих буферов состоит из буфера вывода и функции-обработчика вывода этого буфера.

## Какой вывод буферизуется?

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

- написали за пределами тегов `<?php ?>`
- выводятся языковыми конструкциями и функциями, явная цель которых заключается в выводе пользовательских переменных или строк, наподобие: echo, print, printf(), var_dump(), var_export(), vprintf()
- выводятся функциями, цель которых состоит в сборе и выводе данных или информации о запущенном скрипте или PHP, наподобие: debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- выводит PHP при неперехваченном исключении или необработанной ошибке (при условии, что включены директивы display_errors и error_reporting)
- записывают в поток `php://output`

> Замечание: Пользовательские буферы вывода не захватывают данные, которые записываются сразу в поток вывода `stdout` или передаются в похожую функцию SAPI-интерфейса. Это включает запись данных в стандартный поток вывода `stdout` функцией fwrite(), или отправку заголовков функциями header() или setcookie().

## Включение буферизации вывода

Буферизацию вывода включают вызовом функции ob_start() или установкой в файле php.ini параметров директивам output_buffering и output_handler. Хотя оба способа умеют создавать буферы вывода, функция ob_start() гибче, поскольку принимает в качестве обработчиков вывода пользовательские функции и умеет задавать операции, разрешенные для буфера (сброс, очистка, удаление). Буферы, которые запустили функцией ob_start(), активируются с той строки, на которой вызвали функцию, тогда как те, которые запустили директивой output_buffering, буферизуют вывод начиная с первой строки скрипта.

PHP также поставляется со встроенным обработчиком вывода `URL-Rewriter`, который запускает свой буфер вывода и разрешает запускать одновременно до двух его экземпляров (один для перезаписи URL-адресов на уровне пользователя и ещё один для поддержки прозрачного идентификатора сессии). Эти буферы запускают вызовом функции output_add_rewrite_var() и (или) включением директивы session.use_trans_sid в файле php.ini.

В модуль `zlib`, который входит в комплект PHP, интегрировали свой буфер вывода, который включают директивой zlib.output_compression в файле php.ini.

> Замечание: Хотя обработчик `URL-Rewriter` и выделяется тем, что разрешает запускать одновременно только до двух своих экземпляров, пользовательские буферы вывода работают с теми же базовыми буферами, которые использует функция ob_start(), а их функциональность реализуется пользовательской функцией обработчика вывода. Поэтому их функциональность в состоянии сымитировать пользовательский код.

## Вложенные буферы вывода

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

Бо́льшая часть функций семейства `ob_*` работает только с активным буфером вывода (который запустили последним), поэтому только активный буфер получится сбросить, очистить или отключить. К функциям, которые работают с другими буферами, относятся — функция ob_list_handlers(), которая возвращает список активных обработчиков вывода, и функция ob_get_status(), которая умеет возвращать информацию только об активном буфере или обо всех буферах.

Вызов функций ob_get_level() или ob_get_status() вернёт уровень вложенности активного буфера вывода.

Предостережение

Функции ob_get_level() и ob_get_status() по-разному оценивают один и тот же уровень вложенности; значение отклонено на единицу. Для функции ob_get_level() первый уровень — это `1`. Тогда как для функции ob_get_status() первый уровень — это `0`.

## Размер буфера

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

За исключением обработчика перезаписи URL-адресов `URL-Rewriter`, размер буферов вывода, если нужно, устанавливают при запуске буфера. Буфер вывода ограничивается только размером доступной языку PHP памяти, если установили значение `0`. Буфер сбросится после каждого блока кода, который даёт вывод ненулевой длины, если установили значение `1`.

Размер буферов вывода получают вызовом функции ob_get_status().

Размеры буферов вывода, которые запустили функцией ob_start(), будут равны целочисленному значению, которое передали во второй параметр функции `chunk_size`. Если параметр не задан, установится значение `0`.

Размеру буфера вывода, который запустила директива output_buffering со значением `«On»`, устанавливается значение 0. Размер буфера будет соответствовать целому числу байтов, которое указали в директиве.

Размеру буфера `URL-Rewriter` установили значение `0`, поэтому размер ограничивается объёмом доступной языку PHP памяти.

Размером буфера вывода модуля `zlib` управляет директива zlib.output_compression в файле php.ini. Размер буфера будет равен `"16K"`, или `16 384` байтам, если для директивы установили значение `"On"`. Размер буфера будет соответствовать целому числу байтов, которое указали в директиве.

## Операции, разрешённые для буферов

Операциями, которые разрешается выполнять буферам, управляют через передачу флагов управления буфером в третий параметр функции ob_start() — `flags`. По умолчанию разрешаются все операции, если параметр не задали. Буфер нельзя будет сбросить, очистить или удалить, если вместо этого задали значение `0`, но содержимое буфера по-прежнему будет доступно.

Флаг `PHP_OUTPUT_HANDLER_CLEANABLE` разрешает функции ob_clean() очищать содержимое буфера.

Внимание

Отсутствие флага `PHP_OUTPUT_HANDLER_CLEANABLE` не помешает функции ob_end_clean() или ob_get_clean() очистить содержимое буфера.

Флаг `PHP_OUTPUT_HANDLER_FLUSHABLE` разрешает функции ob_flush() сбрасывать содержимого буфера.

Внимание

Отсутствие флага `PHP_OUTPUT_HANDLER_FLUSHABLE` не помешает функции ob_end_flush() или ob_get_flush() сбросить содержимое буфера.

Флаг `PHP_OUTPUT_HANDLER_REMOVABLE` разрешает функциям ob_end_clean(), ob_end_flush(), ob_get_clean() и ob_get_flush() отключать буфер.

Флаг `PHP_OUTPUT_HANDLER_STDFLAGS` — комбинация трёх флагов, которая разрешает выполнять с буфером каждую из трёх операций.

## Сброс, доступ и очистка содержимого буфера

Сброс отправляет и удаляет содержимое активного буфера. Буферы вывода сбрасываются, когда размер вывода превышает размер буфера, скрипт завершает работу или вызываются функции ob_flush(), ob_end_flush() или ob_get_flush().

Предостережение

Вызов функций ob_end_flush() или ob_get_flush() отключит активный буфер.

Предостережение

Сброс буферов также сбросит возвращаемое обработчиком вывода значение, которое обработчик вывода умеет изменять, и если так, значение будет отличаться от содержимого буфера. Например, передача в обработчик вывода функции ob_gzhandler() приведёт к сжатию данных вывода и сбросу сжатого вывода.

Содержимое активного буфера получают вызовом функций ob_get_contents(), ob_get_clean() или ob_get_flush().

Если нужен только размер содержимого буфера, функции ob_get_length() или ob_get_status() вернут размер содержимого в байтах.

Предостережение

Вызов функций ob_get_clean() или ob_get_flush() отключит активный буфер после возврата его содержимого.

Содержимое активного буфера очищают вызовом функций ob_clean(), ob_end_clean() или ob_get_clean().

Предостережение

Вызов функций ob_end_clean() или ob_get_clean() отключит активный буфер вывода.

## Отключение буферов

Буферы вывода отключают вызовом функций ob_end_clean(), ob_end_flush(), ob_get_flush() или ob_get_clean().

Внимание

Буферы вывода, которые запустили без флага `PHP_OUTPUT_HANDLER_REMOVABLE`, нельзя отключить, а попытка удалить такие буферы выдаст ошибку уровня `E_NOTICE`.

Каждый буфер вывода, который не закрыли до конца скрипта или вызовом конструкции exit(), сбросит и отключит процесс завершения работы PHP. Буферы сбрасываются и отключаются в порядке, обратном их запуску. Буфер, который запустили последним, будет первым, а буфер, который запустили первым, сбросится и отключится в последнюю очередь.

Предостережение

Пользовательский обработчик вывода активируют, чтобы предотвратить сброс буфера вывода при завершении работы PHP, если сброс содержимого буферов не нужен.

## Обработчики вывода

Обработчики вывода — callable-выражения, которые связаны с буферами вывода, которые запускаются вызовом функций ob_clean(), ob_flush(), ob_end_flush(), ob_get_flush(), ob_end_clean(), ob_get_clean() или при завершении работы PHP.

> Замечание: Процесс завершения работы сбросит возвращаемое значение обработчика.

Если при запуске буфера вывода обработчик не задали или значение равно `null`, активируется внутренний обработчик вывода `default output handler`, который при вызове возвращает неизменённое содержимое буфера. Обработчиками вывода пользуются для возврата измененной версии содержимого буфера и (или) или получения побочных эффектов (например, отправки заголовков).

PHP поставляется с двумя внутренними обработчиками вывода: `default output handler` и `URL-Rewriter` (который интегрировали в собственный буфер вывода и только до двух экземпляров которого разрешается запускать).

Модули, которые входят в комплект PHP, включают четыре дополнительные обработчика вывода: mb_output_handler(), ob_gzhandler(), ob_iconv_handler(), ob_tidyhandler().

## Работа с обработчиками вывода

При вызове обработчикам вывода передаётся содержимое буфера и битовая маска, которая указывает состояние буферизации вывода.

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  Содержимое буфера вывода.
`phase`
  Битовая маска `PHP_OUTPUT_HANDLER_*`-констант .

Внимание

Вызов следующих функций из обработчика вывода вызовет фатальную ошибку: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

> Замечание: Обработчик вывода не запустится вызовом функций ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() или при завершении работы PHP, если установили флаг состояния обработчика `PHP_OUTPUT_HANDLER_DISABLED`. Этот флаг не влияет на вызов функции ob_clean() или ob_flush().

> Замечание: Функция завершения работы на ряде веб-серверов умеет изменять рабочую директорию скрипта, например на сервере Apache или встроенном веб-сервере.

## Флаги, передаваемые обработчикам вывода

Битовая маска, которую передали во второй параметр обработчика вывода — `phase` даёт информацию о вызове обработчика.

> Замечание: В битовую маску разрешается включать больше одного флага, а для проверки того, установлен ли флаг, указывают побитовый оператор `&`.

Внимание

Значение флага `PHP_OUTPUT_HANDLER_WRITE` и его псевдонима `PHP_OUTPUT_HANDLER_CONT` равно `0`, поэтому установили ли значение, определяют только операторами равенства (`==` или `===`).

PHP устанавливает следующие флаги на конкретном этапе жизненного цикла обработчика: `PHP_OUTPUT_HANDLER_START` — при первом вызове обработчика. Флаг `PHP_OUTPUT_HANDLER_FINAL` или его псевдоним `PHP_OUTPUT_HANDLER_END` — при последнем вызове обработчика, т. е. он отключается. PHP также установит этот флаг, когда буферы выключаются процессом завершения работы PHP.

Конкретный вызов обработчика устанавливает следующие флаги: `PHP_OUTPUT_HANDLER_FLUSH` — при запуске обработчика вызовом функции ob_flush(). Флаг `PHP_OUTPUT_HANDLER_WRITE` или его псевдоним `PHP_OUTPUT_HANDLER_CONT` — когда размер содержимого обработчика равен или превышает размер буфера, а обработчик вызвали во время автоматической очистки буфера. Флаг `PHP_OUTPUT_HANDLER_FLUSH` — когда обработчик запустили вызовом функций ob_clean(), ob_end_clean() или ob_get_clean(). При вызове функции ob_end_clean() или ob_get_clean() также устанавливается флаг `PHP_OUTPUT_HANDLER_FINAL`.

> Замечание: При вызове функции ob_end_flush() или ob_get_flush() флаг `PHP_OUTPUT_HANDLER_FINAL` устанавливается, а флаг `PHP_OUTPUT_HANDLER_FLUSH` — нет.

## Значения, которые возвращает обработчик вывода

Значение, которое возвращает обработчик вывода, следует стандартной семантике PHP-типов и внутренне преобразовывается в строку, с двумя исключениями: массивы (array) и логические значения (bool).

Массивы преобразовываются в строку `"Array"`, но предупреждение `Array to string conversion` не срабатывает.

Если обработчик возвращает значение `false`, возвращается содержимое буфера, если возвращает `true`, — пустая строка.

> Замечание: Если обработчик возвращает значение `false` или выбрасывает исключение, PHP устанавливает для обработчика флаг состояния `PHP_OUTPUT_HANDLER_DISABLED`.

## Исключения в обработчиках вывода

Если в обработчике вывода выбрасывается неперехваченное исключение, программа завершается, а процесс завершения работы вызывает обработчик, затем выводится сообщение об ошибке `Uncaught Exception`.

Если в обработчике вывода, который вызвали функцией ob_flush(), ob_end_flush() или ob_get_flush(), выбрасывается неперехваченное исключение, содержимое буфера сбрасывается перед сообщением об ошибке.

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

> Замечание: Если обработчик вывода выбрасывает исключение, PHP устанавливает для обработчика флаг состояния `PHP_OUTPUT_HANDLER_DISABLED`.

## Ошибки в обработчиках вывода

Если в обработчике вывода выдаётся неустранимая ошибка, программа продолжает выполняться.

Если в обработчике, который вызвали функцией ob_flush(), ob_end_flush() или ob_get_flush(), возникает неустранимая ошибка, буфер сбрасывает данные, которые вернул обработчик. Если обработчик возвращает значение `false`, сбрасываются буфер и сообщение об ошибке. Если возвращает другое значение, возвращаемое обработчиком значение сбрасывается, но не сообщение об ошибке.

> Замечание: Если обработчик возвращает значение `false` PHP устанавливает для обработчика флаг состояния `PHP_OUTPUT_HANDLER_DISABLED`.

Если в обработчике вывода возникает фатальная ошибка, программа завершается, а процесс завершения работы вызывает обработчик, затем сбрасывается сообщение об ошибке.

Если в обработчике вывода, который вызвали функцией ob_flush(), ob_end_flush() или ob_get_flush(), возникает фатальная ошибка, содержимое буферов сбрасывается перед сообщением об ошибке.

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

## Вывод обработчиков вывода

При конкретных обстоятельствах выходные данные, которые создаются в обработчике, сбрасываются вместе с содержимым буфера. Этот вывод не добавляется в буфер и не становится строкой, которую возвращает функция ob_get_flush().

Если во время операций сброса (при вызове функций ob_flush(), ob_end_flush(), ob_get_flush() и при завершении работы) возвращаемое значение обработчика равно `false`, содержимое буфера сбрасывается, а затем идёт вывод. Если обработчик не вызывается при завершении работы, то обработчик выбрасывает исключение; вызов конструкции exit() ведёт себя так же.

> Замечание: Если обработчик возвращает значение `false`, PHP устанавливает для обработчика флаг состояния `PHP_OUTPUT_HANDLER_DISABLED`.

## Флаги состояния обработчика вывода

PHP устанавливает флаги состояния обработчика битовой маски флагов (`flags`) буфера каждый раз при вызове обработчика вывода и делает их частью флагов (`flags`), которые возвращает функция ob_get_status(). Если обработчик успешно выполняется и не возвращает значение `false`, PHP устанавливает флаги состояния `PHP_OUTPUT_HANDLER_STARTED` и `PHP_OUTPUT_HANDLER_PROCESSED`. Если обработчик возвращает значение `false` или выбрасывает исключение во время работы, PHP устанавливает флаги состояния `PHP_OUTPUT_HANDLER_STARTED` и `PHP_OUTPUT_HANDLER_DISABLED`.

> Замечание: Обработчик не будет запускаться при вызове функций ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() или при завершении процесса работы PHP, если для обработчика установили значение `PHP_OUTPUT_HANDLER_DISABLED`. До PHP 8.4.0 этот флаг не влиял на вызов функций ob_clean() и ob_flush().

# Примеры

## Содержание

- Основы
- Перезапись вывода

## Основы

Пример #1 Пример контроля вывода

    <?php

    ob_start();
    echo "Привет\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

В приведённом примере вывод языковой конструкции echo будет храниться в буфере вывода до вызова функции ob_end_flush(). Тем временем вызов функции setcookie() успешно сохранится в cookie браузера, не вызывая ошибки (заголовки не получится отправить в браузер, когда данные уже отправлены).

## Перезапись вывода

Начиная с PHP 7.1.0 функции output_add_rewrite_var() и output_reset_rewrite_vars() работают с отдельным буфером вывода, то есть не работают с буфером вывода прозрачной поддержки sid.

Пример #1 Пример перезаписи вывода

    <?php

    // Код работает с PHP 7.1.0, 7.0.10, 5.6.25 и выше.

    // HTTP_HOST — целевой хост по умолчанию. Зададим значение, чтобы код примера заработал.
    $_SERVER['HTTP_HOST'] = 'php.net';

    // Обработчик перезаписи вывода перезаписывает только элемент form. Добавим пару a=href.
    // Теги указываются синтаксисом tag_name=url_attr: img=src,iframe=src.
    // Пробелы между настройками недопустимы.
    // form — тег, в который добавятся скрытые поля input
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // Значения добавятся к URL-адресу и элементу form
    output_add_rewrite_var('test', 'value');
    ?>
    <a href="//php.net/index.php?bug=1234">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post">
     <input type="text" name="title" />
    </form>

Результат выполнения приведённого примера:

    <a href="//php.net/?bug=1234&test=value">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
     <input type="text" name="title" />
    </form>

С PHP 7.1.0 у функций перезаписи вывода появились отдельные INI-настройки — url_rewriter.tags и url_rewriter.hosts.

# Функции контроля вывода

# Смотрите также

Смотрите также header() и setcookie().

# flush

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

flush — Сбрасывает системный буфер вывода

### Описание

function flush(): void

Функция сбрасывает системные буферы записи PHP и серверной части, с которой работает PHP (например: CGI, веб-сервер). В среде командной строки функция flush() попытается сбросить только содержимое буферов, тогда как в веб-контексте сбрасываются заголовки и содержимое буферов.

> Замечание: Функция flush(), возможно, не сумеет переопределить схему буферизации веб-сервера и работа функции не отразится на буферизации на стороне клиента в браузере.

> Замечание: Функция не влияет на обработчики вывода пользовательского уровня, например те, которые запускаются функциями ob_start() или output_add_rewrite_var().

Внимание

Функция flush() может мешать обработчикам вывода, которые устанавливают и отправляют заголовки в веб-контексте (например, функция-обработчик ob_gzhandler()) отправляя заголовки до того, как обработчики смогут это сделать.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | При работе PHP в режиме FastCGI заголовки без тела теперь успешно сбросятся.

### Смотрите также

- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_clean() - Очищает (стирает) содержимое активного буфера вывода
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — Очищает (стирает) содержимое активного буфера вывода

### Описание

function ob_clean(): bool

Функция вызывает обработчик вывода (с флагом `PHP_OUTPUT_HANDLER_CLEAN`), отбрасывает значение, которое вернул обработчик, и очищает (стирает) содержимое активного буфера вывода.

Функция не отключает активный буфер вывода, как это делают функции ob_end_clean() и ob_get_clean().

Функция ob_clean() завершится ошибкой, если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция генерирует ошибку уровня `E_NOTICE`, если возникла ошибка.

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его
- ob_get_clean() - Получает содержимое активного буфера вывода и выключает его
- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода

# ob_end_clean

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

ob_end_clean — Очищает (стирает) содержимое активного буфера вывода и отключает его

### Описание

function ob_end_clean(): bool

Функция вызывает обработчик вывода с флагами `PHP_OUTPUT_HANDLER_CLEAN` и `PHP_OUTPUT_HANDLER_FINAL`, отбрасывает значение, которое вернул обработчик, отбрасывает содержимое активного буфера вывода и отключает его.

Функция ob_end_clean() завершится ошибкой, если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_REMOVABLE`.

Функция ob_end_clean() отбросит содержимое активного буфера вывода, даже если буфер запустили без флага `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция генерирует ошибку уровня `E_NOTICE`, если возникла ошибка.

### Примеры

Следующий пример показывает, как избавиться от содержимого активного буфера вывода:

Пример #1 Пример очистки и отключения активного буфера вывода функцией ob_end_clean()

    <?php

    ob_start();
    echo 'Текст, который не отобразится.';
    ob_end_clean();

    ?>

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_clean() - Очищает (стирает) содержимое активного буфера вывода
- ob_get_clean() - Получает содержимое активного буфера вывода и выключает его
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода

# ob_end_flush

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

ob_end_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода

### Описание

function ob_end_flush(): bool

Функция вызывает обработчик вывода с флагом `PHP_OUTPUT_HANDLER_FINAL`, сбрасывает (отправляет) значение, которое вернул обработчик, отбрасывает содержимое активного буфера вывода и отключает активный буфер.

Функция ob_end_flush() завершится ошибкой, если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_REMOVABLE`.

Функция ob_end_flush() сбросит (отправит) значение, которое вернулось из обработчика вывода, даже если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция генерирует ошибку уровня `E_NOTICE`, если возникла ошибка.

### Примеры

Пример #1 Пример сброса и отключения активного буфера вывода функцией ob_end_flush()

Следующий пример показывает простой способ сброса и завершения всех буферов вывода:

    <?php

    while (@ob_end_flush());

    ?>

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_get_flush() - Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его
- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода

### Описание

function ob_flush(): bool

Функция вызывает обработчик вывода с флагом the `PHP_OUTPUT_HANDLER_FLUSH`, сбрасывает (отправляет) значение, которое вернул обработчик, и отбрасывает содержимое активного буфера вывода.

Функция не отключает активный буфер вывода, как это делают функции ob_end_flush() или ob_get_flush().

Функция ob_flush() завершится ошибкой, если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция генерирует ошибку уровня `E_NOTICE`, если возникла ошибка.

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_get_flush() - Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его
- ob_clean() - Очищает (стирает) содержимое активного буфера вывода

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — Получает содержимое активного буфера вывода и выключает его

### Описание

function ob_get_clean(): string|false

Функция вызывает обработчик вывода с флагами `PHP_OUTPUT_HANDLER_CLEAN` и `PHP_OUTPUT_HANDLER_FINAL`, отбрасывает значение, которое вернул обработчик, возвращает содержимое активного буфера вывода и отключает его.

Функция ob_get_clean() завершится ошибкой, если активный буфер вывода запустили без флага `PHP_OUTPUT_HANDLER_REMOVABLE`.

Функция ob_get_clean() отбросит содержимое активного буфера вывода, даже если буфер запустили без флага `PHP_OUTPUT_HANDLER_CLEANABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает содержимое активного буфера вывода, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция ob_get_clean() вернёт значение `false`, но не выдаст ошибку уровня `E_NOTICE`, если нет активного буфера вывода.

### Ошибки

Функция генерирует ошибку уровня `E_NOTICE`, если возникла ошибка.

### Примеры

Пример #1 Пример получения и отключения активного буфера вывода функцией ob_get_clean()

    <?php

    ob_start();

    echo "Привет, мир!";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);

    ?>

Результат выполнения приведённого примера:

    string(21) "Привет, мир!"

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_clean() - Очищает (стирает) содержимое активного буфера вывода
- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его
- ob_get_flush() - Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его

# ob_get_contents

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

ob_get_contents — Возвращает содержимое буфера вывода

### Описание

function ob_get_contents(): string|false

Получает содержимое буфера без его очистки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция вернёт содержимое буфера вывода или `false`, если буферизация вывода не активирована.

### Примеры

Пример #1 Простой пример использования функции ob_get_contents()

    <?php

    ob_start();

    echo "Привет ";

    $out1 = ob_get_contents();

    echo "Мир";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

Результат выполнения приведённого примера:

    string(6) "Привет "
    string(11) "Привет Мир"

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_length() - Возвращает размер буфера вывода

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его

### Описание

function ob_get_flush(): string|false

Функция вызывает обработчик вывода (с флагом `PHP_OUTPUT_HANDLER_FINAL`), сбрасывает (отправляет) возвращённое им значение, возвращает содержимое активного буфера вывода и отключает активный буфер вывода.

Функция ob_get_flush() завершится неудачно, если активный буфер вывода был запущен без флага `PHP_OUTPUT_HANDLER_REMOVABLE`.

Функция ob_get_flush() сбросит (отправит) возвращённое обработчиком вывода значение, даже если активный буфер вывода был запущен без флага `PHP_OUTPUT_HANDLER_FLUSHABLE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает содержимое активного буфера вывода в случае успешного выполнения или `false` в случае возникновения ошибки.

### Ошибки

Если функция завершается неудачно, она выдаёт ошибку уровня `E_NOTICE`.

### Примеры

Пример #1 Пример использования функции ob_get_flush()

    <?php

    // Включена директива буфера вывода: output_buffering=On
    print_r(ob_list_handlers());

    // Сохранить буфер в файл
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_get_clean() - Получает содержимое активного буфера вывода и выключает его

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — Возвращает размер буфера вывода

### Описание

function ob_get_length(): int|false

Вернёт размер в байтах содержимого в буфере вывода.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер в байтах содержимого буфера вывода или `false`, если буферизация не активна.

### Примеры

Пример #1 Простой пример использования функции ob_get_length()

    <?php

    ob_start();

    echo "Привет ";

    $len1 = ob_get_length();

    echo "Мир";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", " . $len2;
    ?>

Результат выполнения приведённого примера:

    13, 19

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_contents() - Возвращает содержимое буфера вывода

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — Возвращает уровень вложенности механизма буферизации вывода

### Описание

function ob_get_level(): int

Возвращает уровень вложенности механизма буферизации вывода.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает уровень вложенности обработчиков буферизации вывода или 0, если буферизация не активна.

Предостережение

Функции ob_get_level() и ob_get_status() по-разному оценивают один и тот же уровень вложенности; значение отклонено на единицу. Для функции ob_get_level() первый уровень — это `1`. Тогда как для функции ob_get_status() первый уровень — это `0`.

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_get_status() - Получает статус буфера вывода
- ob_get_contents() - Возвращает содержимое буфера вывода

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — Получает статус буфера вывода

### Описание

function ob_get_status(bool `$full_status` = `false`): array

Функция ob_get_status() возвращает информацию о состоянии буфера верхнего уровня или на всех уровнях активных буферов, если параметр `full_status` установлен в `true`.

### Список параметров

`full_status`

  Если `true`, то вернёт все уровни активных буферов. Если `false` или не установлен, то вернёт статус только самого верхнего уровня.

### Возвращаемые значения

Если параметр `full_status` опущен или равен `false`, возвращает простой массив с информацией о статусе активного уровня вывода.

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

Возвращает пустой массив, если буферизация вывода не была включена.

Элементы массива, которые возвращает функция ob_get_status()
Key | Value
--- | ---
name | Имя активного обработчика вывода (подробнее об этом рассказано в описании возвращаемых значений функции ob_list_handlers()).
type | `0` (внутренний обработчик) или `1` (предоставленный пользователем обработчик)
flags | Битовая маска флагов, заданных в функции ob_start(), тип обработчика вывода (см. выше) и статус процесса буферизации (константы `PHP_OUTPUT_HANDLER_*` ). Если обработчик успешно обработал буфер и не вернул `false`, будут установлены значения констант `PHP_OUTPUT_HANDLER_STARTED` и `PHP_OUTPUT_HANDLER_PROCESSED`. Если обработчик не смог обработать буфер или вернул `false`, будут установлены значения констант `PHP_OUTPUT_HANDLER_STARTED` и `PHP_OUTPUT_HANDLER_DISABLED`.
level | Уровень вложенности вывода (начинается с нуля). Заметьте, что значение, возвращаемое функцией ob_get_level() для того же уровня, больше на единицу. Первый уровень для функции ob_get_status() — это `0`, а для функции ob_get_level() — это `1`.
chunk_size | Размер части в байтах. Значение, устанавленное в функции ob_start(), или значение настройки output_buffering, если она включена и её значение установлено как целое положительное число.
buffer_size | Размер буфера вывода в байтах.
buffer_used | Размер данных буфера вывода в байтах (то же, что и возвращаемое функцией ob_get_length() целочисленное значение).

### Примеры

Пример #1 Массив, который будет возвращён, если значение параметра `full_status` равно `false`

    Array
    (
        [name] => URL-Rewriter
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

Пример #2 Массив, который будет возвращён, если значение параметра `full_status` равно `true`

    Array
    (
        [0] => Array
            (
                [name] => default output handler
                [type] => 0
                [flags] => 112
                [level] => 1
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 2048
            )

        [1] => Array
            (
                [name] => URL-Rewriter
                [type] => 0
                [flags] => 112
                [level] => 2
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 1024
            )

    )

### Смотрите также

- ob_get_level() - Возвращает уровень вложенности механизма буферизации вывода
- ob_list_handlers() - Возвращает список активных обработчиков вывода
- ob_get_length() - Возвращает размер буфера вывода
- ob_start() - Включает буферизацию вывода

# ob_implicit_flush

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

ob_implicit_flush — Включает или выключает неявный сброс буфера вывода

### Описание

function ob_implicit_flush(bool `$enable` = `true`): void

Функция ob_implicit_flush() включает или выключает неявный сброс буфера вывода. Неявный сброс приведёт к операции сброса после каждого блока кода, который выводит данные, поэтому явные вызовы функции flush() больше не потребуются.

> Замечание: PHP не рассматривает печать пустых строк или отправку заголовков как вывод и не сбрасывает буфер в вывод.

> Замечание: Функция не влияет на обработчики вывода пользовательского уровня наподобие тех, которые запускаются функцией ob_start() или output_add_rewrite_var().

### Список параметров

`enable`

  Значение `true` включает неявный сброс, а значение `false` — отключает.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `enable` теперь принимает значение с типом bool; раньше принималось значение с типом int.

### Смотрите также

- flush() - Сбрасывает системный буфер вывода
- ob_start() - Включает буферизацию вывода
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — Возвращает список активных обработчиков вывода

### Описание

function ob_list_handlers(): array

Выводит список активных обработчиков вывода.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив со списком активных обработчиков вывода, если есть.

Возвращает строку `"default output handler"`, если настройка output_buffering включена и настройка output_handler не установлена, или в функцию ob_start() не передана callback-функция или вместо неё передано значение `null`. Включение настройки output_buffering и установка значения для настройки output_handler эквивалентно передаче в функцию ob_start() внутренней (встроенной) функции.

Возвращает абсолютное имя переданной в параметр callable функции, если в параметр callable функции ob_start() была передана callback-функция. Возвращает абсолютное имя объекта с методом __invoke(), если параметр callable — это объект, который реализует метод __invoke(). Возвращает строку `"Closure::__invoke"`, если параметр callable — это объект класса Closure.

### Примеры

Пример #1 Пример использования функции ob_list_handlers()

    <?php
    // настройка включена output_buffering=On, значение для настройки output_handler не установлено
    var_dump(ob_list_handlers());
    ob_end_flush();

    // callback-функция не передана или null
    ob_start();
    var_dump(ob_list_handlers());
    ob_end_flush();

    // анонимная функция
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // стрелочная функция
    ob_start(fn($string) => $string);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // callback-функция как объект первого класса
    $firstClassCallable = userDefinedFunction(...);

    ob_start([$firstClassCallable, '__invoke']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // внутренняя (встроенная функция)
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // пользовательская функция
    function userDefinedFunction($string, $flags) { return $string; };

    ob_start('userDefinedFunction');
    var_dump(ob_list_handlers());
    ob_end_flush();

    class MyClass {
        public static function staticHandle($string) {
            return $string;
        }

        public static function handle($string) {
            return $string;
        }

        public function __invoke($string) {
            return $string;
        }
    }

    // класс и статический метод
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // объект и нестатический метод
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // объект вызываемого класса
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

Результат выполнения приведённого примера:

    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(7) "print_r"
    }
    array(1) {
      [0]=>
      string(19) "userDefinedFunction"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(21) "MyClass::staticHandle"
    }
    array(1) {
      [0]=>
      string(15) "MyClass::handle"
    }
    array(1) {
      [0]=>
      string(17) "MyClass::__invoke"
    }

### Смотрите также

- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_get_flush() - Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его
- ob_start() - Включает буферизацию вывода

# ob_start

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

ob_start — Включает буферизацию вывода

### Описание

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Функция включает буферизацию вывода. Пока буферизация вывода активна, вывод из скрипта не отправляется, вместо этого вывод сохраняется во внутреннем буфере. Раздел «Какой вывод буферизуется?» рассказывает, на какой именно вывод это влияет.

Буферы вывода помещаются в стек, поэтому функцию ob_start() разрешается вызывать при другом активном буфере. Если активировали несколько буферов вывода, вывод фильтруется последовательно через каждый из буферов в порядке вложенности. Подробнее об этом рассказывает раздел «Вложенные буферы вывода».

Подробное описание буферов вывода даёт раздел «Пользовательские буферы вывода».

### Список параметров

`callback`

  Параметр `callback` принимает необязательный аргумент с типом callable. Когда требуется, чтобы при вызове с аргументами функция не вызывала callback-функцию, в параметр передают значение `null`.

  Функция, которую передали в параметр `callback`, вызывается при вызове функций сброса (отправки) или очистки буфера вывода, или при сбросе буфера вывода в конце скрипта.

  Сигнатура `callback`-функции:

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    Содержимое буфера вывода.
  `phase`
    Битовая маска из семейства констант `PHP_OUTPUT_HANDLER_*` . Подробнее о флагах рассказывает раздел «Флаги, передаваемые обработчикам вывода».

  Если параметр `callback` вернёт `false`, возвращается содержимое буфера. Подробнее об этом рассказывает раздел «Значения, которые возвращает обработчик вывода».

  Внимание

  Вызов любой из следующих функций из обработчика вывода выдаст фатальную ошибку: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

  Подробнее о `callback`-функциях (обработчиках вывода) рассказывают разделы «Обработчики вывода» и «Работа с обработчиками вывода».

`chunk_size`

  При установке необязательного параметра `chunk_size` буфер сбрасываться после каждого блока кода, размер буфера которого достиг или превысил значение параметра `chunk_size`. Значение по умолчанию `0` означает, что вывод буферизуется до тех пор, пока буфер не выключится. Подробнее об этом рассказывает раздел «Размер буфера».

`flags`

  Параметр `flags` — битовая маска, которая управляет операциями с буфером вывода. По умолчанию разрешаются очистка, сброс и удаление буферов вывода, что явно устанавливается флагами управления буфером . Подробнее об этом рассказывает раздел «Операции, разрешённые для буферов».

  Каждый флаг управляет доступом к набору функций, как описывает таблица:

  Константа | Функции
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean()
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_flush()
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush()

  > Замечание: До PHP 8.4.0 через параметр flags также устанавливали флаги статуса обработчика вывода.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример пользовательской callback-функции

    <?php

    function callback($buffer)
    {
        // Заменить каждое яблоко апельсином
        return (str_replace("яблоки", "апельсины", $buffer));
    }

    ob_start("callback");

    ?>
    <html>
    <body>
    <p>Это всё равно, что сравнить яблоки и апельсины.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

Результат выполнения приведённого примера:

    <html>
    <body>
    <p>Это всё равно, что сравнить апельсины и апельсины.</p>
    </body>
    </html>

Пример #2 Пример нестираемого буфера вывода

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### Смотрите также

- ob_get_contents() - Возвращает содержимое буфера вывода
- ob_end_clean() - Очищает (стирает) содержимое активного буфера вывода и отключает его
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_implicit_flush() - Включает или выключает неявный сброс буфера вывода
- ob_gzhandler() - Сжимает буфер вывода в формат gzip как callback-функция функции ob_start
- ob_iconv_handler() - Преобразовывает символы из текущей кодировки в кодировку выходного буфера
- mb_output_handler() - Преобразовывает кодировку символов в буфере вывода, выступая в роли callback-функции
- ob_tidyhandler() - Функция обратного вызова ob_start для восстановление буфера

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — Добавляет значения в обработчик перезаписи URL-адресов

### Описание

function output_add_rewrite_var(string `$name`, string `$value`): bool

Функция запускает обработчик буфера вывода `'URL-Rewriter'`, если он не активен, сохраняет значения параметров `name` и `value`, и когда буфер сбрасывается, перезаписывает URL-адреса и формы на основе пригодных ini-настроек. Очередные вызовы функции сохраняют каждую дополнительную пару из имени и значения до тех пор, пока обработчик не отключится.

Когда буфер вывода сбрасывается (вызовом функций ob_flush(), ob_end_flush(), ob_get_flush() или в конце работы скрипта), обработчик `'URL-Rewriter'` добавляет в атрибуты HTML-тегов пары из имени и значения как параметры запроса для URL-адресов и скрытые поля на основе значений директив конфигурации url_rewriter.tags и url_rewriter.hosts в формы.

Каждая пара имени и значения, которую добавили в обработчик `'URL-Rewriter'`, добавится в URL-адреса и (или) формы, даже если это задублирует URL-параметры запроса или элементы с одинаковыми названиями атрибутов.

> Замечание: После отключения обработчика `'URL-Rewriter'` его невозможно запустить снова.

Внимание

До PHP 8.4.0 хосты для перезаписи задавали через директиву session.trans_sid_hosts, а не url_rewriter.hosts.

### Список параметров

`name`

  Имя параметра.

`value`

  Значение параметра.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Начиная с PHP 7.1.0 функция работает с выделенным буфером вывода, директива url_rewriter.tags учитывается только при работе с функциями вывода, а директива url_rewriter.hosts доступна. До PHP 7.1.0 переменные перезаписи, которые установили функцией output_add_rewrite_var(), работали с общим буфером вывода с поддержкой прозрачного идентификатора сессии. Смотрите описание директивы session.trans_sid_tags.

### Примеры

Пример #1 Пример добавления значения в обработчик перезаписи URL-адресов функцией output_add_rewrite_var()

    <?php

    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // Ссылки
    echo '<a href="file.php">ссылка</a>
    <a href="http://example.com">ссылка2</a>';

    // Форма
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());

Результат выполнения приведённого примера:

    <a href="file.php?var=value">ссылка</a>
    <a href="http://example.com">ссылка2</a>

    <form action="script.php" method="post">
    <input type="hidden" name="var" value="value" />
    <input type="text" name="var2" />
    </form>

    Array
    (
        [0] => URL-Rewriter
    )

### Смотрите также

- output_reset_rewrite_vars() - Сбросить значения обработчика URL
- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_list_handlers() - Возвращает список активных обработчиков вывода
- url_rewriter.tags
- url_rewriter.hosts

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — Сбросить значения обработчика URL

### Описание

function output_reset_rewrite_vars(): bool

Функция удаляет все переменные перезаписи, ранее установленные функцией output_add_rewrite_var().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | До PHP 7.1.0, переменные перезаписи установленные функцией output_add_rewrite_var() используют тот же буфер модуля сессии "trans sid". С PHP 7.1.0, используется отдельный буфер и output_reset_rewrite_vars() только удаляет переменные перезаписи определённые output_add_rewrite_var().

### Примеры

Пример #1 Пример использования функции output_reset_rewrite_vars()

    <?php

    ini_set('url_rewriter.tags', 'a=href');

    output_add_rewrite_var('var', 'value');

    echo '<a href="file.php">ссылка</a>';
    ob_flush();

    output_reset_rewrite_vars();
    echo '<a href="file.php">ссылка</a>';
    ?>

Результат выполнения приведённого примера:

    <a href="file.php?var=value">ссылка</a>
    <a href="file.php">ссылка</a>

### Смотрите также

- output_add_rewrite_var() - Добавляет значения в обработчик перезаписи URL-адресов
- ob_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_list_handlers() - Возвращает список активных обработчиков вывода
- url_rewriter.tags
- url_rewriter.hosts
- session.trans_sid_tags
- session.trans_sid_hosts

## Содержание

- flush — Сбрасывает системный буфер вывода
- ob_clean — Очищает (стирает) содержимое активного буфера вывода
- ob_end_clean — Очищает (стирает) содержимое активного буфера вывода и отключает его
- ob_end_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
- ob_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
- ob_get_clean — Получает содержимое активного буфера вывода и выключает его
- ob_get_contents — Возвращает содержимое буфера вывода
- ob_get_flush — Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его
- ob_get_length — Возвращает размер буфера вывода
- ob_get_level — Возвращает уровень вложенности механизма буферизации вывода
- ob_get_status — Получает статус буфера вывода
- ob_implicit_flush — Включает или выключает неявный сброс буфера вывода
- ob_list_handlers — Возвращает список активных обработчиков вывода
- ob_start — Включает буферизацию вывода
- output_add_rewrite_var — Добавляет значения в обработчик перезаписи URL-адресов
- output_reset_rewrite_vars — Сбросить значения обработчика URL

- Установка и настройка
  - Настройка во время выполнения
- Предопределённые константы
- Буферизация вывода
- Сброс (отправка) системных буферов
- Пользовательские буферы вывода
  - Какой вывод буферизуется?
  - Вложенные буферы вывода
  - Размер буфера
  - Операции, разрешённые для буферов
  - Обработчики вывода
  - Работа с обработчиками вывода
  - Флаги, передаваемые обработчикам вывода
  - Значения, которые возвращает обработчик вывода
- Примеры
  - Основы
  - Перезапись вывода
- Функции контроля вывода
  - flush — Сбрасывает системный буфер вывода
  - ob_clean — Очищает (стирает) содержимое активного буфера вывода
  - ob_end_clean — Очищает (стирает) содержимое активного буфера вывода и отключает его
  - ob_end_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода
  - ob_flush — Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода
  - ob_get_clean — Получает содержимое активного буфера вывода и выключает его
  - ob_get_contents — Возвращает содержимое буфера вывода
  - ob_get_flush — Сбрасывает (отправляет) возвращённое активным обработчиком вывода значение, возвращает содержимое активного буфера вывода и отключает его
  - ob_get_length — Возвращает размер буфера вывода
  - ob_get_level — Возвращает уровень вложенности механизма буферизации вывода
  - ob_get_status — Получает статус буфера вывода
  - ob_implicit_flush — Включает или выключает неявный сброс буфера вывода
  - ob_list_handlers — Возвращает список активных обработчиков вывода
  - ob_start — Включает буферизацию вывода
  - output_add_rewrite_var — Добавляет значения в обработчик перезаписи URL-адресов
  - output_reset_rewrite_vars — Сбросить значения обработчика URL

# Опции и информация PHP

# Введение

Эти функции позволяют вам получить множество информации о самом PHP, например, установки конфигурации, загруженные модули, версию и многое другое. Вы так же найдёте функции для установки параметров работы PHP. Вероятно, самую известную функцию в PHP - phpinfo() - можно найти здесь.

# Установка и настройка

## Содержание

- Настройка во время выполнения

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Настройки PHP/Параметры конфигурации информации
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | Устарело с PHP 8.3.0
assert.bail | "0" | `INI_ALL` | Устарело с PHP 8.3.0
assert.warning | "1" | `INI_ALL` | Устарело с PHP 8.3.0
assert.callback | NULL | `INI_ALL` | Устарело с PHP 8.3.0
assert.quiet_eval | "0" | `INI_ALL` | Удалено в PHP 8.0.0
assert.exception | "1" | `INI_ALL` | До PHP 8.0.0 значение по умолчанию было `"0"`. Устарело с PHP 8.3.0
enable_dl | "1" | `INI_SYSTEM` | Функция устарела и ее удалят в будущем.
max_execution_time | "30" | `INI_ALL` |
max_input_time | "-1" | `INI_PERDIR` |
max_input_nesting_level | "64" | `INI_PERDIR` |
max_input_vars | 1000 | `INI_PERDIR` |
zend.enable_gc | "1" | `INI_ALL` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | Доступна с PHP 8.3.0.
zend.reserved_stack_size | "0" | `INI_SYSTEM` | Доступна с PHP 8.3.0.
fiber.stack_size |  | `INI_ALL` | Доступна с PHP 8.1.0.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`assert.active` bool

  Включение выполнение assert(). zend.assertions следует использовать вместо этого для управления поведением функции assert().

  Внимание

  Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

`assert.bail` bool

  Завершение работы скрипта при провале проверки утверждений.

  Внимание

  Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

`assert.warning` bool

  Вызов предупреждений PHP для каждой проваленной проверки утверждения.

  Внимание

  Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

`assert.callback` string

  Пользовательская функция, вызываемая при провале проверки утверждений.

`assert.quiet_eval` bool
  Внимание

  В PHP 8.0.0 функциональность УДАЛИЛИ.

  Используйте эту настройку функции error_reporting() во время выполнения проверки утверждений. При включении настройки сообщения об ошибках во время проверки утверждений показываться не будут (неявный вызов error_reporting(0)). Если настройка выключена, ошибки будут выдаваться в соответствии с настройками error_reporting()

`assert.exception` bool

  Выбрасывает исключение AssertionError в случае неудачной проверки утверждения.

  Внимание

  Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

`enable_dl` bool

  Директива позволяет включать и выключать динамическую подгрузку модулей PHP с помощью функции dl().

  Главной причиной, по которой требуется выключение динамической загрузки, является безопасность. С помощью динамической загрузки можно обойти все open_basedir ограничения. По умолчанию динамическая загрузка разрешена.

`max_execution_time` int

  Эта директива задаёт максимальное время в секундах, в течение которого скрипт должен полностью загрузиться. Если этого не происходит, парсер завершает работу скрипта. Этот механизм помогает предотвратить зависание сервера из-за плохо написанного скрипта. По умолчанию на загрузку даётся `30` секунд. Если PHP запущен из командной строки, это значение по умолчанию равно `0`.

  В системах, отличных от Windows, на максимальное время выполнения не влияют системные вызовы, потоковые операции и т.п. За дополнительной информацией обращайтесь к документации к функции set_time_limit().

  Веб-серверы обычно имеют свои настройки времени ожидания, по превышении которого сами завершают выполнение скрипта PHP. В Apache есть директива `Timeout`, в IIS есть функция CGI timeout. В обоих случаях по умолчанию установлено 300 секунд. Точные значения можно узнать из документации к веб-серверу.

`max_input_time` int

  Эта директива задаёт максимальное время в секундах, в течение которого скрипт должен разобрать все входные данные, переданные запросами вроде POST или GET. Это время измеряется от момента, когда PHP вызван на сервере до момента, когда скрипт начинает выполняться. Значение по умолчанию `-1`, что означает, что будет использоваться max_execution_time. Если установить равным `0`, то ограничений по времени не будет.

`max_input_nesting_level` int

  Задаёт максимальную глубину вложенности входных переменных (то есть $_GET, $_POST.)

`max_input_vars` int

  Сколько входных переменных может быть принято в одном запросе (ограничение накладывается на каждую из глобальных переменных $_GET, $_POST и $_COOKIE отдельно). Использование этой директивы снижает вероятность сбоев в случае атак с использованием хеш-коллизий. Если входных переменных больше, чем задано директивой, выбрасывается предупреждение `E_WARNING`, а все последующие переменные в запросе игнорируются.

`zend.enable_gc` bool

  Включает или отключает сборщик циклических ссылок.

`zend.max_allowed_stack_size` int

  Максимальное пространство стека, которое операционная система позволяет занимать программе. Попытка занять больше места, чем позволяет операционная система, обычно приводит к жёсткому аварийному завершению работы, при этом отладочная информация будет недоступна. Чтобы облегчить отладку, движок выбрасывает ошибку Error до того, как это произойдёт (когда программа использует более zend.max_allowed_stack_size-zend.reserved_stack_size байт стека).

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

  Для этого параметра возможны следующие значения:

  - `0`: Автоматическое определение максимального пространства стека, которое операционная система позволяет занимать программе. Значение используется по умолчанию. Если определение невозможно, используется известное системное значение по умолчанию.
  - `-1`: Отключает проверку размера стека в движке.
  - Положительное целое число: Фиксированный размер в байтах. Слишком большое значение приведёт к тому же, что и отключение проверки размера стека.

  Поскольку размер стека файберов определяется значением fiber.stack_size, значение этого параметра используется вместо zend.max_allowed_stack_size при проверке использования стека во время выполнения файбера.

  > Замечание:

  > Это не связано с переполнениями стека буфера и не является функцией безопасности.

`zend.reserved_stack_size` int

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

  Для этого параметра возможны следующие значения:

  - `0`: Автоматическое определение разумного размера.
  - Положительное целое число: Фиксированный размер в байтах.
`fiber.stack_size` int

  Размер стека в байтах, выделенный для каждого файбера.

  Значение по умолчанию - 1 Мбайт на системах с размером указателя менее 8 байт или 2 Мбайт в противном случае.

# Предопределённые константы

Следующие константы доступны как часть ядра PHP.

Константы | Описание
--- | ---
Предопределённые константы функции phpcredits()
`CREDITS_GROUP` (int) | Список разработчиков ядра PHP.
`CREDITS_GENERAL` (int) | Главные разработчики: дизайн и концепции языка, авторы PHP и модуля SAPI.
`CREDITS_SAPI` (int) | Список модулей серверного API для PHP и их авторы.
`CREDITS_MODULES` (int) | Список модулей для PHP и их авторы.
`CREDITS_DOCS` (int) | Члены команды разработчиков документации.
`CREDITS_FULLPAGE` (int) | Часто указывают в сочетании с другими флагами. Константа указывает, что требуется вывести полную отдельную HTML-страницу вместе с информацией других флагов.
`CREDITS_QA` (int) | Члены команды контроля качества.
`CREDITS_ALL` (int) | Все разработчики, аналогично значению: `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`. Будет сгенерирована HTML-страница с заданными тегами. Это значение по умолчанию.

Константы | Описание
--- | ---
phpinfo() constants
`INFO_GENERAL` (int) | Строка конфигурации, расположение файла php.ini, дата сборки, веб-сервер, система и другая информация.
`INFO_CREDITS` (int) | Разработчики языка PHP. Смотрите также описание функции phpcredits().
`INFO_CONFIGURATION` (int) | Текущие локальные и основные значения PHP-директив. Смотрите также описание функции ini_get().
`INFO_MODULES` (int) | Загруженные модули и их настройки.
`INFO_ENVIRONMENT` (int) | Информация о переменных среды, которая также доступна в суперглобальном массиве $_ENV.
`INFO_VARIABLES` (int) | Показывает каждую предопределённую переменную из группы суперглобальных переменных, которые содержит аббревиатура `EGPCS`: Environment, GET, POST, Cookie, Server.
`INFO_LICENSE` (int) | Информация о лицензии PHP. Смотрите также «» FAQ по лицензии ».
`INFO_ALL` (int) | Константа показывает всю информацию приведённого списка и играет роль значения по умолчанию.

Константы | Описание
--- | ---
Константы INI-режима
`INI_USER` (int) | Запись разрешается устанавливать в пользовательском скрипте (например, функцией ini_set()) или в реестре Windows. Запись разрешается устанавливать в файле .user.ini
`INI_PERDIR` (int) | Запись разрешается устанавливать в файлах php.ini, .htaccess, httpd.conf или .user.ini.
`INI_SYSTEM` (int) | Запись разрешается устанавливать в файле php.ini или httpd.conf.
`INI_ALL` (int) | Запись разрешается устанавливать где угодно.

Константы проверки утверждений. Значения констант передают в функцию функции assert_options(), чтобы установить параметры проверки утверждений.

Константы | Описание
--- | ---
assert() constants
`ASSERT_ACTIVE` (int) | Включает оценку утверждения, которую выполняет функция assert(). Внимание Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
`ASSERT_CALLBACK` (int) | Callback-функция, которая вызывается, если утверждение не прошло проверку. Внимание Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
`ASSERT_BAIL` (int) | Прерывает выполнение, если утверждение не прошло проверку. Внимание Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
`ASSERT_EXCEPTION` (int) | Указывает, выбрасывать ли исключение AssertionError для каждого утверждения, которое не прошло проверку. Внимание Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
`ASSERT_WARNING` (int) | Указывает, выдавать ли PHP-предупреждение для каждого утверждения, которое не прошло проверку. Внимание Начиная с PHP 8.3.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.
`ASSERT_QUIET_EVAL` (int) | Отключает сообщения об ошибках, уровень которых устанавливают в директиве `error_reporting`, во время проверки выражения утверждения. Внимание В PHP 8.0.0 функциональность УДАЛИЛИ.

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

Константы | Описание
--- | ---
Константы для Windows
`PHP_WINDOWS_VERSION_MAJOR` (int) | Мажорная версия ОС Windows в виде значения `4` для версий NT4, Me, 98 и 95, значения `5` для версий XP, 2003 R2, 2003 и 2000 или значения `6` для версий Vista, 2008, 7, 8 и 8.1.
`PHP_WINDOWS_VERSION_MINOR` (int) | Минорная версия ОС Windows в виде значения `0` для версий Vista, 2008, 2000, NT4 и 95, значения `1` для XP, значения `2` для версий 2003 R2, 2003 и XP x64, значения `10` для 98 или значения `90` для версии ME.
`PHP_WINDOWS_VERSION_BUILD` (int) | Номер сборки Windows (например, у Windows Vista с пакетом обновления SP1 — сборка 6001).
`PHP_WINDOWS_VERSION_PLATFORM` (int) | Платформа, на которой работает PHP, в виде значения `2` для ОС Windows Vista, XP, 2000 и NT4, Server 2008 и 2003, а на Windows ME, 98 и 95 — значения `1`.
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | Мажорная версия установленного пакета обновлений. Значение будет равно `0`, если сервисный пакет в систему не установили, а, например, для Windows XP с третьим пакетом обновления — значение будет равно `3`.
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | Минорная версия установленного пакета обновлений. Значение будет равно `0`, если сервисный пакет в систему не установили.
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | Маска набора продуктов — битовая маска, которая сообщает, установили ли на машину конкретную функцию Windows. Таблица в следующем параграфе приводит возможные значения битовых полей.
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | Содержит значение для определения констант семейства `PHP_WINDOWS_NT_*`. Значение — константа семейства `PHP_WINDOWS_NT_*`, которая указывает тип платформы.
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | Сообщает информацию о контроллере домена.
`PHP_WINDOWS_NT_SERVER` (int) | Система, которую установили на сервере (например, Server 2008, 2003 или 2000). Обратите внимание: если сервер — контроллер домена, о нём сообщает константа `PHP_WINDOWS_NT_DOMAIN_CONTROLLER`.
`PHP_WINDOWS_NT_WORKSTATION` (int) | Система, которую установили на рабочую станцию (например, Vista, XP, 2000 или NT4).

Таблица показывает список функций, которые умеет проверять битовая маска `PHP_WINDOWS_VERSION_SUITEMASK`.

Битовые поля маски набора продуктов Windows
Биты | Описание
--- | ---
`0x00000004` | В систему установили компоненты Microsoft BackOffice.
`0x00000400` | На машину установили Windows Server 2003 Web Edition.
`0x00004000` | На машину установили Windows Server 2003 Compute Cluster Edition.
`0x00000080` | На машину установили Windows Server 2008 Datacenter, Windows Server 2003 Datacenter Edition или Windows 2000 Datacenter Server.
`0x00000002` | На машину установили Windows Server 2008 Enterprise, Windows Server 2003 Enterprise Edition, Windows 2000 Advanced Server или Windows NT Server 4.0 Enterprise Edition.
`0x00000040` | На машину установили ОС Windows XP Embedded.
`0x00000200` | На машину установили Windows Vista Home Premium, Windows Vista Home Basic или Windows XP Home Edition.
`0x00000100` | ОС Windows поддерживает удалённый рабочий стол (Remote Desktop), но поддерживается только один интерактивный сеанс. Значение устанавливается, если система не работает в режиме сервера приложений.
`0x00000001` | Когда-то в систему установили ОС Microsoft Small Business Server, но затем, возможно, обновили до другой версии ОС Windows.
`0x00000020` | На машину установили Microsoft Small Business Server с действующей клиентской лицензией с ограничениями.
`0x00002000` | На машину установили Windows Storage Server 2003 R2 или Windows Storage Server 2003.
`0x00000010` | В систему установили службы терминалов (Terminal Services). Значение всегда устанавливается. Если значение установлено, а бит `0x00000100` не установлен, значит, систему запустили в режиме сервера приложений.
`0x00008000` | На машину установили Windows Home Server.

# Опции PHP/информационные функции

# assert

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

assert — Проверяет утверждение

### Описание

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

Функция assert() определяет ожидания: утверждения, которые проверяются в средах разработки и тестирования, но перед развёртыванием в производственной среде код оптимизируют — удаляют проверки утверждений, чтобы исключить накладные расходы.

Утверждения помогают отлаживать код. В одном случае утверждениями проверяют, выполняются ли предварительные условия: корректные условия вычисляются как значение `true`, а ложность условий указывает на ошибки программирования. В другом сценарии проверяют доступность конкретной функции модуля или не накладывает ли система конкретные ограничения.

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

Функция assert() проверяет, выполняется ли ожидание, установленное в параметре `assertion`. Функция assert() выполнит действие, которое сконфигурировали во втором параметре, если условие не выполнилось и поэтому вернуло значение `false`.

Поведение конструкции assert() определяется следующими INI-настройками:

Опции настройки конструкции assert
Имя | По умолчанию | Описание | Список изменений
--- | --- | --- | ---
zend.assertions | `1` | `1`: генерирует и выполняет код. Значение указывают в режиме разработки `0`: генерирует, но не выполняет код при выполнении `-1`: не генерирует код. Значение указывают в производственном режиме |
assert.active | `true` | Со значением `false` функция assert() не проверяет ожидание и возвращает `true` без проверки утверждения. | Директива устарела с PHP 8.3.0.
assert.callback | `null` | Пользовательская функция, которая вызывается, если утверждение не прошло проверку. Callback-функцию определяют со следующей сигнатурой: function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | До PHP 8.0.0 сигнатуру callback-функции определяли так: function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Директива устарела с PHP 8.3.0.
assert.exception | `true` | Со значением `true` функция выбрасывает исключение AssertionError, если ожидание не оправдалось. | Директива устарела с PHP 8.3.0.
assert.bail | `false` | Со значением `true` выполнение PHP-скрипта прервётся, если ожидание не оправдалось. | Директива устарела с PHP 8.3.0.
assert.warning | `true` | Со значением `true` функция выдаёт ошибку уровня `E_WARNING`, если ожидание не оправдалось. INI-настройка не работает, если включили директиву assert.exception. | Директива устарела с PHP 8.3.0.

### Список параметров

`assertion`

  Выражение, значение возврата которого выполняется, а резлультат выполнения указывает, прошло ли утверждение проверку.

  Внимание

  До PHP 8.0.0 аргумент с типом string для параметра `assertion` интерпретировался как PHP-код и выполнялся функцией eval(). Эта строка передавалась в callback-функцию как третий аргумент. Это поведение УСТАРЕЛО в PHP 7.2.0, а в PHP 8.0.0 поведение УДАЛИЛИ.

`description`

  При передаче в параметр `description` значения с типом Throwable функция выбрасывает исключение, но только если утверждение `assertion` не прошло проверку.

  > Замечание:

  > Начиная с PHP 8.0.0 исключение выбрасывается до вызова callback-функции утверждения, если такой пользовательский обработчик определили.

  > Замечание:

  > Начиная с PHP 8.0.0 объект (object) исключения выбрасывается независимо от конфигурации директивы assert.exception.

  > Замечание:

  > Начиная с PHP 8.0.0 настройка assert.bail не работает, если в параметр передали объект исключения и утверждение не прошло проверку.

  При передаче в параметр `description` значения с типом string это сообщение появится в исключении или предупреждении. Необязательное описание, которое функция включит в сообщение, если утверждение `assertion` не пройдет проверку.

  При пропуске параметра `description` PHP на этапе компиляции сгенерирует описание ошибки, эквивалентное строке исходного кода самого утверждения assert().

### Возвращаемые значения

Функция assert() возвращает значение `true`, если хотя бы одно из следующих утверждений истинно:

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- В параметр `description` передали объект пользовательского исключения.

Функция assert() проверяет утверждения и возвращает `true` при истинности аргумента `assertion`, но только если ни одно из отключающих проверки условий не выполняется, иначе функция возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | INI-настройки `assert.` устарели.
8.0.0 | Функция assert() больше не оценивает строковые аргументы, вместо этого строки рассматриваются как любой другой аргумент. Вместо `assert('$a == $b')` лучше вызывать assert($a == $b). Директиву `assert.quiet_eval` php.ini и константу `ASSERT_QUIET_EVAL` тоже удалили, поскольку они больше не дают никакого эффекта.
8.0.0 | При передаче в параметр `description` экземпляра класса Throwable исключение выбрасывается, если утверждение не прошло проверку, независимо от значения опции assert.exception.
8.0.0 | При передаче в параметр `description` экземпляра класса Throwable пользовательская callback-функция не вызывается, даже если её установили.
8.0.0 | Объявление пользовательской функции с названием `assert()` запретили, даже внутри пространства имён. Попытка объявить функцию выдаст ошибку уровня `E_COMPILE_ERROR`.
7.3.0 | Объявление пользовательской функции с названием `assert()` устарело, даже внутри пространства имён. Объявление функции теперь выдаёт ошибку уровня `E_DEPRECATED`.
7.2.0 | Передача в параметр `assertion` утверждений в значении с типом string устарела. Функция теперь выдаст ошибку уровня `E_DEPRECATED`, когда и для опции assert.active, и для опции zend.assertions установили значение `1`.

### Примеры

Пример #1 Пример проверки утверждения функцией assert()

    <?php

    assert(1 > 2);
    echo 'Привет!';

    ?>

Приведённый пример выведет следующее, если утверждения включили в директиве `zend.assertions=1`:

    Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'assert(1 > 2)')
    #1 {main}
      thrown in example.php on line 2

Приведённый пример выведет следующее, если утверждения отключили путём установки для директивы значений `zend.assertions=0` или `zend.assertions=-1`:

    Привет!

Пример #2 Пример пользовательского сообщения

    <?php

    assert(1 > 2, "Ожидается, что один больше двух");
    echo 'Привет!';

    ?>

Приведённый пример выведет следующее, если утверждения включили:

    Fatal error: Uncaught AssertionError: Ожидается, что один больше двух in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Expected one to...')
    #1 {main}
      thrown in example.php on line 2

Приведённый пример выведет следующее, если утверждения выключили:

    Привет!

Пример #3 Пример пользовательского класса ошибок

    <?php

    class ArithmeticAssertionError extends AssertionError {}

    assert(1 > 2, new ArithmeticAssertionError("Ожидается, что один больше двух"));
    echo 'Hi!';

    ?>

Приведённый пример выведет следующее, если утверждения включили:

    Fatal error: Uncaught ArithmeticAssertionError: Ожидается, что один больше двух in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

Приведённый пример выведет следующее, если утверждения выключили:

    Привет!

### Смотрите также

- assert_options() - Устанавливает или получает флаги проверки утверждения

# assert_options

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

assert_options — Устанавливает или получает флаги проверки утверждения

Внимание

Начиная с PHP 8.3.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function assert_options(int `$option`, mixed `$value` = ?): mixed

Функция устанавливает опции, которые управляют проверкой утверждений функцией assert(), или запрашивает текущие значения опций.

> Замечание: Разработчики не рекомендуют пользоваться функцией assert_options() и взамен предлагают устанавливать директиву файла php.ini zend.assertions функцией ini_set() и получать директиву assert.exception функцией ini_get().

### Список параметров

`option`

  Настройки механизма проверки утверждений
  Настройка | INI-параметр | Значение по умолчанию | Описание
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | Включает механизм проверки утверждений
  ASSERT_EXCEPTION | assert.exception | 1 | Выбрасывает исключение AssertionError для каждого неудачного утверждения
  ASSERT_WARNING | assert.warning | 1 | Выводит PHP-предупреждение для каждой неудачной проверки
  ASSERT_BAIL | assert.bail | 0 | Завершает выполнение, если проверка не удалась
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | Отключает директиву error_reporting во время проверки утверждения. С PHP 8.0.0 опцию удалили
  ASSERT_CALLBACK | assert.callback | (`null`) | Callback-функция, которая вызывается для утверждений, которые не прошли проверку

`value`

  Необязательное новое значение опции.

  Требование к сигнатуре callback-функции, которую установили опцией `ASSERT_CALLBACK` или через директиву assert.callback:

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    Файл, в котором вызвали функцию assert().
  `line`
    Строка, в которой вызвали функцию assert().
  `assertion`
    До PHP 8.0.0, утверждение, которое передавали в функцию assert(), но только если утверждение задавали как строку. При передаче утверждения в виде логического условия параметр будет пустой строкой. Начиная с PHP 8.0.0 значение параметра всегда равно `null`.
  `description`
    Описание, которое передали в функцию assert().
  Передача пустой строки в параметр `value` сбрасывает callback-функцию проверки неудачных утверждений.

### Возвращаемые значения

Функция возвращает исходное значение опции.

### Ошибки

Функция выбрасывает исключение ValueError, если в параметр `option` передали недопустимую опцию.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция assert_options() устарела.
8.0.0 | Теперь функция выбрасывает исключение ValueError, если в параметр `option` передали недопустимую опцию; раньше возвращалось значение `false`.

### Примеры

Пример #1 Пример установки опций проверки утверждений функцией assert_options()

    <?php

    // Функция для обработки утверждений,
    // которые не прошли проверку
    function function assert_failure($file, $line, $assertion, $message)
    {
        echo "Проверка утверждения $assertion в файле $file на строке $line не прошла проверку: $message";
    }

    // Тестовая функция
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // Настройки проверки
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // Заведомо ошибочное утверждение
    test_assert(1);

    // Этот код не выполнится, пока значение опции ASSERT_BAIL
    // равно true
    echo 'Никогда не выведется';

    ?>

### Смотрите также

- assert() - Проверяет утверждение

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Возвращает заголовок текущего процесса

### Описание

function cli_get_process_title(): ?string

Возвращает заголовок текущего процесса, установленный cli_set_process_title(). Обратите внимание, что в зависимости от вашей операционной системы, это имя может не совпадать с тем, что покажут утилиты ps и top.

Эта функция доступна только в режиме CLI.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвратит строку с заголовком процесса или `null` в случае возникновения ошибки.

### Ошибки

Если команда не поддерживается вашей операционной системой, то будет вызвана ошибка уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования cli_get_process_title()

    <?php
    echo "Заголовок процесса: " . cli_get_process_title() . "\n";
    ?>

### Смотрите также

- cli_set_process_title() - Устанавливает заголовок процесса

# cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — Устанавливает заголовок процесса

### Описание

function cli_set_process_title(string `$title`): bool

Устанавливает заголовок процесса, видимое утилитами top и ps. Эта функция доступна только в режиме CLI.

### Список параметров

`title`
  Новое имя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если команда не поддерживается вашей операционной системой, то будет вызвана ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Функция cli_set_process_title() теперь выдаёт ошибку уровня `E_WARNING` при установке слишком длинного заголовка процесса; раньше заголовок усекался.

### Примеры

    <?php
    $title = "Мой потрясающий PHP-скрипт";
    $pid = getmypid(); // вы можете использовать это, чтобы увидеть заголовок процесса в ps

    if (!cli_set_process_title($title)) {
        echo "Не удалось установить заголовок процесса для PID $pid...\n";
        exit(1);
    } else {
        echo "Заголовок процесса '$title' для PID $pid был установлен!\n";
        sleep(5);
    }
    ?>

### Смотрите также

- cli_get_process_title() - Возвращает заголовок текущего процесса

# dl

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

dl — Загружает модуль PHP во время выполнения

### Описание

function dl(string `$extension_filename`): bool

Загружает модуль PHP, заданный аргументом `extension_filename`.

Чтобы проверить, что заданный модуль уже загружен, используйте функцию extension_loaded(). Функция работает как для встроенных модулей, так и для динамически загруженных (т.е. загруженных как через php.ini, так и через dl()).

Внимание

Функция доступна только для CLI и встроенного SAPI, а также для CGI SAPI при запуске из командной строки.

### Список параметров

`extension_filename`

  Аргумент содержит только имя файла модуля, который требуется загрузить. Это имя зависит от платформы. Например, модуль sockets (если скомпилирован, как загружаемый модуль, а не модуль по умолчанию!) будет называться sockets.so на Unix-платформах, и php_sockets.dll в среде Windows.

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

  Windows - Если явно не задано в php.ini, модуль будет грузиться из C:\php5\ по умолчанию.

  Unix - Если явно не задано в php.ini, директория по умолчанию зависит от

  - PHP собран с настройкой `--enable-debug` или без неё
  - PHP собран с поддержкой ZTS (Zend Thread Safety) или нет
  - текущий внутренний номер `ZEND_MODULE_API_NO` (номер внутреннего модуля Zend API, который, как правило, является датой основного изменения API модуля, например `20010901`)
  Принимая во внимание вышесказанное, получаем следующие значения по умолчанию для директории модуля `<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`, например, /usr/local/php/lib/php/extensions/debug-non-zts-20010901 или /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Если механизм загрузки модулей недоступен или отключён (значение off настройки enable_dl в php.ini), будет выдана ошибка `E_ERROR` и выполнение прекращается. Если dl() не сможет загрузить заданную библиотеку, то в дополнение к `false` будет выдано сообщение `E_WARNING`.

### Примеры

Пример #1 Примеры использования dl()

    <?php
    // Пример загрузки модуля, основываясь на ОС
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // Или на константе PHP_SHLIB_SUFFIX
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### Примечания

> Замечание:

> dl() чувствительна к регистру на Unix-платформах.

### Смотрите также

- Директивы загрузки модулей
- extension_loaded() - Определяет, загружен ли модуль

# extension_loaded

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

extension_loaded — Определяет, загружен ли модуль

### Описание

function extension_loaded(string `$extension`): bool

Определяет, загружен ли указанный модуль.

### Список параметров

`extension`

  Имя модуля. Этот параметр регистронезависимый.

  Чтобы посмотреть все имена модулей, воспользуйтесь функцией phpinfo(). Если вы работаете с `CGI`- или `CLI`-версией PHP, используйте параметр -m для отображения списка доступных модулей:

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### Возвращаемые значения

Возвращает `true`, если модуль с заданным именем `extension` загружен или `false` в противном случае.

### Примеры

Пример #1 Пример использования extension_loaded()

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### Смотрите также

- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- get_extension_funcs() - Возвращает массив имён функций модуля
- phpinfo() - Выводит информацию о текущей конфигурации PHP
- dl() - Загружает модуль PHP во время выполнения
- function_exists() - Возвращает true, если указанная функция определена

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — Принудительно запускает сборщик мусора

### Описание

function gc_collect_cycles(): int

Функция принудительно запускает механизм поиска циклических ссылок.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает количество найденных ссылок.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Возвращаемое значение больше не учитывает строки и ресурсы, которые были косвенно собраны через циклы.

### Смотрите также

- Сборка мусора

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — Отключает сборщик циклических ссылок

### Описание

function gc_disable(): void

Функция отключает сборщик циклических ссылок путём установки для директивы zend.enable_gc значения `0`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- Сборка мусора

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — Включает сборщик циклических ссылок

### Описание

function gc_enable(): void

Функция включает сборщик циклических ссылок путём установки для директивы zend.enable_gc значения `1`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- Сборка мусора

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — Возвращает текущее состояние сборщика циклических ссылок

### Описание

function gc_enabled(): bool

Функция возвращает текущее состояние сборщика циклических ссылок.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если сборщик мусора включён, иначе `false`.

### Примеры

Пример #1 Пример использования gc_enabled()

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### Смотрите также

- Сборка мусора

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Освобождает память, которую использует менеджер памяти Zend Engine

### Описание

function gc_mem_caches(): int

Функция освобождает память, которую использует менеджер памяти Zend Engine.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает количество освобождённых байтов.

### Смотрите также

- Сборка мусора

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — Получает информацию о текущем статусе сборщика мусора

### Описание

function gc_status(): array

Функция возвращает информацию о текущем статусе сборщика мусора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает ассоциативный массив со следующими элементами:

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция gc_status() теперь возвращает следующие дополнительные поля: `"running"`, `"protected"`, `"full"`, `"buffer_size"`, `"application_time"`, `"collector_time"`, `"destructor_time"` и `"free_time"`.

### Примеры

Пример #1 Пример получения информации о текущем статусе сборщика мусора функцией gc_status()

    <?php

    // Создадим дерево объектов, для которых потребуется собирать мусор
    $a = new stdClass();

    $a->b = [];

    for ($i = 0; $i < 100000; $i++) {
        $b = new stdClass();
        $b->a = $a;
        $a->b[] = $b;
    }

    unset($a);
    unset($b);

    gc_collect_cycles();

    var_dump(gc_status());

    ?>

Вывод приведённого примера будет похож на:

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

Результат выполнения приведённого примера в PHP 8.3 аналогичен:

    array(12) {
      ["running"]=>
      bool(false)
      ["protected"]=>
      bool(false)
      ["full"]=>
      bool(false)
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["buffer_size"]=>
      int(131072)
      ["roots"]=>
      int(0)
      ["application_time"]=>
      float(0.031182458)
      ["collector_time"]=>
      float(0.020106291)
      ["destructor_time"]=>
      float(0)
      ["free_time"]=>
      float(0.003707167)
    }

### Смотрите также

- Сборка мусора

# get_cfg_var

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

get_cfg_var — Извлекает значение параметра конфигурации PHP

### Описание

function get_cfg_var(string `$option`): string|array|false

Функция извлекает значение параметра конфигурации PHP, который указали в строке `option`.

Функция не возвращает информацию о конфигурации, которую установили при сборке PHP или записали в конфигурационном файле веб-сервера Apache.

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

### Список параметров

`option`

  Название параметра конфигурации.

### Возвращаемые значения

Функция возвращает текущее значение параметра конфигурации PHP, название которого указали в строке `option`, или `false`, если возникла ошибка.

### Смотрите также

- ini_get() - Получает значение параметра конфигурации
- ini_get_all() - Получает все параметры конфигурации

# get_current_user

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

get_current_user — Получает имя владельца текущего PHP-скрипта

### Описание

function get_current_user(): string

Функция возвращает имя владельца текущего PHP-скрипта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает имя пользователя в виде строки.

### Примеры

Пример #1 Пример использования функции get_current_user()

    <?php

    echo 'Текущий владелец скрипта: ' . get_current_user();

    ?>

Вывод приведённого примера будет похож на:

    Текущий владелец скрипта: SYSTEM

### Смотрите также

- getmyuid() - Получение UID владельца скрипта PHP
- getmygid() - Получить GID владельца скрипта PHP
- getmypid() - Получает ID процесса PHP
- getmyinode() - Получает значение inode текущего скрипта
- getlastmod() - Получает время последней модификации страницы

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — Возвращает ассоциативный массив с именами всех констант и их значений

### Описание

function get_defined_constants(bool `$categorize` = `false`): array

Возвращает ассоциативный массив с именами и значениями всех определённых в настоящее время констант. Массив будет включать в себя константы, определённые модулями, а также созданные функцией define().

### Список параметров

`categorize`

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

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  Вывод приведённого примера будет похож на:

      Array
      (
          [Core] => Array
              (
                  [E_ERROR] => 1
                  [E_WARNING] => 2
                  [E_PARSE] => 4
                  [E_NOTICE] => 8
                  [E_CORE_ERROR] => 16
                  [E_CORE_WARNING] => 32
                  [E_COMPILE_ERROR] => 64
                  [E_COMPILE_WARNING] => 128
                  [E_USER_ERROR] => 256
                  [E_USER_WARNING] => 512
                  [E_USER_NOTICE] => 1024
                  [E_ALL] => 2047
                  [TRUE] => 1
              )

          [pcre] => Array
              (
                  [PREG_PATTERN_ORDER] => 1
                  [PREG_SET_ORDER] => 2
                  [PREG_OFFSET_CAPTURE] => 256
                  [PREG_SPLIT_NO_EMPTY] => 1
                  [PREG_SPLIT_DELIM_CAPTURE] => 2
                  [PREG_SPLIT_OFFSET_CAPTURE] => 4
                  [PREG_GREP_INVERT] => 1
              )

          [user] => Array
              (
                  [MY_CONSTANT] => 1
              )

      )

### Возвращаемые значения

Возвращает массив вида "имя константы" => "значение константы", с возможностью сгруппировать его по имени модуля, зарегистрировавшего константу.

### Примеры

Пример #1 Пример использования get_defined_constants()

    <?php
    print_r(get_defined_constants());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [E_ERROR] => 1
        [E_WARNING] => 2
        [E_PARSE] => 4
        [E_NOTICE] => 8
        [E_CORE_ERROR] => 16
        [E_CORE_WARNING] => 32
        [E_COMPILE_ERROR] => 64
        [E_COMPILE_WARNING] => 128
        [E_USER_ERROR] => 256
        [E_USER_WARNING] => 512
        [E_USER_NOTICE] => 1024
        [E_ALL] => 2047
        [TRUE] => 1
    )

### Смотрите также

- defined() - Проверяет, существует ли константа с заданным именем
- constant() - Возвращает значение константы
- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- get_defined_functions() - Возвращает массив определённых функций
- get_defined_vars() - Возвращает массив всех определённых переменных

# get_extension_funcs

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

get_extension_funcs — Возвращает массив имён функций модуля

### Описание

function get_extension_funcs(string `$extension`): array|false

Функция возвращает имена всех функций, определённых в модуле с именем `extension`.

### Список параметров

`extension`

  Имя модуля.

  > Замечание:

  > Значение этого аргумента должно задаваться в нижнем регистре.

### Возвращаемые значения

Возвращает массив имён функций или `false`, если `extension` не является допустимым модулем.

### Примеры

Пример #1 Выводит функции XML

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => xml_parser_create
        [1] => xml_parser_create_ns
        [2] => xml_set_object
        [3] => xml_set_element_handler
        [4] => xml_set_character_data_handler
        [5] => xml_set_processing_instruction_handler
        [6] => xml_set_default_handler
        [7] => xml_set_unparsed_entity_decl_handler
        [8] => xml_set_notation_decl_handler
        [9] => xml_set_external_entity_ref_handler
        [10] => xml_set_start_namespace_decl_handler
        [11] => xml_set_end_namespace_decl_handler
        [12] => xml_parse
        [13] => xml_parse_into_struct
        [14] => xml_get_error_code
        [15] => xml_error_string
        [16] => xml_get_current_line_number
        [17] => xml_get_current_column_number
        [18] => xml_get_current_byte_index
        [19] => xml_parser_free
        [20] => xml_parser_set_option
        [21] => xml_parser_get_option
    )

### Смотрите также

- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- ReflectionExtension::getFunctions() - Получение функций модуля

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — Получение текущего значения настройки конфигурации include_path

### Описание

function get_include_path(): string|false

Получает значение настройки конфигурации include_path.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает путь к файлу в виде строки или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования get_include_path()

    <?php
    echo get_include_path();

    // или используя ini_get()
    echo ini_get('include_path');
    ?>

### Смотрите также

- ini_get() - Получает значение параметра конфигурации
- restore_include_path() - Восстанавливает начальное значение параметра конфигурации include_path
- set_include_path() - Устанавливает значение настройки конфигурации include_path
- include - include

# get_included_files

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

get_included_files — Возвращает массив имён включённых в скрипт файлов

### Описание

function get_included_files(): array

Получает имена всех файлов, которые были включены в скрипт с использованием include, include_once, require или require_once.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив, содержащий имена всех файлов.

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

Файлы, добавляемые в скрипт неоднократно, попадут в массив только в одном экземпляре.

### Примеры

Пример #1 Пример использования get_included_files()

    <?php
    // Этот скрипт расположен в файле abc.php

    include 'test1.php';
    include_once 'test2.php';
    require 'test3.php';
    require_once 'test4.php';

    $included_files = get_included_files();

    foreach ($included_files as $filename) {
        echo "$filename\n";
    }

    ?>

Результат выполнения приведённого примера:

    /path/to/abc.php
    /path/to/test1.php
    /path/to/test2.php
    /path/to/test3.php
    /path/to/test4.php

### Смотрите также

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - Псевдоним get_included_files

# get_loaded_extensions

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

get_loaded_extensions — Возвращает массив имён скомпилированных и загруженных модулей

### Описание

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

Функция возвращает массив имён модулей, которые скомпилировали и загрузили в PHP-интерпретатор.

### Список параметров

`zend_extensions`

  Возвращать только модули Zend или обычные модули наподобие mysqli. По умолчанию — `false` (возврат обычных модулей).

### Возвращаемые значения

Функция возвращает индексный массив имён модулей.

### Примеры

Пример #1 Пример использования функции get_loaded_extensions()

    <?php

    print_r(get_loaded_extensions());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Core
        [1] => date
        [2] => libxml
        [3] => pcre
        [4] => sqlite3
        [5] => zlib
        [6] => ctype
        [7] => dom
        [8] => fileinfo
        [9] => filter
        [10] => hash
        [11] => json
        [12] => mbstring
        [13] => SPL
        [14] => PDO
        [15] => session
        [16] => posix
        [17] => Reflection
        [18] => standard
        [19] => SimpleXML
        [20] => pdo_sqlite
        [21] => Phar
        [22] => tokenizer
        [23] => xml
        [24] => xmlreader
        [25] => xmlwriter
        [26] => gmp
        [27] => iconv
        [28] => intl
        [29] => bcmath
        [30] => sodium
        [31] => Zend OPcache
    )

### Смотрите также

- get_extension_funcs() - Возвращает массив имён функций модуля
- extension_loaded() - Определяет, загружен ли модуль
- dl() - Загружает модуль PHP во время выполнения
- phpinfo() - Выводит информацию о текущей конфигурации PHP

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — Получает текущее значение настройки конфигурации magic_quotes_gpc

Внимание

Начиная с PHP 7.4.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function get_magic_quotes_gpc(): false

Функция возвращает только значение `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает только значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функцию удалили.
7.4.0 | Функция устарела.

### Смотрите также

- addslashes() - Экранирует строку слешами
- stripslashes() - Удаляет экранирование символов
- get_magic_quotes_runtime() - Получает текущее значение настройки конфигурации magic_quotes_runtime
- ini_get() - Получает значение параметра конфигурации

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — Получает текущее значение настройки конфигурации magic_quotes_runtime

Внимание

Начиная с PHP 7.4.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function get_magic_quotes_runtime(): false

Функция возвращает только значение `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает только значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функцию удалили.
7.4.0 | Функция устарела.

### Смотрите также

- get_magic_quotes_gpc() - Получает текущее значение настройки конфигурации magic_quotes_gpc

# get_required_files

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

get_required_files — Псевдоним get_included_files()

### Описание

Псевдоним функции get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Возвращает активные ресурсы

### Описание

function get_resources(?string `$type` = `null`): array

Возвращает массив всех текущих активных ресурсов (resource), опционально отфильтрованный по типу ресурса.

> Замечание: Функция предназначена для отладки и тестирования. Функцию не следует использовать в рабочем окружении, особенно для доступа или даже управления ресурсами, которые обычно недоступны (например, базовый ресурс потока экземпляров SplFileObject).

### Список параметров

`type`

  Если задано, то get_resources() вернёт только ресурсы указанного типа. Список доступных типов ресурсов.

  Если в качестве типа задана строка `Unknown`, то будут возвращены только ресурсы неизвестного типа.

  Если не задано, то будут возвращены все ресурсы.

### Возвращаемые значения

Возвращает массив текущих активных ресурсов, проиндексированных по номеру ресурса.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `type` теперь допускает значение null.

### Примеры

Пример #1 Пример использования get_resources()

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

Пример #2 Пример использования get_resources() с фильтрацией

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### Смотрите также

- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- get_defined_constants() - Возвращает ассоциативный массив с именами всех констант и их значений
- get_defined_functions() - Возвращает массив определённых функций
- get_defined_vars() - Возвращает массив всех определённых переменных

# getenv

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

getenv — Получает значение одной или всех переменных окружения

### Описание

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

Функция получает значение одной или всех переменных окружения.

Список переменных окружения также выводит функция phpinfo(). Многие из этих переменных описывает раздел 4.1. Request Meta-Variables стандарта » RFC 3875.

### Список параметров

`name`

  Имя переменной в виде строки (string) или `null`.

`local_only`

  Функция возвращает только локальные переменные окружения, которые установила операционная система или команда putenv, если для этого параметра установили значение `true`. Параметр повлияет на результат работы функции, только если значение параметра `name` — строка (string).

### Возвращаемые значения

Функция возвращает значение переменной окружения `name` или `false`, если переменная окружения `name` не существует. Если значение параметра `name` равно `null`, функция возвращает все переменные окружения в виде ассоциативного массива (array).

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `name` теперь принимает значение `null`.
7.1.0 | Теперь, чтобы получить ассоциативный массив (array) всех переменных окружения, параметр `name` можно не указывать.
7.0.9 | Добавлен параметр `local_only`.

### Примеры

Пример #1 Пример использования функции getenv()

    <?php

    // Пример вызова функции getenv()
    $ip = getenv('REMOTE_ADDR');

    // Или просто получаем значение из суперглобальной переменной $_SERVER или $_ENV
    $ip = $_SERVER['REMOTE_ADDR'];

    // Надёжно получаем значение переменной окружения независимо от того,
    // установили ли или нет значение через интерфейс SAPI или изменили командой putenv
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR');

    ?>

### Примечания

Внимание

Если PHP запустили через интерфейс SAPI наподобие Fast CGI, эта функция будет возвращать значения переменных окружения, которые установили через SAPI, даже если локальную переменную с таким же именем установили функцией putenv(). Устанавливайте параметр `local_only`, чтобы функция возвращала значение локальных переменных окружения.

### Смотрите также

- putenv() - Устанавливает значение переменной среды
- apache_getenv() - Возвращает переменную окружения подпроцесса сервера Apache
- Суперглобальные переменные

# getlastmod

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

getlastmod — Получает время последней модификации страницы

### Описание

function getlastmod(): int|false

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

Время последней модификации конкретного файла возвращает функция filemtime().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает время последней модификации текущей страницы. Значение возвращается как метка Unix-времени, аналогичная той, которую передают в функцию date(). Функция возвращает значение `false`, если возникла ошибка.

### Примеры

Пример #1 Пример getlastmod()

    <?php

    // Выводит строку наподобие 'Последнее изменение: March 04 1998 20:43:59.'
    echo "Последнее изменение: " . date ("F d Y H:i:s.", getlastmod());

    ?>

### Смотрите также

- date() - Форматирует метку времени эпохи Unix
- getmyuid() - Получение UID владельца скрипта PHP
- getmygid() - Получить GID владельца скрипта PHP
- get_current_user() - Получает имя владельца текущего PHP-скрипта
- getmyinode() - Получает значение inode текущего скрипта
- getmypid() - Получает ID процесса PHP
- filemtime() - Получает время последнего изменения файла

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — Получить GID владельца скрипта PHP

### Описание

function getmygid(): int|false

Получает идентификатор группы текущего скрипта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает групповой идентификатор текущего скрипта или `false`, если возникла ошибка.

### Смотрите также

- getmyuid() - Получение UID владельца скрипта PHP
- getmypid() - Получает ID процесса PHP
- get_current_user() - Получает имя владельца текущего PHP-скрипта
- getmyinode() - Получает значение inode текущего скрипта
- getlastmod() - Получает время последней модификации страницы

# getmyinode

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

getmyinode — Получает значение inode текущего скрипта

### Описание

function getmyinode(): int|false

Получает inode текущего скрипта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает inode текущего скрипта в виде целого числа или `false` в случае ошибки.

### Смотрите также

- getmygid() - Получить GID владельца скрипта PHP
- getmyuid() - Получение UID владельца скрипта PHP
- getmypid() - Получает ID процесса PHP
- get_current_user() - Получает имя владельца текущего PHP-скрипта
- getlastmod() - Получает время последней модификации страницы

# getmypid

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

getmypid — Получает ID процесса PHP

### Описание

function getmypid(): int|false

Функция получает идентификатор процесса PHP.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает идентификатор процесса PHP или `false`, если возникла ошибка.

### Примечания

Внимание

Идентификаторы процессов в системе не уникальны, поэтому это слабые источники энтропии. Не рекомендуем полагаться на pid в контекстах, которые влияют на безопасность.

### Смотрите также

- getmygid() - Получить GID владельца скрипта PHP
- getmyuid() - Получение UID владельца скрипта PHP
- get_current_user() - Получает имя владельца текущего PHP-скрипта
- getmyinode() - Получает значение inode текущего скрипта
- getlastmod() - Получает время последней модификации страницы

# getmyuid

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

getmyuid — Получение UID владельца скрипта PHP

### Описание

function getmyuid(): int|false

Получает идентификатор пользователя текущего скрипта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор пользователя текущего скрипта или `false` в случае ошибки.

### Смотрите также

- getmygid() - Получить GID владельца скрипта PHP
- getmypid() - Получает ID процесса PHP
- get_current_user() - Получает имя владельца текущего PHP-скрипта
- getmyinode() - Получает значение inode текущего скрипта
- getlastmod() - Получает время последней модификации страницы

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — Получает параметры из списка аргументов командной строки

### Описание

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

Анализирует параметры переданные в скрипт.

### Список параметров

`short_options`
  Каждый символ в этой строке будет рассматриваться как параметр и сравниваться с символами, переданными в скрипт, перед которыми будет стоять дефис (`-`). Например, строка параметров `"x"` распознается, как параметр `-x`. Допускаются только символы a-z, A-Z и 0-9.
`long_options`
  Массив параметров. Каждый элемент массива будет использоваться как строковый параметр и сравниваться с параметрами, переданными в скрипт, перед которыми будет стоять двойной дефис (`--`). Например, элемент longopts `"opt"` будет расшифровываться как `--opt`.
`rest_index`
  Если задан параметр `rest_index`, то индекс, на котором остановился разбор, будет записан в него.

Аргумент `short_options` может содержать следующие элементы:

- Отдельные символы (не имеющие значений)
- Символы, за которыми следует двоеточие (параметр требует значения)
- Символы, за которыми следует два двоеточия (необязательное значение)

Значения параметров идут сразу за строкой параметра (символом). Если требуется значение, то нет разницы, есть между ними пробел или нет.

> Замечание: Необязательные значения нельзя отделять от других пробелом `" "`.

Значения массива `long_options` могут содержать:

- Строка (параметр не принимает никаких значений)
- Строка, за которой следует двоеточие (параметр требует значения)
- Строка, за которой следует два двоеточия (необязательное значение)

> Замечание:

> Форматы `short_options` и `long_options` практически совпадают. Различие состоит только в том, что `long_options` принимает массив параметров (в котором каждый элемент является параметром) в то время, как `short_options` принимает строку (где параметром является каждый символ).

### Возвращаемые значения

Функция вернёт массив пар параметров / аргументов или `false`, если возникла ошибка.

> Замечание:

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

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Добавлен параметр `rest_index`.

### Примеры

Пример #1 Пример использования getopt(): основы

    <?php
    // Скрипт example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

Результат выполнения приведённого примера:

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

Пример #2 Пример использования getopt(): добавление длинных опций

    <?php
    // Скрипт example.php
    $shortopts  = "";
    $shortopts .= "f:";  // Обязательное значение
    $shortopts .= "v::"; // Необязательное значение
    $shortopts .= "abc"; // Эти параметры не принимают никаких значений

    $longopts  = array(
        "required:",     // Обязательное значение
        "optional::",    // Необязательное значение
        "option",        // Нет значения
        "opt",           // Нет значения
    );
    $options = getopt($shortopts, $longopts);
    var_dump($options);
    ?>

    shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

Результат выполнения приведённого примера:

    array(6) {
      ["f"]=>
      string(11) "value for f"
      ["v"]=>
      bool(false)
      ["a"]=>
      bool(false)
      ["required"]=>
      string(5) "value"
      ["optional"]=>
      string(14) "optional value"
      ["option"]=>
      bool(false)
    }

Пример #3 Пример использования getopt(): Передача нескольких параметров как одного

    <?php
    // Скрипт example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

Результат выполнения приведённого примера:

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

Пример #4 Пример getopt() с параметром `rest_index`

    <?php
    // Скрипт example.php
    $rest_index = null;
    $opts = getopt('a:b:', [], $rest_index);
    $pos_args = array_slice($argv, $rest_index);
    var_dump($pos_args);

    shell> php example.php -a 1 -b 2 -- test

Результат выполнения приведённого примера:

    array(1) {
      [0]=>
      string(4) "test"
    }

### Смотрите также

- $argv

# getrusage

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

getrusage — Получает информацию об использовании текущего ресурса

### Описание

function getrusage(int `$mode` = 0): array|false

Это интерфейс к getrusage(2). Функция получает данные, возвращаемые из системного вызова.

### Список параметров

`mode`

  Если аргумент `mode` равен 1, getrusage будет вызвана с `RUSAGE_CHILDREN`.

### Возвращаемые значения

Возвращает ассоциативный массив, содержащий данные возвращённые из системного вызова. Имена элементов соответствуют документированным именам полей. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования getrusage()

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // количество операций вывода блока
    echo $dat["ru_inblock"];       // количество операций приёма блока
    echo $dat["ru_msgsnd"];        // количество отправленных сообщений IPC
    echo $dat["ru_msgrcv"];        // количество принятых сообщений IPC
    echo $dat["ru_maxrss"];        // наибольший размер установленной резидентной памяти
    echo $dat["ru_ixrss"];         // суммарное значение размера разделяемой памяти
    echo $dat["ru_idrss"];         // суммарное значение размера неразделяемых данных
    echo $dat["ru_minflt"];        // количество исправленных страниц (лёгкая ошибка страницы)
    echo $dat["ru_majflt"];        // количество ошибочных страниц (тяжёлая ошибка страницы)
    echo $dat["ru_nsignals"];      // количество полученных сигналов
    echo $dat["ru_nvcsw"];         // количество согласованных переключений контекста
    echo $dat["ru_nivcsw"];        // количество несогласованных переключений контекста
    echo $dat["ru_nswap"];         // количество свопов
    echo $dat["ru_utime.tv_usec"]; // время на задачи пользователя (user time) (микросекунды)
    echo $dat["ru_utime.tv_sec"];  // время на задачи пользователя (user time) (секунды)
    echo $dat["ru_stime.tv_usec"]; // время на системные задачи (system time) (микросекунды)
    echo $dat["ru_stime.tv_sec"];  // время на системные задачи (system time) (секунды)
    ?>

### Примечания

> Замечание:

> В Windows getrusage() возвращает только следующее:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"` (только если `mode` - `RUSAGE_SELF`)
> - `"ru_maxrss"` (только если `mode` - `RUSAGE_SELF`)

> Если getrusage() вызвана с `mode` равным `1` (`RUSAGE_CHILDREN`), то будет собираться информация по использованию ресурсов потоками (что означает, что внутри функция будет вызываться с `RUSAGE_THREAD`).

> Замечание:

> В BeOS 2000, возвращается только следующее:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### Смотрите также

- Страница системной документации getrusage(2)

# ini_alter

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

ini_alter — Псевдоним ini_set()

### Описание

Псевдоним функции ini_set().

# ini_get

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

ini_get — Получает значение параметра конфигурации

### Описание

function ini_get(string `$option`): string|false

Функция возвращает значение параметра конфигурации в случае успешного выполнения.

### Список параметров

`option`

  Название параметра конфигурации.

### Возвращаемые значения

Функция возвращает значение параметра конфигурации в виде строки. Для значений `null` функция вернёт пустую строку. Функция вернёт `false`, если опция не существует.

### Примеры

Пример #1 Примеры использования функции ini_get()

    <?php

    /**
     * Файл php.ini содержит следующие настройки:
     *
     * display_errors = On
     * opcache.enable_cli = Off
     * post_max_size = 8M
     */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\n";
    echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
    echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
    echo 'post_max_size in bytes = ' . ini_parse_quantity(ini_get('post_max_size'));

    ?>

Вывод приведённого примера будет похож на:

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size in bytes = 8388608

### Примечания

> Замечание: Логические значения

> Логическое ini-значение `off` возвращается как пустая строка или как строка "0", тогда как ini-значение `on` возвращается как строка "1". Функция умеет также возвращать строковый литерал INI-значения.

> Замечание: Значения размера памяти

> В файле php.ini размер памяти во многих ini-значениях директив наподобие upload_max_filesize хранится в сокращённой нотации. Функция ini_get() вернёт точную строку, которая хранится в файле php.ini, а не целочисленный (int) эквивалент строкового значения. Попытка передать значения таких директив в стандартные арифметические функции не даст того же результата, который функции вернули бы при работе с целочисленными значениями. Для преобразования сокращённой нотации в байты вызывают функцию ini_parse_quantity().

> Замечание:

> Функция ini_get() не умеет читать «массив» ini-опций наподобие `pdo.dsn.*` и возвращает `false` для таких параметров.

### Смотрите также

- get_cfg_var() - Извлекает значение параметра конфигурации PHP
- ini_get_all() - Получает все параметры конфигурации
- ini_parse_quantity() - Интерпретирует сокращение размера в значении ini-параметра
- ini_restore() - Восстанавливает значение параметра конфигурации
- ini_set() - Устанавливает значение параметра конфигурации

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — Получает все параметры конфигурации

### Описание

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

Функция возвращает все зарегистрированные параметры конфигурации.

### Список параметров

`extension`

  Необязательное название модуля. Функция возвращает информацию об опциях только того модуля, название которого указали, если значение параметра не равно `null` или строке (string) `core`.

`details`

  Возвращать для каждого параметра подробную информацию или только текущее значение. Значение по умолчанию равно `true`: возвращать подробные сведения.

### Возвращаемые значения

Функция возвращает ассоциативный массив с именами директив в качестве ключей. Функция возвращает `false` и вызывает ошибку уровня `E_WARNING`, если модуль `extension` не существует.

Если параметр `details` равен значению по умолчанию — `true`, массив будет содержать элемент `global_value` со значением параметра из файла php.ini, элемент `local_value` со значением, которое установили, например, через функцию ini_set() или файл .htaccess, и элемент `access` с уровнем доступа.

Элемент массива будет содержать текущее значение параметра, если значение параметра `details` равно `false`.

Смотрите раздел руководства «Места установки параметров конфигурации», который даёт дополнительную информацию о значениях уровней доступа.

> Замечание:

> У директив бывает больше одного уровня доступа, тогда элемент с ключом `access` будет содержать битовую маску значений, которая соответствует значениям уровней доступа.

### Примеры

Пример #1 Примеры использования функции ini_get_all()

    <?php

    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [pcre.backtrack_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

        [pcre.recursion_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

    )
    Array
    (
        [allow_call_time_pass_reference] => Array
            (
                [global_value] => 0
                [local_value] => 0
                [access] => 6
            )

        [allow_url_fopen] => Array
            (
                [global_value] => 1
                [local_value] => 1
                [access] => 4
            )

        ...

    )

Пример #2 Пример отключения параметра `details`

    <?php

    print_r(ini_get_all("pcre", false)); // Добавлено в PHP 5.3.0
    print_r(ini_get_all(null, false)); // Добавлено в PHP 5.3.0

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### Примечания

> Замечание:

> Функция ini_get_all() игнорирует «массивы» ini-опций наподобие `pdo.dsn.*`.

### Смотрите также

- Как изменить настройки конфигурации
- ini_get() - Получает значение параметра конфигурации
- ini_restore() - Восстанавливает значение параметра конфигурации
- ini_set() - Устанавливает значение параметра конфигурации
- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- phpinfo() - Выводит информацию о текущей конфигурации PHP
- ReflectionExtension::getINIEntries() - Получение ini-настроек модуля

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Интерпретирует сокращение размера в значении ini-параметра

### Описание

function ini_parse_quantity(string `$shorthand`): int

Функция интерпретирует и в случае успешного выполнения возвращает размер в байтах, который получила из сокращения значения ini-параметра.

### Список параметров

`shorthand`

  Сокращение значения ini-параметра для разбора. Параметр требует целое число, за которым следует необязательный множитель. Поддерживаются следующие множители: `k` или `K` — килобайт, `1024` байта; `m` или `M` — мегабайт, `1 048 576` байтов; `g` или `G` — гигабайт, `1 073 741 824` байта. Параметр принимает десятичные, шестнадцатеричные с префиксом `0x` или `0X`, восьмеричные с префиксом `0o`, `0O` или `0` и двоичные с префиксом `0b` или `0B` числа.

### Возвращаемые значения

Функция возвращает размер в байтах в виде целого числа (int), который получила после интерпретации сокращения размера ini-значения.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если не смогла разобрать значение или встретила недопустимый множитель.

### Примеры

Пример #1 Пример использования функции ini_parse_quantity()

    <?php

    var_dump(ini_parse_quantity('1024'));
    var_dump(ini_parse_quantity('1024M'));
    var_dump(ini_parse_quantity('512K'));
    var_dump(ini_parse_quantity('0xFFk'));
    var_dump(ini_parse_quantity('0b1010k'));
    var_dump(ini_parse_quantity('0o1024'));
    var_dump(ini_parse_quantity('01024'));
    var_dump(ini_parse_quantity('Foobar'));
    var_dump(ini_parse_quantity('10F'));

    ?>

Результат выполнения приведённого примера:

    int(1024)
    int(1073741824)
    int(524288)
    int(261120)
    int(10240)
    int(532)
    int(532)

    Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
    int(0)

    Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
    int(10)

### Смотрите также

- ini_get() - Получает значение параметра конфигурации

# ini_restore

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

ini_restore — Восстанавливает значение параметра конфигурации

### Описание

function ini_restore(string `$option`): void

Функция восстанавливает исходное значение параметра конфигурации.

### Список параметров

`option`

  Название параметра конфигурации.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования функции ini_restore()

    <?php

    $setting = 'html_errors';

    echo 'Текущее значение параметра \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_set($setting, ini_get($setting) ? 0 : 1);
    echo 'Новое значение параметра \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_restore($setting);
    echo 'Исходное значение параметра \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    Текущее значение параметра 'html_errors': 1
    Новое значение параметра 'html_errors': 0
    Исходное значение параметра 'html_errors': 1

### Смотрите также

- ini_get() - Получает значение параметра конфигурации
- ini_get_all() - Получает все параметры конфигурации
- ini_set() - Устанавливает значение параметра конфигурации

# ini_set

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

ini_set — Устанавливает значение параметра конфигурации

### Описание

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

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

### Список параметров

`option`

  Не каждую доступную опцию получится изменить функцией ini_set(). Список доступных параметров приводит приложение.

`value`

  Новое значение параметра.

### Возвращаемые значения

Функция возвращает старое значение параметра в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `value` теперь принимает скалярные типы, включая `null`. Раньше параметр принимал только строковые (string) значения.

### Примеры

Пример #1 Пример установки значения для ini-параметра

    <?php

    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');

    ?>

### Смотрите также

- get_cfg_var() - Извлекает значение параметра конфигурации PHP
- ini_get() - Получает значение параметра конфигурации
- ini_get_all() - Получает все параметры конфигурации
- ini_restore() - Восстанавливает значение параметра конфигурации
- Как изменить настройки конфигурации

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — Возвращает пиковое значение памяти, которую потребил PHP-скрипт или которую система выделила PHP-процессу

### Описание

function memory_get_peak_usage(bool `$real_usage` = `false`): int

Функция возвращает пиковый объем памяти в байтах, который потребил PHP-скрипт.

### Список параметров

`real_usage`

  При передаче в параметр значения `true` функция возвращает пиковый объём памяти, которую система выделила PHP-процессу. При вызове функции без аргументов или при передаче в аргументе значения `false` функция сообщит только о пиковом количестве памяти, которую внутренняя функция `emalloc()` выделила PHP-скрипту.

### Возвращаемые значения

Функция возвращает пиковый объем памяти в байтах.

### Смотрите также

- memory_get_usage() - Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу
- memory_reset_peak_usage() - Сбрасывает пиковое значение объёма памяти, выделенной PHP
- memory_limit

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу

### Описание

function memory_get_usage(bool `$real_usage` = `false`): int

Функция возвращает количество памяти в байтах, которое потребляет текущий PHP-скрипт.

### Список параметров

`real_usage`

  При передаче в параметр значения `true` функция возвращает общий объём памяти, которую система выделила PHP-процессу, включая свободные страницы памяти. При вызове функции без аргументов или при передаче в аргументе значения `false` функция сообщит только о количестве памяти, которую заинимает PHP-скрипт.

> Замечание:

> PHP отслеживает только ту память, которую движок выделили через внутреннюю функцию `emalloc()`.

### Возвращаемые значения

Функция возвращает количество памяти в байтах.

### Примеры

Пример #1 Пример поведения функции memory_get_usage() при получении информации о памяти, которую потребляет PHP-скрипт

    <?php

    // Это только пример, конкретные цифры
    // зависят от системы

    echo memory_get_usage() . "\n"; // 36640

    $a = str_repeat("Hello", 4242);

    echo memory_get_usage() . "\n"; // 57960

    unset($a);

    echo memory_get_usage() . "\n"; // 36744

    ?>

### Смотрите также

- memory_get_peak_usage() - Возвращает пиковое значение памяти, которую потребил PHP-скрипт или которую система выделила PHP-процессу
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Сбрасывает пиковое значение объёма памяти, выделенной PHP

### Описание

function memory_reset_peak_usage(): void

Сбрасывает пиковое значение объёма выделенной памяти, возвращаемое функцией memory_get_peak_usage().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования memory_reset_peak_usage()

    <?php

    var_dump(memory_get_peak_usage());

    $a = str_repeat("Hello", 424242);
    var_dump(memory_get_peak_usage());

    unset($a);
    memory_reset_peak_usage();

    $a = str_repeat("Hello", 2424);
    var_dump(memory_get_peak_usage());

    ?>

Вывод приведённого примера будет похож на:

    int(422440)
    int(2508672)
    int(399208)

### Смотрите также

- memory_get_peak_usage() - Возвращает пиковое значение памяти, которую потребил PHP-скрипт или которую система выделила PHP-процессу

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — Получить путь к загруженному файлу php.ini

### Описание

function php_ini_loaded_file(): string|false

Проверяет, загружен ли файл php.ini, и возвращает его путь.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Путь к загруженному файлу php.ini или `false`, если файл не загружен.

### Примеры

Пример #1 Пример использования php_ini_loaded_file()

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'Загруженный php.ini: ' . $inipath;
    } else {
        echo 'Файл php.ini не загружен';
    }
    ?>

Вывод приведённого примера будет похож на:

    Loaded php.ini: /usr/local/php/php.ini

### Смотрите также

- php_ini_scanned_files() - Возвращает список .ini-файлов, найденных в дополнительной ini-директории
- phpinfo() - Выводит информацию о текущей конфигурации PHP
- Конфигурационный файл

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — Возвращает список .ini-файлов, найденных в дополнительной ini-директории

### Описание

function php_ini_scanned_files(): string|false

php_ini_scanned_files() возвращает список разделённых запятыми конфигурационных файлов, проанализированных после php.ini. Директории, в которых производится поиск, задаются при компиляции и, опционально, переменной окружения во время исполнения. Больше информации можно найти в инструкции по установке.

Возвращаемые имена файлов включают полный путь.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

При успехе возвращает строку с разделёнными запятыми именами .ini-файлов. За каждой запятой следует новая строка. Если директива --with-config-file-scan-dir не задана и переменная окружения PHP_INI_SCAN_DIR тоже не задана, функция вернёт `false`. Если директива задана и она пуста, будет возвращена пустая строка. Если файл не удаётся распознать, он всё же будет включён в список, но при этом PHP сообщит об ошибке. Эта ошибка будет возникать как при компиляции, так и во время работы php_ini_scanned_files().

### Примеры

Пример #1 Простой пример вывода списка ini-файлов

    <?php
    if ($filelist = php_ini_scanned_files()) {
        if (strlen($filelist) > 0) {
            $files = explode(',', $filelist);

            foreach ($files as $file) {
                echo "<li>" . trim($file) . "</li>\n";
            }
        }
    }
    ?>

### Смотрите также

- ini_set() - Устанавливает значение параметра конфигурации
- phpinfo() - Выводит информацию о текущей конфигурации PHP
- php_ini_loaded_file() - Получить путь к загруженному файлу php.ini

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — Возвращает тип интерфейса между веб-сервером и PHP

### Описание

function php_sapi_name(): string|false

Возвращает строку в нижнем регистре, содержащую описание типа интерфейса (Server API, SAPI), который использует PHP. Например, в CLI PHP эта строка будет "cli", в то время как с Apache может быть несколько разных значений в зависимости от конкретного SAPI. Возможные значение приведены ниже.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает тип интерфейса в виде строки в нижнем регистре или `false`, если возникла ошибка.

Возможные возвращаемые значения (список может быть неполным): `apache`, `apache2handler`, `cgi` (до PHP 5.3), `cgi-fcgi`, `cli`, `cli-server`, `embed`, `fpm-fcgi`, `litespeed`, `phpdbg`.

### Примеры

Пример #1 Пример использования php_sapi_name()

В этом примере проверяется подстрока `cgi`, так как это также может быть `cgi-fcgi`.

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "Вы используете CGI PHP\n";
    } else {
        echo "Вы используете не CGI PHP\n";
    }
    ?>

### Примечания

> Замечание: Альтернативный вариант

> Константа PHP `PHP_SAPI` хранит то же значение, что и php_sapi_name().

Подсказка

# Важный аспект

Имя SAPI может определиться неточно, так как, например, в случае с `apache` интерфейс может быть определён как `apache2handler`.

### Смотрите также

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — Возвращает информацию об операционной системе, в которой работает PHP

### Описание

function php_uname(string `$mode` = "a"): string

Функция php_uname() возвращает описание операционной системы, в которой запустили PHP. Это та же строка, с которой начинается вывод функции phpinfo(). Для вывода только названия операционной системы указывают константу `PHP_OS`. Обратите внимание, эта константа содержит название операционной системы, в которой собрали PHP.

На отдельных старых UNIX-платформах функция иногда не определяет текущую ОС и тогда возвращает ОС, в которой собрали PHP. Такое бывает, только если библиотечный вызов функции uname() не существует или не работает.

### Список параметров

`mode`

  `mode` — один символ, который определяет, какая информация возвращается:

  - `'a'`: Значение по умолчанию. В этом режиме функция возвращает ту же информацию, что и отдельные режимы, разделённые пробелом. `'s'`, `'n'`, `'r'`, `'v'`, `'m'`.

  - `'s'`: Название операционной системы, например `FreeBSD`.
  - `'n'`: Имя хоста, например `localhost.example.com`.
  - `'r'`: Номер релиза, например `5.1.2-RELEASE`.
  - `'v'`: Информация о версии. Сильно различается в зависимости от операционной системы.
  - `'m'`: Архитектура процессора, например `i386`.

### Возвращаемые значения

Функция возвращает описание ОС в виде строки.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция выбрасывает ошибку ValueError, если указали недопустимый режим `mode`.

### Примеры

Пример #1 Примеры получения информации об операционной системе функцией php_uname()

    <?php

    echo php_uname();
    echo PHP_OS;

    /* Разные варианты:
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'Сервер работает под управлением Windows!';
    } else {
        echo 'Сервер работает под управлением ОС, отличной от Windows!';
    }

    ?>

В языке также предопределили ряд PHP-констант, которые связаны с работой функции:

Пример #2 Пример констант, которые связаны с ОС

    <?php

    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;

    ?>

### Смотрите также

- phpversion() - Получает текущую версию PHP
- php_sapi_name() - Возвращает тип интерфейса между веб-сервером и PHP
- phpinfo() - Выводит информацию о текущей конфигурации PHP

# phpcredits

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

phpcredits — Выводит список разработчиков PHP

### Описание

function phpcredits(int `$flags` = `CREDITS_ALL`): true

Эта функция выводит список разработчиков PHP, модулей и т.д. Она генерирует соответствующий HTML-код для вставки на страницу.

### Список параметров

`flags`

  Использование аргумента `flags` позволяет произвольно компоновать информацию об отдельных группах разработчиков.

  Предопределённые флаги phpcredits()
  Имя | Описание
  --- | ---
  CREDITS_ALL | Все разработчики, эквивалентно использованию: `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`. В этом случае будет сгенерирована полностью независимая HTML-страница с соответствующими тэгами.
  CREDITS_DOCS | Участники команды документирования
  CREDITS_FULLPAGE | Обычно используется в комбинации с другими флагами. Указывает на то, что независимая HTML страница должна содержать информацию других флагов.
  CREDITS_GENERAL | Главные разработчики: Концепция и дизайн языка, авторы PHP и модуля SAPI.
  CREDITS_GROUP | Список разработчиков ядра языка
  CREDITS_MODULES | Список модулей для PHP и их авторов
  CREDITS_SAPI | Список модулей серверных API и их авторов

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Выводит основных разработчиков

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

Пример #2 Выводит разработчиков ядра и участников команды документирования

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

Пример #3 Вывод всех разработчиков

    <html>
     <head>
      <title>Сведения об авторах</title>
     </head>
     <body>
    <?php
    // какой-то код
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // ещё код
    ?>
     </body>
    </html>

### Примечания

> Замечание:

> В режиме работы из командной строки (CLI) phpcredits() выводит обычный текст вместо HTML.

### Смотрите также

- phpversion() - Получает текущую версию PHP
- phpinfo() - Выводит информацию о текущей конфигурации PHP

# phpinfo

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

phpinfo — Выводит информацию о текущей конфигурации PHP

### Описание

function phpinfo(int `$flags` = `INFO_ALL`): true

Выводит большое количество информации о текущем состоянии PHP. Сюда входит информация о настройках компиляции PHP, о модулях, о версии, информация о сервере и среде выполнения (если PHP компилировался как модуль), окружении PHP, версии ОС, о путях, об основных и локальных значениях настроек конфигурации, о HTTP-заголовках и лицензии PHP.

Так как каждая система имеет свои особенности, phpinfo() используется в основном для проверки настроек конфигурации и для просмотра доступных предопределённых констант в данной системе.

phpinfo() также используется в целях отладки, так как содержит все данные EGPCS (Environment, GET, POST, Cookie, Server).

### Список параметров

`flags`

  Вывод функции можно настраивать, передавая битовую маску из одной или более приведённых ниже констант (constants). Эта маска передаётся в качестве необязательного аргумента `flags`. Отдельные константы или битовые значения можно комбинировать с помощью побитового оператора ИЛИ.

  Настройки phpinfo()
  Имя (константа) | Значение | Описание
  --- | --- | ---
  INFO_GENERAL | 1 | Строка конфигурации, расположение php.ini, дата сборки, сервер, система и др.
  INFO_CREDITS | 2 | Разработчики PHP. Смотрите также phpcredits().
  INFO_CONFIGURATION | 4 | Текущие значение основных и локальных PHP директив. Смотрите также ini_get().
  INFO_MODULES | 8 | Загруженные модули и их настройки. Смотрите также get_loaded_extensions().
  INFO_ENVIRONMENT | 16 | Информация о переменных окружения, которая также доступна в $_ENV.
  INFO_VARIABLES | 32 | Выводит все предопределённые переменные из EGPCS (Environment, GET, POST, Cookie, Server).
  INFO_LICENSE | 64 | Информация о лицензии PHP. Смотрите также » license FAQ.
  INFO_ALL | -1 | Выводит все приведённое выше.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Пример использования phpinfo()

    <?php

    // Показывать всю информацию, по умолчанию INFO_ALL
    phpinfo();

    // Показывать информацию только о загруженных модулях.
    // phpinfo(8) выдаёт тот же результат.
    phpinfo(INFO_MODULES);

    ?>

### Примечания

> Замечание:

> В версиях PHP до 5.5, часть информации не выводится, если настройка expose_php установлена в `off`. Это PHP и Zend логотипы и информация о разработчиках.

> Замечание:

> В режиме CLI phpinfo() выводит обычный текст вместо HTML.

### Смотрите также

- phpversion() - Получает текущую версию PHP
- phpcredits() - Выводит список разработчиков PHP
- ini_get() - Получает значение параметра конфигурации
- ini_set() - Устанавливает значение параметра конфигурации
- get_loaded_extensions() - Возвращает массив имён скомпилированных и загруженных модулей
- Предопределённые переменные

# phpversion

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

phpversion — Получает текущую версию PHP

### Описание

function phpversion(?string `$extension` = `null`): string|false

Функция возвращает строку с номером версии текущего PHP-интерпретатора или модуля.

### Список параметров

`extension`

  Необязательное имя модуля.

### Возвращаемые значения

Функция возвращает текущую версию PHP в виде строки (string). При передаче в параметр `extension` строкового (string) аргумента функция phpversion() возвращает версию модуля или `false`, если информации о версии нет или модуль не включили.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `extension` теперь принимает значение null.

### Примеры

Пример #1 Пример использования функции phpversion()

    <?php

    // Выводит строку вида 'Текущая версия PHP: 8.3.12'
    echo 'Текущая версия PHP: ' . phpversion();

    // Выводит строку вида '1.22.3' или ничего, если модуль не включили
    echo phpversion('zip');

    ?>

Пример #2 Пример работы с константой `PHP_VERSION_ID`

    <?php

    /**
     * Константу PHP_VERSION_ID определяют как число, причём чем больше число, тем новее
     * версия PHP. Значение константы определяют выражением, которое приводит предыдущий абзац:
     *
     * $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
     *
     * Теперь через константу PHP_VERSION_ID можно проверять, какую функциональность
     * поддерживает текущая версия PHP, для этого не нужно каждый раз вызывать функцию version_compare(),
     * чтобы проверить, поддерживает ли функцию текущая версия PHP.
     *
     * Например, можно определить константы семейства PHP_*_VERSION,
     * которые недоступны в версиях до 5.2.7:
     */
    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // и так далее…
    }

    ?>

### Примечания

> Замечание:

> Информацию о версии PHP также даёт предопределённая константа `PHP_VERSION`. Дополнительную информацию о семантических значениях, из которых состоит полная версия выпуска PHP, дают константы семейства `PHP_*_VERSION`.

> Замечание:

> Отдельные модули определяют свой номер версии, но бо́льшая часть встроенных модулей в качестве своего номера версии будет использовать версию PHP.

### Смотрите также

- Константы PHP_VERSION
- version_compare() - Сравнивает две «стандартизованные» строки с номером версии PHP
- phpinfo() - Выводит информацию о текущей конфигурации PHP
- phpcredits() - Выводит список разработчиков PHP
- zend_version() - Получает версию движка Zend

# putenv

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

putenv — Устанавливает значение переменной среды

### Описание

function putenv(string `$assignment`): bool

Функция добавляет настройку `assignment` в переменные окружения сервера. Переменная будет существовать только на протяжении текущего запроса. По окончании запроса среда восстанавливается в исходное состояние.

### Список параметров

`assignment`

  Установка в виде `"FOO=BAR"`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример установки значения переменной среды

    <?php

    putenv("UNIQID=$uniqid");

    ?>

### Смотрите также

- getenv() - Получает значение одной или всех переменных окружения
- apache_setenv() - Устанавливает переменную subprocess_env Apache

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — Восстанавливает начальное значение параметра конфигурации include_path

Внимание

Начиная с PHP 7.4.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function restore_include_path(): void

Функция восстанавливает исходное значение параметра конфигурации include_path, которое установили в файле php.ini

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функцию удалили.
7.4.0 | Функция устарела.

### Примеры

Пример #1 Пример восстановления исходного значения директивы функцией restore_include_path()

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // Или вызовом функции ini_restore()
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### Смотрите также

- ini_restore() - Восстанавливает значение параметра конфигурации
- get_include_path() - Получение текущего значения настройки конфигурации include_path
- set_include_path() - Устанавливает значение настройки конфигурации include_path
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — Устанавливает значение настройки конфигурации include_path

### Описание

function set_include_path(string `$include_path`): string|false

Задаёт значение настройки конфигурации include_path на время выполнения скрипта.

### Список параметров

`include_path`

  Новое значение настройки include_path

### Возвращаемые значения

Возвращает старое значение include_path в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования set_include_path()

    <?php
    set_include_path('/usr/lib/pear');

    // Или так
    ini_set('include_path', '/usr/lib/pear');
    ?>

Пример #2 Составление более длинного пути include path

Используя константу `PATH_SEPARATOR`, можно добавить к пути вложенные директории независимо от операционной системы.

В этом примере мы добавим /usr/lib/pear в конец существующего пути `include_path`.

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### Смотрите также

- ini_set() - Устанавливает значение параметра конфигурации
- get_include_path() - Получение текущего значения настройки конфигурации include_path
- restore_include_path() - Восстанавливает начальное значение параметра конфигурации include_path
- include - include

# set_time_limit

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

set_time_limit — Ограничивает время выполнения скрипта

### Описание

function set_time_limit(int `$seconds`): bool

Функция задаёт время в секундах, в течение которого скрипт завершит работу. PHP выдаст фатальную ошибку, если скрипт не успевает. По умолчанию даётся 30 секунд, иначе — количество секунд директивы `max_execution_time` файла php.ini, если опцию установили.

При вызове функция set_time_limit() перезапускает счётчик с нуля. Другими словами, если время ожидания изначально составляло 30 секунд, а через 25 секунд после запуска скрипта вызвали функцию `set_time_limit(20)`, скрипт будет работать максимум 45 секунд.

### Список параметров

`seconds`

  Максимальное время выполнения в секундах. При значении 0 время выполнения не ограничивается.

### Возвращаемые значения

Функция возвращает `true` в случае успешного выполнения, иначе `false`.

### Примечания

> Замечание:

> Функция set_time_limit() и директива max_execution_time влияют на время выполнения только самого скрипта. Время действий за пределами скрипта — системных вызовов функции system(), потоковых операций, запросов к базам данных и т. п. — не включается при определении максимального времени работы скрипта. Это не относится к системам Windows, в которых рассчитывается абсолютное время выполнения.

### Смотрите также

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — Возвращает путь к директории временных файлов

### Описание

function sys_get_temp_dir(): string

Функция возвращает путь к директории, в которой PHP по умолчанию хранит временные файлы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает путь к каталогу временных файлов.

### Примеры

Пример #1 Пример использования функции sys_get_temp_dir()

    <?php

    // Создаём временный файл в каталоге
    // временных файлов функцией sys_get_temp_dir()
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;

    ?>

Вывод приведённого примера будет похож на:

    C:\Windows\Temp\TuxA318.tmp

### Смотрите также

- tmpfile() - Создаёт временный файл
- tempnam() - Создаёт файл с уникальным именем

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — Сравнивает две «стандартизованные» строки с номером версии PHP

### Описание

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() сравнивает две "PHP-стандартизованные" строки с номерами версий.

Функция сначала заменяет подчёркивание `_`, дефис `-` и знак плюса `+` на точку `.` в строках версий, а также добавляет точки `.` до и после каждого символа, не являющегося числом. Например, '4.3.2RC1' преобразуется в '4.3.2.RC.1'. После этого сравнивает части строк слева направо. Если часть строки содержит специальные символы версий, они обрабатываются следующим образом: `любая строка, не найденная в этом списке` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`. Таким образом можно сравнивать не только версии разных уровней, вроде '4.1' и '4.1.2', но и специфичные версии, включающие статус разработки.

### Список параметров

`version1`

  Номер первой версии.

`version2`

  Номер второй версии.

`operator`

  Необязательный параметр `operator`. Возможные значения: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, `ne`.

  Аргумент чувствителен к регистру, поэтому значения должны быть в нижнем регистре.

### Возвращаемые значения

По умолчанию функция version_compare() возвращает `-1`, если первая версия меньше второй; `0`, когда они равны; `1`, если вторая меньше первой.

При использовании аргумента `operator` функция вернёт `true`, если выражение в соответствии с оператором верно, и `false` в противном случае.

### Примеры

В примере ниже используется константа `PHP_VERSION`, она содержит номер версии PHP, который выполняет код.

Пример #1 Пример использования version_compare()

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'Я использую PHP версии не ниже 7.0.0, моя версия: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'Я использую PHP версии не ниже 5.3.0, моя версия: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'Я использую PHP 5.0.0 или выше, моя версия: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'Я до сих пор использую PHP 4, моя версия: ' . PHP_VERSION . "\n";
    }
    ?>

### Примечания

> Замечание:

> Константа `PHP_VERSION` хранит номер текущей версии PHP.

> Замечание:

> Заметьте, что дорелизные версии, такие как 5.3.0-dev, считаются меньше, чем финальные (вида 5.3.0).

> Замечание:

> Специальные слова вроде `alpha` и `beta` чувствительны к регистру. Строки версий, не придерживающиеся PHP-стандарта, нужно приводить к нижнему регистру функцией strtolower() до вызова version_compare().

### Смотрите также

- phpversion() - Получает текущую версию PHP
- php_uname() - Возвращает информацию об операционной системе, в которой работает PHP
- function_exists() - Возвращает true, если указанная функция определена

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — Возвращает уникальный идентификатор текущего потока выполнения

### Описание

function zend_thread_id(): int

Эта функция возвращает уникальный идентификатор текущего потока выполнения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор потока выполнения в виде целого числа.

### Примеры

Пример #1 Пример использования zend_thread_id()

    <?php
    $thread_id = zend_thread_id();

    echo 'Идентификатор текущего потока выполнения: ' . $thread_id;
    ?>

Вывод приведённого примера будет похож на:

    Идентификатор текущего потока выполнения: 7864

### Примечания

> Замечание:

> Эта функция доступна, только если PHP собран с поддержкой ZTS (Zend Thread Safety) и работает в режиме отладки (`--enable-debug`).

# zend_version

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

zend_version — Получает версию движка Zend

### Описание

function zend_version(): string

Возвращает строку с номером версии работающего в данный момент ядра Zend Engine.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает номер версии Zend Engine в виде строки.

### Примеры

Пример #1 Пример использования zend_version()

    <?php
    echo "Версия движка Zend: " . zend_version();
    ?>

Вывод приведённого примера будет похож на:

    Версия движка Zend: 2.2.0

### Смотрите также

- phpinfo() - Выводит информацию о текущей конфигурации PHP
- phpcredits() - Выводит список разработчиков PHP
- phpversion() - Получает текущую версию PHP

## Содержание

- assert — Проверяет утверждение
- assert_options — Устанавливает или получает флаги проверки утверждения
- cli_get_process_title — Возвращает заголовок текущего процесса
- cli_set_process_title — Устанавливает заголовок процесса
- dl — Загружает модуль PHP во время выполнения
- extension_loaded — Определяет, загружен ли модуль
- gc_collect_cycles — Принудительно запускает сборщик мусора
- gc_disable — Отключает сборщик циклических ссылок
- gc_enable — Включает сборщик циклических ссылок
- gc_enabled — Возвращает текущее состояние сборщика циклических ссылок
- gc_mem_caches — Освобождает память, которую использует менеджер памяти Zend Engine
- gc_status — Получает информацию о текущем статусе сборщика мусора
- get_cfg_var — Извлекает значение параметра конфигурации PHP
- get_current_user — Получает имя владельца текущего PHP-скрипта
- get_defined_constants — Возвращает ассоциативный массив с именами всех констант и их значений
- get_extension_funcs — Возвращает массив имён функций модуля
- get_include_path — Получение текущего значения настройки конфигурации include_path
- get_included_files — Возвращает массив имён включённых в скрипт файлов
- get_loaded_extensions — Возвращает массив имён скомпилированных и загруженных модулей
- get_magic_quotes_gpc — Получает текущее значение настройки конфигурации magic_quotes_gpc
- get_magic_quotes_runtime — Получает текущее значение настройки конфигурации magic_quotes_runtime
- get_required_files — Псевдоним get_included_files
- get_resources — Возвращает активные ресурсы
- getenv — Получает значение одной или всех переменных окружения
- getlastmod — Получает время последней модификации страницы
- getmygid — Получить GID владельца скрипта PHP
- getmyinode — Получает значение inode текущего скрипта
- getmypid — Получает ID процесса PHP
- getmyuid — Получение UID владельца скрипта PHP
- getopt — Получает параметры из списка аргументов командной строки
- getrusage — Получает информацию об использовании текущего ресурса
- ini_alter — Псевдоним ini_set
- ini_get — Получает значение параметра конфигурации
- ini_get_all — Получает все параметры конфигурации
- ini_parse_quantity — Интерпретирует сокращение размера в значении ini-параметра
- ini_restore — Восстанавливает значение параметра конфигурации
- ini_set — Устанавливает значение параметра конфигурации
- memory_get_peak_usage — Возвращает пиковое значение памяти, которую потребил PHP-скрипт или которую система выделила PHP-процессу
- memory_get_usage — Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу
- memory_reset_peak_usage — Сбрасывает пиковое значение объёма памяти, выделенной PHP
- php_ini_loaded_file — Получить путь к загруженному файлу php.ini
- php_ini_scanned_files — Возвращает список .ini-файлов, найденных в дополнительной ini-директории
- php_sapi_name — Возвращает тип интерфейса между веб-сервером и PHP
- php_uname — Возвращает информацию об операционной системе, в которой работает PHP
- phpcredits — Выводит список разработчиков PHP
- phpinfo — Выводит информацию о текущей конфигурации PHP
- phpversion — Получает текущую версию PHP
- putenv — Устанавливает значение переменной среды
- restore_include_path — Восстанавливает начальное значение параметра конфигурации include_path
- set_include_path — Устанавливает значение настройки конфигурации include_path
- set_time_limit — Ограничивает время выполнения скрипта
- sys_get_temp_dir — Возвращает путь к директории временных файлов
- version_compare — Сравнивает две «стандартизованные» строки с номером версии PHP
- zend_thread_id — Возвращает уникальный идентификатор текущего потока выполнения
- zend_version — Получает версию движка Zend

- Установка и настройка
  - Настройка во время выполнения
- Предопределённые константы
- Опции PHP/информационные функции
  - assert — Проверяет утверждение
  - assert_options — Устанавливает или получает флаги проверки утверждения
  - cli_get_process_title — Возвращает заголовок текущего процесса
  - cli_set_process_title — Устанавливает заголовок процесса
  - dl — Загружает модуль PHP во время выполнения
  - extension_loaded — Определяет, загружен ли модуль
  - gc_collect_cycles — Принудительно запускает сборщик мусора
  - gc_disable — Отключает сборщик циклических ссылок
  - gc_enable — Включает сборщик циклических ссылок
  - gc_enabled — Возвращает текущее состояние сборщика циклических ссылок
  - gc_mem_caches — Освобождает память, которую использует менеджер памяти Zend Engine
  - gc_status — Получает информацию о текущем статусе сборщика мусора
  - get_cfg_var — Извлекает значение параметра конфигурации PHP
  - get_current_user — Получает имя владельца текущего PHP-скрипта
  - get_defined_constants — Возвращает ассоциативный массив с именами всех констант и их значений
  - get_extension_funcs — Возвращает массив имён функций модуля
  - get_include_path — Получение текущего значения настройки конфигурации include_path
  - get_included_files — Возвращает массив имён включённых в скрипт файлов
  - get_loaded_extensions — Возвращает массив имён скомпилированных и загруженных модулей
  - get_magic_quotes_gpc — Получает текущее значение настройки конфигурации magic_quotes_gpc
  - get_magic_quotes_runtime — Получает текущее значение настройки конфигурации magic_quotes_runtime
  - get_required_files — Псевдоним get_included_files
  - get_resources — Возвращает активные ресурсы
  - getenv — Получает значение одной или всех переменных окружения
  - getlastmod — Получает время последней модификации страницы
  - getmygid — Получить GID владельца скрипта PHP
  - getmyinode — Получает значение inode текущего скрипта
  - getmypid — Получает ID процесса PHP
  - getmyuid — Получение UID владельца скрипта PHP
  - getopt — Получает параметры из списка аргументов командной строки
  - getrusage — Получает информацию об использовании текущего ресурса
  - ini_alter — Псевдоним ini_set
  - ini_get — Получает значение параметра конфигурации
  - ini_get_all — Получает все параметры конфигурации
  - ini_parse_quantity — Интерпретирует сокращение размера в значении ini-параметра
  - ini_restore — Восстанавливает значение параметра конфигурации
  - ini_set — Устанавливает значение параметра конфигурации
  - memory_get_peak_usage — Возвращает пиковое значение памяти, которую потребил PHP-скрипт или которую система выделила PHP-процессу
  - memory_get_usage — Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу
  - memory_reset_peak_usage — Сбрасывает пиковое значение объёма памяти, выделенной PHP
  - php_ini_loaded_file — Получить путь к загруженному файлу php.ini
  - php_ini_scanned_files — Возвращает список .ini-файлов, найденных в дополнительной ini-директории
  - php_sapi_name — Возвращает тип интерфейса между веб-сервером и PHP
  - php_uname — Возвращает информацию об операционной системе, в которой работает PHP
  - phpcredits — Выводит список разработчиков PHP
  - phpinfo — Выводит информацию о текущей конфигурации PHP
  - phpversion — Получает текущую версию PHP
  - putenv — Устанавливает значение переменной среды
  - restore_include_path — Восстанавливает начальное значение параметра конфигурации include_path
  - set_include_path — Устанавливает значение настройки конфигурации include_path
  - set_time_limit — Ограничивает время выполнения скрипта
  - sys_get_temp_dir — Возвращает путь к директории временных файлов
  - version_compare — Сравнивает две «стандартизованные» строки с номером версии PHP
  - zend_thread_id — Возвращает уникальный идентификатор текущего потока выполнения
  - zend_version — Получает версию движка Zend

# Интерактивный отладчик PHP

# Введение

Поскольку phpdbg реализован в виде модуля SAPI, то он может полностью контролировать окружение без воздействия на функциональность и скорость выполнения вашего кода.

Phpdbg претендует на то, чтобы считаться легковесным, мощным и простым в использовании отладчиком для PHP. Он предоставляет следующие возможности:

- Пошаговая отладка
- Гибкие точки прерывания (метод класса, функция, строка файла, адрес, опкод)
- Лёгкий доступ к PHP с помощью встроенной функции eval()
- Пользовательское API
- Независимость от SAPI - легко интегрируется
- Поддержка конфигурационных файлов PHP
- Определение собственных суперглобальных переменных JIT
- Опциональная поддержка ввода с клавиатуры - удобная работа через терминал
- Лёгок в использовании - читайте документацию :)

Опции командной строки
Опция | Пример аргумента | Описание
--- | --- | ---
-c | -c/my/php.ini | Указывает php.ini, который надо загрузить
-d | -dmemory_limit=4G | Установка соответствующей директивы php.ini
-n |  | Запрет использования стандартного php.ini
-q |  | Не показывать приветственный баннер
-v |  | Разрешить вывод oplog
-b |  | Запретить использование цветов
-i | -imy.init | Задать файл .phpdbginit
-I |  | Игнорировать стандартный .phpdbginit
-O | -Omy.oplog | Задать файл для записи oplog
-r |  | Запустить контекст исполнения
-rr |  | Запустить контекст исполнения и выйти после запуска (не обращать внимание на точки останова)
-e |  | Генерировать расширенную информацию для отладчика/профилировщика
-E |  | Разрешить пошаговый eval. Будьте осторожны!
-s | -s=, -s=foo | Прочитать код для исполнения из стандартного потока ввода с опциональным разделителем
-S | -Scli | Переопределить имя SAPI. Будьте осторожны!
-l | -l4000 | Задать порт удалённой консоли
-a | -a192.168.0.3 | Задать адрес удалённой консоли
-x |  | Включить вывод в формате xml (вместо стандартного текстового)
-p | -p, -p=func, -p* | Вывести опкоды и выйти
-h |  | Вывести справочный раздел
-V |  | Напечатать номер версии
-- | -- arg1 arg2 | Используется для разделения аргументов phpdbg и php $argv; любые $argv добавляйте после него

# Установка и настройка

## Содержание

- Настройка во время выполнения

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

phpdbg Опции настройки
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Удалено, начиная с PHP 8.1.0
phpdbg.path |  | 6 | Удалено, начиная с PHP 8.1.0

Краткое разъяснение конфигурационных директив.

`phpdbg.eol` mixed

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

  int Значение | string Псевдоним
  --- | ---
  `0` | `CRLF`, `crlf`, `DOS`, `dos`
  `1` | `LF`, `lf`, `UNIX`, `unix`
  `2` | `CR`, `cr`, `MAC`, `mac`

`phpdbg.path` string

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`PHPDBG_VERSION` (string)
`PHPDBG_FILE` (int)
  Удалено в PHP 7.3.0.
`PHPDBG_METHOD` (int)
  Удалено в PHP 7.3.0.
`PHPDBG_LINENO` (int)
  Удалено в PHP 7.3.0.
`PHPDBG_FUNC` (int)
  Удалено в PHP 7.3.0.
`PHPDBG_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# Функции phpdbg

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Добавить точку прерывания на конкретную строку файла

### Описание

function phpdbg_break_file(string `$file`, int `$line`): void

Добавляет точку прерывания на строку `line` файла `file`.

### Список параметров

`file`
  Имя файла.
`line`
  Номер строки.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_break_function() - Добавить точку прерывания на вызов функции
- phpdbg_break_method() - Добавить точку прерывания на вызов метода класса
- phpdbg_break_next() - Добавить точку прерывания на следующий опкод
- phpdbg_clear() - Убрать все точки прерывания

# phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Добавить точку прерывания на вызов функции

### Описание

function phpdbg_break_function(string `$function`): void

Добавляет точку прерывания на вызов функции `function`.

### Список параметров

`function`
  Имя функции.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_break_file() - Добавить точку прерывания на конкретную строку файла
- phpdbg_break_method() - Добавить точку прерывания на вызов метода класса
- phpdbg_break_next() - Добавить точку прерывания на следующий опкод
- phpdbg_clear() - Убрать все точки прерывания

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Добавить точку прерывания на вызов метода класса

### Описание

function phpdbg_break_method(string `$class`, string `$method`): void

Добавляет точку прерывания на вызов метода `method` класса `class`.

### Список параметров

`class`
  Имя класса.
`method`
  Имя метода.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_break_file() - Добавить точку прерывания на конкретную строку файла
- phpdbg_break_function() - Добавить точку прерывания на вызов функции
- phpdbg_break_next() - Добавить точку прерывания на следующий опкод
- phpdbg_clear() - Убрать все точки прерывания

# phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Добавить точку прерывания на следующий опкод

### Описание

function phpdbg_break_next(): void

Добавляет точку прерывания на следующий опкод.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_break_file() - Добавить точку прерывания на конкретную строку файла
- phpdbg_break_function() - Добавить точку прерывания на вызов функции
- phpdbg_break_method() - Добавить точку прерывания на вызов метода класса
- phpdbg_clear() - Убрать все точки прерывания

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Убрать все точки прерывания

### Описание

function phpdbg_clear(): void

Удаляет все заданные ранее точки прерывания. Работает как для заданных с помощью функций phpdbg_break_*(), так и для добавленных вручную через консоль.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_break_file() - Добавить точку прерывания на конкретную строку файла
- phpdbg_break_function() - Добавить точку прерывания на вызов функции
- phpdbg_break_method() - Добавить точку прерывания на вызов метода класса
- phpdbg_break_next() - Добавить точку прерывания на следующий опкод

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Задать цвет для элемента

### Описание

function phpdbg_color(int `$element`, string `$color`): void

Устанавливает цвет `color` для элемента `element`.

### Список параметров

`element`
  Одна из констант `PHPDBG_COLOR_*`.
`color`
  Имя цвета. Одно из: `white`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan` или `black`. Опционально можно использовать суффиксы `-bold` или `-underline`. К примеру `white-bold` или `green-underline`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_prompt() - Установить приглашение командной строки

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Завершает oplog (журнал операций)

### Описание

function phpdbg_end_oplog(array `$options` = []): ?array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`options`

### Возвращаемые значения

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Попытаться задать контекст исполнения

### Описание

function phpdbg_exec(string `$context`): string|bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`context`

### Возвращаемые значения

Предыдущий контекст исполнения, если он был задан. `true`, если контекст исполнения ранее не был задан. Если запрос на установку контекста завершится с ошибкой, то будет возвращено `false` и вызвана ошибка уровня `E_WARNING`.

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — Получает исполняемый файл

### Описание

function phpdbg_get_executable(array `$options` = []): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`options`

### Возвращаемые значения

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Установить приглашение командной строки

### Описание

function phpdbg_prompt(string `$string`): void

Устанавливает приглашение командной строки как задано в `string`.

### Список параметров

`string`
  Строка, которая будет использована как приглашение.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- phpdbg_color() - Задать цвет для элемента

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Запускает oplog (журнал операций)

### Описание

function phpdbg_start_oplog(): void

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- phpdbg_break_file — Добавить точку прерывания на конкретную строку файла
- phpdbg_break_function — Добавить точку прерывания на вызов функции
- phpdbg_break_method — Добавить точку прерывания на вызов метода класса
- phpdbg_break_next — Добавить точку прерывания на следующий опкод
- phpdbg_clear — Убрать все точки прерывания
- phpdbg_color — Задать цвет для элемента
- phpdbg_end_oplog — Завершает oplog (журнал операций)
- phpdbg_exec — Попытаться задать контекст исполнения
- phpdbg_get_executable — Получает исполняемый файл
- phpdbg_prompt — Установить приглашение командной строки
- phpdbg_start_oplog — Запускает oplog (журнал операций)

- Установка и настройка
  - Настройка во время выполнения
- Предопределённые константы
- Функции phpdbg
  - phpdbg_break_file — Добавить точку прерывания на конкретную строку файла
  - phpdbg_break_function — Добавить точку прерывания на вызов функции
  - phpdbg_break_method — Добавить точку прерывания на вызов метода класса
  - phpdbg_break_next — Добавить точку прерывания на следующий опкод
  - phpdbg_clear — Убрать все точки прерывания
  - phpdbg_color — Задать цвет для элемента
  - phpdbg_end_oplog — Завершает oplog (журнал операций)
  - phpdbg_exec — Попытаться задать контекст исполнения
  - phpdbg_get_executable — Получает исполняемый файл
  - phpdbg_prompt — Установить приглашение командной строки
  - phpdbg_start_oplog — Запускает oplog (журнал операций)

# runkit7

# Введение

Модуль runkit7 предоставляет средства для изменения констант, пользовательских функций и пользовательских классов. Также предусмотрены пользовательские суперглобальные переменные.

Этот пакет является форком пакета » runkit, обеспечивающего поддержку PHP 7.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Изменение констант, функций, классов и методов так же как и Пользовательские суперглобальные переменные работает со всеми выпусками PHP 7. Никаких особых требований не требуется.

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/runkit7.

Бинарные файлы ОС Windows (DLL-файлы) для этого PECL-модуля доступны на сайте репозитория PECL.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации Runkit
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`runkit.superglobal` string
  Разделённый запятыми список имён переменных, которые будут рассматриваться как суперглобальные. Это значение должно быть установлено в общесистемном файле php.ini, но может работать в контекстах конфигурации perdir в зависимости от вашего SAPI.

  Пример #1 Пользовательские суперглобальные файлы с runkit.superglobal=_FOO,_BAR в php.ini

      <?php
      function show_values() {
        echo "Foo is $_FOO\n";
        echo "Bar is $_BAR\n";
        echo "Baz is $_BAZ\n";
      }

      $_FOO = 'foo';
      $_BAR = 'bar';
      $_BAZ = 'baz';

      /* Отобразит foo и bar, но не baz */
      show_values();
      ?>

`runkit.internal_override` bool
  Позволяет изменять/переименовывать/удалять внутренние функции.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`RUNKIT7_IMPORT_FUNCTIONS` (int)
  runkit7_import() флаг, указывающий, что нормальные функции должны быть импортированы из указанного файла.
`RUNKIT7_IMPORT_CLASS_METHODS` (int)
  runkit7_import() флаг, указывающий, что методы класса должны быть импортированы из указанного файла.
`RUNKIT7_IMPORT_CLASS_CONSTS` (int)
  runkit7_import() флаг, указывающий, что константы класса должны быть импортированы из указанного файла.
`RUNKIT7_IMPORT_CLASS_PROPS` (int)
  runkit7_import() флаг, указывающий, что стандартные свойства класса должны быть импортированы из указанного файла.
`RUNKIT7_IMPORT_CLASS_STATIC_PROPS` (int)
  runkit7_import() флаг, указывающий, что статические свойства класса должны быть импортированы из указанного файла. Доступно с Runkit 1.0.1.
`RUNKIT7_IMPORT_CLASSES` (int)
  runkit7_import() флаг, представляющий побитовое значение ИЛИ константы `RUNKIT7_IMPORT_CLASS_*`.
`RUNKIT7_IMPORT_OVERRIDE` (int)
  runkit7_import() флаг, указывающий, что если какие-либо импортированные функции, методы, константы или свойства уже существуют, они должны быть заменены новыми определениями. Если этот флаг не установлен, то любые импортированные определения, которые уже существуют, будут отброшены.
`RUNKIT7_ACC_RETURN_REFERENCE` (int)
  Включите этот флаг, чтобы создаваемая или повторно объявленная функция или метод возвращали ссылку.
`RUNKIT7_ACC_PUBLIC` (int)
  Флаг для runkit7_method_add() и runkit7_method_redefine(), чтобы сделать метод публичным.
`RUNKIT7_ACC_PROTECTED` (int)
  Флаг для runkit7_method_add() and runkit7_method_redefine(), чтобы сделать метод защищённым.
`RUNKIT7_ACC_PRIVATE` (int)
  Флаг для runkit7_method_add() and runkit7_method_redefine(), чтобы сделать метод приватным.
`RUNKIT7_ACC_STATIC` (int)
  Флаг для runkit7_method_add() and runkit7_method_redefine(), чтобы сделать метод статичным.
`RUNKIT7_FEATURE_MANIPULATION` (int)
  Равен 1, если включена манипуляция во время выполнения и 0 в противном случае.
`RUNKIT7_FEATURE_SUPERGLOBALS` (int)
  Равен 1, если пользовательские суперглобальные переменные включены и 0 в противном случае.
`RUNKIT7_FEATURE_SANDBOX` (int)
  Всегда 0, нереально реализовать функцию песочницы в php 7.

# Функции runkit7

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Аналогичен define(), но также позволяет определить константу класса

### Описание

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### Список параметров

`constant_name`
  Имя объявляемой константы. Либо строка для обозначения глобальной константы, либо `classname::constname` для определения константы класса.
`value`
  Значение константы (NULL, Bool, Long, Double, String, Array или Resource).
`newVisibility`
  Видимость константы для констант класса. По умолчанию общедоступный. Одна из констант `RUNKIT7_ACC_*`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- define() - Определяет именованную константу
- runkit7_constant_redefine() - Переопределяет уже определённую константу
- runkit7_constant_remove() - Удаляет уже определённую константу

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Переопределяет уже определённую константу

### Описание

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### Список параметров

`constant_name`
  Константа, которую необходимо переопределить. Либо имя глобальной константы, либо `classname::constname` для переопределения константы класса.
`value`
  Значение, присваиваемое константе.
`new_visibility`
  Новая видимость константы для констант класса. По умолчанию без изменений. Одна из констант `RUNKIT7_ACC_*`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- runkit7_constant_add() - Аналогичен define(), но также позволяет определить константу класса
- runkit7_constant_remove() - Удаляет уже определённую константу

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Удаляет уже определённую константу

### Описание

function runkit7_constant_remove(string `$constant_name`): bool

### Список параметров

`constant_name`
  Константа, которую необходимо удалить. Либо имя глобальной константы, либо `classname::constname` для удаления константы класса.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- define() - Определяет именованную константу
- runkit7_constant_add() - Аналогичен define(), но также позволяет определить константу класса
- runkit7_constant_redefine() - Переопределяет уже определённую константу

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Добавляет новую функцию, функция аналогична create_function()

### Описание

function runkit7_function_add(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_add(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Список параметров

`function_name`
  Имя создаваемой функции.
`argument_list`
  Список аргументов, разделённых запятыми.
`code`
  Код, составляющий функцию.
`closure`
  Замыкание (closure), определяющее функцию.
`return_by_reference`
  Определяет, должна ли функция возвращаться по ссылке.
`doc_comment`
  Документальный комментарий функции.
`return_type`
  Тип возвращаемого значения функции.
`is_strict`
  Определяет, должна ли функция вести себя так, как если бы она была объявлена в файле с `strict_types=1`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_function_add()

    <?php
    runkit7_function_add('testme','$a,$b','echo "Значение A - $a\n"; echo "Значение B - $b\n";');
    testme(1,2);
    ?>

Результат выполнения приведённого примера:

    Значение A - 1
    Значение B - 2

### Смотрите также

- create_function() - Создаёт функцию динамически, оценивая строку кода
- runkit7_function_redefine() - Заменяет определение функции новой реализацией
- runkit7_function_copy() - Копирует функцию в новое имя функции
- runkit7_function_rename() - Изменяет имя функции
- runkit7_function_remove() - Удаляет определение функции
- runkit7_method_add() - Динамически добавляет новый метод в заданный класс

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Копирует функцию в новое имя функции

### Описание

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### Список параметров

`source_name`
  Имя существующей функции.
`target_name`
  Имя новой функции, в которую нужно скопировать определение.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_function_copy()

    <?php
    function original() {
      echo "В функции\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

Результат выполнения приведённого примера:

    В функции
    В функции

### Смотрите также

- runkit7_function_add() - Добавляет новую функцию, функция аналогична create_function
- runkit7_function_redefine() - Заменяет определение функции новой реализацией
- runkit7_function_rename() - Изменяет имя функции
- runkit7_function_remove() - Удаляет определение функции

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Заменяет определение функции новой реализацией

### Описание

function runkit7_function_redefine(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_redefine(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

> Замечание: По умолчанию, только пользовательские функции могут быть удалены, переименованы или изменены. Для перекрытия внутренних функций, необходимо включить в php.ini опцию `runkit.internal_override`.

### Список параметров

`function_name`
  Имя функции для переопределения.
`argument_list`
  Новый список аргументов, принимаемых функцией.
`code`
  Реализация нового кода.
`closure`
  Замыкание (closure), определяющее функцию.
`return_by_reference`
  Определяет, должна ли функция возвращаться по ссылке.
`doc_comment`
  Документальный комментарий функции.
`return_type`
  Тип возвращаемого значения функции.
`is_strict`
  Определяет, должна ли функция вести себя так, как если бы она была объявлена в файле с `strict_types=1`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_function_redefine()

    <?php
    function testme() {
      echo "Оригинальная реализация Testme\n";
    }
    testme();
    runkit7_function_redefine('testme','','echo "Новая реализация Testme\n";');
    testme();
    ?>

Результат выполнения приведённого примера:

    Оригинальная реализация Testme
    Новая реализация Testme

### Смотрите также

- runkit7_function_add() - Добавляет новую функцию, функция аналогична create_function
- runkit7_function_copy() - Копирует функцию в новое имя функции
- runkit7_function_rename() - Изменяет имя функции
- runkit7_function_remove() - Удаляет определение функции
- runkit7_method_redefine() - Динамически изменяет код заданного метода

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Удаляет определение функции

### Описание

function runkit7_function_remove(string `$function_name`): bool

> Замечание: По умолчанию, только пользовательские функции могут быть удалены, переименованы или изменены. Для перекрытия внутренних функций, необходимо включить в php.ini опцию `runkit.internal_override`.

### Список параметров

`function_name`
  Имя удаляемой функции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- runkit7_function_add() - Добавляет новую функцию, функция аналогична create_function
- runkit7_function_copy() - Копирует функцию в новое имя функции
- runkit7_function_redefine() - Заменяет определение функции новой реализацией
- runkit7_function_rename() - Изменяет имя функции

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Изменяет имя функции

### Описание

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> Замечание: По умолчанию, только пользовательские функции могут быть удалены, переименованы или изменены. Для перекрытия внутренних функций, необходимо включить в php.ini опцию `runkit.internal_override`.

### Список параметров

`source_name`
  Текущее имя функции.
`target_name`
  Новое имя функции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- runkit7_function_add() - Добавляет новую функцию, функция аналогична create_function
- runkit7_function_copy() - Копирует функцию в новое имя функции
- runkit7_function_redefine() - Заменяет определение функции новой реализацией
- runkit7_function_remove() - Удаляет определение функции

# runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Обрабатывает функцию импорта файла PHP и определения классов, при необходимости перезаписывая

Внимание

Функционал был удалён в PECL runkit7 4.0.0.

### Описание

function runkit7_import(string `$filename`, int `$flags` = ?): bool

Функция подобна include. Однако любой код, находящийся за пределами функции или класса, просто игнорируется. Кроме того, в зависимости от значения `flags`, любые функции или классы, которые уже существуют в текущей запущенной среде, могут быть автоматически перезаписаны их новыми определениями.

### Список параметров

`filename`
  Имя файла для импорта определений функций и классов.
`flags`
  Побитовое ИЛИ констант `RUNKIT7_IMPORT_*`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Динамически добавляет новый метод в заданный класс

### Описание

function runkit7_method_add(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_add(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Список параметров

`class_name`
  Класс, в котором нужно добавить метод.
`method_name`
  Имя метода, который нужно добавить.
`argument_list`
  Разделённый запятыми список аргументов для нового метода.
`code`
  Код, который будет выполняться при вызове `method_name`.
`closure`
  Замыкание (closure), определяющее метод.
`flags`
  Метод может быть `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` или `RUNKIT7_ACC_PRIVATE`, и, при необходимости, объединён с помощью побитового ИЛИ с `RUNKIT7_ACC_STATIC`.
`doc_comment`
  Документальный комментарий метода.
`return_type`
  Тип возвращаемого значения метода.
`is_strict`
  Определяет, будет ли метод вести себя так, как если бы он был объявлен в файле с `strict_types=1`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_method_add()

    <?php
    class Example {
        function foo() {
            echo "foo!\n";
        }
    }

    // создание объекта Example
    $e = new Example();

    // добавление нового общедоступного метода
    runkit7_method_add(
        'Example',
        'add',
        '$num1, $num2',
        'return $num1 + $num2;',
        RUNKIT7_ACC_PUBLIC
    );

    // добавление 12 + 4
    echo $e->add(12, 4);
    ?>

Результат выполнения приведённого примера:

    16

### Смотрите также

- runkit7_method_copy() - Копирует метод из одного класса в другой
- runkit7_method_redefine() - Динамически изменяет код заданного метода
- runkit7_method_remove() - Динамически удаляет заданный метод
- runkit7_method_rename() - Динамически изменяет имя заданного метода
- runkit7_function_add() - Добавляет новую функцию, функция аналогична create_function

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Копирует метод из одного класса в другой

### Описание

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### Список параметров

`destination_class`
  Целевой класс для скопированного метода.
`destination_method_name`
  Название метода назначения.
`source_class`
  Исходный класс скопированного метода.
`source_method_name`
  Имя метода для копирования из исходного класса. Если этот параметр опущен, предполагается значение `destination_method_name`.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования runkit7_method_copy()

    <?php
    class Foo {
        function example() {
            return "foo!\n";
        }
    }

    class Bar {
        // изначально никаких методов
    }

    // копирование метода example() из класса Foo в класс Bar как baz()
    runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

    // функция вывода скопирована
    echo Bar::baz();
    ?>

Результат выполнения приведённого примера:

    foo!

### Смотрите также

- runkit7_method_add() - Динамически добавляет новый метод в заданный класс
- runkit7_method_redefine() - Динамически изменяет код заданного метода
- runkit7_method_remove() - Динамически удаляет заданный метод
- runkit7_method_rename() - Динамически изменяет имя заданного метода
- runkit7_function_copy() - Копирует функцию в новое имя функции

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Динамически изменяет код заданного метода

### Описание

function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Список параметров

`class_name`
  Класс, в котором нужно переопределить метод.
`method_name`
  Имя метода, который нужно переопределить.
`argument_list`
  Разделённый запятыми список аргументов для переопределённого метода.
`code`
  Новый код, который будет выполняться при вызове `method_name`.
`closure`
  Замыкание (closure), определяющее метод.
`flags`
  Переопределённый метод может быть `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` или `RUNKIT7_ACC_PRIVATE`, и, при необходимости, объединён с помощью побитового ИЛИ с `RUNKIT7_ACC_STATIC`.
`doc_comment`
  Документальный комментарий метода.
`return_type`
  Тип возвращаемого значения метода.
`is_strict`
  Определяет, будет ли метод вести себя так, как если бы он был объявлен в файле с `strict_types=1`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_method_redefine()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // создание объекта Example
    $e = new Example();

    // вывод Example::foo() (до переопределения)
    echo "До: " . $e->foo();

    // Переопределение метода 'foo'
    runkit7_method_redefine(
        'Example',
        'foo',
        '',
        'return "bar!\n";',
        RUNKIT7_ACC_PUBLIC
    );

    // вывод Example::foo() (после переопределения)
    echo "После: " . $e->foo();
    ?>

Результат выполнения приведённого примера:

    До: foo!
    После: bar!

### Смотрите также

- runkit7_method_add() - Динамически добавляет новый метод в заданный класс
- runkit7_method_copy() - Копирует метод из одного класса в другой
- runkit7_method_remove() - Динамически удаляет заданный метод
- runkit7_method_rename() - Динамически изменяет имя заданного метода
- runkit7_function_redefine() - Заменяет определение функции новой реализацией

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Динамически удаляет заданный метод

### Описание

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> Замечание: Эту функцию нельзя использовать для влияния на работающие в этот момент (или цепные) методы.

### Список параметров

`class_name`
  Класс, в котором нужно удалить метод.
`method_name`
  Имя удаляемого метода.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_method_remove()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }

        function bar() {
            return "bar!\n";
        }
    }

    // Remove the 'foo' method
    runkit7_method_remove(
        'Example',
        'foo'
    );

    echo implode(' ', get_class_methods('Example'));

    ?>

Результат выполнения приведённого примера:

    bar

### Смотрите также

- runkit7_method_add() - Динамически добавляет новый метод в заданный класс
- runkit7_method_copy() - Копирует метод из одного класса в другой
- runkit7_method_redefine() - Динамически изменяет код заданного метода
- runkit7_method_rename() - Динамически изменяет имя заданного метода
- runkit7_function_remove() - Удаляет определение функции

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Динамически изменяет имя заданного метода

### Описание

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> Замечание: Эту функцию нельзя использовать для влияния на работающие в этот момент (или цепные) методы.

### Список параметров

`class_name`
  Класс, в котором нужно переименовать метод.
`source_method_name`
  Метод, который нужно переименовать.
`target_method_name`
  Новое имя метода.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования runkit7_method_rename()

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // Переименование метода 'foo' в 'bar'
    runkit7_method_rename(
        'Example',
        'foo',
        'bar'
    );

    // Вывод переименованной функции
    echo (new Example)->bar();
    ?>

Результат выполнения приведённого примера:

    foo!

### Смотрите также

- runkit7_method_add() - Динамически добавляет новый метод в заданный класс
- runkit7_method_copy() - Копирует метод из одного класса в другой
- runkit7_method_redefine() - Динамически изменяет код заданного метода
- runkit7_method_remove() - Динамически удаляет заданный метод
- runkit7_function_rename() - Изменяет имя функции

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Возвращает дескриптор целочисленного объекта для данного объекта

### Описание

function runkit7_object_id(object `$obj`): int

Функция эквивалентна spl_object_id().

Функция возвращает уникальный идентификатор объекта. Идентификатор объекта уникален на протяжении всего времени существования объекта. После уничтожения объекта его идентификатор может быть повторно использован для других объектов. Поведение похоже на spl_object_hash().

### Список параметров

`obj`
  Любой объект.

### Возвращаемые значения

Целочисленный идентификатор, уникальный для каждого существующего в данный момент объекта и всегда одинаковый для каждого объекта.

### Примечания

> Замечание: Когда объект уничтожен, его идентификатор может быть повторно использован для других объектов.

### Смотрите также

- spl_object_id() - Получает целочисленный идентификатор объекта

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Возвращает числовой индексированный массив зарегистрированных суперглобальных переменных

### Описание

function runkit7_superglobals(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает числовой индексированный массив зарегистрированных суперглобальных переменных. Например: _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES.

### Смотрите также

- Область видимости переменной

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Возвращает информацию о переданном значении с типами данных, количеством ссылок и так далее

### Описание

function runkit7_zval_inspect(string `$value`): array

### Список параметров

`value`
  Значение, чтобы вернуть представление.

### Возвращаемые значения

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `address`
- `refcount` (необязательный)
- `is_ref` (необязательный)
- `type`

### Примеры

Пример #1 Пример использования runkit7_zval_inspect()

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

Результат выполнения приведённого примера:

    array(4) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["refcount"]=>
      int(2)
      ["is_ref"]=>
      bool(false)
      ["type"]=>
      int(8)
    }

    array(2) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["type"]=>
      int(4)
    }

### Смотрите также

- Объяснение ссылок
- » Объяснение ссылок (Дерик Ретанс)

## Содержание

- runkit7_constant_add — Аналогичен define(), но также позволяет определить константу класса
- runkit7_constant_redefine — Переопределяет уже определённую константу
- runkit7_constant_remove — Удаляет уже определённую константу
- runkit7_function_add — Добавляет новую функцию, функция аналогична create_function
- runkit7_function_copy — Копирует функцию в новое имя функции
- runkit7_function_redefine — Заменяет определение функции новой реализацией
- runkit7_function_remove — Удаляет определение функции
- runkit7_function_rename — Изменяет имя функции
- runkit7_import — Обрабатывает функцию импорта файла PHP и определения классов, при необходимости перезаписывая
- runkit7_method_add — Динамически добавляет новый метод в заданный класс
- runkit7_method_copy — Копирует метод из одного класса в другой
- runkit7_method_redefine — Динамически изменяет код заданного метода
- runkit7_method_remove — Динамически удаляет заданный метод
- runkit7_method_rename — Динамически изменяет имя заданного метода
- runkit7_object_id — Возвращает дескриптор целочисленного объекта для данного объекта
- runkit7_superglobals — Возвращает числовой индексированный массив зарегистрированных суперглобальных переменных
- runkit7_zval_inspect — Возвращает информацию о переданном значении с типами данных, количеством ссылок и так далее

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции runkit7
  - runkit7_constant_add — Аналогичен define(), но также позволяет определить константу класса
  - runkit7_constant_redefine — Переопределяет уже определённую константу
  - runkit7_constant_remove — Удаляет уже определённую константу
  - runkit7_function_add — Добавляет новую функцию, функция аналогична create_function
  - runkit7_function_copy — Копирует функцию в новое имя функции
  - runkit7_function_redefine — Заменяет определение функции новой реализацией
  - runkit7_function_remove — Удаляет определение функции
  - runkit7_function_rename — Изменяет имя функции
  - runkit7_import — Обрабатывает функцию импорта файла PHP и определения классов, при необходимости перезаписывая
  - runkit7_method_add — Динамически добавляет новый метод в заданный класс
  - runkit7_method_copy — Копирует метод из одного класса в другой
  - runkit7_method_redefine — Динамически изменяет код заданного метода
  - runkit7_method_remove — Динамически удаляет заданный метод
  - runkit7_method_rename — Динамически изменяет имя заданного метода
  - runkit7_object_id — Возвращает дескриптор целочисленного объекта для данного объекта
  - runkit7_superglobals — Возвращает числовой индексированный массив зарегистрированных суперглобальных переменных
  - runkit7_zval_inspect — Возвращает информацию о переданном значении с типами данных, количеством ссылок и так далее

# User Operations для Zend

# Введение

Модуль uopz (User Operations for Zend) предоставляет функциональность Zend Engine, обычно используемую во время компиляции и выполнении, чтобы разрешить модификацию внутренних структур, представляющих PHP-код, и для взаимодействия пользовательского кода с виртуальной машиной.

uopz поддерживает следующие действия:

- Перегрузка некоторых опкодов, включая ZEND_EXIT и ZEND_NEW
- Функции и методы резервного копирования и восстановления
- Переименование функций и методов
- Копирование функций и методов
- Удаление функций и методов
- Переопределение глобальных и классовых констант
- Удаление глобальных и классовых констант
- Создание и модификация классов во время выполнения

> Замечание:

> Все поддерживаемые действия совместимы с opcache

Предостережение

PECL uopz 6.1.1 несовместим с Xdebug >= 2.9.4. Более поздние версии uopz несовместимы с Xdebug < 2.9.4.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

C uopz 5.0 требуется PHP 7.0. Начиная с uopz 5.1 требуется PHP 7.1+.

## Установка

Выпуски модуля uopz распространяются через репозиторий PECL, а исходный код находится на сайте » Github, самый простой путь установки — из репозитория PECL: » https://pecl.php.net/package/uopz.

Пользователям ОС Windows модуль в виде готового исполняемого файла доступен на сайте репозитория » PECL.

Начиная с 5.0.0 модуль требуется загружать как обычный PHP-модуль — через директиву extension. До этой версии модуль требовалось загружать как Zend-модуль — через директиву zend_extension.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки модуля uopz
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
uopz.disable | "0" | `INI_SYSTEM` | Доступна с uopz 5.0.2
uopz.exit | "0" | `INI_SYSTEM` | Доступна с uopz 6.0.1
uopz.overloads | "1" | `INI_SYSTEM` | Доступна с uopz 2.0.2. Удалили с uopz 5.0.0.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`uopz.disable` bool

  При включении опции модуль uopz перестанет влиять на работу движка PHP.

`uopz.exit` bool

  Разрешать ли модулю исполнять опкод exit. Настройку разрешается переопределять во время исполнения функцией uopz_allow_exit().

`uopz.overloads` bool

  Разрешает использовать функцию uopz_overload().

> Замечание: При работе модуля с модулем OPcache иногда требуется отключение оптимизаций модуля OPcache через директиву файла конфигурации: `opcache.optimization_level=0`.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Следующие опкоды определяются как константы с помощью uopz до версии 5.0.0:

`ZEND_EXIT` (int)
  Вызывается с помощью exit() and die(), не принимает аргументов. Возвращает логический `true` для выхода, `false` для продолжения
`ZEND_NEW` (int)
  Вызывается конструкцией объекта, получает класс создаваемого объекта в качестве единственного аргумента
`ZEND_THROW` (int)
  Вызывается конструкцией throw, получает класс выбрасываемого исключения в качестве единственного аргумента
`ZEND_FETCH_CLASS` (int)
  Вызывается во время композиции, получает имя получаемого в качестве единственного аргумента
`ZEND_ADD_TRAIT` (int)
  Вызывается во время композиции, получает класс добавляемого трейта первым аргументом, и имя трейта в качестве второго аргумента
`ZEND_ADD_INTERFACE` (int)
  Вызывается во время композиции, получает класс добавляемого интерфейса первым аргументом, и имя интерфейса в качестве второго аргумента
`ZEND_INSTANCEOF` (int)
  Вызывается оператором instanceof, получает проверяемый объект первым аргументом и имя класса, который должен быть в объекте в качестве второго аргумента

Следующие константы управляют поведением виртуальной машины после вызова обработчика пользователя, будьте предельно осторожны! Эти константы удалены с uopz версии 5.0.0.

`ZEND_USER_OPCODE_CONTINUE` (int)
  Продвинуть 1 опкод и продолжить
`ZEND_USER_OPCODE_ENTER` (int)
  Ввести новый new op_array без рекурсии
`ZEND_USER_OPCODE_LEAVE` (int)
  Вернуть вызывающий op_array внутри того же исполнителя
`ZEND_USER_OPCODE_DISPATCH` (int)
  Отправить в исходный обработчик опкода
`ZEND_USER_OPCODE_DISPATCH_TO` (int)
  Отправить на конкретный обработчик (посредством бинарного OR с константой опкода ZEND)
`ZEND_USER_OPCODE_RETURN` (int)
  Выйти из исполнителя (возврат из функции)

Следующие модификаторы регистрируются как константы uopz

`ZEND_ACC_PUBLIC` (int)
  Отметить функцию как общедоступную, по умолчанию
`ZEND_ACC_PROTECTED` (int)
  Отметить функцию как защищённую
`ZEND_ACC_PRIVATE` (int)
  Отметить функцию как закрытую
`ZEND_ACC_STATIC` (int)
  Отметить функцию как статическую
`ZEND_ACC_FINAL` (int)
  Отметить функцию как окончательную
`ZEND_ACC_ABSTRACT` (int)
  Отметить функцию как абстрактную
`ZEND_ACC_CLASS` (int)
  Фиктивная регистрация для согласованности, запись класса по умолчанию. Удалено в uopz 5.0.0.
`ZEND_ACC_INTERFACE` (int)
  Отметить класс как интерфейс. Удалено в uopz 5.0.0.
`ZEND_ACC_TRAIT` (int)
  Отметить класс как трейт. Удалено в uopz 5.0.0.
`ZEND_ACC_FETCH` (int)
  Используется только для получения флагов. Удалено в uopz 5.0.0.

# Функции Uopz

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Добавляет несуществующую функцию или метод

### Описание

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function uopz_add_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `&$flags` = ZEND_ACC_PUBLIC,
int `&$all` = `true`
): bool

Добавляет несуществующую функцию или метод.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

`handler`

  Объект Closure, который определяет новую функцию или метод.

`flags`

  Флаги для установки новой функции или метода.

`all`

  Будут ли затронуты все классы, которые происходят от класса (`class`).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

uopz_add_function() выбрасывает RuntimeException, если добавляемая функция или метод уже существует.

### Примеры

Пример #1 Простое использование uopz_add_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

Результат выполнения приведённого примера:

    bar

### Смотрите также

- uopz_del_function() - Удаляет ранее добавленную функцию или метод
- uopz_set_return() - Предоставить возвращаемое значение для существующей функции

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Позволяет управлять отключённым опкодом exit

### Описание

function uopz_allow_exit(bool `$allow`): void

По умолчанию uopz отключает опкод exit, поэтому вызовы exit() практически игнорируются. uopz_allow_exit() позволяет контролировать это поведение.

### Список параметров

`allow`

  Разрешить выполнение опкодов exit или нет.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования uopz_allow_exit()

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

Результат выполнения приведённого примера:

    1

### Примечания

Предостережение

OPcache оптимизирует мёртвый код после безусловного завершения.

### Смотрите также

- uopz_get_exit_status() - Получить последний установленный статус выхода

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Резервирует функцию

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Резервирует функцию во время выполнения, которая будет восстановлена при завершении работы скрипта

### Список параметров

`class`

  Имя класса, содержащего функцию для резервирования

`function`

  Имя функции

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_backup()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

Результат выполнения приведённого примера:

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Составить класс

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_compose(
string `$name`,
array `$classes`,
array `$methods` = ?,
array `$properties` = ?,
int `$flags` = ?
): void

Создаёт класс заданного имени, который реализует, наследует или использует все предоставленные классы

### Список параметров

`name`

  Корректное имя класса

`classes`

  Массив имён классов, интерфейсов и трейтов

`methods`

  Ассоциативный массив методов, где значения либо замыкания, либо представлены структурой [модификаторы => замыкание]

`properties`

  Ассоциативный массив свойств, где ключи - имена, а значения - модификаторы

`flags`

  Тип записи, по умолчанию ZEND_ACC_CLASS

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_compose()

    <?php
    class myClass {}
    trait myTrait {}
    interface myInterface {}

    uopz_compose(
        Composed::class, [
            myClass::class,
            myTrait::class,
            myInterface::class
        ], [
        "__construct" => function() {
            /* ... */
        }
    ]);

    var_dump(
     class_uses(Composed::class),
     class_parents(Composed::class),
     class_implements(Composed::class));
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["myTrait"]=>
      string(7) "myTrait"
    }
    array(1) {
      ["myClass"]=>
      string(7) "myClass"
    }
    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Скопировать функцию

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Скопировать функцию по имени

### Список параметров

`class`

  Имя класса, содержащего функцию для копирования

`function`

  Имя функции

### Возвращаемые значения

Объект Closure для определённой функции

### Примеры

Пример #1 Пример использования uopz_copy()

    <?php
    $strtotime = uopz_copy('strtotime');

    uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
        /* здесь можно вызвать оригинальную функцию strtotime */
        var_dump($arg1);
    });

    var_dump(strtotime('dummy'));
    ?>

Результат выполнения приведённого примера:

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Удаляет ранее добавленную функцию или метод

### Описание

function uopz_del_function(string `$function`): bool
function uopz_del_function(string `$class`, string `$function`, int `&$all` = `true`): bool

Удаляет ранее добавленную функцию или метод.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

`all`

  Будут ли затронуты все классы, которые происходят от класса (`class`).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

uopz_del_function() выбрасывает RuntimeException, если удаляемые функция или метод не были добавлены с помощью uopz_add_function().

### Примеры

Пример #1 Простое использование uopz_del_function()

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    var_dump(function_exists('foo'));
    uopz_del_function('foo');
    var_dump(function_exists('foo'));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

### Смотрите также

- uopz_add_function() - Добавляет несуществующую функцию или метод
- uopz_unset_return() - Отменяет ранее установленное возвращаемое значение для функции

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Удалить функцию

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Удаляет функцию или метод

### Список параметров

`class`

`function`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_delete()

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

Вывод приведённого примера будет похож на:

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Пример #2 Пример использования uopz_delete() с классом

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_delete(My::class, "strlen");

    echo My::strlen("Hello World");
    ?>

Вывод приведённого примера будет похож на:

    PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

# uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — Расширить класс во время выполнения

### Описание

function uopz_extend(string `$class`, string `$parent`): bool

Расширяет текущий класс `class` родительским `parent`

### Список параметров

`class`

  Название класса для расширения

`parent`

  Название класса для наследования

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Начиная с PHP 7.4.0, uopz_extend() выбрасывает RuntimeException, если OPcache включён и запись класса либо `class`, либо `parent` (если это признак) неизменны.

### Примеры

Пример #1 Пример использования uopz_extend()

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["B"]=>
      string(1) "B"
    }

# uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — Получить или установить флаги для функции или класса

### Описание

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function uopz_flags(string `$class`, string `$function`, int `$flags` = PHP_INT_MAX): int

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

### Список параметров

`class`

  Имя класса

`function`

  Имя функции. Если задан `class` и пустая строка передана как `function`, uopz_flags() получает или устанавливает флаги записи класса.

`flags`

  Корректный набор флагов ZEND_ACC_. Если не заданы, uopz_flags() используется как геттер.

### Возвращаемые значения

При установке новых флагов, возвращает старые флаги, иначе возвращает текущие флаги

### Ошибки

Начиная с PHP 7.4.0, если передан параметр `flags`, uopz_flags() выбрасывает RuntimeException, если OPcache включён и запись класса либо `class`, либо `parent` (если это признак) неизменны.

### Список изменений

Версия | Описание
--- | ---
PECL uopz 5.0.0 | Параметр `flags` теперь необязательный. Ранее `ZEND_ACC_FETCH` должен был передаваться, чтобы uopz_flags() использовался как геттер.

### Примеры

Пример #1 Пример использования uopz_flags()

    <?php
    class Test {
        public function method() {
            return __CLASS__;
        }
    }

    $flags = uopz_flags("Test", "method");

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

    var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

Пример #2 "Отменить final" класса

    <?php
    final class MyClass
    {
    }

    $flags = uopz_flags(MyClass::class, '');
    uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
    var_dump((new ReflectionClass(MyClass::class))->isFinal());
    ?>

Результат выполнения приведённого примера:

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Создаёт функцию во время выполнения

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function uopz_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `$modifiers` = ?
): void

Создаёт функцию во время выполнения

### Список параметров

`class`

  Имя класса для получения новой функции

`function`

  Имя функции

`handler`

  Замыкание для функции

`modifiers`

  Модификаторы для функции, по умолчанию скопированы или ZEND_ACC_PUBLIC

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_function()

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Привет, Мир");
    ?>

Результат выполнения приведённого примера:

    11

Пример #2 Пример использования uopz_function() с классом

    <?php
    class My {}

    uopz_function(My::class, "strlen", function($arg) {
        return strlen($arg);
    }, ZEND_ACC_STATIC);

    echo My::strlen("Привет, Мир");
    ?>

Результат выполнения приведённого примера:

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Получить последний установленный статус выхода

### Описание

function uopz_get_exit_status(): mixed

Получает последний установленный статус выхода, то есть значение, переданное в exit().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Эта функция возвращает последний статус выхода или `null`, если exit() не был вызван.

### Примеры

Пример #1 Пример использования uopz_get_exit_status()

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

Результат выполнения приведённого примера:

    123

### Примечания

Предостережение

OPcache оптимизирует мёртвый код после безусловного завершения.

### Смотрите также

- uopz_allow_exit() - Позволяет управлять отключённым опкодом exit

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Получает ранее установленный обработчик на функцию или метод

### Описание

function uopz_get_hook(string `$function`): Closure
function uopz_get_hook(string `$class`, string `$function`): Closure

Получает ранее установленный обработчик на функцию или метод.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

### Возвращаемые значения

Возвращает ранее установленный обработчик на функцию или метод, либо `null`, если обработчик не был установлен.

### Примеры

Пример #1 Простое использование uopz_get_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

Вывод приведённого примера будет похож на:

    object(Closure)#2 (0) {
    }

### Смотрите также

- uopz_set_hook() - Устанавливает обработчик для выполнения при вызове функции или метода
- uopz_unset_hook() - Удаляет ранее установленную функцию или метод

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Получить текущий имитатор (mock) для класса

### Описание

function uopz_get_mock(string `$class`): mixed

Возвращает текущий имитатор `class`.

### Список параметров

`class`

  Название имитированного класса

### Возвращаемые значения

Либо строка, содержащая название имитатора, либо объект, либо `null`, если имитатор не задан.

### Примеры

Пример #1 Пример использования uopz_get_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    echo uopz_get_mock(A::class);
    ?>

Результат выполнения приведённого примера:

    mockA

### Смотрите также

- uopz_set_mock() - Использовать имитатор вместо класса для новых объектов
- uopz_unset_mock() - Удалить ранее установленный имитатор

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Получает значение класса или свойство экземпляра

### Описание

function uopz_get_property(string `$class`, string `$property`): mixed
function uopz_get_property(object `$instance`, string `$property`): mixed

Получает значение существующего статического свойства класса, если указан класс (`class`), либо значение существующего свойства экземпляра, если передан экземпляр (`instance`).

### Список параметров

`class`

  Имя класса.

`instance`

  Экземпляр объекта.

`property`

  Имя свойства.

### Возвращаемые значения

Возвращает значение класса или свойство экземпляра, либо `null`, если свойство не определено.

### Примеры

Пример #1 Простое использование uopz_get_property()

    <?php
    class Foo {
        private static $staticBar = 10;
        private $bar = 100;
    }
    $foo = new Foo;
    var_dump(uopz_get_property('Foo', 'staticBar'));
    var_dump(uopz_get_property($foo, 'bar'));
    ?>

Вывод приведённого примера будет похож на:

    int(10)
    int(100)

### Смотрите также

- uopz_set_property() - Устанавливает значение существующего свойства класса или экземпляра

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Получает предыдущее установленное возвращаемое значение для функции

### Описание

function uopz_get_return(string `$function`): mixed
function uopz_get_return(string `$class`, string `$function`): mixed

Получает возвращаемое значение `function`, ранее установленное с помощью uopz_set_return().

### Список параметров

`class`

  Имя класса, содержащего функцию

`function`

  Имя функции

### Возвращаемые значения

Ранее установленное возвращаемое значение или объект Closure.

### Примеры

Пример #1 Пример использования uopz_get_return()

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

Результат выполнения приведённого примера:

    42

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — Получает статические переменные из области видимости функции или метода

### Описание

function uopz_get_static(string `$class`, string `$function`): array
function uopz_get_static(string `$function`): array

Функция получает статические переменные из области видимости функции или метода.

### Список параметров

`class`

  Название класса.

`function`

  Название функции или метода.

### Возвращаемые значения

В случае успешного выполнения функция возвращает ассоциативный массив (array), в котором имена переменных сопоставляются с текущими значениями, или `null`, если функция или метод не существует.

Начиная с PHP 8.3.0 статические инициализаторы вычисляются или в течение компиляции, или, если это невозможно, только при первом запуске функции или метода, и тогда перед первым вызовом значение статической переменной сообщается как `null`.

### Примеры

Пример #1 Простое использование функции uopz_get_static()

    <?php

    function foo()
    {
        static $bar = 'baz';
    }

    var_dump(uopz_get_static('foo'));

    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### Смотрите также

- ReflectionFunctionAbstract::getStaticVariables() - Получает статические переменные
- uopz_set_static() - Устанавливает статические переменные в области видимости функции или метода

# uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — Реализует интерфейс во время выполнения

### Описание

function uopz_implement(string `$class`, string `$interface`): bool

Делает `class`, реализующий `interface`

### Список параметров

`class`

`interface`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Начиная с PHP 7.4.0, uopz_implement() выбрасывает RuntimeException, если OPcache включён и запись класса `class` неизменна.

### Примеры

Пример #1 Пример использования uopz_implement()

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Перегрузить опкод VM

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_overload(int `$opcode`, Callable `$callable`): void

Перегружает определённый `opcode` с помощью пользовательской функции

### Список параметров

`opcode`

  Корректный опкод, смотрите константы для получения поддерживаемых опкодов

`callable`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_overload()

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Привет, Мир";
    ?>

Результат выполнения приведённого примера:

    Привет, Мир

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Переопределить константу

### Описание

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Переопределяет заданную константу `constant` на значение `value`

### Список параметров

`class`

  Имя класса, содержащего константу

`constant`

  Имя константы

`value`

  Новое значение константы, должно быть корректным типом для постоянной переменной

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования uopz_redefine()

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

Результат выполнения приведённого примера:

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Переименовать функцию во время выполнения

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Переименовывает функцию `function` на `rename`

> Замечание:

> Если обе функции существуют, эта функция по сути поменяет имена

### Список параметров

`class`

  Имя класса, содержащего функцию

`function`

  Имя существующей функции

`rename`

  Новое имя функции

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_rename()

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

Вывод приведённого примера будет похож на:

    11

Пример #2 Пример использования uopz_rename() с классом

    <?php
    class My {
        public function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_rename(My::class, "strlen", "original_strlen");

    echo My::original_strlen("Hello World");
    ?>

Результат выполнения приведённого примера:

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Восстановить ранее зарезервированную функцию

Внимание

Эта функция была УДАЛЕНА в PECL uopz 5.0.0.

### Описание

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Восстановить ранее зарезервированную функцию

### Список параметров

`class`

  Имя класса, содержащего функцию для восстановления

`function`

  Имя функции

### Возвращаемые значения

### Примеры

Пример #1 Пример использования uopz_restore()

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

Вывод приведённого примера будет похож на:

    Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8

# uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Устанавливает обработчик для выполнения при вызове функции или метода

### Описание

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function uopz_set_hook(string `$class`, string `$function`, Closure `$hook`): bool

Устанавливает обработчик для выполнения при вызове функции или метода.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

`hook`

  Замыкание, выполняемое при вызове функции или метода.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Простое использование uopz_set_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

Результат выполнения приведённого примера:

    barfoo

### Смотрите также

- uopz_get_hook() - Получает ранее установленный обработчик на функцию или метод
- uopz_unset_hook() - Удаляет ранее установленную функцию или метод

# uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — Использовать имитатор вместо класса для новых объектов

### Описание

function uopz_set_mock(string `$class`, mixed `$mock`): void

Если `mock` - это строка, содержащая имя класса, тогда он будет создан вместо `class`. `mock` также может быть объектом.

> Замечание:

> Только динамический доступ к свойствам и методам будет использовать объект `mock`. Статический доступ будет использовать оригинальный `class`. Смотрите пример ниже.

### Список параметров

`class`

  Имя класса, который будет имитирован.

`mock`

  Имитатор в виде строки, содержащей имя используемого класса, либо объект. Если передана строка, она должна быть содержать абсолютное имя класса. В этом случае рекомендуется использовать магическую константу `::class`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль uopz 6.0.0 | Функция больше не поддерживает имитирование статических функций. Вместо этого пользуются функциями uopz_redefine() и uopz_set_return(), или Componere.

### Примеры

Пример #1 Пример использования функции uopz_set_mock()

    <?php

    class A
    {
        public function who()
        {
            echo "A";
        }
    }

    class mockA
    {
        public function who()
        {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    (new A)->who();

    ?>

Результат выполнения приведённого примера:

    mockA

Пример #2 Пример использования uopz_set_mock()

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                public function who() {
                                    echo "mockA";
                                }
                            });
    (new A)->who();
    ?>

Результат выполнения приведённого примера:

    mockA

Пример #3 uopz_set_mock() и статические члены класса

Начиная с uopz 6.0.0, имитация статических членов класса не поддерживается.

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                const CON = 'mockA';
                                public static function who() {
                                    echo "mockA";
                                }
                            });
    echo A::CON, PHP_EOL;
    A::who();

Результат выполнения приведённого примера:

    A
    A

Вывод примера в uopz 5:

    mockA
    mockA

### Смотрите также

- uopz_get_mock() - Получить текущий имитатор (mock) для класса
- uopz_unset_mock() - Удалить ранее установленный имитатор

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Устанавливает значение существующего свойства класса или экземпляра

### Описание

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function uopz_set_property(object `$instance`, string `$property`, mixed `$value`): void

Задаёт значение существующего статического свойства класса, если задан класс (`class`), либо значение существующего свойства экземпляра (вне зависимости от того, существует ли свойство экземпляра), если передан экземпляр (`instance`).

### Список параметров

`class`

  Имя класса.

`instance`

  Экземпляр объекта.

`property`

  Имя свойства.

`value`

  Значение, присваиваемое свойству.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Простое использование uopz_set_property()

    <?php
    class Foo {
       private static $staticBar;
       private $bar;
       public static function testStaticBar() {
          return self::$staticBar;
       }
       public function testBar() {
          return $this->bar;
       }
    }
    $foo = new Foo;
    uopz_set_property('Foo', 'staticBar', 10);
    uopz_set_property($foo, 'bar', 100);
    var_dump(Foo::testStaticBar());
    var_dump($foo->testBar());
    ?>

Результат выполнения приведённого примера:

    int(10)

### Смотрите также

- uopz_get_property() - Получает значение класса или свойство экземпляра

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Предоставить возвращаемое значение для существующей функции

### Описание

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function uopz_set_return(
string `$class`,
string `$function`,
mixed `$value`,
bool `$execute` = `false`
): bool

Установить возвращаемое значение для `function` на `value`. Если `value` замыкание и установлен `execute`, замыкание будет выполняться вместо исходной функции. Можно вызвать исходную функцию из замыкания.

> Замечание:

> Эта функция заменяет uopz_rename().

### Список параметров

`class`

  Имя класса, содержащего функцию

`function`

  Имя существующей функции

`value`

  Возвращаемое значение функцией. Если передано замыкание и параметр execute установлен, замыкание будет выполнено вместо исходной функции.

`execute`

  Если true, и в параметре value передано замыкание, замыкание будет выполнено вместо исходной функции.

### Возвращаемые значения

True в случае успешного выполнения, false в противном случае.

### Примеры

Пример #1 Пример использования uopz_set_return()

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

Результат выполнения приведённого примера:

    42

Пример #2 Пример использования uopz_set_return()

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

Результат выполнения приведённого примера:

    12

Пример #3 Пример использования uopz_set_return() с классом

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }
    uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
    echo My::strlen("Banana");
    ?>

Результат выполнения приведённого примера:

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Устанавливает статические переменные в области видимости функции или метода

### Описание

function uopz_set_static(string `$function`, array `$static`): void
function uopz_set_static(string `$class`, string `$function`, array `$static`): void

Устанавливает статические переменные в области видимости функции или метода.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

`static`

  Ассоциативный массив (array) имён переменных, сопоставленных с их значениями.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Простое использование uopz_set_static()

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

Результат выполнения приведённого примера:

    string(3) "qux"

### Смотрите также

- uopz_get_static() - Получает статические переменные из области видимости функции или метода

# uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — Отменяет определение константы

### Описание

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Удаляет константу во время выполнения

### Список параметров

`class`

  Название класса, содержащего `constant`

`constant`

  Имя существующей константы

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования uopz_undefine()

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

Результат выполнения приведённого примера:

    bool(false)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Удаляет ранее установленную функцию или метод

### Описание

function uopz_unset_hook(string `$function`): bool
function uopz_unset_hook(string `$class`, string `$function`): bool

Удаляет ранее установленную функцию или метод.

### Список параметров

`class`

  Имя класса.

`function`

  Имя функции или метода.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Простое использование uopz_unset_hook()

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    echo PHP_EOL;
    uopz_unset_hook('foo');
    foo();
    ?>

Результат выполнения приведённого примера:

    barfoo
    foo

### Смотрите также

- uopz_set_hook() - Устанавливает обработчик для выполнения при вызове функции или метода
- uopz_get_hook() - Получает ранее установленный обработчик на функцию или метод

# uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — Удалить ранее установленный имитатор

### Описание

function uopz_unset_mock(string `$class`): void

Удаляет ранее установленный имитатор для `class`.

### Список параметров

`class`

  Имя имитированного класса.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает RuntimeException, если ранее не был задан имитатор для `class`.

### Примеры

Пример #1 Пример использования uopz_unset_mock()

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    uopz_unset_mock(A::class);
    A::who();
    ?>

Результат выполнения приведённого примера:

    A

### Смотрите также

- uopz_set_mock() - Использовать имитатор вместо класса для новых объектов
- uopz_get_mock() - Получить текущий имитатор (mock) для класса

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Отменяет ранее установленное возвращаемое значение для функции

### Описание

function uopz_unset_return(string `$function`): bool
function uopz_unset_return(string `$class`, string `$function`): bool

Отменяет возвращаемое значение `function`, ранее заданное функцией uopz_set_return().

### Список параметров

`class`

  Имя класса, содержащего функцию

`function`

  Имя функции

### Возвращаемые значения

True в случае успешного выполнения

### Примеры

Пример #1 Пример использования uopz_unset_return()

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

Результат выполнения приведённого примера:

    48

## Содержание

- uopz_add_function — Добавляет несуществующую функцию или метод
- uopz_allow_exit — Позволяет управлять отключённым опкодом exit
- uopz_backup — Резервирует функцию
- uopz_compose — Составить класс
- uopz_copy — Скопировать функцию
- uopz_del_function — Удаляет ранее добавленную функцию или метод
- uopz_delete — Удалить функцию
- uopz_extend — Расширить класс во время выполнения
- uopz_flags — Получить или установить флаги для функции или класса
- uopz_function — Создаёт функцию во время выполнения
- uopz_get_exit_status — Получить последний установленный статус выхода
- uopz_get_hook — Получает ранее установленный обработчик на функцию или метод
- uopz_get_mock — Получить текущий имитатор (mock) для класса
- uopz_get_property — Получает значение класса или свойство экземпляра
- uopz_get_return — Получает предыдущее установленное возвращаемое значение для функции
- uopz_get_static — Получает статические переменные из области видимости функции или метода
- uopz_implement — Реализует интерфейс во время выполнения
- uopz_overload — Перегрузить опкод VM
- uopz_redefine — Переопределить константу
- uopz_rename — Переименовать функцию во время выполнения
- uopz_restore — Восстановить ранее зарезервированную функцию
- uopz_set_hook — Устанавливает обработчик для выполнения при вызове функции или метода
- uopz_set_mock — Использовать имитатор вместо класса для новых объектов
- uopz_set_property — Устанавливает значение существующего свойства класса или экземпляра
- uopz_set_return — Предоставить возвращаемое значение для существующей функции
- uopz_set_static — Устанавливает статические переменные в области видимости функции или метода
- uopz_undefine — Отменяет определение константы
- uopz_unset_hook — Удаляет ранее установленную функцию или метод
- uopz_unset_mock — Удалить ранее установленный имитатор
- uopz_unset_return — Отменяет ранее установленное возвращаемое значение для функции

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции Uopz
  - uopz_add_function — Добавляет несуществующую функцию или метод
  - uopz_allow_exit — Позволяет управлять отключённым опкодом exit
  - uopz_backup — Резервирует функцию
  - uopz_compose — Составить класс
  - uopz_copy — Скопировать функцию
  - uopz_del_function — Удаляет ранее добавленную функцию или метод
  - uopz_delete — Удалить функцию
  - uopz_extend — Расширить класс во время выполнения
  - uopz_flags — Получить или установить флаги для функции или класса
  - uopz_function — Создаёт функцию во время выполнения
  - uopz_get_exit_status — Получить последний установленный статус выхода
  - uopz_get_hook — Получает ранее установленный обработчик на функцию или метод
  - uopz_get_mock — Получить текущий имитатор (mock) для класса
  - uopz_get_property — Получает значение класса или свойство экземпляра
  - uopz_get_return — Получает предыдущее установленное возвращаемое значение для функции
  - uopz_get_static — Получает статические переменные из области видимости функции или метода
  - uopz_implement — Реализует интерфейс во время выполнения
  - uopz_overload — Перегрузить опкод VM
  - uopz_redefine — Переопределить константу
  - uopz_rename — Переименовать функцию во время выполнения
  - uopz_restore — Восстановить ранее зарезервированную функцию
  - uopz_set_hook — Устанавливает обработчик для выполнения при вызове функции или метода
  - uopz_set_mock — Использовать имитатор вместо класса для новых объектов
  - uopz_set_property — Устанавливает значение существующего свойства класса или экземпляра
  - uopz_set_return — Предоставить возвращаемое значение для существующей функции
  - uopz_set_static — Устанавливает статические переменные в области видимости функции или метода
  - uopz_undefine — Отменяет определение константы
  - uopz_unset_hook — Удаляет ранее установленную функцию или метод
  - uopz_unset_mock — Удалить ранее установленный имитатор
  - uopz_unset_return — Отменяет ранее установленное возвращаемое значение для функции

# Windows Cache для PHP

# Введение

Windows Cache Extension для PHP — кеширующий модуль, который увеличивает скорость работы PHP-приложений на системах под управлением ОС Windows и Windows Server. Как только модуль Windows Cache Extension включается и загружается PHP-движком, приложения начинают получать преимущества модуля без изменения кода приложения.

Модуль включает 5 типов кешей. Далее рассказывается про назначение и преимущества каждого типа кеша.

- PHP Opcode Cache — PHP — скриптовый язык, который читает входящий поток данных, который содержит текст и (или) инструкции языка и выдаёт новый поток данных, обычно в HTML-формате. То есть на стороне веб-сервера PHP читает, разбирает, компилирует и запускает PHP-скрипт каждый раз, когда скрипт клиент запрашивает. Чтение, разбор и компиляция создают дополнительную нагрузку на ядра процессора и файловую систему сервера, что сказывается на конечной производительности приложения. Кеширование языком PHP байт-кода (операционного кода, или опкода) держит уже скомпилированный код в разделяемой памяти и выполняет код при очередных запросах к тому же скрипту.

  Поддержку кеширования опкодов удалили в модуле `Wincache 2.0.0`. Поэтому если требуется кеширование, лучше использовать PHP-модуль OPcache.

- File Cache — даже при включённом кешировании PHP-опкода движок PHP всё равно обращается к файлам скриптов в файловой системе. Когда PHP-скрипты хранятся в удалённом файловом общедоступном UNC-ресурсе, файловые операции значительно снижают производительность. Модуль Windows Cache Extension включает файловый кеш, который сохраняет содержимое скриптов в разделяемой памяти, что сокращает количество операций с файловой системой, которые выполняет PHP-движок.

- Resolve File Path Cache — PHP-скрипты часто включают или оперируют файлами по относительным путям. Каждый путь файла PHP-движок сначала нормализует до абсолютного пути. Когда приложение обрабатывает много PHP-файлов и обращается к файлам по относительным путям, операция разрешения абсолютных путей негативно влияет на производительность приложения. Модуль кеша Windows предоставляет кеш разрешения путей к файлам Resolve File Path, который хранит сопоставления относительных и абсолютных путей, чем уменьшает количество операций разрешения путей, которые выполняет механизм PHP.

- User Cache (доступен с версии 1.1.0) — PHP-скрипты умеют использовать преимущества кеширования в разделяемой памяти через API-интерфейс пользовательского кеша. Объекты и переменные PHP хранятся в пользовательском кеше и переиспользуются в очередных запросах. Этот тип кеша повышает производительность PHP-скриптов и разрешает обмениваться данными между PHP-процессами.

- Session Handler (доступно с версии 1.1.0) — обработчик сессий WinCache хранит данные PHP-сессии в кеше разделяемой памяти. Этот тип кеша избегает дисковых операций при чтении и записи сессионных данных, что повышает производительность, когда в PHP-сессии хранится большой объём данных.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Скрипт статистики WinCache
- Обработчик сессий WinCache
- Перенаправление функций WinCache

## Требования

В данный момент модуль поддерживается только для следующих конфигураций:

Windows OS:

- Windows XP SP3 с IIS 5.1 и » FastCGI Extension
- Windows Server 2003 с IIS 6.0 и » FastCGI Extension
- Windows Vista SP1 с IIS 7.0 и FastCGI Module
- Windows Server 2008 с IIS 7.0 и FastCGI Module
- Windows 7 с IIS 7.5 и FastCGI Module
- Windows Server 2008 R2 с IIS 7.5 и FastCGI Module

PHP:

- PHP 5.2.X, не потокобезопасная сборка
- PHP 5.3 X86, не потокобезопасная VC9 сборка

> Замечание: Модуль WinCache может использоваться только если IIS настроен использовать PHP через FastCGI.

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/wincache.

Существует два пакета для этого модуля: один пакет для PHP 5.2.X, а другой для PHP 5.3.X. Выбор необходимого пакета зависит от вашей версии PHP.

Для установки и включения модуля следуйте следующей инструкции:

1. Разархивируйте пакет во временную папку.

2. Скопируйте php_wincache.dll в каталог с модулями PHP. Обычно этот каталог называется "ext" и расположен там же, где установлен PHP. К примеру: C:\Program Files\PHP\ext.

3. Используя текстовый редактор откройте файл php.ini, который обычно лежит там же, где установлен PHP. К примеру: C:\Program Files\PHP\php.ini.

4. Добавьте в конец файла строку: `extension = php_wincache.dll`.

5. Сохраните и закройте файл php.ini.

6. Пересоздайте пул приложений IIS для того, чтобы изменения вступили в силу. Для проверки того, что модуль включён, создайте файл phpinfo.php с кодом, вызывающим функцию PHP phpinfo.

7. Сохраните phpinfo.php в корневом каталоге веб-сайта и обратитесь к нему через веб-браузер по следующей ссылке http://localhost/phpinfo.php. Найдите в выводе секцию `wincache`. Если модуль включён, то функция phpinfo покажет список конфигурационных параметров WinCache.

> Замечание: Не забудьте удалить файл phpinfo.php после того, как он перестанет быть нужен.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

В таблице представлен список конфигурационных параметров модуля WinCache:

Конфигурационные параметры WinCache
Имя | По умолчанию | Минимум | Максимум | Место изменения | Список изменений
--- | --- | --- | --- | --- | ---
wincache.fcenabled | "1" | "0" | "1" | `INI_ALL` | Доступно с WinCache 1.0.0
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.fcachesize | "24" | "5" | "255" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.fcndetect | "1" | "0" | "1" | `INI_SYSTEM` | Доступно с WinCache 1.1.0
wincache.maxfilesize | "256" | "10" | "2048" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.ocenabled | "1" | "0" | "1" | `INI_ALL` | Доступно с WinCache 1.0.0. Удалено в 2.0.0.0
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Доступно с WinCache 1.0.0. Удалено в 2.0.0.0
wincache.ocachesize | "96" | "15" | "255" | `INI_SYSTEM` | Доступно с WinCache 1.0.0. Удалено в 2.0.0.0
wincache.filecount | "4096" | "1024" | "16384" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.chkinterval | "30" | "0" | "300" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.ttlmax | "1200" | "0" | "7200" | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.enablecli | 0 | 0 | 1 | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.ignorelist | NULL | NULL | NULL | `INI_ALL` | Доступно с WinCache 1.0.0
wincache.namesalt | NULL | NULL | NULL | `INI_SYSTEM` | Доступно с WinCache 1.0.0
wincache.ucenabled | 1 | 0 | 1 | `INI_SYSTEM` | Доступно с WinCache 1.1.0
wincache.ucachesize | 8 | 5 | 85 | `INI_SYSTEM` | Доступно с WinCache 1.1.0
wincache.scachesize | 8 | 5 | 85 | `INI_SYSTEM` | Доступно с WinCache 1.1.0
wincache.rerouteini | NULL | NULL | NULL | `INI_SYSTEM` | Доступно с WinCache 1.2.0. Удалено в 1.3.7
wincache.reroute_enabled | 1 | 0 | 1 | `INI_SYSTEM`|`INI_PERDIR` | Доступно с WinCache 1.3.7
wincache.srwlocks | 1 | 0 | 1 | `INI_SYSTEM` | Доступно с WinCache 1.3.6.3. Удалено в 2.0.0.0
wincache.filemapdir | NULL | NULL | NULL | `INI_SYSTEM` | Доступно с WinCache 1.3.7.4

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`wincache.fcenabled` bool
  Включает/отключает файловое кеширование.
`wincache.fcenabledfilter` string
  Определяет список идентификаторов IIS веб-серверов, разделённых запятой, для которых должно быть разрешено/запрещено файловое кеширование. Эта настройка работает в паре с `wincache.fcenabled`: если `wincache.fcenabled` установлено в 1, то для серверов, перечисленных в `wincache.fcenabledfilter` файловое кеширование будет отключено; если `wincache.fcenabled` установлено как 0, то для серверов, перечисленных в `wincache.fcenabledfilter` файловое кеширование будет включено.
`wincache.fcachesize` int
  Определяет максимальный размер памяти (в мегабайтах) для файлового кеша. Когда размер всех закешированных файлов превысит это значение, из кеша будут удалены самые устаревшие файлы.
`wincache.fcndetect` bool
  Включает/отключает функциональность оповещения об изменении файла. Если функционал оповещения об изменениях файла поддерживается, то он может быть использован для обновления кеша опкодов и файлового кеша при получении соответствующих оповещений. Если подобный механизм не поддерживается, например, при использовании сетевых папок, wincache будет самостоятельно проверять файлы на предмет изменения через заданные в настройке `wincache.chkinterval` интервалы времени.
`wincache.maxfilesize` int
  Определяет максимальный размер одного файла (в килобайтах) для файлового кеша. Если размер файла превышает заданное значение, то он не будет закеширован. Данная настройка применяется только к файловому кешу.
`wincache.ocenabled` bool
  Внимание

  Эта опция была УДАЛЕНА в версии 2.0.0.0

  Включает/отключает кеширование опкодов
`wincache.ocenabledfilter` string
  Внимание

  Эта опция была УДАЛЕНА в версии 2.0.0.0

  Определяет список идентификаторов IIS веб-серверов, разделённых запятой, для которых должно быть разрешено/запрещено кеширование опкодов. Эта настройка работает в паре с `wincache.ocenabled`: если `wincache.ocenabled` установлено в 1, то для серверов, перечисленных в `wincache.ocenabledfilter` файловое кеширование будет отключено; если `wincache.ocenabled` установлено как 0, то для серверов, перечисленных в `wincache.ocenabledfilter` файловое кеширование будет разрешено.
`wincache.ocachesize` int
  Внимание

  Эта опция была УДАЛЕНА в версии 2.0.0.0

  Определяет максимальный размер памяти (в мегабайтах) для кеша опкодов. Когда размер всех закешированных опкодов превысит это значение, из кеша будут удалены самые устаревшие из них. Обратите внимание, что кеш опкодов должен быть как минимум в 3 раза больше файлового кеша. Если это не так, то размер кеша опкодов будет автоматически увеличен.
`wincache.filecount` int
  Определяет, сколько примерно файлов будет закешировано модулем, чтобы при старте был выделен соответствующий кусок памяти. Если количество файлов превысит заданное значение, то WinCache произведёт переаллокацию памяти.
`wincache.chkinterval` int
  Определяет насколько часто (в секундах) модуль будет проверять файлы на предмет их изменения для обновления кешей. Значение 0 отключает данный функционал. Изменения файлов не будут отражены в кеше до тех пор, пока закешированная запись не будет удалена из кеша сборщиком устаревших записей, либо пока не будет переработан пул приложений IIS, либо не будет вызвана функция wincache_refresh_if_changed.
`wincache.ttlmax` int
  Определяет максимальное время (в секундах) невостребованности для записи в кеше. Установка в 0 отключает процесс удаления устаревших записей, что приведёт к тому, что запись будет лежать в кеше пока сервер IIS не будет остановлен.
`wincache.enablecli` bool
  Определяет, разрешено ли кеширование при работе PHP из командной строки (CLI).
`wincache.ignorelist` string

  Определяет список файлов, которые не нужно кешировать. Указываются только имена файлов. Символ разделитель - вертикальная черта "|".

  Пример #1 Пример использования `wincache.ignorelist`

      wincache.ignorelist = "index.php|misc.php|admin.php"

`wincache.namesalt` string
  Определяет строку, которая будет использоваться при именовании объектов, помещаемых в разделяемую память. Это необходимо для предотвращения коллизий, когда несколько процессов работают с разделяемой памятью. Длина данной строки не должна превышать 8 символов.
`wincache.ucenabled` bool
  Включает/отключает пользовательский кеш.
`wincache.ucachesize` int
  Определяет максимальный размер памяти (в мегабайтах) для пользовательского кеша. Когда размер всех закешированных переменных превысит это значение, из кеша будут удалены самые устаревшие переменные.
`wincache.scachesize` int
  Определяет максимальный размер памяти (в мегабайтах) для сессионного кеша. Когда размер всех закешированных данных превысит это значение, из кеша будут удалены самые устаревшие данные.
`wincache.rerouteini` string
  Внимание

  Эта опция была УДАЛЕНА в версии 1.3.7. Начиная с 1.3.7. вместо неё используйте `wincache.reroute_enabled`.

  Задаёт абсолютный или относительный путь к reroute.ini, который содержит список функций PHP, чья реализация должна быть подменена реализацией из модуля WinCache. Если задан относительный путь, то он будет разрешаться относительно местоположения файла php-cgi.exe.
`wincache.reroute_enabled` bool
  Включает/отключает перенаправление некоторых функций файлового ввода/вывода для работы через файловый кеш.
`wincache.srwlocks` bool
  Внимание

  Эта опция была УДАЛЕНА в версии 2.0.0.0

  Включает/отключает использование разделяемых блокировок чтения/записи. Выключение полезно при отладке ситуаций взаимных блокировок в WinCache.
`wincache.filemapdir` string
  Задаёт абсолютный путь к директории, где WinCache будет держать временные файлы для сегментов разделяемой памяти. Эта директория должна располагаться на локальной машине и ни в коем случае не на сетевой файловой системе. Если директория не указана, то WinCache будет использовать Windows System Page File.

## Скрипт статистики WinCache

Установочный пакет WinCache содержит PHP-скрипт, wincache.php, который можно использовать для получения статистики использования кеша.

Если модуль WinCache был установлен с помощью Microsoft Web Platform Installer, то скрипт будет располагаться по пути %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. На 64-разрядных версиях Windows Server, скрипт лежит по пути %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. Если модуль устанавливался самостоятельно, то wincache.php будет лежать в том же каталоге, в который вы распаковывали установочный пакет.

Для использования wincache.php, скопируйте его в корневой каталог веб-сайта или в любой его подкаталог. Для защиты скрипта, откройте его в текстовом редакторе и измените значения констант USERNAME и PASSWORD. Если для аутентификации в IIS используется другой механизм, то следуйте инструкциям в комментариях:

Пример #1 Настройка аутентификации для wincache.php

    <?php
    /**
     * ======================== CONFIGURATION SETTINGS ==============================
     * If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
     * If you use authentication then replace the default password.
     */
    define('USE_AUTHENTICATION', 1);
    define('USERNAME', 'wincache');
    define('PASSWORD', 'wincache');

    /**
     * The Basic PHP authentication will work only when IIS is configured to support
     * Anonymous Authentication' and nothing else. If IIS is configured to support/use
     * any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
     * In that case use the array below to define the names of users in your
     * domain/network/workgroup which you want to grant access to.
     */
    $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

    /**
     * If the array contains string 'all', then all the users authenticated by IIS
     * will have access to the page. Uncomment the below line and comment above line
     * to grant access to all users who gets authenticated by IIS.
     */
    /* $user_allowed = array('all'); */

    /** ===================== END OF CONFIGURATION SETTINGS ========================== */
    ?>

> Замечание: Всегда защищайте скрипт wincache.php с помощью встроенного механизма, либо с помощью механизма аутентификации веб-сервера. Оставляя доступ к скрипту открытым вы можете скомпрометировать ваше приложение и веб-сервер.

## Обработчик сессий WinCache

Обработчик сессий WinCache (доступен с WinCache 1.1.0) может использоваться для хранения данных сессий в кеше в разделяемой памяти. Использование памяти вместо файловой системы поможет улучшить производительность вашего приложения, если оно сохраняет большое количество сессионных данных. Кеш сессий Wincache использует дублирование данных на диске, что позволяет сохранить сессионные данные при пересоздании пула приложений IIS.

Для настройки использования обработчика сессий WinCache измените в файле php.ini настройку session.save_handler на wincache. По умолчанию, для хранения данных сессий используется временная директория Windows. Для изменения пути к сессионному файлу используйте настройку session.save_path.

Пример #1 Включение обработчика сессий WinCache

    session.save_handler = wincache
    session.save_path = C:\inetpub\temp\session\

## Перенаправление функций WinCache

ОБРАТИТЕ ВНИМАНИЕ: wincache.rerouteini удалена в WinCache 1.3.7.0. Она была заменена автоматическим перенаправлением. Смотрите wincache.reroute_enabled.

Перенаправление функций WinCache (доступно с WinCache 1.2.0, удалено с WinCache 1.3.7.0) может использоваться для замены встроенных функций их эквивалентами, оптимизированными для работы с файловым кешем. Модуль WinCache включает оптимизированные под Windows реализации функций работы с файлами, что может повысить производительность PHP-приложений в случаях работы с файлами и сетевыми папками. Оптимизированные версии представлены для следующих функций:

- file_exists
- file_get_contents
- readfile
- is_readable
- is_writable
- is_dir
- realpath
- filesize

Для настройки использования перенаправления в WinCache используется файл reroute.ini, который включён в установочный пакет. Скопируйте этот файл в ту же директорию, где находится php.ini. После этого добавьте в php.ini настройку wincache.rerouteini и укажите абсолютный или относительный путь к reroute.ini.

Пример #1 Включение перенаправления функций в WinCache

    wincache.rerouteini = C:\PHP\reroute.ini

> Замечание: Если перенаправление функций включено, то рекомендуется увеличить размер файлового кеша WinCache. Его размер настраивается в директиве wincache.fcachesize.

Файл reroute.ini содержит описание привязок встроенных функций PHP к их эквивалентам модуля WinCache. Каждая строка файла определяет привязку с использованием следующего синтаксиса:

`<Имя функции PHP>:[<количество параметров функции>]=<имя функции wincache>`

Пример файла приведён ниже. В этом примере вызов PHP-функции file_get_contents() подменяется вызовом функции wincache_file_get_contents() только если количество переданных параметров меньше или равно 2. Указание количества параметров полезно если подменяющая функция реализует обработку не всех исходных параметров.

Пример #2 Содержимое файла Reroute.ini

    [FunctionRerouteList]
    file_exists=wincache_file_exists
    file_get_contents:2=wincache_file_get_contents
    readfile:2=wincache_readfile
    is_readable=wincache_is_readable
    is_writable=wincache_is_writable
    is_writeable=wincache_is_writable
    is_file=wincache_is_file
    is_dir=wincache_is_dir
    realpath=wincache_realpath
    filesize=wincache_filesize

# Функции WinCache

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Получает информацию о файлах, закешированных в файловом кеше

### Описание

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Получает информацию о содержимом файлового кеша и его использовании.

### Список параметров

`summaryonly`

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

### Возвращаемые значения

Массив метаданных о файловом кеше или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `total_cache_uptime` - общее время в секундах, в течение которого файловый кеш был активен
- `total_file_count` - общее количество файлов, которые в данный момент находятся в файловом кеше
- `total_hit_count` - количество раз, когда файлы обслуживались из файлового кеша
- `total_miss_count` - количество раз, когда файлы не были найдены в файловом кеше

- `file_entries` - массив, содержащий информацию обо всех закешированных файлах:

  - `file_name` - абсолютное имя закешированного файла
  - `add_time` - время в секундах с момента добавления файла в кеш
  - `use_time` - время в секундах с момента обращения к файлу в кеше
  - `last_check` - время в секундах с момента проверки файла на наличие модификаций
  - `hit_count` - количество раз, когда файл был обработан из кеша
  - `file_size` - размер кешируемого файла в байтах

### Примеры

Пример #1 Пример использования wincache_fcache_fileinfo()

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (   [total_cache_uptime] => 3234
        [total_file_count] => 5
        [total_hit_count] => 0
        [total_miss_count] => 1
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 1
                        [use_time] => 0
                        [last_check] => 1
                        [hit_count] => 1
                        [file_size] => 2435
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Смотрите также

- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — Получает информацию об использовании памяти файлового кеша

### Описание

function wincache_fcache_meminfo(): array|false

Получает информацию об использовании памяти файлового кеша.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив метаданных об использовании памяти файлового кеша или `false`, если возникла ошибка

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `memory_total` - объем памяти в байтах, выделенный для файлового кеша
- `memory_free` - объем свободной памяти в байтах, доступной для файлового кеша
- `num_used_blks` - количество блоков памяти, используемых файловым кешем
- `num_free_blks` - количество свободных блоков памяти, доступных для файлового кеша
- `memory_overhead` - объем памяти в байтах, используемый для внутренних структур файлового кеша

### Примеры

Пример #1 Пример использования wincache_fcache_meminfo()

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — Получает эксклюзивную блокировку для данного ключа

### Описание

function wincache_lock(string `$key`, bool `$isglobal` = `false`): bool

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

Внимание

Использование wincache_lock() и wincache_unlock() может вызвать взаимную блокировку при выполнении скриптов PHP в многопроцессорной среде, такой как FastCGI. Не используйте эти функции, если вы не уверены, что вам это нужно. Для большинства операций с пользовательским кешем эти функции использовать не обязательно.

### Список параметров

`key`

  Имя ключа в кеше для включения блокировки.

`isglobal`

  Определяет, является ли область блокировки общесистемной или локальной. Локальные блокировки относятся к пулу приложений в случае IIS FastCGI или ко всем процессам PHP, которые имеют один и тот же идентификатор родительского процесса.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования wincache_lock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // получить эксклюзивную блокировку
        ftruncate($fp, 0); // обрезать файл
        fwrite($fp, "Напишите что-нибудь здесь\n");
        wincache_unlock(“lock_txt_lock”); // снять блокировку
    } else {
        echo "Не удалось получить блокировку!";
    }
    fclose($fp);
    ?>

### Смотрите также

- wincache_unlock() - Снимает эксклюзивную блокировку данного ключа
- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — Получает информацию о файлах, закешированных в кеше опкодов

### Описание

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Получает информацию о содержимом кеша опкодов и его использовании.

Внимание

В PHP 7.0.0 функцию УДАЛИЛИ.

### Список параметров

`summaryonly`

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

### Возвращаемые значения

Массив метаданных о кеше опкодов или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `total_cache_uptime` - общее время в секундах, в течение которого кеш опкода был активен.
- `total_file_count` - общее количество файлов, которые в настоящее время находятся в кеше опкодов.
- `total_hit_count` - количество раз, когда скомпилированный опкод был использован из кеша.
- `total_miss_count` - количество раз, когда скомпилированный опкод не был найден в кеше.
- `is_local_cache` - true, если метаданные кеша предназначены для экземпляра локального кеша, false, если метаданные предназначены для глобального кеша.

- `file_entries` - массив, содержащий информацию обо всех закешированных файлах:

  - `file_name` - абсолютное имя закешированного файла.
  - `add_time` - время в секундах с момента добавления файла в кеш опкодов.
  - `use_time` - время в секундах с момента обращения к файлу в кеше опкодов.
  - `last_check` - время в секундах с момента проверки файла на наличие модификаций.
  - `hit_count` - количество раз, когда файл был использован из кеша.
  - `function_count` - количество функций в закешированном файле.
  - `class_count` - количество классов в закешированном файле.

### Примеры

Пример #1 Пример использования wincache_ocache_fileinfo()

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — Получает информацию об использовании кеш-памяти опкодов

### Описание

function wincache_ocache_meminfo(): array|false

Получает информацию об использовании кеш-памяти опкодов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив метаданных об использовании кеш-памяти опкодов или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `memory_total` - объём памяти в байтах, выделенный для кеша опкодов.
- `memory_free` - объём свободной памяти в байтах, доступной для кеша опкодов.
- `num_used_blks` - количество блоков памяти, используемых кешем опкодов.
- `num_free_blks` - количество свободных блоков памяти, доступных для кеша опкодов.
- `memory_overhead` - объём памяти в байтах, используемый для внутренних структур кеша опкодов.

Внимание

В PHP 7.0.0 функцию УДАЛИЛИ.

### Примеры

Пример #1 Пример использования wincache_ocache_meminfo()

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — Обновляет записи кеша для закешированных файлов

### Описание

function wincache_refresh_if_changed(array `$files` = NULL): bool

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

### Список параметров

`files`

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

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

Пример #1 Пример использования wincache_refresh_if_changed()

    <?php
    $filename = 'C:\inetpub\wwwroot\config.php';
    $handle = fopen($filename, 'w+');
    if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
    fwrite($handle, '<?php $setting=something; ?>');
    fclose($handle);
    wincache_refresh_if_changed(array($filename));
    ?>

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше

# wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — Получает информацию о разрешении кеша пути к файлу разрешения

### Описание

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

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

### Список параметров

`summaryonly`

### Возвращаемые значения

Массив метаданных о кеше пути к файлу разрешения или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `total_file_count` - общее количество сопоставлений пути к файлу, хранящихся в кеше.

- `rplist_entries` - массив, содержащий информацию обо всех путях закешированных файлов:

  - `resolve_path` - путь к файлу.
  - `subkey_data` - соответствующий абсолютный путь к файлу.

### Примеры

Пример #1 Пример использования wincache_rplist_fileinfo()

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [total_file_count] => 5
        [rplist_entries] => Array
            (
                [1] => Array
                    (
                        [resolve_path] => checkcache.php
                        [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                    )

                [2] => Array (...iterates for each cached file)
            )
    )

### Смотрите также

- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения

### Описание

function wincache_rplist_meminfo(): array|false

Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив метаданных, описывающий использование памяти с помощью кеша пути к файлу разрешения или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `memory_total` - объём памяти в байтах, выделенный для кеша пути к файлу разрешения.
- `memory_free` - объём свободной памяти в байтах, доступной для кеша пути к файлу разрешения.
- `num_used_blks` - количество блоков памяти, используемых кешем пути к файлу разрешения.
- `num_free_blks` - количество свободных блоков памяти, доступных для кеша пути к файлу разрешения.
- `memory_overhead` - объём памяти в байтах, используемый для внутренних структур кеширования пути к файлу разрешения.

### Примеры

Пример #1 Пример использования wincache_rplist_meminfo()

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — Получает информацию о файлах, закешированных в кеше сессии

### Описание

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Получает информацию о содержимом кеша сессии и его использовании.

### Список параметров

`summaryonly`

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

### Возвращаемые значения

Массив метаданных о кеше сессии или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `total_cache_uptime` - общее время в секундах, в течение которого кеш сессии был активен.
- `total_item_count` - общее количество элементов, которые в настоящее время находятся в кеше сессии.
- `is_local_cache` - true, если метаданные кеша предназначены для экземпляра локального кеша, false, если метаданные предназначены для глобального кеша.
- `total_hit_count` - количество раз, когда данные были обработаны из кеша.
- `total_miss_count` - количество раз, когда данные не были найдены в кеше.

- `scache_entries` - массив, содержащий информацию обо всех закешированных элементах:

  - `key_name` - имя ключа, который используется для хранения данных.
  - `value_type` - тип значения, хранимого ключом.
  - `use_time` - время в секундах с момента обращения к файлу в кеше опкодов.
  - `last_check` - время в секундах с момента проверки файла на наличие модификаций.
  - `ttl_seconds` - время, оставшееся для данных, чтобы оставаться в кеше, 0 означает бесконечность.
  - `age_seconds` - время, прошедшее с момента добавления данных в кеш.
  - `hitcount` - количество раз, когда данные были получены из кеша.

### Примеры

Пример #1 Пример использования wincache_scache_info()

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [scache_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — Получает информацию об использовании кеш-памяти сессии

### Описание

function wincache_scache_meminfo(): array|false

Получает информацию об использовании памяти кешем сессии.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив метаданных об использовании кеш-памяти сессии или `false`, если возникла ошибка.

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `memory_total` - объём памяти в байтах, выделенный для кеш-памяти сессии.
- `memory_free` - объём свободной памяти в байтах, доступной для кеш-памяти сессии.
- `num_used_blks` - количество блоков памяти, используемых кешем сессии.
- `num_free_blks` - количество свободных блоков памяти, доступных для кеша сессии.
- `memory_overhead` - объём памяти в байтах, используемый для внутренних структур кеша сессии.

### Примеры

Пример #1 Пример использования wincache_scache_meminfo()

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии

# wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную

### Описание

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Функция добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную с таким ключом. Переменная остаётся в пользовательском кеше до истечения срока действия или пока переменную не удалят функцией wincache_ucache_delete() или wincache_ucache_clear().

### Список параметров

`key`

  Параметр `key` — имя переменной, с которым значение сохраняется в кеше. Функция выдаст ошибку и вернёт `false`, если переменная с ключом `key` уже содержится в кеше. Параметр `key` чувствителен к регистру. Функция wincache_ucache_set() переопределит значение, даже если элемент с ключом `key` уже содержится в кеше. Параметр `key` также принимает массив пар «имя => значение», где имя — ключ значения. Массив передают для добавления в кеш набора значений за одну операцию и чтобы исключить состояние гонки.

`value`

  Значение переменной, которую требуется сохранить. Параметр `value` поддерживает все типы данных, кроме ресурсов, таких как дескрипторы файлов. Параметр игнорируется, если в первом аргументе передали массив. Общая рекомендация — при передаче в параметр `key` массива передавать в аргументе `value` значение `null`. Функция сериализует объекты, если в параметр `value` передали объект или массив объектов. Подробнее о сериализации объектов рассказывает описание магического метода __sleep().

`values`

  Ассоциативный массив ключей и значений.

`ttl`

  Время в секундах, в течение которого переменная хранится в кеше. После истечения времени `ttl` переменная удаляется из кеша. Значение по умолчанию — `0`, поэтому переменная останется в кеше бессрочно, или пока переменную не удалят функцией wincache_ucache_delete() или wincache_ucache_clear().

### Возвращаемые значения

При передаче в параметр `key` строки функция возвращает `true`, если завершилась успешно, или `false`, если возникла ошибка.

При передаче в параметр `key` массива функция возвращает:

- Пустой массив, если все пары «имя => значение» в массиве возможно установить;
- Значение `false`, если ни одну пару «имя => значение» из массива невозможно установить;
- Массив пар «имя => значение», которые не добавились в пользовательский кеш, если одни пары возможно установить, а другие — нет.

### Примеры

Пример #1 Пример добавления переменной в пользовательский кеш по строковому ключу `key` функцией wincache_ucache_add()

    <?php

    $bar = 'BAR';
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_get('foo'));

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    string(3) "BAR"

Пример #2 Пример добавления переменных в пользовательский кеш функцией wincache_ucache_add() с передачей в параметр `key` массива

    <?php

    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');

    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_get('Blue'));

Результат выполнения приведённого примера:

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### Смотрите также

- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- __sleep()

# wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — Сравнивает переменную со старым значением и присваивает ей новое значение

### Описание

function wincache_ucache_cas(string `$key`, int `$old_value`, int `$new_value`): bool

Сравнивает переменную, связанную с `key` с `old_value` и, если она совпадает, присваивает ей `new_value`.

### Список параметров

`key`

  `key`, который использовался для сохранения переменной в кеш. `key` чувствителен к регистру.

`old_value`

  Старое значение переменной, на которую указывает `key` в пользовательском кеше. Значение должно быть типа `long`, иначе функция вернёт `false`.

`new_value`

  Новое значение, которое будет присвоено указателю переменной `key`, если будет найдено совпадение. Значение должно быть типа `long`, иначе функция вернёт `false`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования wincache_ucache_cas()

    <?php
    wincache_ucache_set('counter', 2922);
    var_dump(wincache_ucache_cas('counter', 2922, 1));
    var_dump(wincache_ucache_get('counter'));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    int(1)

### Смотрите также

- wincache_ucache_inc() - Увеличивает значение, связанное с ключом
- wincache_ucache_dec() - Уменьшает значение, связанное с ключом

# wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — Удаляет всё содержимое пользовательского кеша

### Описание

function wincache_ucache_clear(): bool

Очищает/удаляет все значения, хранящиеся в пользовательском кеше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования wincache_ucache_clear()

    <?php
    wincache_ucache_set('green', 1);
    wincache_ucache_set('red', 2);
    wincache_ucache_set('orange', 4);
    wincache_ucache_set('blue', 8);
    wincache_ucache_set('cyan', 16);
    $array1 = array('green', 'red', 'orange', 'blue', 'cyan');
    var_dump(wincache_ucache_get($array1));
    var_dump(wincache_ucache_clear());
    var_dump(wincache_ucache_get($array1));
    ?>

Результат выполнения приведённого примера:

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### Смотрите также

- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_add() - Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше

# wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — Уменьшает значение, связанное с ключом

### Описание

function wincache_ucache_dec(string `$key`, int `$dec_by` = 1, bool `&$success` = ?): mixed

Уменьшает значение, связанное с `key` на 1 или как указано в `dec_by`.

### Список параметров

`key`

  `key`, который использовался для сохранения переменной в кеш. `key` чувствителен к регистру.

`dec_by`

  Значение, на которое должна быть уменьшена переменная, связанная с `key`. Если аргумент является числом с плавающей точкой, он будет усечён до ближайшего целого числа. Переменная, связанная с `key`, должна иметь тип `long`, иначе функция завершится ошибкой и вернёт `false`.

`success`

  Будет установлено значение `true` в случае успешного выполнения и `false` в случае возникновения ошибки.

### Возвращаемые значения

Возвращает уменьшенное значение в случае успешного выполнения и `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

Результат выполнения приведённого примера:

    int(2922)
    bool(true)

### Смотрите также

- wincache_ucache_inc() - Увеличивает значение, связанное с ключом
- wincache_ucache_cas() - Сравнивает переменную со старым значением и присваивает ей новое значение

# wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — Удаляет переменные из пользовательского кеша

### Описание

function wincache_ucache_delete(mixed `$key`): bool

Удаляет элементы из пользовательского кеша, на которые указывает параметр `key`.

### Список параметров

`key`

  Параметр `key`, который использовался для хранения переменной в кеше. `key` чувствителен к регистру. `key` может быть массивом ключей.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

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

### Примеры

Пример #1 Пример использования wincache_ucache_delete() с `key` в виде строки

    <?php
    wincache_ucache_set('foo', 'bar');
    var_dump(wincache_ucache_delete('foo'));
    var_dump(wincache_ucache_exists('foo'));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

Пример #2 Пример использования wincache_ucache_delete() с `key` в виде массива

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

Результат выполнения приведённого примера:

    array(4) { [0]=> string(5) "green"
               [1]=> string(4) "blue"
               [2]=> string(6) "yellow"
               [3]=> string(4) "cyan" }

Пример #3 Пример использования wincache_ucache_delete() с `key` в виде массива, из которого нельзя удалить некоторые элементы

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('orange', 'red', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

Результат выполнения приведённого примера:

    array(2) { [0]=> string(6) "yellow"
               [1]=> string(4) "cyan" }

### Смотрите также

- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_add() - Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше

# wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — Проверяет, существует ли переменная в пользовательском кеше

### Описание

function wincache_ucache_exists(string `$key`): bool

Проверяет, существует ли переменная `key` в пользовательском кеше или нет.

### Список параметров

`key`

  Параметр `key`, который использовался для хранения переменной в кеше. `key` чувствителен к регистру.

### Возвращаемые значения

Возвращает `true`, если переменная с `key` существует, в противном случае возвращает `false`.

### Примеры

Пример #1 Пример использования wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_add() - Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше

# wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — Получает переменную, хранящуюся в пользовательском кеше

### Описание

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Получает переменную, хранящуюся в пользовательском кеше.

### Список параметров

`key`

  Параметр `key`, который использовался для хранения переменной в кеше. `key` чувствителен к регистру. `key` может быть массивом ключей. В этом случае возвращаемое значение будет массивом значений каждого элемента в массиве `key`. Если возвращается объект или массив, содержащий объекты, то объекты будут десериализованы. Подробнее о десериализации объектов смотрите __wakeup().

`success`

  Будет установлено значение `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Возвращаемые значения

Если параметр `key` является строкой, функция возвращает значение переменной, хранящейся с этим ключом. Для параметра `success` будет установлено значение `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

Если параметр `key` - это массив, параметр `success` всегда будет иметь значение `true`. Возвращённый массив (пары имя => значение) будет содержать только те пары имя => значение, для которых операция получения в пользовательском кеше была успешной. Если ни один из ключей в массиве ключей не находит совпадения в пользовательском кеше, будет возвращён пустой массив.

### Примеры

Пример #1 wincache_ucache_get() с `key` в виде строки

    <?php
    wincache_ucache_add('color', 'blue');
    var_dump(wincache_ucache_get('color', $success));
    var_dump($success);
    ?>

Результат выполнения приведённого примера:

    string(4) "blue"
    bool(true)

Пример #2 wincache_ucache_get() с `key` в виде массива

    <?php
    $array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'Blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_get($array2, $success));
    var_dump($success);
    ?>

Результат выполнения приведённого примера:

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### Смотрите также

- wincache_ucache_add() - Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- __wakeup()

# wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — Увеличивает значение, связанное с ключом

### Описание

function wincache_ucache_inc(string `$key`, int `$inc_by` = 1, bool `&$success` = ?): mixed

Увеличивает значение, связанное с `key` на 1 или как указано в `inc_by`.

### Список параметров

`key`

  `key`, который использовался для сохранения переменной в кеш. `key` чувствителен к регистру.

`inc_by`

  Значение, на которое должна быть увеличена переменная, связанная с `key`. Если аргумент является числом с плавающей точкой, он будет усечён до ближайшего целого числа. Переменная, связанная с `key`, должна иметь тип `long`, иначе функция завершится ошибкой и вернёт `false`.

`success`

  Будет установлено значение `true` в случае успешного выполнения и `false` в случае возникновения ошибки.

### Возвращаемые значения

Возвращает увеличенное значение в случае успешного выполнения и `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

Результат выполнения приведённого примера:

    int(2922)
    bool(true)

### Смотрите также

- wincache_ucache_dec() - Уменьшает значение, связанное с ключом
- wincache_ucache_cas() - Сравнивает переменную со старым значением и присваивает ей новое значение

# wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — Получает информацию о данных, хранящихся в пользовательском кеше

### Описание

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Получает информацию о данных, хранящихся в пользовательском кеше.

### Список параметров

`summaryonly`

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

`key`

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

### Возвращаемые значения

Массив метаданных об использовании пользовательского кеша или `false`, если возникла ошибка

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `total_cache_uptime` - общее время в секундах, в течение которого пользовательский кеш был активен.
- `total_item_count` - общее количество элементов, которые в данный момент находятся в пользовательском кеше.
- `is_local_cache` - true - метаданные кеша предназначены для экземпляра локального кеша, false, если метаданные предназначены для глобального кеша.
- `total_hit_count` - количество раз, когда данные были получены из кеша.
- `total_miss_count` - количество раз, когда данные не были найдены в кеше.

- `ucache_entries` - массив, содержащий информацию обо всех кешированных элементах:

  - `key_name` - имя ключа, который используется для хранения данных.
  - `value_type` - тип значения, хранимого ключом.
  - `use_time` - время в секундах с момента обращения к файлу в кеше опкодов.
  - `last_check` - время в секундах с момента проверки файла на наличие модификаций.
  - `is_session` - указывает, являются ли данные переменной сессии.
  - `ttl_seconds` - время, оставшееся для данных, чтобы находиться в кеше, 0 означает бесконечность.
  - `age_seconds` - время, прошедшее с момента добавления данных в кеш.
  - `hitcount` - количество раз, когда данные были получены из кеша.

### Примеры

Пример #1 Пример использования wincache_ucache_info()

    <?php
    wincache_ucache_get('green');
    wincache_ucache_set('green', 2922);
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    print_r(wincache_ucache_info());
    ?>

Результат выполнения приведённого примера:

    Array
    ( ["total_cache_uptime"] => int(0)
      ["is_local_cache"] => bool(false)
      ["total_item_count"] => int(1)
      ["total_hit_count"] => int(3)
      ["total_miss_count"] => int(1)
      ["ucache_entries"] => Array(1)
        ( [1] => Array(6)
          (
            ["key_name"] => string(5) "green"
            ["value_type"] => string(4) "long"
            ["is_session"] => int(0)
            ["ttl_seconds"] => int(0)
            ["age_seconds"] => int(0)
            ["hitcount"] => int(3)
           )
        )
    )

### Смотрите также

- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo() - Получает информацию об использовании кеш-памяти опкодов
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — Получает информацию об использовании памяти пользовательского кеша

### Описание

function wincache_ucache_meminfo(): array|false

Получает информацию об использовании памяти пользовательского кеша.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив метаданных об использовании памяти пользовательского кеша или `false`, если возникла ошибка

Массив, возвращаемый этой функцией, содержит следующие элементы:

- `memory_total` - объем памяти в байтах, выделенный для пользовательского кеша
- `memory_free` - объем свободной памяти в байтах, доступной для пользовательского кеша
- `num_used_blks` - количество блоков памяти, используемых пользовательским кешем
- `num_free_blks` - количество свободных блоков памяти, доступных для пользовательского кеша
- `memory_overhead` - объем памяти в байтах, используемый для внутренних структур пользовательского кеша

### Примеры

Пример #1 Пример использования wincache_ucache_meminfo()

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Смотрите также

- wincache_fcache_fileinfo() - Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo() - Получает информацию об использовании памяти файлового кеша
- wincache_ocache_fileinfo() - Получает информацию о файлах, закешированных в кеше опкодов
- wincache_rplist_fileinfo() - Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo() - Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_refresh_if_changed() - Обновляет записи кеша для закешированных файлов
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo() - Получает информацию об использовании кеш-памяти сессии

# wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — Добавляет или перезаписывает переменную в пользовательский кеш

### Описание

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_set(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Функция добавляет переменную в пользовательский кеш. Функция заменит переменную, если кеш уже содержит переменную с таким ключом. Добавленная или обновлённая переменная остаётся в пользовательском кеше до истечения срока действия или пока переменную не удалят функцией wincache_ucache_delete() или wincache_ucache_clear().

### Список параметров

`key`

  Параметр `key` — имя переменной, с которым значение сохраняется в кеше. Функция перезапишет предыдущее значение новым, если переменная с ключом `key` уже содержится в кеше. Параметр `key` чувствителен к регистру. Параметр `key` также принимает массив пар «имя => значение», где имя — ключ значения. Массив передают для добавления в кеш набора значений за одну операцию и чтобы исключить состояние гонки.

`value`

  Значение переменной, которую требуется сохранить. Параметр `value` поддерживает все типы данных, кроме ресурсов, таких как дескрипторы файлов. Параметр игнорируется, если первым аргументом является массив. Общее руководство - передать `null` в качестве `value` при использовании массива `key`. Функция сериализует объекты, если в параметр `value` передали объект или массив объектов. Подробнее о сериализации объектов рассказывает описание магического метода __sleep().

`values`

  Ассоциативный массив ключей и значений.

`ttl`

  Время в секундах, в течение которого переменная хранится в кеше. После истечения времени `ttl` переменная удаляется из кеша. Значение по умолчанию — `0`, поэтому переменная останется в кеше бессрочно, или пока переменную не удалят функцией wincache_ucache_delete() или wincache_ucache_clear().

### Возвращаемые значения

При передаче в параметр `key` строки функция возвращает `true`, если завершилась успешно, или `false`, если возникла ошибка.

При передаче в параметр `key` массива функция возвращает:

- Пустой массив, если все пары «имя => значение» в массиве возможно установить;
- Значение `false`, если ни одну пару «имя => значение» из массива невозможно установить;
- Массив пар «имя => значение», которые не добавились в пользовательский кеш, если одни пары возможно установить, а другие — нет.

### Примеры

Пример #1 Пример добавления или перезаписи переменной в пользовательском кеше по строковому ключу `key` функцией wincache_ucache_set()

    <?php

    $bar = 'BAR';
    var_dump(wincache_ucache_set('foo', $bar));
    var_dump(wincache_ucache_get('foo'));

    $bar1 = 'BAR1';
    var_dump(wincache_ucache_set('foo', $bar1));
    var_dump(wincache_ucache_get('foo'));

Результат выполнения приведённого примера:

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

Пример #2 Пример добавления или перезаписи переменной в пользовательском кеше функцией wincache_ucache_set() с передачей в параметре `key` массива

    <?php

    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');

    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

Результат выполнения приведённого примера:

    array(0) {}
    array(0) {}
    string(1) "6"

### Смотрите также

- wincache_ucache_add() - Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- __sleep()

# wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — Снимает эксклюзивную блокировку данного ключа

### Описание

function wincache_unlock(string `$key`): bool

Снимает исключительную блокировку, которая была получена для данного ключа с помощью wincache_lock(). Если какой-либо другой процесс был заблокирован в ожидании блокировки этого ключа, этот процесс сможет получить блокировку.

Внимание

Использование wincache_lock() и wincache_unlock() может вызвать взаимную блокировку при выполнении скриптов PHP в многопроцессорной среде, такой как FastCGI. Не используйте эти функции, если вы не уверены, что вам это нужно. Для большинства операций с пользовательским кешем эти функции использовать не обязательно.

### Список параметров

`key`

  Имя ключа в кеше для снятия блокировки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования wincache_unlock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // получить эксклюзивную блокировку
        ftruncate($fp, 0); // обрезать файл
        fwrite($fp, "Напишите что-нибудь здесь\n");
        wincache_unlock(“lock_txt_lock”); // снять блокировку
    } else {
        echo "Не удалось получить блокировку!";
    }
    fclose($fp);
    ?>

### Смотрите также

- wincache_lock() - Получает эксклюзивную блокировку для данного ключа
- wincache_ucache_set() - Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_ucache_get() - Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_delete() - Удаляет переменные из пользовательского кеша
- wincache_ucache_clear() - Удаляет всё содержимое пользовательского кеша
- wincache_ucache_exists() - Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_meminfo() - Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_info() - Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_scache_info() - Получает информацию о файлах, закешированных в кеше сессии

## Содержание

- wincache_fcache_fileinfo — Получает информацию о файлах, закешированных в файловом кеше
- wincache_fcache_meminfo — Получает информацию об использовании памяти файлового кеша
- wincache_lock — Получает эксклюзивную блокировку для данного ключа
- wincache_ocache_fileinfo — Получает информацию о файлах, закешированных в кеше опкодов
- wincache_ocache_meminfo — Получает информацию об использовании кеш-памяти опкодов
- wincache_refresh_if_changed — Обновляет записи кеша для закешированных файлов
- wincache_rplist_fileinfo — Получает информацию о разрешении кеша пути к файлу разрешения
- wincache_rplist_meminfo — Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
- wincache_scache_info — Получает информацию о файлах, закешированных в кеше сессии
- wincache_scache_meminfo — Получает информацию об использовании кеш-памяти сессии
- wincache_ucache_add — Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
- wincache_ucache_cas — Сравнивает переменную со старым значением и присваивает ей новое значение
- wincache_ucache_clear — Удаляет всё содержимое пользовательского кеша
- wincache_ucache_dec — Уменьшает значение, связанное с ключом
- wincache_ucache_delete — Удаляет переменные из пользовательского кеша
- wincache_ucache_exists — Проверяет, существует ли переменная в пользовательском кеше
- wincache_ucache_get — Получает переменную, хранящуюся в пользовательском кеше
- wincache_ucache_inc — Увеличивает значение, связанное с ключом
- wincache_ucache_info — Получает информацию о данных, хранящихся в пользовательском кеше
- wincache_ucache_meminfo — Получает информацию об использовании памяти пользовательского кеша
- wincache_ucache_set — Добавляет или перезаписывает переменную в пользовательский кеш
- wincache_unlock — Снимает эксклюзивную блокировку данного ключа

# Сборка для Windows

## Содержание

- Пререквизиты
- Компиляция и сборка
- Проверка сборки

## Пререквизиты

Для сборки модуля WinCache требуется:

1. Исходный код PHP
2. Окружение сборки PHP
3. Исходный код WinCache

Первые два пункта полностью покрываются статьёй руководства » сборка PHP под Windows.

Получение исходного кода WinCache описано в разделе Скачивание PECL-модулей.

## Компиляция и сборка

Следующие шаги описывают, как компилировать и собирать WinCache под Windows OS:

1. Откройте консоль командной строки

2. Перейдите в папку с исходными кодами PHP

3. Выполните команду:

       cscript.exe win32\build\buildconf.js

4. Выполните команду:

       configure.bat --help

   Вывод будет содержать новый флаг `--enable-wincache`.

5. Выполните команду:

       configure.js [все опции для сборки PHP] --enable-wincache

   `--enable-wincache` это единственная дополнительная опция, которая требуется для правильной сборки модуля WinCache. Эта опция соберёт WinCache и будет статически связывать его с PHP dll. Чтобы создать модуль WinCache в качестве автономной библиотеки DLL, используйте параметр `--enable-wincache=shared`.

6. Выполните команду:

       nmake

## Проверка сборки

Следующие шаги описывают процесс проверки того, что модуль был собран корректно:

1. Перейдите в папку, где находится скомпилированный PHP

2. Выполните команду:

       php.exe -n -d extension=php_wincache.dll -re wincache

   Если модуль собран правильно, в выводе этой команды будут показаны INI-директивы и функции поддерживаемые WinCache.

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Скрипт статистики WinCache
  - Обработчик сессий WinCache
  - Перенаправление функций WinCache
- Функции WinCache
  - wincache_fcache_fileinfo — Получает информацию о файлах, закешированных в файловом кеше
  - wincache_fcache_meminfo — Получает информацию об использовании памяти файлового кеша
  - wincache_lock — Получает эксклюзивную блокировку для данного ключа
  - wincache_ocache_fileinfo — Получает информацию о файлах, закешированных в кеше опкодов
  - wincache_ocache_meminfo — Получает информацию об использовании кеш-памяти опкодов
  - wincache_refresh_if_changed — Обновляет записи кеша для закешированных файлов
  - wincache_rplist_fileinfo — Получает информацию о разрешении кеша пути к файлу разрешения
  - wincache_rplist_meminfo — Получает информацию об использовании памяти с помощью кеша пути к файлу разрешения
  - wincache_scache_info — Получает информацию о файлах, закешированных в кеше сессии
  - wincache_scache_meminfo — Получает информацию об использовании кеш-памяти сессии
  - wincache_ucache_add — Добавляет переменную в пользовательский кеш, только если кеш ещё не содержит переменную
  - wincache_ucache_cas — Сравнивает переменную со старым значением и присваивает ей новое значение
  - wincache_ucache_clear — Удаляет всё содержимое пользовательского кеша
  - wincache_ucache_dec — Уменьшает значение, связанное с ключом
  - wincache_ucache_delete — Удаляет переменные из пользовательского кеша
  - wincache_ucache_exists — Проверяет, существует ли переменная в пользовательском кеше
  - wincache_ucache_get — Получает переменную, хранящуюся в пользовательском кеше
  - wincache_ucache_inc — Увеличивает значение, связанное с ключом
  - wincache_ucache_info — Получает информацию о данных, хранящихся в пользовательском кеше
  - wincache_ucache_meminfo — Получает информацию об использовании памяти пользовательского кеша
  - wincache_ucache_set — Добавляет или перезаписывает переменную в пользовательский кеш
  - wincache_unlock — Снимает эксклюзивную блокировку данного ключа
- Сборка для Windows
  - Пререквизиты
  - Компиляция и сборка
  - Проверка сборки

# Hierarchical Profiler

# Введение

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

XHProf содержит простой HTML интерфейс (написанный на PHP). UI на основе браузера сильно облегчает просмотр результатов и пересылку их всем желающим. Также поддерживается графическое отображение графа вызовов.

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

XHProf поддерживает сравнение двух разных запусков ("diff") или агрегацию данных нескольких запусков. Сравнительные и агрегированные отчёты, также как одиночные, предоставляют как "плоские", так и "иерархические" взгляды на результаты профилирования.

Дополнительная документация доступна на сайте » facebook xhprof.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

В целом не требуется, так как xhprof включает интерфейс, написанный на PHP. Он используется для сохранения и отображения результатов профилирования в удобном виде в браузере. Таким образом, включение встроенного в PHP веб-сервера позволит использовать xprof максимально продуктивно.

Также существует форк GUI интерфейса - » http://github.com/preinheimer/xhprof

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/xhprof

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Xhprof
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

Краткое разъяснение конфигурационных директив.

`xhprof.output_dir` string

  Директория используемая реализацией интерфейса iXHProfRuns по умолчанию (класс XHProfRuns_Default) для сохранения результатов профилирования.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`XHPROF_FLAGS_NO_BUILTINS` (int)
  Используется для исключения профилирования встроенных функций.
`XHPROF_FLAGS_CPU` (int)
  Используется для добавления в отчёт информации по профилированию CPU.
`XHPROF_FLAGS_MEMORY` (int)
  Используется для добавления в отчёт информации по профилированию памяти.

# Примеры

Пример #1 Примеры использования Xhprof, опционально с GUI

В этом примере профайлер запускается, останавливается и использует встроенный GUI интерфейс для сохранения и разбора результатов. Другими словами, исполнение кода модуля завершается на функции xhprof_disable().

    <?php
    xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

    for ($i = 0; $i <= 1000; $i++) {
        $a = $i * $i;
    }

    $xhprof_data = xhprof_disable();

    $XHPROF_ROOT = "/tools/xhprof/";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

    $xhprof_runs = new XHProfRuns_Default();
    $run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

    echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

    ?>

Вывод приведённого примера будет похож на:

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Функции Xhprof

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Останавливает профилирование xhprof

### Описание

function xhprof_disable(): ?array

Останавливает профилирование и возвращает собранные данные.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив с результатами профилирования. Возвращает `null`, если профилирование отключено.

### Примеры

Пример #1 Пример использования xhprof_disable()

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [main()==>strlen] => Array
            (
                [ct] => 1
                [wt] => 279
            )

        [main()==>xhprof_disable] => Array
            (
                [ct] => 1
                [wt] => 9
            )

        [main()] => Array
            (
                [ct] => 1
                [wt] => 610
            )

    )

# xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Запуск профилирования xhprof

### Описание

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

Запускает профилирование.

### Список параметров

`flags`

  Необязательные флаги для получения дополнительной информации при профилировании. Подробности можно найти в разделе Константы XHprof. Например, `XHPROF_FLAGS_MEMORY` включает профилирование памяти.

`options`

  Массив (array) необязательных опций, а конкретно опция 'ignored_functions' со списком функций, которые не нужно профилировать.

### Возвращаемые значения

`null`

### Список изменений

Версия | Описание
--- | ---
PECL xhprof 0.9.2 | Добавлен необязательный параметр `options`.

### Примеры

Пример #1 Пример использования xhprof_enable()

    <?php
    // 1. время исполнения + память + CPU; также игнорируем функции стандартной библиотеки
    xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

    // 2. время исполнения; игнорируем при профилировании call_user_func*
    xhprof_enable(
        0,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));

    // 3. время исполнения + память; игнорируем при профилировании call_user_func*
    xhprof_enable(
        XHPROF_FLAGS_MEMORY,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));
    ?>

### Смотрите также

- xhprof_disable() - Останавливает профилирование xhprof
- xhprof_sample_enable() - Запуск сэмплирующего режима профилирования XHProf
- memory_get_usage() - Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу
- getrusage() - Получает информацию об использовании текущего ресурса

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Остановить сэмплирующие профилирование xhprof

### Описание

function xhprof_sample_disable(): ?array

Останавливает профилировщик xhprof в режиме выборки и возвращает информацию о профиле.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив данных, собранный профайлером. Возвращает `null`, если профилирование отключено.

### Примеры

Пример #1 Пример использования xhprof_sample_disable()

    <?php
    xhprof_sample_enable();

    for ($i = 0; $i <= 10000; $i++) {
        $a = strlen($i);
        $b = $i * $a;
        $c = rand();
    }

    $xhprof_data = xhprof_sample_disable();

    print_r($xhprof_data);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Запуск сэмплирующего режима профилирования XHProf

### Описание

function xhprof_sample_enable(): void

Запуск сэмплирующего режима профилирования, который является облегчённой версией xhprof_enable(). Интервал семплирования составляет 0.1 секунды и при каждой итерации записывается стек вызовов. Данный режим предназначен для снижения накладных расходов при мониторинге производительности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`null`

### Смотрите также

- xhprof_sample_disable() - Остановить сэмплирующие профилирование xhprof
- xhprof_enable() - Запуск профилирования xhprof
- memory_get_usage() - Возвращает количество памяти, которую потребляет PHP-скрипт или которую система выделила PHP-процессу
- getrusage() - Получает информацию об использовании текущего ресурса

## Содержание

- xhprof_disable — Останавливает профилирование xhprof
- xhprof_enable — Запуск профилирования xhprof
- xhprof_sample_disable — Остановить сэмплирующие профилирование xhprof
- xhprof_sample_enable — Запуск сэмплирующего режима профилирования XHProf

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Примеры
- Функции Xhprof
  - xhprof_disable — Останавливает профилирование xhprof
  - xhprof_enable — Запуск профилирования xhprof
  - xhprof_sample_disable — Остановить сэмплирующие профилирование xhprof
  - xhprof_sample_enable — Запуск сэмплирующего режима профилирования XHProf

# Yac

# Введение

Yac (Yet Another cache) - это свободный от блокировок кеш пользовательских данных с общей памятью, который можно использовать для замены APC и локального кеширования в памяти.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/yac.

Бинарные файлы ОС Windows (DLL-файлы) для этого PECL-модуля доступны на сайте репозитория PECL.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Yac
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
yac.compress_threshold | -1 | `INI_SYSTEM` |
yac.debug | 0 | `INI_ALL` |
yac.enable | 1 | `INI_SYSTEM` |
yac.enable_cli | 0 | `INI_SYSTEM` |
yac.keys_memory_size | 4M | `INI_SYSTEM` |
yac.serializer | php | `INI_SYSTEM` |
yac.values_memory_size | 64M | `INI_SYSTEM` |

Краткое разъяснение конфигурационных директив.

`yac.compress_threshold` int

`yac.debug` int

`yac.enable` int

`yac.enable_cli` int

`yac.keys_memory_size` string

`yac.serializer` string

`yac.values_memory_size` string

## Типы ресурсов

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`YAC_VERSION` (string)
`YAC_MAX_KEY_LEN` (int)
  Максимальная длина ключа может быть 48 байтов.
`YAC_MAX_VALUE_RAW_LEN` (int)
`YAC_MAX_RAW_COMPRESSED_LEN` (int)
`YAC_SERIALIZER_PHP` (int)
  Использовать php serialize в качестве сериализатора
`YAC_SERIALIZER_JSON` (int)
  Использовать json в качестве сериализатора (требуется --enable-json)
`YAC_SERIALIZER_IGBINARY` (int)
  Использовать igbinary в качестве сериализатора (требуется --enable-igbinary)
`YAC_SERIALIZER_MSGPACK` (int)
  Использовать msgpack в качестве сериализатора (требуется --enable-msgpack)
`YAC_SERIALIZER` (string)
  Какой сериализатор используется в yac

# Класс Yac

(PECL yac >= 1.0.0)

## Введение

## Обзор класса

class Yac {
/* Свойства */
protected $_prefix;
/* Методы */
public function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## Свойства

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Сохраняет в кеш

### Описание

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Добавляет элемент в кеш.

### Список параметров

`keys`

  Ключ (string)

`value`

  Смешанное значение. Могут быть сохранены все типы значений php, кроме resource

`ttl`

  Время жизни

### Возвращаемые значения

bool, `true` в случае успешного выполнения, `false` в случае возникновения ошибки

> Замечание:

> Yac::add() может завершиться с ошибкой, если не удалось получить блокировку cas, поэтому, если вам нужно, чтобы значение сохранялось должным образом, вы можете написать следующее:

> Пример #1 Убедитесь, что элемент хранится

>     while(!$yac->set("key", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Конструктор класса

### Описание

public function Yac::__construct(string `$prefix` = "")

Префикс используется для добавления к ключам, его можно использовать для предотвращения конфликтов между приложениями.

### Список параметров

`prefix`

  Префикс (string)

### Ошибки

Выбрасывает Exception, если Yac не включён. Выбрасывает Exception, если `prefix` превышает максимальную длину ключа 48 (`YAC_MAX_KEY_LEN`) байтов.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Удаляет элементы из кеша

### Описание

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

Удаляет элементы из кеша

### Список параметров

`keys`

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

`ttl`

  Если задана задержка, удаление отметит элементы как недопустимые в течение ttl секунд.

### Возвращаемые значения

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Дамп кеша

### Описание

public function Yac::dump(int `$$num`): mixed

Дамп значений, хранящихся в кеше

### Список параметров

`num`

  Максимальное количество элементов, которые должны быть возвращены

### Возвращаемые значения

Смешанное значение.

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Очищает кеш

### Описание

public function Yac::flush(): bool

Удаляет все кешированные значения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Логическое значение, всегда возвращает true

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Извлекает значения из кеша

### Описание

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Извлекает значения из кеша

### Список параметров

`key`

  Ключ (string) или массив (array), состоящий из нескольких ключей

`cas`

  Если не `null`, будет установлен регистр извлечённых элементов.

### Возвращаемые значения

Метод возвращает смешанное значение в случае успешного выполнения, false, если возникла ошибка.

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Геттер

### Описание

public function Yac::__get(string `$key`): mixed

Извлекает значения из кеша

### Список параметров

`key`

  Ключ (string)

### Возвращаемые значения

Метод возвращает смешанное значение в случае успешного выполнения, `null`, если возникла ошибка.

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Состояние кеша

### Описание

public function Yac::info(): array

Получает статус кеш-системы

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Вернуть массив, соответствующий: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Сохраняет в кеш

### Описание

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Добавляет элемент в кеш, если ключ уже существует, заменяет его.

### Список параметров

`keys`

  Ключ (string)

`value`

  Смешанное значение. Могут быть сохранены все типы значений php, кроме resource

`ttl`

  Время жизни

### Возвращаемые значения

Собственное значение

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Сеттер

### Описание

public function Yac::__set(string `$keys`, mixed `$value`): mixed

Сохраняет элемент в кеш

### Список параметров

`keys`

  Ключ (string)

`value`

  Смешанное значение. Могут быть сохранены все типы значений php, кроме resource

### Возвращаемые значения

Всегда возвращает собственное значение

## Содержание

- Yac::add — Сохраняет в кеш
- Yac::__construct — Конструктор класса
- Yac::delete — Удаляет элементы из кеша
- Yac::dump — Дамп кеша
- Yac::flush — Очищает кеш
- Yac::get — Извлекает значения из кеша
- Yac::__get — Геттер
- Yac::info — Состояние кеша
- Yac::set — Сохраняет в кеш
- Yac::__set — Сеттер

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Yac — Класс Yac
  - Yac::add — Сохраняет в кеш
  - Yac::__construct — Конструктор класса
  - Yac::delete — Удаляет элементы из кеша
  - Yac::dump — Дамп кеша
  - Yac::flush — Очищает кеш
  - Yac::get — Извлекает значения из кеша
  - Yac::__get — Геттер
  - Yac::info — Состояние кеша
  - Yac::set — Сохраняет в кеш
  - Yac::__set — Сеттер

- APCu — Пользовательский кеш APC
  - Установка и настройка
  - Предопределённые константы
  - Функции APCu
  - APCUIterator — Класс APCUIterator
- Componere
  - Установка и настройка
  - Componere\Abstract\Definition — Класс Componere\Abstract\Definition
  - Componere\Definition — Класс Componere\Definition
  - Componere\Patch — Класс Componere\Patch
  - Componere\Method — Класс Componere\Method
  - Componere\Value — Класс Componere\Value
  - Функции Componere
- Обработка ошибок — Обработка и логирование ошибок
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции обработки ошибок
- FFI — Интерфейс внешней функции (Foreign Function Interface)
  - Установка и настройка
  - Примеры
  - FFI — Основной интерфейс к коду и данным языка C
  - FFI\CData — Доступ к данным C
  - FFI\CType — Доступ к типам C
  - FFI\Exception — Исключения FFI
  - FFI\ParserException — Исключения парсера FFI
- OPcache
  - Установка и настройка
  - Предзагрузка
  - Функции OPcache
- Operator Overloading — Operator Overloading for Objects
  - Установка и настройка
  - Operator Overloading Magic Methods
- Контроль вывода — Управление буфером вывода
  - Установка и настройка
  - Предопределённые константы
  - Буферизация вывода
  - Сброс (отправка) системных буферов
  - Пользовательские буферы вывода
  - Примеры
  - Функции контроля вывода
- Опции/информация PHP — Опции и информация PHP
  - Установка и настройка
  - Предопределённые константы
  - Опции PHP/информационные функции
- phpdbg — Интерактивный отладчик PHP
  - Установка и настройка
  - Предопределённые константы
  - Функции phpdbg
- runkit7
  - Установка и настройка
  - Предопределённые константы
  - Функции runkit7
- uopz — User Operations для Zend
  - Установка и настройка
  - Предопределённые константы
  - Функции Uopz
- WinCache — Windows Cache для PHP
  - Установка и настройка
  - Функции WinCache
  - Сборка для Windows
- Xhprof — Hierarchical Profiler
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Xhprof
- Yac
  - Установка и настройка
  - Предопределённые константы
  - Yac — Класс Yac

# Обработка аудиоформатов

# Аудиопотоки OpenAL

# Введение

Платформонезависимая работа с аудиопотоками. Требуется » библиотека OpenAL.

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/openal.

DLL для этого модуля PECL пока недоступна. Смотрите также раздел сборка на Windows.

## Типы ресурсов

Этот модуль определяет четыре типа ресурсов: Open AL(Device) - возвращается openal_device_open(), Open AL(Context) - возвращается openal_context_create(), Open AL(Buffer) - возвращается openal_buffer_create(), и Open AL(Source) - возвращается openal_source_create().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`ALC_FREQUENCY` (int)
  Атрибут контекста
`ALC_REFRESH` (int)
  Атрибут контекста
`ALC_SYNC` (int)
  Атрибут контекста
`AL_FREQUENCY` (int)
  Настройка буфера
`AL_BITS` (int)
  Настройка буфера
`AL_CHANNELS` (int)
  Настройка буфера
`AL_SIZE` (int)
  Настройка буфера
`AL_BUFFER` (int)
  Настройка источника/слушателя (целое число)
`AL_SOURCE_RELATIVE` (int)
  Настройка источника/слушателя (целое число)
`AL_SOURCE_STATE` (int)
  Настройка источника/слушателя (целое число)
`AL_PITCH` (int)
  Настройка источника/слушателя (рациональное число)
`AL_GAIN` (int)
  Настройка источника/слушателя (рациональное число)
`AL_MIN_GAIN` (int)
  Настройка источника/слушателя (рациональное число)
`AL_MAX_GAIN` (int)
  Настройка источника/слушателя (рациональное число)
`AL_MAX_DISTANCE` (int)
  Настройка источника/слушателя (рациональное число)
`AL_ROLLOFF_FACTOR` (int)
  Настройка источника/слушателя (рациональное число)
`AL_CONE_OUTER_GAIN` (int)
  Настройка источника/слушателя (рациональное число)
`AL_CONE_INNER_ANGLE` (int)
  Настройка источника/слушателя (рациональное число)
`AL_CONE_OUTER_ANGLE` (int)
  Настройка источника/слушателя (рациональное число)
`AL_REFERENCE_DISTANCE` (int)
  Настройка источника/слушателя (рациональное число)
`AL_POSITION` (int)
  Настройка источника/слушателя (рациональный вектор)
`AL_VELOCITY` (int)
  Настройка источника/слушателя (рациональный вектор)
`AL_DIRECTION` (int)
  Настройка источника/слушателя (рациональный вектор)
`AL_ORIENTATION` (int)
  Настройка источника/слушателя (рациональный вектор)
`AL_FORMAT_MONO8` (int)
  Формат PCM
`AL_FORMAT_MONO16` (int)
  Формат PCM
`AL_FORMAT_STEREO8` (int)
  Формат PCM
`AL_FORMAT_STEREO16` (int)
  Формат PCM
`AL_INITIAL` (int)
  Статус источника
`AL_PLAYING` (int)
  Статус источника
`AL_PAUSED` (int)
  Статус источника
`AL_STOPPED` (int)
  Статус источника
`AL_LOOPING` (int)
  Статус источника
`AL_TRUE` (int)
  Логическое значение, понимаемое OpenAL
`AL_FALSE` (int)
  Логическое значение, понимаемое OpenAL

# Функции OpenAL

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Сгенерировать буфер OpenAL

### Описание

function openal_buffer_create(): resource

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ресурс Open AL(Buffer) в случае успешного выполнения или `false` в случае возникновения ошибки.

### Смотрите также

- openal_buffer_loadwav() - Загрузить файл в формате wav в буфер
- openal_buffer_data() - Загрузка буфера с данными

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — Загрузка буфера с данными

### Описание

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### Список параметров

`buffer`
  Ресурс Open AL(Buffer) (созданный ранее с помощью openal_buffer_create()).
`format`
  Формат `data`, представленный одной из констант: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` и `AL_FORMAT_STEREO16`
`data`
  Блок двоичных аудиоданных в указанном формате `format` и с частотой `freq`.
`freq`
  Частота `data`, заданная в герцах.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_buffer_loadwav() - Загрузить файл в формате wav в буфер
- openal_stream() - Начать потоковую передачу с источника

# openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — Уничтожает буфер OpenAL

### Описание

function openal_buffer_destroy(resource `$buffer`): bool

### Список параметров

`buffer`
  Ресурс Open AL(Buffer) (ранее созданный с помощью openal_buffer_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_buffer_create() - Сгенерировать буфер OpenAL

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Получить свойство буфера OpenAL

### Описание

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### Список параметров

`buffer`
  Ресурс Open AL(Buffer) (созданный ранее с помощью openal_buffer_create()).
`property`
  Одно из свойств, заданное в виде константы: `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS` и `AL_SIZE`.

### Возвращаемые значения

Возвращает целочисленное значение, соответствующее запрошенному свойству `property` или `false`, если возникла ошибка.

### Смотрите также

- openal_buffer_create() - Сгенерировать буфер OpenAL

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Загрузить файл в формате wav в буфер

### Описание

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### Список параметров

`buffer`
  Ресурс Open AL(Buffer) (ранее созданный с помощью openal_buffer_create()).
`wavfile`
  Путь к файлу .wav в файловой системе local.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_buffer_data() - Загрузка буфера с данными
- openal_stream() - Начать потоковую передачу с источника

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — Создать контекст обработки звука

### Описание

function openal_context_create(resource `$device`): resource

### Список параметров

`device`
  Ресурс Open AL(Device) (созданный ранее с помощью openal_device_create()).

### Возвращаемые значения

Возвращает ресурс Open AL(Context) в случае успешного выполнения, `false` в случае возникновения ошибки.

### Смотрите также

- openal_device_open() - Инициализировать звуковой уровень OpenAL
- openal_context_destroy() - Уничтожает контекст

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — Сделать указанный контекст текущим

### Описание

function openal_context_current(resource `$context`): bool

### Список параметров

`context`
  Ресурс Open AL(Context) (созданный ранее с помощью openal_context_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_context_create() - Создать контекст обработки звука

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Уничтожает контекст

### Описание

function openal_context_destroy(resource `$context`): bool

### Список параметров

`context`
  Ресурс Open AL(Context) (созданный ранее с помощью openal_context_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_context_create() - Создать контекст обработки звука

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Обработать указанный контекст

### Описание

function openal_context_process(resource `$context`): bool

### Список параметров

`context`
  Ресурс Open AL(Context) (созданный ранее с помощью openal_context_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_context_create() - Создать контекст обработки звука
- openal_context_current() - Сделать указанный контекст текущим
- openal_context_suspend() - Приостановить указанный контекст

# openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — Приостановить указанный контекст

### Описание

function openal_context_suspend(resource `$context`): bool

### Список параметров

`context`
  Ресурс Open AL(Context) (созданный ранее с помощью openal_context_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_context_create() - Создать контекст обработки звука
- openal_context_current() - Сделать указанный контекст текущим
- openal_context_process() - Обработать указанный контекст

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — Закрыть устройство OpenAL

### Описание

function openal_device_close(resource `$device`): bool

### Список параметров

`device`
  Ресурс Open AL(Device) (созданный ранее с помощью openal_device_open()), который нужно закрыть.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_device_open() - Инициализировать звуковой уровень OpenAL

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Инициализировать звуковой уровень OpenAL

### Описание

function openal_device_open(string `$device_desc` = ?): resource

### Список параметров

`device_desc`
  При необходимости открыть аудиоустройство, указав значение параметра `device_desc`. Если `device_desc` не указан, будет использовано первое аудиоустройство.

### Возвращаемые значения

Возвращает ресурс Open AL(Device) в случае успешного выполнения или `false` в случае возникновения ошибки.

### Смотрите также

- openal_device_close() - Закрыть устройство OpenAL
- openal_context_create() - Создать контекст обработки звука

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — Получить свойство прослушивателя

### Описание

function openal_listener_get(int `$property`): mixed

### Список параметров

`property`
  Запрашиваемое свойство, представленное одной из констант: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) и `AL_ORIENTATION` (array(float,float,float)).

### Возвращаемые значения

Возвращает число с плавающей точкой или массив чисел с плавающими точками (при необходимости) или `false`, если возникла ошибка.

### Смотрите также

- openal_listener_set() - Установка свойства прослушивателя

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Установка свойства прослушивателя

### Описание

function openal_listener_set(int `$property`, mixed `$setting`): bool

### Список параметров

`property`
  Устанавливаемое свойство, представленное одной из констант: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) и `AL_ORIENTATION` (array(float,float,float)).
`setting`
  Значение для установки, либо число с плавающей точкой, либо массив с числами с плавающими точками.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_listener_get() - Получить свойство прослушивателя

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Сгенерировать источник ресурса

### Описание

function openal_source_create(): resource

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ресурс Open AL(Source) в случае успешного выполнения или `false` в случае возникновения ошибки.

### Смотрите также

- openal_source_set() - Установить свойство источника
- openal_source_play() - Начать воспроизведение источника
- openal_source_destroy() - Уничтожение ресурса источника

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — Уничтожение ресурса источника

### Описание

function openal_source_destroy(resource `$source`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_create() - Сгенерировать источник ресурса

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Получить свойство источника OpenAL

### Описание

function openal_source_get(resource `$source`, int `$property`): mixed

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).
`property`
  Получаемое свойство, представленное одной из констант: `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).

### Возвращаемые значения

Возвращает тип, связанный с извлекаемым свойством или `false`, если возникла ошибка.

### Смотрите также

- openal_source_create() - Сгенерировать источник ресурса
- openal_source_set() - Установить свойство источника
- openal_source_play() - Начать воспроизведение источника

# openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — Поставить источник на паузу

### Описание

function openal_source_pause(resource `$source`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_stop() - Остановить воспроизведение источника
- openal_source_play() - Начать воспроизведение источника
- openal_source_rewind() - Перемотать источник в начало

# openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — Начать воспроизведение источника

### Описание

function openal_source_play(resource `$source`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_stop() - Остановить воспроизведение источника
- openal_source_pause() - Поставить источник на паузу
- openal_source_rewind() - Перемотать источник в начало

# openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — Перемотать источник в начало

### Описание

function openal_source_rewind(resource `$source`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_stop() - Остановить воспроизведение источника
- openal_source_pause() - Поставить источник на паузу
- openal_source_play() - Начать воспроизведение источника

# openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — Установить свойство источника

### Описание

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).
`property`
  Устанавливаемое свойство, представляющее одну из констант: `AL_BUFFER` (OpenAL (источник)), `AL_LOOPING` (bool), `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).
`setting`
  Значение для присвоения указанному свойству `property`. Обратитесь к описанию параметра `property` для описания ожидаемых параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_create() - Сгенерировать источник ресурса
- openal_source_get() - Получить свойство источника OpenAL
- openal_source_play() - Начать воспроизведение источника

# openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — Остановить воспроизведение источника

### Описание

function openal_source_stop(resource `$source`): bool

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- openal_source_play() - Начать воспроизведение источника
- openal_source_pause() - Поставить источник на паузу
- openal_source_rewind() - Перемотать источник в начало

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — Начать потоковую передачу с источника

### Описание

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### Список параметров

`source`
  Ресурс Open AL(Source) (созданный ранее с помощью openal_source_create()).
`format`
  Формат данных `data`, представленный одной из констант: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` и `AL_FORMAT_STEREO16`
`rate`
  Частота передачи данных в поток задаётся в герцах.

### Возвращаемые значения

Возвращает ресурс потока в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- openal_source_create() - Сгенерировать источник ресурса
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме

## Содержание

- openal_buffer_create — Сгенерировать буфер OpenAL
- openal_buffer_data — Загрузка буфера с данными
- openal_buffer_destroy — Уничтожает буфер OpenAL
- openal_buffer_get — Получить свойство буфера OpenAL
- openal_buffer_loadwav — Загрузить файл в формате wav в буфер
- openal_context_create — Создать контекст обработки звука
- openal_context_current — Сделать указанный контекст текущим
- openal_context_destroy — Уничтожает контекст
- openal_context_process — Обработать указанный контекст
- openal_context_suspend — Приостановить указанный контекст
- openal_device_close — Закрыть устройство OpenAL
- openal_device_open — Инициализировать звуковой уровень OpenAL
- openal_listener_get — Получить свойство прослушивателя
- openal_listener_set — Установка свойства прослушивателя
- openal_source_create — Сгенерировать источник ресурса
- openal_source_destroy — Уничтожение ресурса источника
- openal_source_get — Получить свойство источника OpenAL
- openal_source_pause — Поставить источник на паузу
- openal_source_play — Начать воспроизведение источника
- openal_source_rewind — Перемотать источник в начало
- openal_source_set — Установить свойство источника
- openal_source_stop — Остановить воспроизведение источника
- openal_stream — Начать потоковую передачу с источника

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Функции OpenAL
  - openal_buffer_create — Сгенерировать буфер OpenAL
  - openal_buffer_data — Загрузка буфера с данными
  - openal_buffer_destroy — Уничтожает буфер OpenAL
  - openal_buffer_get — Получить свойство буфера OpenAL
  - openal_buffer_loadwav — Загрузить файл в формате wav в буфер
  - openal_context_create — Создать контекст обработки звука
  - openal_context_current — Сделать указанный контекст текущим
  - openal_context_destroy — Уничтожает контекст
  - openal_context_process — Обработать указанный контекст
  - openal_context_suspend — Приостановить указанный контекст
  - openal_device_close — Закрыть устройство OpenAL
  - openal_device_open — Инициализировать звуковой уровень OpenAL
  - openal_listener_get — Получить свойство прослушивателя
  - openal_listener_set — Установка свойства прослушивателя
  - openal_source_create — Сгенерировать источник ресурса
  - openal_source_destroy — Уничтожение ресурса источника
  - openal_source_get — Получить свойство источника OpenAL
  - openal_source_pause — Поставить источник на паузу
  - openal_source_play — Начать воспроизведение источника
  - openal_source_rewind — Перемотать источник в начало
  - openal_source_set — Установить свойство источника
  - openal_source_stop — Остановить воспроизведение источника
  - openal_stream — Начать потоковую передачу с источника

- OpenAL — Аудиопотоки OpenAL
  - Установка и настройка
  - Предопределённые константы
  - Функции OpenAL

# Службы аутентификации

# Radius

# Введение

Пакет базируется на библиотеке libradius (Remote Authentication Dial In User Service) из FreeBSD. Он позволяет производить учёт и аутентификацию клиентов путём запросов к удалённым сетевым сервисам.

Этот PECL-модуль добавляет полную поддержку Radius Authentication (» RFC 2865) и Radius Accounting (» RFC 2866). Этот пакет доступен для Unix (тестировался во FreeBSD и Linux) и для Windows.

> Замечание: Подробное описание библиотеки libradius можно найти » тут. Детальная информация о файле конфигурации лежит » тут.

# Установка и настройка

## Содержание

- Установка

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/radius.

# Предопределённые константы

## Содержание

- Опции службы RADIUS
- Типы пакетов службы RADIUS
- Типы атрибутов службы RADIUS
- Атрибуты RADIUS специфичные для разных производителей

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`RADIUS_MPPE_KEY_LEN` (int)
  Максимальная длина ключей протокола MPPE.

## Опции службы RADIUS

Ряд функций службы RADIUS принимает флаги опций как битовые маски. Константы, представляющие эти флаги, перечислены ниже.

`RADIUS_OPTION_SALT` (int)
  Опция, если установили, шифрует значение атрибута солью.
`RADIUS_OPTION_TAGGED` (int)
  Опция, если установили, помечает значение атрибута значением параметра тега.

## Типы пакетов службы RADIUS

Пакеты запросов и ответов, которые передают по протоколу RADIUS, включают тип. Эти константы упрощают указание типов при вызове функции radius_create_request() и при обработке ответа, который даёт функция radius_send_request().

`RADIUS_ACCESS_REQUEST` (int)
  По сообщению Access-Request сервер RADIUS аутентифицирует пользователя, который отправил запрос. Пакеты запроса доступа должны включать атрибут `RADIUS_NAS_IP_ADDRESS` или `RADIUS_NAS_IDENTIFIER`, также должны включать атрибут `RADIUS_USER_PASSWORD`, `RADIUS_CHAP_PASSWORD` или `RADIUS_STATE`, и рекомендуется включать атрибут `RADIUS_USER_NAME`.
`RADIUS_ACCESS_ACCEPT` (int)
  Ответ Access-Accept на запрос Access-Request сигнализирует, что сервер RADIUS успешно аутентифицировал пользователя.
`RADIUS_ACCESS_REJECT` (int)
  Ответ Access-Reject на запрос Access-Request говорит, что RADIUS-сервер не смог аутентифицировать пользователя.
`RADIUS_ACCESS_CHALLENGE` (int)
  Ответ Access-Challenge на запрос Access-Request означает, что серверу RADIUS требуется дополнительная информация в другом запросе Access-Request перед аутентификацией пользователя.
`RADIUS_ACCOUNTING_REQUEST` (int)
  В сообщении Accounting-Request клиент передаёт на RADIUS-сервер учётную информацию для службы.
`RADIUS_ACCOUNTING_RESPONSE` (int)
  Accounting-Response — ответ на запрос Accounting-Request.
`RADIUS_COA_REQUEST` (int)
  Сервер RADIUS посылает запрос CoA-Request, чтобы сообщить, что полномочия в сеансе пользователя изменились. Ответ должен быть отправлен в виде сообщения CoA-ACK или CoA-NAK. Константа доступна в модуле PECL radius 1.3.0 и выше.
`RADIUS_COA_ACK` (int)
  Клиент отправляет на сервер RADIUS ответ с сообщением CoA-ACK, чтобы указать, что полномочия пользователя обновились. Константа доступна в модуле PECL radius 1.3.0 и выше.
`RADIUS_COA_NAK` (int)
  Клиент отправляет на сервер RADIUS ответ с сообщением CoA-NAK, чтобы указать, что полномочия пользователя не могут обновиться. Константа доступна в модуле PECL radius 1.3.0 и выше.
`RADIUS_DISCONNECT_REQUEST` (int)
  Запрос Disconnect-Request с сервера RADIUS сообщает, что сеанс пользователя нужно прервать. Константа доступна в модуле PECL radius 1.3.0 и выше.
`RADIUS_DISCONNECT_ACK` (int)
  Клиент отправляет на сервер RADIUS ответ с сообщением Disconnect-ACK, чтобы указать, что сессия пользователя прервана. Константа доступна в модуле PECL radius 1.3.0 и выше.
`RADIUS_DISCONNECT_NAK` (int)
  Клиент отправляет на сервер RADIUS ответ с сообщением Disconnect-NAK, чтобы указать, что сессия пользователя не прервана. Константа доступна в модуле PECL radius 1.3.0 и выше.

## Типы атрибутов службы RADIUS

Эти константы описывают типы атрибутов протокола RADIUS, которые передают в функции radius_put_addr(), radius_put_attr(), radius_put_int() и radius_put_string().

`RADIUS_USER_NAME` (int)
  Атрибут User-Name. Ожидается, что значение атрибута будет строкой (string), которая содержит имя аутентифицируемого пользователя, и которую устанавливают функцией radius_put_attr().
`RADIUS_USER_PASSWORD` (int)
  Атрибут User-Password. Ожидается, что значение атрибута будет строкой (string), которая содержит пароль пользователя, и которую устанавливают функцией radius_put_attr(). Это значение будет обфусцировано при передаче согласно » разделу 5.2 стандарта RFC 2865.
`RADIUS_CHAP_PASSWORD` (int)
  Атрибут Chap-Password. Ожидается, что значение атрибута будет строкой (string), первый байт которой содержит идентификатор CHAP пользователя, а следующие 16 байтов содержат MD5-хэш CHAP-идентификатора, пароль в виде открытого текста и значение запроса CHAP, объединенные вместе. Обратите внимание, что проверочное значение CHAP также должно быть отдельно послано в атрибуте `RADIUS_CHAP_CHALLENGE`.

  Пример #1 Использование паролей CHAP

      <?php

      // Сначала создадим обработчик аутентификации и запрос
      $radh = radius_auth_open();
      radius_add_server($radh, $server, $port, $secret, 3, 3);
      radius_create_request($radh, RADIUS_ACCESS_REQUEST);

      // Теперь, предполагая, что переменная $password содержит открытый пароль:

      // Создаём проверочное значение
      $challenge = mt_rand();

      // Задаём идентификатор CHAP
      $ident = 1;

      // Добавляем атрибут Chap-Password
      $cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
      radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

      // Добавляем атрибут Chap-Challenge
      radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

      /* Теперь нужно добавить оставшиеся атрибуты
       * и вызывать функцию radius_send_request(). */

      ?>

`RADIUS_NAS_IP_ADDRESS` (int)
  Атрибут NAS-IP-Address. Ожидается, что значение будет IP-адресом клиента RADIUS в виде целого числа. Атрибут устанавливается функцией radius_put_addr().
`RADIUS_NAS_PORT` (int)
  Атрибут NAS-Port. Значение атрибута должно быть физическим портом пользователя на клиенте RADIUS в виде целого числа (int), которое устанавливается функцией radius_put_int().
`RADIUS_SERVICE_TYPE` (int)
  Атрибут Service-Type. Значение атрибута указывает на тип службы, которую запрашивает пользователь; ожидается целое число (int), которое можно установить функцией radius_put_int().

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

  - `RADIUS_LOGIN`
  - `RADIUS_FRAMED`
  - `RADIUS_CALLBACK_LOGIN`
  - `RADIUS_CALLBACK_FRAMED`
  - `RADIUS_OUTBOUND`
  - `RADIUS_ADMINISTRATIVE`
  - `RADIUS_NAS_PROMPT`
  - `RADIUS_AUTHENTICATE_ONLY`
  - `RADIUS_CALLBACK_NAS_PROMPT`
`RADIUS_FRAMED_PROTOCOL` (int)

  Атрибут Framed-Protocol. Значение атрибута указывает тип кадрирования для доступа; ожидается целое число (int), которое можно установить функцией radius_put_int(). Возможные значения атрибута включают следующие константы:

  - `RADIUS_PPP`
  - `RADIUS_SLIP`
  - `RADIUS_ARAP`
  - `RADIUS_GANDALF`
  - `RADIUS_XYLOGICS`
`RADIUS_FRAMED_IP_ADDRESS` (int)
  Атрибут Framed-IP-Address. Атрибут должен содержать адрес пользовательской сети в виде целого числа. Атрибут устанавливается функцией radius_put_addr() и извлекается функцией radius_cvt_addr().
`RADIUS_FRAMED_IP_NETMASK` (int)
  Атрибут Framed-IP-Netmask. Значение атрибута должно быть маской сети пользователя, представленной в виде целого числа (int), которое можно установить функцией radius_put_addr() и извлечь функцией radius_cvt_addr().
`RADIUS_FRAMED_ROUTING` (int)
  Атрибут Framed-Routing. Значение атрибута указывает метод маршрутизации для пользователя; ожидается целое число (int), которое можно установить функцией radius_put_int().

  Возможные значения включают:

  - `0`: Без маршрутизации
  - `1`: Посылка пакетов маршрутизации
  - `2`: Прослушивание пакетов маршрутизации
  - `3`: Отправка и прослушивание
`RADIUS_FILTER_ID` (int)
  Атрибут Filter-ID. Атрибут должен быть зависящей от реализации, человеко-читаемой строкой фильтров. Атрибут устанавливается функцией radius_put_attr().
`RADIUS_FRAMED_MTU` (int)
  Атрибут Framed-MTU. Значение атрибута указывает MTU для пользователя; ожидается целое число (int), которое можно установить функцией radius_put_int().
`RADIUS_FRAMED_COMPRESSION` (int)

  Атрибут Framed-Compression. Значение атрибута указывает на используемый тип сжатия; ожидается целое число (int), которое можно установить функцией radius_put_int(). Возможные значения атрибута включают следующие константы:

  - `RADIUS_COMP_NONE`: Без сжатия
  - `RADIUS_COMP_VJ`: Сжатие заголовков VJ TCP/IP
  - `RADIUS_COMP_IPXHDR`: Сжатие заголовков IPX
  - `RADIUS_COMP_STAC_LZS`: Сжатие Stac-LZS (добавлено в PECL radius 1.3.0b2)
`RADIUS_LOGIN_IP_HOST` (int)
  Атрибут Login-IP-Host. Значение атрибута должно быть IP-адресом для подключения пользователя, представленным в виде целого числа (int), которое можно установить функцией radius_put_addr().
`RADIUS_LOGIN_SERVICE` (int)
  Атрибут Login-Service. Значение атрибута означает сервис, с которым пользователь соединяется на сервере аутентификации. Это значение можно преобразовать в целое число PHP функцией radius_cvt_int().
`RADIUS_LOGIN_TCP_PORT` (int)
  Атрибут Login-TCP-Port. Значение атрибута означает порт, с которым пользователь соединяется на сервере аутентификации. Это значение можно преобразовать в целое число PHP с помощью функции radius_cvt_int().
`RADIUS_REPLY_MESSAGE` (int)
  Атрибут Reply-Message. Значение атрибута содержит текст, который можно показать пользователю в ответ на запрос аутентификации.
`RADIUS_CALLBACK_NUMBER` (int)
  Атрибут Callback-Number. Атрибут содержит строку, которую можно использовать как функцию обратного вызова.
`RADIUS_CALLBACK_ID` (int)
  Атрибут Callback-Id. Строка, которая содержит имя вызываемого метода, специфичного для конкретной реализации.
`RADIUS_FRAMED_ROUTE` (int)
  Атрибут Framed-Route. Строка, которая содержит зависящий от реализации список маршрутов сконфигурированных для пользователя.
`RADIUS_FRAMED_IPX_NETWORK` (int)
  Атрибут Framed-IPX-Network. Целое число, которое определяет сеть IPX, настроенную для пользователя или `0xFFFFFFFE`, что призывает клиента RADIUS выбрать сеть самостоятельно. Можно извлечь с помощью radius_cvt_int().
`RADIUS_STATE` (int)
  Атрибут State. Значение атрибута — строка (string), которая зависит от реализации, включённая в ответ сервера Access-Challenge, которую нужно включить в следующий запрос Access-Request, и которая устанавливается функцией radius_put_attr().
`RADIUS_CLASS` (int)
  Атрибут Class. Произвольная строка, включённая в сообщение Access-Accept, которую нужно отправить на сервер учётных данных в запросе Accounting-Request, и которая устанавливается функцией radius_put_attr().
`RADIUS_VENDOR_SPECIFIC` (int)
  Атрибут Vendor-Specific. Обычно значения атрибутов поставщика должны устанавливаться функциями radius_put_vendor_addr(), radius_put_vendor_attr(), radius_put_vendor_int() и radius_put_vendor_string(), а не напрямую. Эта константа в основном полезна при интерпретации специфичных для поставщика атрибутов в ответах RADIUS-сервера; когда получен специфичный для поставщика атрибут, вызывают функцию radius_get_vendor_attr(), чтобы получить доступ к идентификатору поставщика, а также типу и значению атрибута.
`RADIUS_SESSION_TIMEOUT` (int)
  Время ожидания сессии.
`RADIUS_IDLE_TIMEOUT` (int)
  Время ожидания простоя.
`RADIUS_TERMINATION_ACTION` (int)
  Прекращение операции.
`RADIUS_CALLED_STATION_ID` (int)
  Идентификатор вызываемой станции.
`RADIUS_CALLING_STATION_ID` (int)
  Идентификатор вызывающей станции.
`RADIUS_NAS_IDENTIFIER` (int)
  NAS ID
`RADIUS_PROXY_STATE` (int)
  Состояние прокси.
`RADIUS_LOGIN_LAT_SERVICE` (int)
  Сервис входа в систему LAT.
`RADIUS_LOGIN_LAT_NODE` (int)
  Узел входа в систему LAT.
`RADIUS_LOGIN_LAT_GROUP` (int)
  Группа входа в систему LAT.
`RADIUS_FRAMED_APPLETALK_LINK` (int)
  Канал пакетной передачи данных для стека протоколов Appletalk.
`RADIUS_FRAMED_APPLETALK_NETWORK` (int)
  Сеть пакетной передачи данных для стека протоколов Appletalk.
`RADIUS_FRAMED_APPLETALK_ZONE` (int)
  Зона пакетной передачи данных для стека протоколов Appletalk.
`RADIUS_CHAP_CHALLENGE` (int)
  Проверочное значение.
`RADIUS_NAS_PORT_TYPE` (int)

  Тип порта NAS, одна из констант:

  - `RADIUS_ASYNC`
  - `RADIUS_SYNC`
  - `RADIUS_ISDN_SYNC`
  - `RADIUS_ISDN_ASYNC_V120`
  - `RADIUS_ISDN_ASYNC_V110`
  - `RADIUS_VIRTUAL`
  - `RADIUS_PIAFS`
  - `RADIUS_HDLC_CLEAR_CHANNEL`
  - `RADIUS_X_25`
  - `RADIUS_X_75`
  - `RADIUS_G_3_FAX`
  - `RADIUS_SDSL`
  - `RADIUS_ADSL_CAP`
  - `RADIUS_ADSL_DMT`
  - `RADIUS_IDSL`
  - `RADIUS_ETHERNET`
  - `RADIUS_XDSL`
  - `RADIUS_CABLE`
  - `RADIUS_WIRELESS_OTHER`
  - `RADIUS_WIRELESS_IEEE_802_11`
`RADIUS_PORT_LIMIT` (int)
  Ограничение на порты.
`RADIUS_LOGIN_LAT_PORT` (int)
  Порт входа в систему LAT.
`RADIUS_CONNECT_INFO` (int)
  Информация о соединении.
`RADIUS_ACCT_STATUS_TYPE` (int)

  Статус системы управления учётными данными, одна из констант:

  - `RADIUS_START`
  - `RADIUS_STOP`
  - `RADIUS_ACCOUNTING_ON`
  - `RADIUS_ACCOUNTING_OFF`
`RADIUS_ACCT_DELAY_TIME` (int)
  Время задержки системы управления учётными данными.
`RADIUS_ACCT_INPUT_OCTETS` (int)
  Входящие байты в систему управления учётными данными.
`RADIUS_ACCT_OUTPUT_OCTETS` (int)
  Исходящие байты из системы управления учётными данными.
`RADIUS_ACCT_SESSION_ID` (int)
  Идентификатор сессии системы управления учётными данными.
`RADIUS_ACCT_AUTHENTIC` (int)

  Тип системы управления учётными данными, одна из констант:

  - `RADIUS_AUTH_RADIUS`
  - `RADIUS_AUTH_LOCAL`
  - `RADIUS_AUTH_REMOTE`
`RADIUS_ACCT_SESSION_TIME` (int)
  Время сессии в системе управления учётными данными.
`RADIUS_ACCT_INPUT_PACKETS` (int)
  Входящие пакеты в систему управления учётными данными.
`RADIUS_ACCT_OUTPUT_PACKETS` (int)
  Исходящие пакеты из системы управления учётными данными.
`RADIUS_ACCT_TERMINATE_CAUSE` (int)

  Аварийное завершение сеанса управления учётными данными:

  - `RADIUS_TERM_USER_REQUEST`
  - `RADIUS_TERM_LOST_CARRIER`
  - `RADIUS_TERM_LOST_SERVICE`
  - `RADIUS_TERM_IDLE_TIMEOUT`
  - `RADIUS_TERM_SESSION_TIMEOUT`
  - `RADIUS_TERM_ADMIN_RESET`
  - `RADIUS_TERM_ADMIN_REBOOT`
  - `RADIUS_TERM_PORT_ERROR`
  - `RADIUS_TERM_NAS_ERROR`
  - `RADIUS_TERM_NAS_REQUEST`
  - `RADIUS_TERM_NAS_REBOOT`
  - `RADIUS_TERM_PORT_UNNEEDED`
  - `RADIUS_TERM_PORT_PREEMPTED`
  - `RADIUS_TERM_PORT_SUSPENDED`
  - `RADIUS_TERM_SERVICE_UNAVAILABLE`
  - `RADIUS_TERM_CALLBACK`
  - `RADIUS_TERM_USER_ERROR`
  - `RADIUS_TERM_HOST_REQUEST`
`RADIUS_ACCT_MULTI_SESSION_ID` (int)
  Многосессионный идентификатор системы управления учётными данными.
`RADIUS_ACCT_LINK_COUNT` (int)
  Количество соединений системы управления учётными данными.

Service-Type Constants
`RADIUS_LOGIN`
`RADIUS_FRAMED`
`RADIUS_CALLBACK_LOGIN`
`RADIUS_CALLBACK_FRAMED`
`RADIUS_OUTBOUND`
`RADIUS_ADMINISTRATIVE`
`RADIUS_NAS_PROMPT`
`RADIUS_AUTHENTICATE_ONLY`
`RADIUS_CALLBACK_NAS_PROMPT`

Framed-Protocol Constants
`RADIUS_PPP`
`RADIUS_SLIP`
`RADIUS_ARAP`
`RADIUS_GANDALF`
`RADIUS_XYLOGICS`

Framed-Compression Constants
`RADIUS_COMP_NONE`
`RADIUS_COMP_VJ`
`RADIUS_COMP_IPXHDR`
`RADIUS_COMP_STAC_LZS`

NAS Port Type Constants
`RADIUS_ASYNC`
`RADIUS_SYNC`
`RADIUS_ISDN_SYNC`
`RADIUS_ISDN_ASYNC_V120`
`RADIUS_ISDN_ASYNC_V110`
`RADIUS_VIRTUAL`
`RADIUS_PIAFS`
`RADIUS_HDLC_CLEAR_CHANNEL`
`RADIUS_X_25`
`RADIUS_X_75`
`RADIUS_G_3_FAX`
`RADIUS_SDSL`
`RADIUS_ADSL_CAP`
`RADIUS_ADSL_DMT`
`RADIUS_IDSL`
`RADIUS_ETHERNET`
`RADIUS_XDSL`
`RADIUS_CABLE`
`RADIUS_WIRELESS_OTHER`
`RADIUS_WIRELESS_IEEE_802_11`

Accounting Status Type Constants
`RADIUS_START`
`RADIUS_STOP`
`RADIUS_ACCOUNTING_ON`
`RADIUS_ACCOUNTING_OFF`

Accounting Authentic Constants
`RADIUS_AUTH_RADIUS`
`RADIUS_AUTH_LOCAL`
`RADIUS_AUTH_REMOTE`

Accounting Terminate Cause Constants
`RADIUS_TERM_USER_REQUEST`
`RADIUS_TERM_LOST_CARRIER`
`RADIUS_TERM_LOST_SERVICE`
`RADIUS_TERM_IDLE_TIMEOUT`
`RADIUS_TERM_SESSION_TIMEOUT`
`RADIUS_TERM_ADMIN_RESET`
`RADIUS_TERM_ADMIN_REBOOT`
`RADIUS_TERM_PORT_ERROR`
`RADIUS_TERM_NAS_ERROR`
`RADIUS_TERM_NAS_REQUEST`
`RADIUS_TERM_NAS_REBOOT`
`RADIUS_TERM_PORT_UNNEEDED`
`RADIUS_TERM_PORT_PREEMPTED`
`RADIUS_TERM_PORT_SUSPENDED`
`RADIUS_TERM_SERVICE_UNAVAILABLE`
`RADIUS_TERM_CALLBACK`
`RADIUS_TERM_USER_ERROR`
`RADIUS_TERM_HOST_REQUEST`

## Атрибуты RADIUS специфичные для разных производителей

`RADIUS_VENDOR_MICROSOFT` (int)

  Атрибуты Microsoft (» RFC 2548):

  - `RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP_ERROR`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_1`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_2`
  - `RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
  - `RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
  - `RADIUS_MICROSOFT_MS_RAS_VENDOR`
  - `RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
  - `RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
  - `RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
  - `RADIUS_MICROSOFT_MS_BAP_USAGE`
  - `RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
  - `RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
  - `RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
  - `RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
  - `RADIUS_MICROSOFT_MS_RAS_VERSION`
  - `RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
  - `RADIUS_MICROSOFT_MS_FILTER`
  - `RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
  - `RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
  - `RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
  - `RADIUS_MICROSOFT_MS_CHAP2_PW`
  - `RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP_ERROR`
`RADIUS_MICROSOFT_MS_CHAP_PW_1`
`RADIUS_MICROSOFT_MS_CHAP_PW_2`
`RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
`RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
`RADIUS_MICROSOFT_MS_RAS_VENDOR`
`RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
`RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
`RADIUS_MICROSOFT_MS_BAP_USAGE`
`RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
`RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
`RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
`RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
`RADIUS_MICROSOFT_MS_RAS_VERSION`
`RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
`RADIUS_MICROSOFT_MS_FILTER`
`RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
`RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
`RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
`RADIUS_MICROSOFT_MS_CHAP2_PW`
`RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

# Примеры

Как начать?

- получить ресурс radius
- настроить библиотеку
- создать запрос
- прикрепить атрибуты
- послать запрос
- получить атрибуты
- закрыть ресурс radius (по желанию)

также смотрите примеры использования.

Пакет содержит пример PHP-скрипта. Этот скрипт демонстрирует как производить аутентификацию с помощью radius, используя PAP или CHAP (md5). Если вы производите аутентификацию с помощью серверов Microsoft Radius, то использовать CHAP (md5) не получится. В таком случае вам придётся использовать MS-CHAPv1 или MS-CHAPv2, но это чуть сложнее, так как вам придётся использовать md4, sha1 и des для генерации корректных данных. Приложенные примеры демонстрируют все методы аутентификации, включая MS-CHAPv1 и MS-CHAPv2. Для получения рабочего MS-CHAP вам понадобятся модули mcrypt и mhash. Начиная с версии 1.2, модуль mcrypt больше не нужен.

# Функции Radius

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Создаёт дескриптор Radius для учёта

### Описание

function radius_acct_open(): resource

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дескриптор в случае успешного выполнения или `false` в случае возникновения ошибки. Функция завершится с ошибкой, только если недостаточно памяти.

### Примеры

Пример #1 Пример использования radius_acct_open()

    <?php
    $res = radius_acct_open ()
        or die ("Не удалось создать дескриптор");
    print("Дескриптор успешно создан");
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — Добавляет сервер

### Описание

function radius_add_server(
resource `$radius_handle`,
string `$hostname`,
int `$port`,
string `$secret`,
int `$timeout`,
int `$max_tries`
): bool

radius_add_server() может вызываться несколько раз и может использоваться вместе с radius_config(). Можно указать не более 10 серверов. Когда задано несколько серверов, они проверяются циклически, пока не будет получен действительный ответ или пока не будет достигнут предел `max_tries` для каждого сервера.

### Список параметров

`radius_handle`
`hostname`
  Параметр `hostname` указывает хост сервера в виде полного доменного имени или IP-адреса, разделённого точками, в текстовом виде.
`port`

  `port` указывает UDP-порт для связи на сервере. Если порт задан как 0, библиотека ищет сервис `radius/udp` или `radacct/udp` в базе данных сетевых сервисов, и использует найденный там порт. Если запись не найдена, библиотека использует стандартные порты Radius, 1812 для аутентификации и 1813 для учёта.

`secret`
  Общий секрет для хоста сервера передаётся в параметре `secret`. Протокол Radius игнорирует всё, кроме первых 128 байтов общего секрета.
`timeout`
  Время ожидания получения ответов от сервера передаётся в параметре `timeout` в секундах.
`max_tries`
  Максимальное количество повторных запросов, которые нужно сделать перед отказом, передаётся в `max_tries`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования radius_add_server()

    <?php
    if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br>";
        exit;
    }
    ?>

### Смотрите также

- radius_config() - Заставляет библиотеку читать данный файл конфигурации

# radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — Создаёт дескриптор Radius для аутентификации

### Описание

function radius_auth_open(): resource

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дескриптор в случае успешного выполнения или `false` в случае возникновения ошибки. Функция завершится с ошибкой, только если недостаточно памяти.

### Примеры

Пример #1 Пример использования radius_auth_open()

    <?php
    $radh = radius_auth_open()
        or die ("Не удалось создать дескриптор");
    echo "Дескриптор успешно создан";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — Освобождает все ресурсы

### Описание

function radius_close(resource `$radius_handle`): bool

Не нужно вызывать эту функцию, потому что php освобождает все ресурсы в конце каждого запроса.

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# radius_config

(PECL radius >= 1.1.0)

radius_config — Заставляет библиотеку читать данный файл конфигурации

### Описание

function radius_config(resource `$radius_handle`, string `$file`): bool

Перед выполнением любых запросов Radius, библиотека должна быть информирована о серверах, с которыми она может связаться. Самый простой способ настроить библиотеку - вызвать radius_config(). radius_config() заставляет библиотеку читать файл конфигурации, формат которого описан в » radius.conf.

### Список параметров

`radius_handle`
`file`
  Путь к файлу конфигурации передаётся в качестве аргумента файла в radius_config(). Библиотека также может быть настроена программно с помощью вызова radius_add_server().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- radius_add_server() - Добавляет сервер

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Создаёт учётную запись или запрос аутентификации

### Описание

function radius_create_request(resource `$radius_handle`, int `$type`): bool

Запрос Radius состоит из кода, указывающего тип запроса, и нуля или более атрибутов, которые предоставляют дополнительную информацию. Чтобы начать создание нового запроса, вызовите radius_create_request().

> Замечание: Внимание: вы должны вызвать эту функцию, прежде чем вы сможете поместить любой атрибут!

### Список параметров

`radius_handle`
`type`
  Тип `RADIUS_ACCESS_REQUEST` или `RADIUS_ACCOUNTING_REQUEST`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования radius_create_request()

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Смотрите также

- radius_send_request() - Отправляет запрос и ждёт ответ

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — Преобразовывает необработанные данные в IP-адрес

### Описание

function radius_cvt_addr(string `$data`): string

Преобразовывает необработанные данные в IP-адрес.

### Список параметров

`data`
  Входные данные

### Возвращаемые значения

Возвращает IP-адрес.

### Примеры

Пример #1 Пример использования radius_cvt_addr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_IP_ADDRESS:
            $ip = radius_cvt_addr($data);
            echo "IP: $ip<br>\n";
            break;

        case RADIUS_FRAMED_IP_NETMASK:
            $mask = radius_cvt_addr($data);
            echo "Маска: $mask<br>\n";
            break;
        }
    }
    ?>

### Смотрите также

- radius_cvt_int() - Преобразовывает необработанные данные в целое число
- radius_cvt_string() - Преобразовывает необработанные данные в строку

# radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — Преобразовывает необработанные данные в целое число

### Описание

function radius_cvt_int(string `$data`): int

Преобразовывает необработанные данные в целое число.

### Список параметров

`data`
  Входные данные

### Возвращаемые значения

Возвращает целое число, полученное из данных.

### Примеры

Пример #1 Пример использования radius_cvt_int()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_MTU:
            $mtu = radius_cvt_int($data);
            echo "Максимальная единица передачи: $mtu<br>\n";
            break;
        }
    }
    ?>

### Смотрите также

- radius_cvt_addr() - Преобразовывает необработанные данные в IP-адрес
- radius_cvt_string() - Преобразовывает необработанные данные в строку

# radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — Преобразовывает необработанные данные в строку

### Описание

function radius_cvt_string(string `$data`): string

Преобразовывает необработанные данные в строку

### Список параметров

`data`
  Входные данные

### Возвращаемые значения

Возвращает строку, полученную из данных.

### Примеры

Пример #1 Пример использования функции radius_cvt_string()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FILTER_ID:
            $id = radius_cvt_string($data);
            echo "Идентификатор фильтра: $id<br>\n";
            break;
        }
    }
    ?>

### Смотрите также

- radius_cvt_addr() - Преобразовывает необработанные данные в IP-адрес
- radius_cvt_int() - Преобразовывает необработанные данные в целое число

# radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — Расшифровывает данные

### Описание

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

Некоторые данные (пароли, MS-CHAPv1 MPPE-ключи) искажены по соображениям безопасности и их необходимо расшифровать, прежде чем вы сможете их использовать.

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`mangled`
  Искажённые данные, которые необходимо расшифровать.

### Возвращаемые значения

Возвращает расшифрованную строку или `false` в случае возникновения ошибки.

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — Получает mppe-ключи из искажённых данных

### Описание

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

При использовании MPPE с MS-CHAPv2, ключи отправляемые и получаемые ключи искажаются (смотрите » RFC 2548), однако эта функция бесполезна, поскольку я не думаю, что есть или будет реализация PPTP-MPPE в PHP.

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`mangled`
  Искажённые данные, которые необходимо деформировать

### Возвращаемые значения

Возвращает деформированную строку или `false` в случае возникновения ошибки.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Извлекает атрибут

### Описание

function radius_get_attr(resource `$radius_handle`): mixed

Как и запросы Radius, каждый ответ может содержать ноль или более атрибутов. После того, как ответ был успешно получен от radius_send_request(), его атрибуты могут быть извлечены один за другим с помощью radius_get_attr(). Каждый раз, когда вызывается radius_get_attr(), функция получает следующий атрибут из текущего ответа.

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Возвращает ассоциативный массив, содержащий тип атрибута и данные или номер ошибки <= 0.

### Примеры

Пример #1 Пример использования radius_get_attr()

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Получен атрибут: %d %d байт %s\n", $attr, strlen($data), bin2hex($data));
    }
    ?>

### Смотрите также

- radius_put_attr() - Присоединяет бинарный атрибут
- radius_get_vendor_attr() - Извлекает атрибут конкретного поставщика
- radius_put_vendor_attr() - Присоединяет бинарный атрибут, зависящий от поставщика
- radius_send_request() - Отправляет запрос и ждёт ответ

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Извлекает данные из помеченного атрибута

### Описание

function radius_get_tagged_attr_data(string `$data`): string|false

Если из radius_get_attr() был возвращён тегированный атрибут, radius_get_tagged_attr_data() вернёт тег из атрибута.

### Список параметров

`data`
  Тегированный атрибут, который нужно раскодировать.

### Возвращаемые значения

Возвращает данные из тегированного атрибута или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования radius_get_tagged_attr_data()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Получен тегированный атрибут с тегом %d и значением %s\n", $tag, $value);
    }
    ?>

### Смотрите также

- radius_get_attr() - Извлекает атрибут
- radius_get_tagged_attr_tag() - Извлекает тег из помеченного атрибута

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Извлекает тег из помеченного атрибута

### Описание

function radius_get_tagged_attr_tag(string `$data`): int|false

Если из radius_get_attr() был возвращён тегированный атрибут, radius_get_tagged_attr_data() вернёт тег из атрибута.

### Список параметров

`data`
  Тегированный атрибут, который нужно раскодировать.

### Возвращаемые значения

Возвращает тег из тегированного атрибута или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования radius_get_tagged_attr_tag()

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Получен тегированный атрибут с тегом %d и значением %s\n", $tag, $value);
    }
    ?>

### Смотрите также

- radius_get_attr() - Извлекает атрибут
- radius_get_tagged_attr_data() - Извлекает данные из помеченного атрибута

# radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — Извлекает атрибут конкретного поставщика

### Описание

function radius_get_vendor_attr(string `$data`): array|false

Функция radius_get_vendor_attr() определит поставщика, только если функция radius_get_attr() вернула атрибут `RADIUS_VENDOR_SPECIFIC`.

### Список параметров

`data`
  Входные данные.

### Возвращаемые значения

Функция возвращает ассоциативный массив, который включает тип атрибута, идентификатор поставщика и данные, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример извлечения атрибутов поставщика функцией radius_get_vendor_attr()

    <?php

    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Ошибка при получении атрибута: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Получен атрибут:%d %d байт %s\n", $attr, strlen($data), bin2hex($data));
        if ($attr == RADIUS_VENDOR_SPECIFIC) {

            $resv = radius_get_vendor_attr($data);
            if (is_array($resv)) {
                $vendor = $resv['vendor'];
                $attrv = $resv['attr'];
                $datav = $resv['data'];
                printf("Получен атрибут поставщика:%d %d байт %s\n", $attrv, strlen($datav), bin2hex($datav));
            }
        }
    }

### Смотрите также

- radius_get_attr() - Извлекает атрибут
- radius_put_vendor_attr() - Присоединяет бинарный атрибут, зависящий от поставщика

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — Присоединяет атрибут IP-адреса

### Описание

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет атрибут IP-адреса к текущему запросу RADIUS.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`type`
  Тип атрибута.
`addr`
  Адрес IPv4 в виде строки, например, `10.0.0.1`.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — Присоединяет бинарный атрибут

### Описание

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет бинарный атрибут к текущему запросу RADIUS.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`type`
  Тип атрибута.
`value`
  Значение атрибута, которое будет рассматриваться как необработанная двоичная строка.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Примеры

Пример #1 Пример использования radius_put_attr()

    <?php

    mt_srand(time());
    $chall = mt_rand();
    $chapval = hash('md5', pack('Ca*',1 , 'sepp' . $chall));
    $pass = pack('CH*', 1, $chapval);

    if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
        echo 'Ошибка Radius:' . radius_strerror($res). "\n<br />";
        exit;
    }

    ?>

### Смотрите также

- radius_get_attr() - Извлекает атрибут
- radius_get_vendor_attr() - Извлекает атрибут конкретного поставщика
- radius_put_vendor_attr() - Присоединяет бинарный атрибут, зависящий от поставщика

# radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — Присоединяет целочисленный атрибут

### Описание

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет целочисленный атрибут к текущему запросу RADIUS.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`type`
  Тип атрибута.
`value`
  Значение атрибута.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Примеры

Пример #1 Пример использования radius_put_int()

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'Ошибка Radius:' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### Смотрите также

- radius_put_string() - Присоединяет строковый атрибут
- radius_put_vendor_int() - Присоединяет целочисленный атрибут, зависящий от поставщика
- radius_put_vendor_string() - Присоединяет строковый атрибут, зависящий от поставщика

# radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — Присоединяет строковый атрибут

### Описание

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет строковый атрибут к текущему запросу RADIUS. В общем, radius_put_attr() - более полезная функция для присоединения строковых атрибутов, поскольку она бинарно безопасна.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`type`
  Тип атрибута.
`value`
  Значение атрибута. Базовая библиотека ожидает, что это значение будет иметь нулевой символ в конце, поэтому этот параметр небезопасен для двоичного кода.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Примеры

Пример #1 Пример использования radius_put_string()

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'Ошибка Radius:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Смотрите также

- radius_put_int() - Присоединяет целочисленный атрибут
- radius_put_vendor_int() - Присоединяет целочисленный атрибут, зависящий от поставщика
- radius_put_vendor_string() - Присоединяет строковый атрибут, зависящий от поставщика

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — Присоединяет атрибут IP-адреса конкретного поставщика

### Описание

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

Присоединяет атрибут поставщика IP-адреса к текущему запросу RADIUS.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`vendor`
  ID производителя (vendor).
`type`
  Тип атрибута.
`addr`
  Адрес IPv4 в виде строки, например, `10.0.0.1`.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — Присоединяет бинарный атрибут, зависящий от поставщика

### Описание

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет к текущему запросу RADIUS бинарный атрибут, зависящий от поставщика.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`vendor`
  ID производителя (vendor).
`type`
  Тип атрибута.
`value`
  Значение атрибута, которое будет рассматриваться как необработанная двоичная строка.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Примеры

Пример #1 Пример использования radius_put_vendor_attr()

    <?php
    if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
        echo 'Ошибка Radius:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Смотрите также

- radius_get_vendor_attr() - Извлекает атрибут конкретного поставщика

# radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — Присоединяет целочисленный атрибут, зависящий от поставщика

### Описание

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет к текущему запросу RADIUS целочисленный атрибут, зависящий от поставщика.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`vendor`
  ID производителя (vendor).
`type`
  Тип атрибута.
`value`
  Значение атрибута.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Смотрите также

- radius_put_vendor_string() - Присоединяет строковый атрибут, зависящий от поставщика

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — Присоединяет строковый атрибут, зависящий от поставщика

### Описание

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Присоединяет к текущему запросу RADIUS строковый атрибут, зависящий от поставщика. В общем, radius_put_vendor_attr() - более полезная функция для присоединения строковых атрибутов, поскольку она бинарно безопасна.

> Замечание: Перед вызовом этой функции необходимо создать запрос с помощью функции radius_create_request().

### Список параметров

`radius_handle`
  Ресурс RADIUS.
`vendor`
  ID производителя (vendor).
`type`
  Тип атрибута.
`value`
  Значение атрибута. Базовая библиотека ожидает, что это значение будет иметь нулевой символ в конце, поэтому этот параметр небезопасен для двоичного кода.
`options`
  Битовая маска опций атрибута. В качестве значений можно использовать `RADIUS_OPTION_TAGGED` и `RADIUS_OPTION_SALT`.
`tag`
  Тег атрибута. Этот параметр будет проигнорирован, если не установлена опция `RADIUS_OPTION_TAGGED`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL radius 1.3.0 | Добавлены параметры `options` и `tag`.

### Смотрите также

- radius_put_vendor_int() - Присоединяет целочисленный атрибут, зависящий от поставщика

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — Возвращает аутентификатор запроса

### Описание

function radius_request_authenticator(resource `$radius_handle`): string

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

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Возвращает аутентификатор запроса в виде строки или `false` в случае возникновения ошибки.

### Смотрите также

- radius_demangle() - Расшифровывает данные

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Зашифровывает значение с помощью соли

### Описание

function radius_salt_encrypt_attr(resource `$radius_handle`, string `$data`): string|false

Применяет алгоритм шифрования RADIUS к заданному значению.

Как правило, это делается автоматически путём предоставления опции `RADIUS_OPTION_SALT` функции установки атрибута, но эту функцию можно использовать, если требуется создание низкоуровневого запроса.

### Список параметров

`data`
  Данные, которые необходимо зашифровать с помощью соли.

### Возвращаемые значения

Возвращает данные, зашифрованные с помощью соли или `false`, если возникла ошибка.

### Смотрите также

- radius_put_addr() - Присоединяет атрибут IP-адреса
- radius_put_attr() - Присоединяет бинарный атрибут
- radius_put_int() - Присоединяет целочисленный атрибут
- radius_put_string() - Присоединяет строковый атрибут

# radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — Отправляет запрос и ждёт ответ

### Описание

function radius_send_request(resource `$radius_handle`): int

После создания запроса Radius отправляет его с помощью radius_send_request().

Функция radius_send_request() отправляет запрос и ожидает корректный ответ, повторяя попытки с определёнными серверами в циклическом режиме по мере необходимости.

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Если получен корректный ответ, radius_send_request() возвращает код Radius, который указывает тип ответа. Обычно это `RADIUS_ACCESS_ACCEPT`, `RADIUS_ACCESS_REJECT` или `RADIUS_ACCESS_CHALLENGE`. Если корректный ответ не получен, radius_send_request() возвращает `false`.

### Смотрите также

- radius_create_request() - Создаёт учётную запись или запрос аутентификации

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Возвращает общий секрет

### Описание

function radius_server_secret(resource `$radius_handle`): string

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

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Возвращает общий секрет сервера в виде строки или `false` в случае возникновения ошибки.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Возвращает сообщение об ошибке

### Описание

function radius_strerror(resource `$radius_handle`): string

В случае возникновения ошибки функций radius, они записывают сообщение об ошибке. Это сообщение можно получить с помощью данной функции.

### Список параметров

`radius_handle`
  Ресурс RADIUS.

### Возвращаемые значения

Возвращает сообщения об ошибках в виде строки из функций radius, завершившихся ошибкой.

## Содержание

- radius_acct_open — Создаёт дескриптор Radius для учёта
- radius_add_server — Добавляет сервер
- radius_auth_open — Создаёт дескриптор Radius для аутентификации
- radius_close — Освобождает все ресурсы
- radius_config — Заставляет библиотеку читать данный файл конфигурации
- radius_create_request — Создаёт учётную запись или запрос аутентификации
- radius_cvt_addr — Преобразовывает необработанные данные в IP-адрес
- radius_cvt_int — Преобразовывает необработанные данные в целое число
- radius_cvt_string — Преобразовывает необработанные данные в строку
- radius_demangle — Расшифровывает данные
- radius_demangle_mppe_key — Получает mppe-ключи из искажённых данных
- radius_get_attr — Извлекает атрибут
- radius_get_tagged_attr_data — Извлекает данные из помеченного атрибута
- radius_get_tagged_attr_tag — Извлекает тег из помеченного атрибута
- radius_get_vendor_attr — Извлекает атрибут конкретного поставщика
- radius_put_addr — Присоединяет атрибут IP-адреса
- radius_put_attr — Присоединяет бинарный атрибут
- radius_put_int — Присоединяет целочисленный атрибут
- radius_put_string — Присоединяет строковый атрибут
- radius_put_vendor_addr — Присоединяет атрибут IP-адреса конкретного поставщика
- radius_put_vendor_attr — Присоединяет бинарный атрибут, зависящий от поставщика
- radius_put_vendor_int — Присоединяет целочисленный атрибут, зависящий от поставщика
- radius_put_vendor_string — Присоединяет строковый атрибут, зависящий от поставщика
- radius_request_authenticator — Возвращает аутентификатор запроса
- radius_salt_encrypt_attr — Зашифровывает значение с помощью соли
- radius_send_request — Отправляет запрос и ждёт ответ
- radius_server_secret — Возвращает общий секрет
- radius_strerror — Возвращает сообщение об ошибке

- Установка и настройка
  - Установка
- Предопределённые константы
  - Опции службы RADIUS
  - Типы пакетов службы RADIUS
  - Типы атрибутов службы RADIUS
  - Атрибуты RADIUS специфичные для разных производителей
- Примеры
- Функции Radius
  - radius_acct_open — Создаёт дескриптор Radius для учёта
  - radius_add_server — Добавляет сервер
  - radius_auth_open — Создаёт дескриптор Radius для аутентификации
  - radius_close — Освобождает все ресурсы
  - radius_config — Заставляет библиотеку читать данный файл конфигурации
  - radius_create_request — Создаёт учётную запись или запрос аутентификации
  - radius_cvt_addr — Преобразовывает необработанные данные в IP-адрес
  - radius_cvt_int — Преобразовывает необработанные данные в целое число
  - radius_cvt_string — Преобразовывает необработанные данные в строку
  - radius_demangle — Расшифровывает данные
  - radius_demangle_mppe_key — Получает mppe-ключи из искажённых данных
  - radius_get_attr — Извлекает атрибут
  - radius_get_tagged_attr_data — Извлекает данные из помеченного атрибута
  - radius_get_tagged_attr_tag — Извлекает тег из помеченного атрибута
  - radius_get_vendor_attr — Извлекает атрибут конкретного поставщика
  - radius_put_addr — Присоединяет атрибут IP-адреса
  - radius_put_attr — Присоединяет бинарный атрибут
  - radius_put_int — Присоединяет целочисленный атрибут
  - radius_put_string — Присоединяет строковый атрибут
  - radius_put_vendor_addr — Присоединяет атрибут IP-адреса конкретного поставщика
  - radius_put_vendor_attr — Присоединяет бинарный атрибут, зависящий от поставщика
  - radius_put_vendor_int — Присоединяет целочисленный атрибут, зависящий от поставщика
  - radius_put_vendor_string — Присоединяет строковый атрибут, зависящий от поставщика
  - radius_request_authenticator — Возвращает аутентификатор запроса
  - radius_salt_encrypt_attr — Зашифровывает значение с помощью соли
  - radius_send_request — Отправляет запрос и ждёт ответ
  - radius_server_secret — Возвращает общий секрет
  - radius_strerror — Возвращает сообщение об ошибке

- Radius
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Radius

# Модули для работы с командной строкой

# Модуль командной строки GNU Readline

# Введение

Функции модуля Readline реализуют интерфейс к библиотеке GNU Readline. Это функции, которые поддерживают редактируемые командные строки. Наример, Bash разрешает использовать стрелки для навигации по строке или для прокрутки истории команд. Из-за интерактивного характера этой библиотеки она малопригодна для написания веб-приложений, но полезна при написании скриптов, которые запускаются из командной строки.

Начиная с PHP 7.1.0 модуль работает в ОС Windows.

Предостережение

Модуль Readline непотокобезопасен! Поэтому не рекомендуют использовать модуль с потокобезопасными SAPI-интерфейсами наподобие Apache-модуля для Windows — mod_winnt.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Функции модуля Readline доступны только при установке библиотеки libreadline. Ссылку для скачивания библиотеки libreadline содержит домашняя страница проекта GNU Readline по адресу » https://tiswww.case.edu/php/chet/readline/rltop.html. Библиотеку поддерживает Чет Рэми (Chet Ramey) — автор оболочки Bash.

Функции для работы с командной строкой также будут доступны, если собрать модуль Readline с библиотекой libedit — замена библиотеки readline, только без лицензии GPL. Библиотека libedit работает по лицензии BSD и доступна для скачивания по адресу » http://www.thrysoee.dk/editline/.

## Установка

Функции модуля доступны только в версиях PHP, которые скомпилировали с поддержкой серверных интерфейсов CGI или CLI и модуля readline. Компиляцию PHP настраивают опцией --with-readline[=DIR].

В ОС Windows модуль доступен по умолчанию начиная с PHP 7.1.0.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Readline
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

Краткое разъяснение конфигурационных директив.

`cli.pager` string
  Внешняя утилита для отображения вывода в командную строку.
`cli.prompt` string
  Подсказка командной строки.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`READLINE_LIB` (string)
  Библиотека функций для работы с командной строкой, с которой собрали модуль Readline; поддерживается сборка с библиотеками `readline` или `libedit`.

# Функции Readline

# readline

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

readline — Читает строку

### Описание

function readline(?string `$prompt` = `null`): string|false

Функция читает одну строку, которую ввёл пользователь. Строку добавляют в историю команд функцией readline_add_history().

### Список параметров

`prompt`
  Текст приглашения, который функция покажет пользователю в командной строке.

### Возвращаемые значения

Функция возвращает одну строку, которую ввёл пользователь. Функция удалит из конца строки, которую вернула командная оболочка, символ новой строки. Функция возвращает `false`, если не осталось данных для чтения.

### Примеры

Пример #1 Пример чтения строки функцией readline()

    <?php

    // Получим 3 команды от пользователя
    for ($i=0; $i < 3; $i++) {
            $line = readline("Command: ");
            readline_add_history($line);
    }

    // Выведем дамп с историей ввода
    print_r(readline_list_history());

    // Выведем дамп с переменными
    print_r(readline_info());

# readline_add_history

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

readline_add_history — Добавляет строку в историю команд

### Описание

function readline_add_history(string `$prompt`): true

Функция добавляет строку в историю команд.

### Список параметров

`prompt`
  Строка, которую требуется добавить в историю команд.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — Инициализирует callback-интерфейс readline и терминал, печатает строку приглашения и немедленно возвращает управление

### Описание

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

Инициализирует callback-интерфейс readline, печатает `prompt` и возвращает управление. Повторный вызов этой функции без предварительного удаления старого callback-интерфейса приведёт к автоматической его перезаписи.

Функционал callback-функций особенно удобен в комбинации с stream_select(), поскольку он, в отличие от readline(), позволяет чередовать ввод-вывод и пользовательский ввод.

### Список параметров

`prompt`
  Строка приглашения.
`callback`
  Функция передаваемая в параметр `callback` должна принимать один параметр - возвращённый пользовательский ввод.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Пример #1 Пример использования callback-интерфейса readline

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "Вы ввели: $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Поговори со мной: ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Введите что-нибудь: ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // читаем символ и вызываем callback-функцию,
            // если введён символ новой строки
            readline_callback_read_char();
        }
    }

    echo "Ввод отключён. Спасибо за внимание.\n";
    ?>

### Смотрите также

- readline_callback_handler_remove() - Удаляет ранее зарегистрированную callback-функцию и восстанавливает терминал
- readline_callback_read_char() - Читает символ и информирует callback-функцию readline, что получена строка
- stream_select() - Запускает эквивалент системного вызова select() на массивах потоков со временем ожидания в секундах и микросекундах

# readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — Удаляет ранее зарегистрированную callback-функцию и восстанавливает терминал

### Описание

function readline_callback_handler_remove(): bool

Удаляет ранее зарегистрированную callback-функцию и восстанавливает настройки терминала.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если удаление прошло успешно или `false`, если удалять нечего.

### Примеры

Пример использования интерфейса callback-функций readline смотрите на странице описания функции readline_callback_handler_install().

### Смотрите также

- readline_callback_handler_install() - Инициализирует callback-интерфейс readline и терминал, печатает строку приглашения и немедленно возвращает управление
- readline_callback_read_char() - Читает символ и информирует callback-функцию readline, что получена строка

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — Читает символ и информирует callback-функцию readline, что получена строка

### Описание

function readline_callback_read_char(): void

Читает введённый пользователем символ. Когда строка получена, эта функция информирует callback-функцию интерфейса readline, заданную с помощью readline_callback_handler_install(), что строка готова к вводу.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример использования интерфейса callback-функций readline смотрите на странице описания функции readline_callback_handler_install().

### Смотрите также

- readline_callback_handler_install() - Инициализирует callback-интерфейс readline и терминал, печатает строку приглашения и немедленно возвращает управление
- readline_callback_handler_remove() - Удаляет ранее зарегистрированную callback-функцию и восстанавливает терминал

# readline_clear_history

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

readline_clear_history — Очищает историю команд

### Описание

function readline_clear_history(): true

Функция очищает историю ввода команд.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

# readline_completion_function

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

readline_completion_function — Регистрирует функцию автодополнения

### Описание

function readline_completion_function(callable `$callback`): bool

Функция регистрирует функцию автодополнения команд. Callback-функция даёт тот же результат, который пользователь получил бы, если бы нажал клавишу Tab при работе в оболочке Bash, когда строка с частью команды дополняется возможным совпадением.

### Список параметров

`callback`
  Название функции, которая принимает строку с фрагментом команды и возвращает массив возможных совпадений.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# readline_info

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

readline_info — Считывает или устанавливает внутренние переменные модуля readline

### Описание

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

Функция считывает или устанавливает внутренние переменные модуля readline.

### Список параметров

`var_name`
  Название переменной.
`value`
  При установке этого параметра функция присвоит настройке новое значение.

### Возвращаемые значения

При вызове без аргументов функция возвращает массив значений, которые содержатся в настройках модуля readline. Элементы массива индексируются следующими ключами: `done`, `end`, `erase_empty_line`, `library_version`, `line_buffer`, `mark`, `pending_input`, `point`, `prompt`, `readline_name` и `terminal_name`. Массив (array) будет содержать только те элементы, которые поддерживает библиотека, с которой собрали модуль readline.

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

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `var_name` и `value` теперь принимают значение null.

# readline_list_history

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

readline_list_history — Получает историю команд

### Описание

function readline_list_history(): array

Функция получает полную историю командной строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив с полной историей командной строки. Индексы элементов массива начинаются с нуля.

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — Информирует readline, что курсор переместился на новую строку

### Описание

function readline_on_new_line(): void

Информирует readline, что курсор переместился на новую строку.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примечания

> Замечание: Функция доступна только в том случае, если поддерживается базовой библиотекой readline. Не поддерживается в Windows.

# readline_read_history

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

readline_read_history — Считывает историю команд из файла

### Описание

function readline_read_history(?string `$filename` = `null`): bool

Функция считывает историю команд из файла.

### Список параметров

`filename`
  Путь к файлу с историей команд.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `filename` теперь принимает значение null.

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — Перерисовывает экран

### Описание

function readline_redisplay(): void

Функция перерисовывает экран.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# readline_write_history

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

readline_write_history — Записывает историю команд в файл

### Описание

function readline_write_history(?string `$filename` = `null`): bool

Функция записывает текущую историю команд в файл.

### Список параметров

`filename`
  Путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `filename` теперь принимает значение null.

## Содержание

- readline — Читает строку
- readline_add_history — Добавляет строку в историю команд
- readline_callback_handler_install — Инициализирует callback-интерфейс readline и терминал, печатает строку приглашения и немедленно возвращает управление
- readline_callback_handler_remove — Удаляет ранее зарегистрированную callback-функцию и восстанавливает терминал
- readline_callback_read_char — Читает символ и информирует callback-функцию readline, что получена строка
- readline_clear_history — Очищает историю команд
- readline_completion_function — Регистрирует функцию автодополнения
- readline_info — Считывает или устанавливает внутренние переменные модуля readline
- readline_list_history — Получает историю команд
- readline_on_new_line — Информирует readline, что курсор переместился на новую строку
- readline_read_history — Считывает историю команд из файла
- readline_redisplay — Перерисовывает экран
- readline_write_history — Записывает историю команд в файл

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции Readline
  - readline — Читает строку
  - readline_add_history — Добавляет строку в историю команд
  - readline_callback_handler_install — Инициализирует callback-интерфейс readline и терминал, печатает строку приглашения и немедленно возвращает управление
  - readline_callback_handler_remove — Удаляет ранее зарегистрированную callback-функцию и восстанавливает терминал
  - readline_callback_read_char — Читает символ и информирует callback-функцию readline, что получена строка
  - readline_clear_history — Очищает историю команд
  - readline_completion_function — Регистрирует функцию автодополнения
  - readline_info — Считывает или устанавливает внутренние переменные модуля readline
  - readline_list_history — Получает историю команд
  - readline_on_new_line — Информирует readline, что курсор переместился на новую строку
  - readline_read_history — Считывает историю команд из файла
  - readline_redisplay — Перерисовывает экран
  - readline_write_history — Записывает историю команд в файл

- Readline — Модуль командной строки GNU Readline
  - Установка и настройка
  - Предопределённые константы
  - Функции Readline

# Модули сжатия и архивации

# Bzip2

# Введение

Функции модуля bzip2 прозрачно читают и записывают bzip2-архивы — файлы с расширением .bz2.

# Установка и настройка

## Содержание

- Требования
- Установка
- Типы ресурсов

## Требования

Модуль использует функции библиотеки » bzip2 (автор: Julian Seward) и требует библиотеки bzip2/libbzip2 версий >= 1.0.x.

## Установка

Поддержка Bzip2 в PHP не включена по умолчанию, для её включения вам следует скомпилировать PHP с указанием директивы --with-bz2[=DIR].

## Типы ресурсов

Модуль определяет один новый тип ресурсов: указатель на bz2-файл, с которым идёт работа.

# Примеры

Следующий пример откроет временный файл, запишет в него тестовую строку, после чего выведет содержимое файла.

Пример #1 Пример работы с bzip2

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "This is a test string.\n";

    // открываем файл для записи
    $bz = bzopen($filename, "w");

    // пишем строку в файл
    bzwrite($bz, $str);

    // закрываем файл
    bzclose($bz);

    // открываем файл для чтения
    $bz = bzopen($filename, "r");

    // читаем 10 символов
    echo bzread($bz, 10);

    // выводим всё, до конца файла (или следующие 1024 символа) и закрываем его.
    echo bzread($bz);

    bzclose($bz);

    ?>

# Функции Bzip2

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — Закрывает файл bzip2

### Описание

function bzclose(resource `$bz`): bool

Закрывает переданный указатель на файл bzip2.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешно открытый bzopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- bzopen() - Открывает файл, сжатый с использованием bzip2

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — Сжимает строку с использованием bzip2

### Описание

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() сжимает переданную строку и возвращает её в виде закодированных данных bzip2.

### Список параметров

`data`
  Сжимаемая строка.
`block_size`
  Определяет размера блока, используемый при сжатии, должен быть числом в диапазоне от 1 до 9, где 9 даст наилучшее, но более ресурсоёмкое сжатие.
`work_factor`
  Контролирует поведение фазы компрессии в худшем случае, когда входные данные являются часто повторяющимися. Параметр может принимать значения между 0 и 250, где 0 означает специальный случай. Генерируемый результат не зависит от параметра `work_factor` и является одним и тем же.

### Возвращаемые значения

Сжатая строка или код ошибки в случае неудачного завершения работы.

### Примеры

Пример #1 Сжатие данных

    <?php
    $str = "sample data";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### Смотрите также

- bzdecompress() - Распаковывает данные, сжатые с использованием bzip2

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — Распаковывает данные, сжатые с использованием bzip2

### Описание

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() распаковывает переданную строку, содержащую сжатые bzip2 данные.

### Список параметров

`data`
  Распаковываемая строка.
`use_less_memory`
  Если `true`, то будет использован альтернативный алгоритм распаковки, использующий меньше памяти (максимально требуемая память находится в районе 2300K), но работает приблизительно вдвое медленнее. Смотрите » документацию по bzip2 для более подробной информации об этой возможности.

### Возвращаемые значения

Распакованная строка или `false` или код ошибки в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Тип `use_less_memory` изменён с int на bool. Ранее значением по умолчанию был `0`.

### Примеры

Пример #1 Распаковка строки

    <?php
    $start_str = "This is not an honest face?";
    $bzstr = bzcompress($start_str);

    echo "Compressed String: ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "Decompressed String: ";
    echo $str;
    echo "\n<br />\n";
    ?>

### Смотрите также

- bzcompress() - Сжимает строку с использованием bzip2

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — Возвращает код ошибки работы с bzip2

### Описание

function bzerrno(resource `$bz`): int

Возвращает код любой bzip2 ошибки, произошедшей с переданным указателем на файл.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешный открытый bzopen().

### Возвращаемые значения

Возвращает код ошибки в виде целого числа.

### Смотрите также

- bzerror() - Возвращает код и строку ошибки работы с bzip2 в виде массива
- bzerrstr() - Возвращает строку ошибки работы с bzip2

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — Возвращает код и строку ошибки работы с bzip2 в виде массива

### Описание

function bzerror(resource `$bz`): array

Возвращает ассоциативный массив с кодом и строкой ошибки, произошедшей с переданным файловым указателем.

### Список параметров

`bz`
  Файловый указатель. Должен быть корректным и указывать на файл, успешно открытый bzopen().

### Возвращаемые значения

Возвращает ассоциативный массив с кодом ошибки с ключом `errno`, и строкой ошибки с ключом `errstr`.

### Примеры

Пример #1 Пример использования bzerror()

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### Смотрите также

- bzerrno() - Возвращает код ошибки работы с bzip2
- bzerrstr() - Возвращает строку ошибки работы с bzip2

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — Возвращает строку ошибки работы с bzip2

### Описание

function bzerrstr(resource `$bz`): string

Возвращает строку с ошибкой bzip2, произошедшей с переданным указателем на файл.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешно открытый bzopen().

### Возвращаемые значения

Возвращает строку, содержащую сообщение об ошибке.

### Смотрите также

- bzerrno() - Возвращает код ошибки работы с bzip2
- bzerror() - Возвращает код и строку ошибки работы с bzip2 в виде массива

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — Ничего не делает

### Описание

function bzflush(resource `$bz`): bool

Функция должна принудительно записывать все буферизованные данные bzip2 в файл, на который ссылается указатель `bz`, но в libbz2 реализована как нулевая функция и поэтому ничего не делает.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешно открытый bzopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- bzread() - Бинарно-безопасное чтение файла bzip2
- bzwrite() - Бинарно-безопасная запись bzip2 файла

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — Открывает файл, сжатый с использованием bzip2

### Описание

function bzopen(string|resource `$file`, string `$mode`): resource|false

bzopen() открывает bzip2 (.bz2) файл для чтения либо записи.

### Список параметров

`file`
  Имя открываемого файла, или существующий ресурс потока.
`mode`
  Поддерживаются только `'r'` (чтение) и `'w'` (запись). Все остальное заставит bzopen() вернуть `false`.

### Возвращаемые значения

bzopen() возвращается указатель на открытый файл, либо `false`, если файл открыть не удалось.

### Примеры

Пример #1 Пример использования bzopen()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Не могу открыть $file для чтения");

    bzclose($bz);

    ?>

### Смотрите также

- bzclose() - Закрывает файл bzip2

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — Бинарно-безопасное чтение файла bzip2

### Описание

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() читает из переданного bzip2 файлового указателя.

Чтение останавливается, если было считано `length` (несжатых) байт или был достигнут конец файла, в зависимости от того, что произойдёт раньше.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешно открытый bzopen().
`length`
  Если не указан, bzread() будет считывать 1024 (несжатых) байта за один раз. За один раз может быть считано максимум 8192 байта.

### Возвращаемые значения

Возвращает распакованные данные либо `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования bzread()

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Невозможно открыть $file");

    $decompressed_file = '';
    while (!feof($bz)) {
      $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "Содержимое $file: <br />\n";
    echo $decompressed_file;

    ?>

### Смотрите также

- bzwrite() - Бинарно-безопасная запись bzip2 файла
- feof() - Проверяет, достигнут ли конец файла
- bzopen() - Открывает файл, сжатый с использованием bzip2

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — Бинарно-безопасная запись bzip2 файла

### Описание

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() записывает строку в переданный bzip2 файловый поток.

### Список параметров

`bz`
  Указатель на файл. Должен быть корректным и указывать на файл, успешно открытый bzopen().
`data`
  Записываемые данные.
`length`
  Если указан, запись остановится после `length` (несжатых) записанных байт, либо если был достигнут конец `data`, в зависимости от того, что произойдёт первым.

### Возвращаемые значения

Возвращает количество записанных байт или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `length` теперь допускает значение null.

### Примеры

Пример #1 Пример использования bzwrite()

    <?php
    $str = "uncompressed data";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### Смотрите также

- bzread() - Бинарно-безопасное чтение файла bzip2
- bzopen() - Открывает файл, сжатый с использованием bzip2

## Содержание

- bzclose — Закрывает файл bzip2
- bzcompress — Сжимает строку с использованием bzip2
- bzdecompress — Распаковывает данные, сжатые с использованием bzip2
- bzerrno — Возвращает код ошибки работы с bzip2
- bzerror — Возвращает код и строку ошибки работы с bzip2 в виде массива
- bzerrstr — Возвращает строку ошибки работы с bzip2
- bzflush — Ничего не делает
- bzopen — Открывает файл, сжатый с использованием bzip2
- bzread — Бинарно-безопасное чтение файла bzip2
- bzwrite — Бинарно-безопасная запись bzip2 файла

- Установка и настройка
  - Требования
  - Установка
  - Типы ресурсов
- Примеры
- Функции Bzip2
  - bzclose — Закрывает файл bzip2
  - bzcompress — Сжимает строку с использованием bzip2
  - bzdecompress — Распаковывает данные, сжатые с использованием bzip2
  - bzerrno — Возвращает код ошибки работы с bzip2
  - bzerror — Возвращает код и строку ошибки работы с bzip2 в виде массива
  - bzerrstr — Возвращает строку ошибки работы с bzip2
  - bzflush — Ничего не делает
  - bzopen — Открывает файл, сжатый с использованием bzip2
  - bzread — Бинарно-безопасное чтение файла bzip2
  - bzwrite — Бинарно-безопасная запись bzip2 файла

# LZF

# Введение

LZF — очень быстрый алгоритм сжатия, идеальный для экономии места при крайне низких временных затратах. Модуль можно оптимизировать под скорость или под эффективность сжатия на моменте компиляции. Модуль использует библиотеку » liblzf, которую создал для своих целей Марк Лейман.

# Установка и настройка

## Содержание

- Установка

## Установка

Модуль » PECL не поставляется вместе с PHP. Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/lzf.

Для использования данного модуля необходимо скомпилировать PHP с поддержкой lzf, используя ключ конфигурации --with-lzf[=DIR]. Также вы можете указать ключ --enable-lzf-better-compression для оптимизации LZF для лучшего сжатия в ущерб скорости работы.

Пользователи Windows должны разрешить php_lzf.dll в php.ini.

# Функции LZF

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — Сжатие LZF

### Описание

function lzf_compress(string `$data`): string

Функция lzf_compress() сжимает строку данных `data` через алгоритм LZF.

### Список параметров

`data`
  Строка для сжатия.

### Возвращаемые значения

Функция возвращает сжатые данные или `false`, если возникла ошибка.

### Смотрите также

- lzf_decompress() - Разархивация LZF

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — Разархивация LZF

### Описание

function lzf_decompress(string `$data`): string

lzf_compress() разархивирует строку `data`, содержащую данные сжатые алгоритмом lzf.

### Список параметров

`data`
  Строка со сжатыми данными.

### Возвращаемые значения

Возвращает разархивированные данные или `false` в случае возникновения ошибки.

### Смотрите также

- lzf_compress() - Сжатие LZF

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Определяет режим оптимизации модуля LZF

### Описание

function lzf_optimized_for(): int

Определяет, с какими настройками оптимизации скомпилирован модуль LZF.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 1, если LZF оптимизирован под скорость работы и 0, если под эффективность сжатия.

## Содержание

- lzf_compress — Сжатие LZF
- lzf_decompress — Разархивация LZF
- lzf_optimized_for — Определяет режим оптимизации модуля LZF

- Установка и настройка
  - Установка
- Функции LZF
  - lzf_compress — Сжатие LZF
  - lzf_decompress — Разархивация LZF
  - lzf_optimized_for — Определяет режим оптимизации модуля LZF

# Phar

# Введение

Модуль phar предоставляет возможность поместить целое PHP-приложение в один-единственный файл c именем phar (PHP Archive) для простого распространения и установки. Помимо этого, модуль phar предоставляет метод абстракции формата файла для создания и обработки архивов tar и zip через класс PharData, примерно как PDO обеспечивает единый интерфейс для доступа к различным базам данных. В отличие от PDO, который не может конвертировать между различными базами данных, Phar может конвертировать данные между форматами tar, zip и phar всего одной строкой кода. Смотрите Phar::convertToExecutable() для примера.

Что же такое phar? Phar-архивы лучше всего можно охарактеризовать как удобный способ группировки нескольких файлов в один. Также phar архив предоставляет возможность распространять целое PHP-приложение в одном единственном файле и запускать его прямо из этого файла без необходимости распаковывать его на диск. Кроме того, phar-архивы могут выполняться PHP с той же лёгкостью, что и любые другие файлы, как из командной строки, так и через веб-сервер. Phar - это как флеш-накопитель для PHP-приложений.

Phar реализует эту функциональность через потоки. Обычно, чтобы использовать в PHP-скрипте внешний файл, вы бы воспользовались, например, include:

Пример #1 Использование внешнего файла

    <?php
     include '/path/to/external/file.php';
     ?>

PHP может рассматривать это как преобразование `/path/to/external/file.php` в обёртку потока `file:///path/to/external/file.php`, а в действительности он использует потоковые функции обёртки простого файлового потока для доступа ко всем локальным файлам.

Чтобы использовать файл `file.php`, находящийся внутри phar-архива `/path/to/myphar.phar`, используется синтаксис очень похожий на синтаксис `file://` выше.

Пример #2 Использование файла внутри phar-архива

    <?php
     include 'phar:///path/to/myphar.phar/file.php';
     ?>

На самом деле, можно рассматривать phar-архив как если бы это был внешний диск, используя любые fopen()-подобные функции, opendir() и mkdir()-подобные функции для чтения, изменения, или создания новых файлов и директорий внутри phar-архива. Это позволяет целому PHP-приложению распространяться в одном файле и запускаться прямо из этого файла.

Наиболее часто используемое применение для phar-архива - это распространение целого приложения в одном файле. Например, установщик PEAR, который поставляется вместе с PHP, является phar-архивом. Для использования phar-архива распространяемого таким способом, архив может быть выполнен через консоль или через веб-сервер.

Phar-архивы могут распространяться как архивы `tar` и `zip`, или как пользовательский формат файла `phar`, предназначенный специально для модуля phar. Каждый формат файла имеет как преимущества, так и недостатки. Форматы tar и zip могут быть прочитаны или извлечены любой сторонней утилитой которая может работать с этими форматами. Но чтобы PHP мог их запускать, ему будет необходим модуль phar. Файлы в phar-формате настраиваются и уникальны для модуля phar, и могут быть созданы только им или PEAR-пакетом » PHP_Archive. Но их преимущество в том, что приложения, созданные в этом формате, будут работать, даже если модуль phar не включён.

Другими словами, даже если модуль phar отключён, phar-архив всё равно может быть выполнен или подключён. Доступ к отдельным файлам в архиве возможен только с модулем phar, если только архив не был создан с помощью PHP_Archive.

Модуль phar также способно конвертировать phar-архив из tar в zip или в phar-формат одной командой:

Пример #3 Конвертирование phar-архива из формата phar в формат tar

    <?php
     $phar = new Phar('myphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // создаст myphar.phar.tar.gz
     ?>

Phar может сжимать отдельные файлы или архив целиком с использованием gzip-компрессии или bzip2-компрессии, а также автоматически проверять целостность архива, используя сигнатуры MD5, SHA-1, SHA-256 или SHA-512.

Наконец, модуль Phar заботится о вашей безопасности и отключает доступ на запись для исполняемых phar-архивов по умолчанию, а также требует отключения на системном уровне настройки `phar.readonly` в php.ini для создания или изменения phar-архивов. Обычные неисполняемые архивы tar и zip, всегда могут быть созданы или изменены с помощью класса PharData.

Если вы создаёте приложение с целью распространения, вы, возможно, захотите прочитать раздел Как создавать Phar-архивы. Если вам нужно больше информации об отличиях между тремя поддерживаемыми phar форматами файлов, вам следует прочитать раздел Phar, Tar и Zip.

Если вы используете phar-приложение, то полезные советы находятся в разделе Как использовать phar-архивы.

Слово `phar` - это сокращение от `PHP` и `Archive`, и оно частично основано на `jar` (Java Archive), знакомом Java-разработчикам.

Реализация Phar-архивов основана на PEAR-пакете » PHP_Archive, и детали реализации схожи, хотя модуль Phar гораздо мощнее. Кроме того, модуль Phar позволяет большинству PHP-приложений запускаться без изменений, тогда как phar-архивы, основанные на PHP_Archive, часто требуют существенных изменений для работы.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Кроме того, вы можете подключить модули zlib и bzip2, чтобы воспользоваться поддерживаемой компрессией phar. Также, чтобы иметь возможность подписывания OpenSSL, должен быть подключён модуль OpenSSL.

Если zend.multibyte включён, то необходимо также включить zend.detect_unicode.

## Установка

Модуль Phar поставляется с PHP и по умолчанию включён. Для отключения поддержки Phar, используйте --disable-phar.

Модуль может быть установлен из репозитория PECL. Более подробные сведения и история версий доступны на » странице Phar в репозитории PECL.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации файловой системы и потоков
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

Краткое разъяснение конфигурационных директив.

`phar.readonly` bool

  Этот параметр отключает поддержку создания или модификации Phar-архивов с помощью потока `phar` и записи объектов Phar на диск. Этот параметр всегда должен быть включён на рабочих машинах, поскольку поддержка записи модулем phar позволила бы простое создание, основанных на PHP, вирусов в случае присутствия других уязвимостей в системе общей безопасности.

  > Замечание:

  > Этот параметр может быть отключён в php.ini только исходя из соображений безопасности. Если параметр `phar.readonly` отключён в php.ini, пользователь может включить `phar.readonly` в скрипте или отключить его позже. Если параметр `phar.readonly` включён в php.ini, скрипт может безвредно "повторно включить" переменную INI, но не может отключить её.

`phar.require_hash` bool

  Этот параметр сделает обязательной какую-либо подпись (в настоящий момент поддерживаются MD5, SHA1, SHA256, SHA512 и OpenSSL) для всех открываемых Phar-архивов и сделает невозможной обработку любого Phar-архива, не содержащего подпись.

  > Замечание:

  > Этот параметр может быть отключён в php.ini. Если параметр `phar.require_hash` отключён в php.ini, пользователь может включить `phar.require_hash` в скрипте или отключить его позже. Если параметр `phar.require_hash` включён в php.ini, скрипт может безвредно "повторно включить" переменную INI, но не может отключить её.

  > Этот параметр не влияет на чтение простых tar-файлов при помощи класса PharData.

  Предостережение

  `phar.require_hash` не обеспечивает безопасности как таковой - это всего лишь мера по защите от запуска повреждённого Phar архива, поскольку кто угодно, имеющий возможность модифицировать архив может с тем же успехом модифицировать и подпись.

`phar.cache_list` string

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

  Пример #1 Пример использования phar.cache_list

      в php.ini (windows):
      phar.cache_list =C:\путь\к\phar1.phar;C:\путь\к\phar2.phar
      в php.ini (unix):
      phar.cache_list =/путь/к/phar1.phar:/путь/к/phar2.phar

## Типы ресурсов

Модуль Phar предоставляет поток `phar`, который позволяет прозрачно обращаться к файлам внутри phar-архива. Смотрите также описание формата Phar-файла.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Константы сжатия Phar
Константа | Значение | Описание
--- | --- | ---
`Phar::NONE` (int) | 0x00000000 | без сжатия
`Phar::COMPRESSED` (int) | 0x0000F000 | битовая маска, которая может быть использована с флагами файла для определения наличия сжатия
`Phar::GZ` (int) | 0x00001000 | сжатие zlib (gzip)
`Phar::BZ2` (int) | 0x00002000 | сжатие bzip2

Константы формата файла Phar
Константа | Значение | Описание
--- | --- | ---
`Phar::PHAR` (int) | 1 | формат файла phar
`Phar::TAR` (int) | 2 | формат файла tar
`Phar::ZIP` (int) | 3 | формат файла zip

Константы подписи Phar
Константа | Значение | Описание
--- | --- | ---
`Phar::MD5` (int) | 0x0001 | подпись с помощью алгоритма хеширования md5
`Phar::SHA1` (int) | 0x0002 | подпись с помощью алгоритма хеширования sha1
`Phar::SHA256` (int) | 0x0003 | подпись с помощью алгоритма хеширования sha256 (требуется модуль hash)
`Phar::SHA512` (int) | 0x0004 | подпись с помощью алгоритма хеширования sha512 (требуется модуль hash)
`Phar::OPENSSL` (int) | 0x0010 | подпись с помощью пары открытого/закрытого ключей OpenSSL. Это подлинная подпись, использующая асимметричный ключ.
`Phar::OPENSSL_SHA256` (int) |  |
`Phar::OPENSSL_SHA512` (int) |  |

Константы переопределения MIME-типов webPhar
Константа | Значение | Описание
--- | --- | ---
`Phar::PHP` (int) | 1 | используется для указания параметру переопределения MIME-типа Phar::webPhar() на то, что расширение должно быть разобрано как файл PHP
`Phar::PHPS` (int) | 2 | используется для указания параметра переопределения MIME-типа Phar::webPhar(), в соответствии с которым расширение должно быть разобрано как исходный файл PHP посредством highlight_file()

# Использование Phar-архивов

## Содержание

- Использование Phar-архивов: Введение
- Использование Phar-архивов: обёртка потока phar
- Использование Phar-архивов: классы Phar и PharData

## Использование Phar-архивов: Введение

Концептуально Phar-архивы аналогичны JAR-архивам Java, но учитывают нужды и гибкость PHP-приложений. Phar-архив используется для распространения законченного PHP-приложения или библиотеки в виде одного файла. Приложение, имеющее вид Phar-архива, используется в точности так же, как и любое другое PHP-приложение:

    php coolapplication.phar

Использование библиотеки, имеющей вид Phar-архива, идентично использованию любой другой PHP-библиотеки:

    <?php
    include 'coollibrary.phar';
    ?>

Обёртка потока `phar` представляет собой основу модуля phar, про её использование подробно написано здесь. Обёртка потока `phar` предоставляет доступ к файлам внутри phar-архива с использованием стандартных файловых функции PHP: fopen(), opendir() и других, которые работают с обычными файлами. Обёртка потока `phar` поддерживает все операции чтения/записи как над файлами, так и над каталогами.

    <?php
    include 'phar://coollibrary.phar/internal/file.php';
    header('Content-type: image/jpeg');
    // доступ к phar-архивам может осуществляться по полному пути или с помощью псевдонима
    echo file_get_contents('phar:///полный/путь/к/coollibrary.phar/images/wow.jpg');
    ?>

Класс Phar реализует расширенные возможности по доступу к файлам и по созданию phar-архивов. Использование класса Phar подробно описано здесь.

    <?php
    try {
        // открыть существующий phar-архив
        $p = new Phar('coollibrary.phar', 0);
        // Phar наследует SPL-класс DirectoryIterator
        foreach (new RecursiveIteratorIterator($p) as $file) {
            // $file является объектом класса PharFileInfo, который наследует SplFileInfo
            echo $file->getFileName() . "\n";
            echo file_get_contents($file->getPathName()) . "\n"; // отображает содержимое;
        }
        if (isset($p['internal/file.php'])) {
            var_dump($p['internal/file.php']->getMetadata());
        }

        // создать новый phar-архив - параметр phar.readonly в php.ini должен быть 0
        // phar.readonly включён по умолчанию из соображений безопасности.
        // На работающих серверах phar-архивы никогда не должны создаваться,
        // а только выполняться.
        if (Phar::canWrite()) {
            $p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
            // создать phar-архив, основанный на tar, сжатый gzip-сжатием (.tar.gz)
            $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

            // создать транзакцию - в newphar.phar ничего не будет записано
            // до тех пор, пока не будет вызван stopBuffering(), однако для этого требуется временное хранилище
            $p->startBuffering();
            // добавить все файлы в каталоге /путь/к/проекту/project, сохранение в phar-архив с префиксом "project"
            $p->buildFromIterator(new RecursiveIteratorIterator(new RecursiveDirectoryIterator('/путь/к/проекту/project')), '/путь/к/проекту/');

            // добавить новый файл используя ArrayAccess
            $p['file1.txt'] = 'Информация';
            $fp = fopen('hugefile.dat', 'rb');
            // скопировать все данные из потока
            $p['data/hugefile.dat'] = $fp;

            if (Phar::canCompress(Phar::GZ)) {
                $p['data/hugefile.dat']->compress(Phar::GZ);
            }

            $p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
            // любое значение может быть сохранено в качестве метаданных файла
            $p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
            $p['index.php'] = file_get_contents('index.php');
            $p->setMetadata(array('bootstrap' => 'index.php'));

            // сохранить phar-архив на диск
            $p->stopBuffering();
        }
    } catch (Exception $e) {
        echo 'Невозможно открыть Phar: ', $e;
    }
    ?>

Кроме того, проверка содержимого phar-файла может быть осуществлена с помощью любого из поддерживаемых симметричных алгоритмов хеширования (MD5, SHA1, SHA256 и SHA512, если ext/hash включён), а также с помощью подписывания асимметричными открытым/закрытым ключами, используя OpenSSL. Для того чтобы использовать подписывание OpenSSL, вам необходимо сгенерировать пару из открытого и закрытого ключей и установить закрытый ключ для подписывания, используя Phar::setSignatureAlgorithm(). Кроме того, открытый ключ, извлечённый при помощи этого кода:

    <?php
    $public = openssl_get_publickey(file_get_contents('private.pem'));
    $pkey = '';
    openssl_pkey_export($public, $pkey);
    ?>

должен быть сохранён рядом с phar-архивом, для проверки которого он используется. Если phar-архив сохранён как `/путь/к/моему/архиву/my.phar`, то открытый ключ должен быть сохранён как `/путь/к/моему/архиву/my.phar.pubkey`, иначе phar не сможет проверить подлинность подписи OpenSSL.

Класс Phar также предоставляет 3 статических метода: Phar::webPhar(), Phar::mungServer() и Phar::interceptFileFuncs(), которые имеют решающее значение для упаковки PHP-приложений, предназначенных для использования на обычных файловых системах и для веб-приложений. Phar::webPhar() реализует фронтальный контроллер, который направляет HTTP-вызовы в правильное место внутри phar-архива. Phar::mungServer() используется для изменения значений массива $_SERVER, что позволяет обмануть приложения, обрабатывающие эти значения. Phar::interceptFileFuncs() инструктирует Phar о необходимости перехвата вызовов fopen(), file_get_contents(), opendir() и прочих функций, основанных на stat (file_exists(), is_readable() и так далее) и перенаправления всех относительных путей внутрь phar-архива.

Например, для упаковки выпуска популярного приложения phpMyAdmin для его использования в качестве phar-архива, требуется только этот простой скрипт, а `phpMyAdmin.phar.tar.php` будет доступен как обычный файл на вашем веб-сервере после изменения значений user/password:

    <?php
    @unlink('phpMyAdmin.phar.tar.php');
    copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
    $a = new Phar('phpMyAdmin.phar.tar.php');
    $a->startBuffering();
    $a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
    /* Конфигурация сервера */
    $i = 0;

    /* Сервер localhost (config:root) [1] */
    $i++;
    $cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
    $cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
    $cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
    $cfg[\'Servers\'][$i][\'compress\'] = false;
    $cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
    $cfg[\'Servers\'][$i][\'user\'] = \'root\';
    $cfg[\'Servers\'][$i][\'password\'] = \'\';

    /* Конец конфигурации сервера */
    if (strpos(PHP_OS, \'WIN\') !== false) {
        $cfg[\'UploadDir\'] = getcwd();
    } else {
        $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
        @mkdir(\'/tmp/pharphpmyadmin\');
        @chmod(\'/tmp/pharphpmyadmin\', 0777);
    }';
    $a->setStub('<?php
    Phar::interceptFileFuncs();
    Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
    echo "phpMyAdmin предназначен для выполнения в веб-браузере\n";
    exit -1;
    __HALT_COMPILER();
    ');
    $a->stopBuffering();
    ?>

## Использование Phar-архивов: обёртка потока phar

Обёртка потока Phar полностью поддерживает fopen() для чтения и записи (не для добавления), unlink(), stat(), fstat(), fseek(), rename() и потоковые операции каталогов, такие как opendir(), rmdir() и mkdir().

Также при помощи контекстов потока можно влиять на сжатие отдельных файлов и пофайловые метаданные в Phar-архиве:

    <?php
    $context = stream_context_create(array('phar' =>
                                        array('compress' => Phar::GZ)),
                                        array('metadata' => array('user' => 'cellog')));
    file_put_contents('phar://my.phar/somefile.php', 0, $context);
    ?>

Обёртка потока `phar` не работает с файлами, расположенными удалённо, и не может с ними работать, так что её использование возможно даже когда параметры INI allow_url_fopen и allow_url_include отключены.

Несмотря на наличие возможности создавать phar-архивы с нуля просто используя потоковые операции, лучшим решением будет использование функционала, встроенного в класс Phar. Обёртку потока лучше всего использовать только для чтения.

## Использование Phar-архивов: классы Phar и PharData

Класс Phar поддерживает чтение и обработку Phar-архивов, а также итерацию через унаследованную функциональность класса RecursiveDirectoryIterator. Благодаря поддержке интерфейса ArrayAccess, доступ к файлам внутри Phar-архива может быть получен, как если бы они были частью ассоциативного массива.

Класс PharData расширяет класс Phar и позволяет создавать и изменять неисполняемые tar- и zip-архивы данных даже в том случае, если параметр `phar.readonly`=1 в php.ini. Фактически функции PharData::setAlias() и PharData::setStub() отключены, поскольку концепция псевдонима и заглушки является уникальной для исполняемых phar-архивов.

Важно отметить, что при создании Phar-архива в конструктор объекта Phar должен быть передан полный путь. Попытки инициализации объекта Phar с относительными путями потерпят неудачу.

Предположим, что `$p` — объект Phar, инициализированный, как показано ниже:

    <?php
    $p = new Phar('/путь/к/myphar.phar', 0, 'myphar.phar');
    ?>

Пустой Phar-архив будет создан в `/путь/к/myphar.phar`, или, если файл `/path/to/myphar.phar` уже существует, он будет открыт повторно. Использование `myphar.phar` показывает концепцию псевдонима, который может быть использован для указания на `/путь/к/myphar.phar` в URL-адресах, подобно тому, как показано ниже:

    <?php
    // эти два вызова file_get_contents() равнозначны в том случае, если
    // /путь/к/myphar.phar имеет явно заданный псевдоним "myphar.phar"
    // в своём манифесте, или если phar был инициализирован созданием объекта Phar,
    // как показано в предыдущем примере
    $f = file_get_contents('phar:///путь/к/myphar.phar/whatever.txt');
    $f = file_get_contents('phar://myphar.phar/whatever.txt');
    ?>

С только что созданным объектом `$p` класса Phar возможно следующее:

- `$a = $p['file.php']` создаст объект класса PharFileInfo, который будет ссылаться на содержимое `phar://myphar.phar/file.php`
- `$p['file.php'] = $v` создаст новый файл (`phar://myphar.phar/file.php`) или перезапишет существующий внутри `myphar.phar`. `$v` может быть строкой или указателем на открытый файл. В последнем случае для создания нового файла будет использовано всё содержимое открытого файла. Обратите внимание, что функционально эквивалентным этому будет вызов `$p->addFromString('file.php', $v)`. Также имеется возможность добавления содержимого файла при помощи `$p->addFile('/path/to/file.php', 'file.php')`. Наконец, пустой каталог может быть создан при помощи `$p->addEmptyDir('empty')`.
- `isset($p['file.php'])` может быть использовано для определения существования файла `phar://myphar.phar/file.php` внутри `myphar.phar`.
- `unset($p['file.php'])` удаляет файл `phar://myphar.phar/file.php` из `myphar.phar`.

Кроме того, использование объекта Phar является единственным способом получить доступ к метаданным архива (через Phar::getMetadata()) и единственным способом установить или получить заглушку Phar-архива через Phar::getStub() и Phar::setStub(). К тому же, работать со сжатием целого Phar-архива можно только используя класс Phar.

Полный перечень функционала объекта Phar задокументирован ниже.

Класс PharFileInfo расширяет класс SplFileInfo и добавляет несколько методов для работы с деталями, присущими файлам, которые содержатся в Phar-архиве, такими как работа со сжатием и метаданными.

# Создание Phar-архивов

## Содержание

- Создание Phar-архивов: Введение

## Создание Phar-архивов: Введение

Должно быть написано в ближайшем будущем. Перед чтением этого обязательно прочитайте Как использовать Phar-архивы.

Отличным началом будет чтение про Phar::buildFromIterator() и об особенностях выбора доступного для архивов формата файла. Хорошее понимание того, что из себя представляет заглушка (stub) и что она имеет решающее значение для создания phar-архива, и поэтому Phar::setStub() и Phar::createDefaultStub() также будут хорошей отправкой точкой. Если вы распространяете веб-приложение, ключевыми будут знания о Phar::webPhar() и связанном с ним методе Phar::mungServer(). Любое приложение, которое обращается к своим собственным файлам, должно учитывать возможность использования Phar::interceptFileFuncs().

# Чем отличается phar от tar- или zip-архива?

## Содержание

- Составные части всех Phar-архивов вне зависимости от формата файла
- Заглушка Phar-файла
- Сравнение Phar, Tar и Zip
- Phar-архивы, основанные на tar
- Phar-архивы, основанные на zip
- Формат файла phar
- Флаги глобальной битовой карты Phar
- Описание записи файла в манифесте Phar
- Формат подписи Phar

## Составные части всех Phar-архивов вне зависимости от формата файла

Все Phar-архивы содержат от трёх до четырёх секций:

1. заглушка

2. манифест, описывающий содержимое

3. содержимое файла

4. [необязательно] подпись для проверки целостности Phar (только для формата файла phar)

## Заглушка Phar-файла

Заглушкой Phar является простой PHP-файл. Минимально возможная заглушка выглядит следующим образом:

    <?php __HALT_COMPILER();

Заглушка должна содержать по крайней мере лексему `__HALT_COMPILER();` в конце файла. Как правило, заглушка содержит функциональность загрузчика, подобно тому, как показано ниже:

    <?php
    Phar::mapPhar();
    include 'phar://myphar.phar/index.php';
    __HALT_COMPILER();

На содержимое заглушки Phar не налагаются ограничения, за исключением того, что она должна завершаться лексемой `__HALT_COMPILER();`. Закрывающий тег PHP ``

    ?>

может быть включён или опущен, но должно быть не более одного пробела между `;` и закрывающим тегом `

    ?>

`, иначе модуль phar не сможет обработать манифест Phar-архива.

В phar-архиве, основанном на tar или zip, заглушка хранится в файле `.phar/stub.php`. Заглушка по умолчанию для Phar-архива, основанного на phar, содержит приблизительно 7 килобайт кода для извлечения содержимого Phar-архива и его выполнения. Смотрите Phar::createDefaultStub() для более подробной информации.

В phar-архиве, основанном на tar или zip, псевдоним phar хранится в файле `.phar/alias.txt` в виде простого текста.

## Сравнение Phar, Tar и Zip

Что хорошего и плохого в трёх поддерживаемых форматах файла в модуле phar? В этой таблице предпринята попытка решить этот вопрос.

Матрица функционала: Phar против Tar против Zip
Функционал | Phar | Tar | Zip
--- | --- | --- | ---
Стандартный формат файла | Нет | Да | Да
Возможно выполнение без модуля Phar [1] | Да | Нет | Нет
Пофайловое сжатие | Да | Нет | Да
Сжатие всего архива | Да | Да | Нет
Проверка подписи всего архива | Да | Да | Да
Поддержка веб-приложений | Да | Да | Да
Пофайловые метаданные | Да | Да | Да
Метаданные всего архива | Да | Да | Да
Создание/изменение архива [2] | Да | Да | Да
Полная поддержка всех функций - обёрток потока | Да | Да | Да
Может быть создан/изменён, даже если phar.readonly=1 [3] | Нет | Да | Да

Подсказка

[1] Без модуля Phar PHP может получить прямой доступ к содержимому Phar-архива только в том случае, если в нём используется `заглушка`, которая извлекает содержимое phar-архива. Заглушка, созданная при помощи Phar::createDefaultStub(), распаковывает phar-архив и запускает его содержимое из временного каталога в том случае, если не был найден модуль phar.

Подсказка

[2] Для доступа на запись требуется, чтобы был отключён параметр `phar.readonly` в php.ini или непосредственно в консоли.

Подсказка

[3] Только архивы tar и zip без `.phar` в имени файла и без исполняемой заглушки `.phar/stub.php` могут быть созданы, если phar.readonly=1.

## Phar-архивы, основанные на tar

Архивы, основанные на формате файла tar, следуют более современному формату файла USTAR. Конструкция заголовка tar-файла делает их более эффективными для доступа, чем формат файла zip, и почти настолько же эффективными, как файлы формата phar. Имена файлов ограничены 255 байтами, включая полный путь к phar-архиву. Ограничений на количество файлов, содержащихся в phar-архиве, основанном на tar, нет. Эти архивы могут быть полностью сжаты в gzip или bzip2 формате и по-прежнему выполняться модулем Phar.

Существует ограниченная поддержка чтения архивов в формате обмена pax, но все распознанные заголовки pax (в настоящее время typeflag `x` and `g`) игнорируются. Также имеется ограниченная поддержка архивов GNU Tar; в настоящее время заголовки `././@LongLink` разрешены.

Для сжатия всего архива используйте Phar::compress(). Для распаковки всего массива используйте Phar::decompress().

## Phar-архивы, основанные на zip

Архивы, основанные на формате файла zip, поддерживают некоторые возможности, встроенные в формат файла zip. Пофайловые и относящиеся ко всему архиву метаданные хранятся в файловых комментариях zip и в комментарии всего zip-архива в виде сериализованных строк. Уже существующие zip-комментарии будут успешно считаны в виде строки. Пофайловое сжатие при чтении/записи поддерживается в случае использования сжатия zlib DEFLATE, а в случае использования bzip2-сжатия поддерживается доступ на чтение. Ограничений на количество файлов, содержащихся в phar-архиве, основанном на zip, нет. Пустые каталоги хранятся в zip-архиве в виде файлов с завершающим слешем как `my/directory/`.

## Формат файла phar

Формат файла phar буквально представляет из себя заглушку/манифест/содержимое/подпись и хранит ключевую информацию о том, что включено в phar-архив в его `манифесте`.

Манифест Phar — это высокооптимизированный формат, который позволяет указывать параметры сжатия файлов, доступа к файлам и даже определяемые пользователем метаданные, такие как владелец или группа файла. Все значения, превышающие 1 байт, хранятся в порядке байтов от младшего к старшему, за исключением версии API, которая по историческим причинам хранится в виде 3 полубайт в порядке от старшего к младшему.

Все неиспользованные флаги зарезервированы для использования в будущем и не должны быть использованы для хранения пользовательской информации. Используйте возможности пофайловых метаданных для хранения индивидуальной информации об отдельных файлах.

Основной формат файла манифеста Phar-архива выглядит следующим образом:

Формат глобального манифеста Phar
Размер в байтах | Описание
--- | ---
4 байта | Длина манифеста в байтах (предел 1 МБ)
4 байта | Количество файлов в Phar-архиве
2 байта | Версия API манифеста Phar (текущая 1.0.0)
4 байта | Флаги глобальной битовой карты Phar
4 байта | Длина псевдонима Phar
?? | Псевдоним Phar (длина основана на предыдущем значении)
4 байта | Длина метаданных Phar (`0` в случае отсутствия)
?? | Сериализованные метаданные Phar, хранящиеся в формате serialize()
по меньшей мере (24 * количество записей) байт | записи для каждого файла

## Флаги глобальной битовой карты Phar

Здесь представлены битовые флаги, на настоящий момент распознаваемые модулем Phar для глобальной битовой карты Phar:

Распознаваемые значения битовой карты
Значение | Описание
--- | ---
`0x00010000` | Если задано, значит этот Phar содержит проверочную подпись
`0x00001000` | Если задано, значит этот Phar содержит по меньшей мере один файл, сжатый при помощи сжатия zlib DEFLATE.
`0x00002000` | Если задано, значит этот Phar содержит по меньшей мере один файл, сжатый при помощи bzip2-сжатия.

## Описание записи файла в манифесте Phar

Каждый файл в манифесте содержит следующую информацию:

Запись файла в манифесте Phar
Размер в байтах | Описание
--- | ---
4 байта | Длина имени файла в байтах
?? | Имя файла (длина указана в предыдущем поле)
4 байта | Размер распакованного файла в байтах
4 байта | Метка времени Unix файла
4 байта | Размер сжатого файла в байтах
4 байта | Контрольная сумма CRC32 содержимого распакованного файла
4 байта | Флаги битовой карты файла
4 байта | Длина сериализованных метаданных файла (`0` в случае отсутствия)
?? | Сериализованные метаданные файла, хранящиеся в формате serialize()

Обратите внимание, что начиная с версии API 1.1.1 пустые каталоги хранятся в виде файлов с завершающим слешем в их имени, как `my/directory/`

К распознаваемым значениям битовой карты файла относятся:

Распознаваемые значения битовой карты
Значение | Описание
--- | ---
`0x000001FF` | Эти биты зарезервированы для определения конкретных прав доступа файла. Права доступа используются для fstat() и могут быть использованы для воссоздания требуемых прав доступа при извлечении.
`0x00001000` | Если задано, то этот файл сжат при помощи сжатия zlib DEFLATE.
`0x00002000` | Если задано, то этот файл сжат при помощи bzip2-сжатия.

## Формат подписи Phar

В содержащих подпись phar-архивах подпись всегда присоединена к концу Phar-архива после загрузчика, манифеста и содержимого файлов. В настоящее время поддерживаются следующие форматы подписи: MD5, SHA1, SHA256, SHA512 и OPENSSL.

Формат подписи
Длина в байтах | Описание
--- | ---
переменная | Собственно подпись. 20 байт в случае использования подписи SHA1, 16 байт в случае использования подписи MD5, 32 байта в случае использования подписи SHA256, 64 байта в случае использования подписи SHA512. Длина подписи OPENSSL зависит от размера закрытого ключа.
4 байта | Флаги подписи. `0x0001` используется для определения подписи MD5, `0x0002` используется для определения подписи SHA1, `0x0003` используется для определения подписи SHA256, `0x0004` используется для определения подписи SHA512. Поддержка подписей SHA256 и SHA512 была введена начиная с версии API 1.1.0. `0x0010` используется для определения подписи OPENSSL, которая доступна с версии API 1.1.1, если доступен OpenSSL.
4 байта | Магический `GBMB` используется для определения наличия подписи.

# Класс Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Введение

Класс Phar предоставляет высокоуровневый интерфейс создания phar-архивов и доступа к ним.

## Обзор класса

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Наследуемые константы */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Константы */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* Методы */
public function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* Наследуемые методы */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлена поддержка модуля меток времени эпохи Unix для архивов на основе Zip.
8.0.0 | Метаданные больше не десериализуются при открытии архива, а откладываются до вызова метода Phar::getMetadata().

## Примечания

Предостережение

До PHP 8.0.0 метаданные десериализовались при открытии архива, что могло привести к уязвимостям в безопасности. Начиная с PHP 8.0.0, метаданные десериализуются только при вызове метода Phar::getMetadata(), у которого есть опции для ограничения десериализации из соображений безопасности.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — Добавляет в phar-архив пустую директорию

### Описание

public function Phar::addEmptyDir(string `$directory`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

С помощью этого метода создаётся пустая директория, путь к которой указан в `dirname`. Этот метод аналогичен ZipArchive::addEmptyDir().

### Список параметров

`directory`

  Имя пустого каталога, который должен быть создан в phar-архиве.

### Возвращаемые значения

Нет возвращаемого значения, в случае возникновения ошибки выбрасывается исключение.

### Примеры

Пример #1 Пример использования Phar::addEmptyDir()

    <?php
    try {
        $a = new Phar('/путь/к/phar.phar');

        $a->addEmptyDir('/полный/путь/к/файлу');
        // показывает, как хранится этот файл
        $b = $a['полный/путь/к/файлу']->isDir();
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- PharData::addEmptyDir() - Добавить пустую директорию в tar/zip-архив
- Phar::addFile() - Добавляет в phar-архив файл из файловой системы
- Phar::addFromString() - Добавляет в phar-архив файл из строки

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — Добавляет в phar-архив файл из файловой системы

### Описание

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

С помощью этого метода в phar-архив может быть добавлен любой файл или содержимое, доступное по URL. Если указан необязательный второй параметр `localName`, то файл будет сохранён в архиве с таким именем, в ином случае в качестве пути для сохранения внутри архива будет использован параметр `file`. При добавлении содержимого, доступного по URL, параметр `localname` должен быть указан, иначе будет выброшено исключение. Этот метод аналогичен ZipArchive::addFile().

### Список параметров

`filename`

  Полный или относительный путь к файлу в файловой системе, который должен быть добавлен в phar-архив.

`localName`

  Путь, по которому файл будет сохранён в архиве.

### Возвращаемые значения

Нет возвращаемого значения, в случае возникновения ошибки выбрасывается исключение.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `localName` теперь допускает значение null.

### Примеры

Пример #1 Пример использования Phar::addFile()

    <?php
    try {
        $a = new Phar('/путь/к/phar.phar');

        $a->addFile('/полный/путь/к/файлу');
        // показывает, как хранится этот файл
        $b = $a['полный/путь/к/файлу']->getContent();

        $a->addFile('/полный/путь/к/файлу', 'моя_папка/file.txt');
        $c = $a['моя_папка/file.txt']->getContent();

        // показывает использование URL
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Примечания

> Замечание: Phar::addFile(), Phar::addFromString() и Phar::offsetSet() сохраняет новый phar-архив каждый раз при их вызове. Если производительность вызывает беспокойство, вместо этого следует использовать Phar::buildFromDirectory() или Phar::buildFromIterator().

### Смотрите также

- Phar::offsetSet() - Изменение содержимого файла
- PharData::addFile() - Добавить существующие файлы к tar/zip-архиву
- Phar::addFromString() - Добавляет в phar-архив файл из строки
- Phar::addEmptyDir() - Добавляет в phar-архив пустую директорию

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — Добавляет в phar-архив файл из строки

### Описание

public function Phar::addFromString(string `$localName`, string `$contents`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

С помощью этого метода в phar-архив может быть добавлена любая строка. Файл будет сохранён в архиве под именем, указанным в параметре `localname`. Этот метод аналогичен ZipArchive::addFromString().

### Список параметров

`localName`

  Путь, по которому файл будет сохранён в архиве.

`contents`

  Содержимое файла для сохранения.

### Возвращаемые значения

Нет возвращаемого значения, в случае возникновения ошибки выбрасывается исключение.

### Примеры

Пример #1 Пример использования Phar::addFromString()

    <?php
    try {
        $a = new Phar('/путь/к/phar.phar');

        $a->addFromString('путь/к/file.txt', 'мой простой файл');
        $b = $a['путь/к/file.txt']->getContent();

        // для добавления содержимого из дескриптора потока для больших файлов используйте offsetSet()
        $c = fopen('/путь/к/hugefile.bin');
        $a['largefile.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Примечания

> Замечание: Phar::addFile(), Phar::addFromString() и Phar::offsetSet() сохраняет новый phar-архив каждый раз при их вызове. Если производительность вызывает беспокойство, вместо этого следует использовать Phar::buildFromDirectory() или Phar::buildFromIterator().

### Смотрите также

- Phar::offsetSet() - Изменение содержимого файла
- PharData::addFromString() - Добавляет файл из строки в архив tar/zip
- Phar::addFile() - Добавляет в phar-архив файл из файловой системы
- Phar::addEmptyDir() - Добавляет в phar-архив пустую директорию

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Возвращает версию API

### Описание

final public static function Phar::apiVersion(): string

Возвращает версию API формата phar-файла, которая будет использована для создания архивов. Модуль Phar поддерживает чтение начиная с версии API 1.0.0. Для использования хешей SHA-256 и SHA-512 требуется версия API 1.1.0, а для хранения пустых директорий требуется версия API 1.1.1.

### Список параметров

### Возвращаемые значения

Строка версии API, как в `"1.0.0"`.

### Примеры

Пример #1 Пример использования Phar::apiVersion()

    <?php
    echo Phar::apiVersion();
    ?>

Результат выполнения приведённого примера:

    1.1.1

# Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — Создаёт phar-архив из файлов, расположенных внутри директории

### Описание

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Заполняет phar-архив содержимым директории. Необязательный второй параметр является регулярным выражением (PCRE) и используется для исключения файлов. Любой файл, чьё имя соответствует регулярному выражению, будет включён, все остальные будут исключены. Для более детализированного контроля используйте Phar::buildFromIterator().

### Список параметров

`directory`

  Полный или абсолютный путь к директории, все файлы которой должны быть добавлены в архив.

`pattern`

  Необязательное регулярное выражение (PCRE), которое используется для фильтрации списка файлов. В архив будут включены только те файлы, пути к которым соответствуют регулярному выражению.

### Возвращаемые значения

Phar::buildFromDirectory() возвращает ассоциативный массив, в котором отражено соответствие пути к файлу внутри архива к пути к файлу в файловой системе.

### Ошибки

Этот метод выбрасывает исключение BadMethodCallException в том случае, если не удалось создать экземпляр итератора внутренних директорий. Исключение PharException выбрасывается в случае ошибок сохранения phar-архива.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Phar::buildFromDirectory() больше не возвращает значение `false`.

### Примеры

Пример #1 Пример использования Phar::buildFromDirectory()

    <?php
    // создать с псевдонимом "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    // добавить все файлы директории project в файл project.phar
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));

    $phar2 = new Phar('project2.phar', 0, 'project2.phar');
    // добавить все файлы директории project в файл project2.phar, включая только php-файлы
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    $phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Смотрите также

- Phar::buildFromIterator() - Создаёт phar-архив из итератора

# Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — Создаёт phar-архив из итератора

### Описание

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Заполняет phar-архив из итератора. Поддерживаются итераторы двух типов: такие, в которых отображается соответствие имени файла внутри phar-архива к файлу на диске, и такие как DirectoryIterator, которые возвращают объекты SplFileInfo. Для итераторов, которые возвращают объекты SplFileInfo, второй параметр является обязательным.

### Список параметров

`iterator`

  Любой итератор, который или ассоциативно отображает пути к файлам внутри phar-архива к файлам на диске, или возвращает объекты SplFileInfo.

`baseDirectory`

  Для итераторов, возвращающих объекты SplFileInfo, — часть полного пути каждого файла, которая должна быть удалена во время его добавления в phar-архив.

### Возвращаемые значения

Phar::buildFromIterator() возвращает ассоциативный массив, в котором отображаются соответствия пути к файлу внутри архива к пути к файлу в файловой системе.

### Ошибки

Этот метод выбрасывает исключение UnexpectedValueException, когда итератор возвращает некорректные значения, такие как целочисленный ключ вместо строки. Исключение BadMethodCallException будет брошено, когда итератор, основанный на SplFileInfo, используется без параметра `baseDirectory`. Исключение PharException выбрасывается в случае ошибок сохранения phar-архива.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Phar::buildFromIterator() больше не возвращает значение `false`.
8.0.0 | `baseDirectory` теперь допускает значение null.

### Примеры

Пример #1 Пример использования Phar::buildFromIterator() с объектами SplFileInfo

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

    /путь/к/проекту/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Для добавления этих файлов в phar-архив "project.phar" может быть использован следующий код:

    <?php
    // создать с псевдонимом "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/путь/к/проекту')),
        '/путь/к/проекту');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

После этого файл project.phar может быть использован немедленно. Такие значения как сжатие и метаданные не устанавливаются методом Phar::buildFromIterator() и могут быть установлены после создания phar-архива.

В качестве интересного замечания можно отметить, что Phar::buildFromIterator() также может быть использован для копирования содержимого существующего phar-архива, поскольку класс Phar является потомком DirectoryIterator:

    <?php
    // создать с псевдонимом "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/путь/к/anotherphar.phar')),
        'phar:///путь/к/anotherphar.phar/путь/к/проекту');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Пример #2 Пример использования Phar::buildFromIterator() с другими типами итераторов

Второй тип предполагает использование любого итератора, возвращаемые значения которого отображают соответствие имени файла внутри phar-архива к файлу на диске, как в случае с ArrayIterator:

    <?php
    // создать с псевдонимом "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'путь/внутри/архива/file.php' => dirname(__FILE__) . '/somefile.php',
            'друго/путь/внутри/архива/file.jpg' => fopen('/путь/к/bigfile.jpg', 'rb'),
         )));
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Смотрите также

- Phar::buildFromDirectory() - Создаёт phar-архив из файлов, расположенных внутри директории

# Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2

### Описание

final public static function Phar::canCompress(int `$compression` = 0): bool

Этот метод следует использовать для проверки поддержки сжатия до загрузки phar-архива, содержащего сжатые файлы.

### Список параметров

`compression`

  Может быть использована одна из констант `Phar::GZ` или `Phar::BZ2` для проверки возможности сжатия по алгоритму zlib или bzip2 соответственно.

### Возвращаемые значения

`true`, если сжатие/распаковка доступны, `false`, в противном случае.

### Примеры

Пример #1 Пример использования Phar::canCompress()

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
    } else {
        echo 'сжатие недоступно';
    }
    ?>

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::convertToExecutable() - Конвертирует phar-архив в другой исполняемый формат файла
- Phar::convertToData() - Конвертирует phar-архив в неисполняемый tar- или zip-файл

# Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — Проверяет, поддерживает ли модуль phar сохранение и создание phar-архивов

### Описание

final public static function Phar::canWrite(): bool

Этот статический метод определяет, был ли отключён доступ на запись в системном файле php.ini с использованием переменной phar.readonly.

### Список параметров

### Возвращаемые значения

`true`, если доступ на запись включён, `false` в противном случае.

### Примеры

Пример #1 Пример использования Phar::canWrite()

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://myphar.phar/file.txt', 'всем привет');
    }
    ?>

### Смотрите также

- phar.readonly
- Phar::isWritable() - Проверяет, можно ли модифицировать phar-архив

# Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия

### Описание

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

В случае использования с phar-архивами, основанными на tar или phar, этот метод сжимает весь архив, используя gzip- или bzip2-сжатие. Полученный файл может быть обработан одной из команд gunzip/bunzip; к нему также можно получить прямой доступ, используя модуль Phar.

В случае использования с phar-архивами, основанными на zip, вызов этого метода потерпит неудачу и будет брошено исключение. Для сжатия по алгоритму gzip должен быть включён модуль zlib. Для сжатия по алгоритму bzip2 должен быть включён модуль bzip2. Как и в случае с другим функционалом, модифицирующим содержание phar-архива, для успешной работы данного метода необходимо, чтобы INI-переменная phar.readonly была отключена.

Кроме того, этот метод автоматически переименовывает архив, добавляя `.gz`, `.bz2` или удаляя расширение, если в качестве первого параметра был передан `Phar::NONE`, сообщающий о необходимости распаковки. В качестве альтернативы расширение файла может быть задано с помощью второго параметра.

### Список параметров

`compression`

  Сжатие должно быть определено одной из констант: `Phar::GZ`, `Phar::BZ2` для использования соответствующего алгоритма сжатия, или `Phar::NONE` для распаковки.

`extension`

  Для сжатия phar-архивов по умолчанию используется расширение `.phar.gz` или `.phar.bz2`, а для сжатия tar-архивов — `.phar.tar.gz` или `.phar.tar.bz2`. В случае распаковки, расширениями по умолчанию являются `.phar` и `.phar.tar`.

### Возвращаемые значения

Возвращает объект Phar или `null` в случае возникновения ошибки.

### Ошибки

Выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, модуль zlib не доступен или модуль bzip2 не включён.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `extension` теперь допускает значение null.

### Примеры

Пример #1 Пример использования Phar::compress()

    <?php
    $p = new Phar('/путь/к/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'привет';
    $p['myfile2.txt'] = 'привет';
    $p1 = $p->compress(Phar::GZ); // копирует в /путь/к/my.phar.gz
    $p2 = $p->compress(Phar::BZ2); // копирует в /путь/к/my.phar.bz2
    $p3 = $p2->compress(Phar::NONE); // исключение: /путь/к/my.phar уже существует
    ?>

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве

# Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — Сжимает все файлы в текущем Phar-архиве

### Описание

public function Phar::compressFiles(int `$compression`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

В случае использования с phar-архивами, основанными на tar, этот метод выбрасывает исключение BadMethodCallException, поскольку сжатие отдельных файлов внутри tar-архива не поддерживается данным форматом. Для сжатия целого phar-архива, основанного на tar, используйте Phar::compress().

В случае использования с phar-архивами, основанными на zip или phar, этот метод сжимает все файлы в Phar-архиве используя указанный алгоритм сжатия. Для возможности воспользоваться данным методом должен быть включён модуль zlib или bzip2. Кроме того, если какие-либо файлы в архиве уже сжаты с использованием bzip2/zlib-сжатия, то для их распаковки перед повторным сжатием должен быть включён соответствующий модуль. Как и в случае с другим функционалом, модифицирующим содержание phar-архива, для успешной работы данного метода необходимо, чтобы INI-переменная phar.readonly была отключена.

### Список параметров

`compression`

  Сжатие должно быть определено одной из констант: `Phar::GZ`, `Phar::BZ2` для использования соответствующего алгоритма сжатия, или `Phar::NONE` для распаковки.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, модуль zlib не доступен или если какие-либо файлы внутри архива были сжаты при помощи bzip2-сжатия и модуль bzip2 не включён.

### Примеры

Пример #1 Пример использования Phar::compressFiles()

    <?php
    $p = new Phar('/путь/к/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'привет';
    $p['myfile2.txt'] = 'привет';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Результат выполнения приведённого примера:

    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив

# Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Создаёт объект Phar-архива

### Описание

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### Список параметров

`filename`

  Путь к уже существующему Phar-архиву или к архиву, который должен быть создан. Расширение в имени файла должно содержать .phar.

`flags`

  Флаги, которые должны быть переданы в родительский класс RecursiveDirectoryIterator.

`alias`

  Псевдоним, с помощью которого должны производиться ссылки на этот Phar-архив в вызовах, связанных с функционалом потоков.

### Ошибки

Выбрасывает исключение BadMethodCallException, если был вызван дважды, и исключение UnexpectedValueException, если phar-архив не может быть открыт.

### Примеры

Пример #1 Пример использования Phar::__construct()

    <?php
    try {
        $p = new Phar('/путь/к/my.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                      'my.phar');
    } catch (UnexpectedValueException $e) {
        die('Не удалось открыть my.phar');
    } catch (BadMethodCallException $e) {
        echo 'Технически это не может произойти';
    }
    // это теперь работает
    echo file_get_contents('phar://my.phar/example.txt');
    // и работает так же, как если бы мы ввели
    echo file_get_contents('phar:///путь/к/my.phar/example.txt');
    ?>

# Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — Конвертирует phar-архив в неисполняемый tar- или zip-файл

### Описание

public function Phar::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Этот метод используется для конвертирования phar-архив в tar- или zip-файл. Чтобы создать сделать tar или zip неисполняемым, из создаваемого в результате конвертации архива удаляются загрузка и псевдоним phar-архива.

Если не были указаны никакие изменения, то данный метод выбросит исключение BadMethodCallException, если форматом файла архива является phar. В случае использования с архивами в формате tar или zip, данный метод конвертирует архив в неисполняемый архив.

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

### Список параметров

`format`

  Значением этого параметра должна быть одна из констант: `Phar::TAR` или `Phar::ZIP`. Если значение установлено в `null`, то существующий формат файла будет сохранён.

`compression`

  Значением этого параметра должна быть одна из констант: `Phar::NONE` для отсутствия сжатия всего архива, `Phar::GZ` для сжатия, основанного на zlib, или `Phar::BZ2` для bzip-сжатия.

`extension`

  Этот параметр используется для переопределения расширение файла по умолчанию для сконвертированного архива. Обратите внимание, что `.phar` не может быть использовано где-либо в имени файла неисполняемого tar- или zip-архива.

  В случае конвертации phar-архива, основанного на tar, расширениями по умолчанию являются: `.tar`, `.tar.gz` и `.tar.bz2`, в зависимости от указанного сжатия. Для архивов, основанных на zip, расширением по умолчанию является `.zip`.

### Возвращаемые значения

Данный метод возвращает объект PharData в случае успешного выполнения и `null` в случае возникновения ошибки.

### Ошибки

Данный метод выбрасывает исключение BadMethodCallException в следующих случаях: при невозможности сжатия; если был передан неизвестный алгоритм сжатия; в запрошенном архиве была включена буферизация с помощью Phar::startBuffering() и не была завершена с помощью Phar::stopBuffering(). В случае возникновения каких-либо проблем в процессе создания phar будет выброшено исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `format`, `compression` и `extension` теперь допускают значение null.

### Примеры

Пример #1 Пример использования Phar::convertToData()

Использование Phar::convertToData():

    <?php
    try {
        $tarphar = new Phar('myphar.phar.tar');
        // обратите внимание, что myphar.phar.tar *не* будет удалён
        // конверировать архив в неисполняемый tar-формат
        // будет создан myphar.tar
        $tar = $tarphar->convertToData();
        //  конверировать архив в неисполняемый zip-формат файла, будет создан myphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // будет создан myphar.tbz
        $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // будет создан myphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // будет выброшено исключение
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::convertToExecutable() - Конвертирует phar-архив в другой исполняемый формат файла
- PharData::convertToExecutable() - Конвертация tar/zip-архива с данными в запускаемый phar-архив
- PharData::convertToData() - Конвертация phar-архива в незапускаемый tar/zip-архив

# Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — Конвертирует phar-архив в другой исполняемый формат файла

### Описание

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Этот метод используется для конвертирования phar-архива в другой формат файла. Например, он может быть использован для создания исполняемого phar-архива, основанного на tar, из исполняемого phar-архива, основанного на zip, или из исполняемого phar-архива с форматом файла phar. Кроме того, данный метод может быть использован для сжатия целого архива, основанного на tar или phar.

Если не были указаны никакие изменения, то данный метод выбросит исключение BadMethodCallException.

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

### Список параметров

`format`

  Значением этого параметра должна быть одна из констант: `Phar::PHAR`, `Phar::TAR` или `Phar::ZIP`. Если значение установлено в `null`, то существующий формат файла будет сохранён.

`compression`

  Значением этого параметра должна быть одна из констант: `Phar::NONE` для отсутствия сжатия всего архива, `Phar::GZ` для сжатия, основанного на zlib, или `Phar::BZ2` для bzip-сжатия.

`extension`

  Этот параметр используется для переопределения расширение файла по умолчанию для сконвертированного архива. Обратите внимание, что все phar-архивы, основанные на tar или zip, должны содержать `.phar` в расширении файла чтобы они могли быть обработаны в качестве phar-архива.

  В случае конвертации архива, основанного на phar, расширениями по умолчанию являются `.phar`, `.phar.gz` и `.phar.bz2`, в зависимости от указанного сжатия. В случае конвертации phar-архива, основанного на tar, расширениями по умолчанию являются `.phar.tar`, `.phar.tar.gz` и `.phar.tar.bz2`. Для архивов, основанных на zip, расширением по умолчанию является `.zip`.

### Возвращаемые значения

Данный метод возвращает объект Phar в успешного выполнения и `null` в случае возникновения ошибки.

### Ошибки

Данный метод выбрасывает исключение BadMethodCallException в следующих случаях: при невозможности сжатия; если был передан неизвестный алгоритм сжатия; в запрошенном архиве была включена буферизация с помощью Phar::startBuffering() и не была завершена с помощью Phar::stopBuffering(). Если поддержка записи отключена, то будет брошено исключение UnexpectedValueException. В случае возникновения каких-либо проблем в процессе создания phar выбрасывается исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `format`, `compression` и `extension` теперь допускают значение null.

### Примеры

Пример #1 Пример использования Phar::convertToExecutable()

Использование Phar::convertToExecutable():

    <?php
    try {
        $tarphar = new Phar('myphar.phar.tar');
        // конвертировать архив в формат phar
        // обратите внимание, что myphar.phar.tar *не* будет удалён
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // будет создан myphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // будет создан myphar.phar.tgz
        $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::convertToData() - Конвертирует phar-архив в неисполняемый tar- или zip-файл
- PharData::convertToExecutable() - Конвертация tar/zip-архива с данными в запускаемый phar-архив
- PharData::convertToData() - Конвертация phar-архива в незапускаемый tar/zip-архив

# Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — Копирует файл внутри phar-архива в новый файл внутри phar-архива

### Описание

public function Phar::copy(string `$from`, string `$to`): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Метод копирует внутренний файл phar-архива в другой новый файл внутри phar-архива. Это объектно-ориентированная альтернатива функции copy() с обёрткой потока phar.

### Список параметров

`from`

`to`

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение UnexpectedValueException, если исходный файл не существует, целевой файл уже существует, доступ на запись запретили, если хотя бы один файл невозможно открыть или невозможно прочитать исходный файл, или выбрасывает исключение PharException, если в phar-файл невозможно записать изменения.

### Примеры

Пример #1 Пример копирования файла внутри phar-архива методом Phar::copy()

Пример показывает работу метода Phar::copy() и эквивалентной ему по функциональности обёртки потока для решения одной и той же задачи. Основная разница между подходами состоит в обработке ошибок. Методы класса Phar выбрасывают исключения, а обёртка потока использует функцию trigger_error().

    <?php

    try {
        $phar = new Phar('myphar.phar');

        $phar['a'] = 'привет';
        $phar->copy('a', 'b');

        echo $phar['b']; // Выводит "phar://myphar.phar/b"
    } catch (Exception $e) {
        // Обработка ошибок
    }

    // Обёртка потока эквивалентна приведённому коду.
    // Вместо исключения срабатывает ошибка уровня E_WARNING
    copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
    echo file_get_contents('phar://myphar.phar/c'); // Выведет "привет"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Возвращает количество записей (файлов) в Phar-архиве

### Описание

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### Список параметров

`mode`

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

### Возвращаемые значения

Количество файлов, содержащихся в этом phar-архиве, либо `0` (число ноль), если архив пуст.

### Примеры

Пример #1 Пример использования Phar::count()

    <?php
    // убедитесь, что архив не существует
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'Не удалось создать phar:', $e;
    }
    echo 'Новый phar содержит ' . $p->count() . " записей\n";
    $p['file.txt'] = 'привет';
    echo 'Новый phar содержит ' . $p->count() . " записей\n";
    ?>

Результат выполнения приведённого примера:

    Новый phar содержит 0 записей
    Новый phar содержит 1 записей

# Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — Создать заглушку в формате phar-архива

### Описание

final public static function Phar::createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string

Этот метод создаёт код заглушку (stub) в специфичном для phar-архива формате и не предназначенный для использования с файловыми архивами на основе tar или zip.

Phar-архивы содержат загрузчик (`stub`), написанный на PHP, который запускается при запуске архива, когда его подключают через include:

    <?php
    include 'myphar.phar';
    ?>

или просто запускают:

    php myphar.phar

Этот метод предоставляет простой способ для создания заглушку, который будет отрабатывать при запуске phar-архива. Кроме того, можно указывать разные файлы для запуска phar-архива через веб-сервер и через командную строку. Заглушка также вызывает Phar::interceptFileFuncs() для простого создания приложений PHP с доступом к файловой системе. Если модуль phar отсутствует, то заглушка распакует phar-архив во временную директорию и запустит приложение оттуда. Функция завершения работы удалит все временные файлы.

### Список параметров

`index`

  Относительный путь в phar-архиве для запуска при доступе из командной строки

`webIndex`

  Относительный путь в phar-архиве для запуска при доступе через браузер

### Возвращаемые значения

Возвращает текст с кодом заглушку, который позволит Phar-архиву запускаться независимо от того, подключён ли модуль Phar или нет.

### Ошибки

Выбросит исключение UnexpectedValueException, если любой из параметров будет длиннее 400 байт.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `index` и `webIndex` теперь допускают значение null.

### Примеры

Пример #1 Пример использования Phar::createDefaultStub()

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::setStub() - Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP
- Phar::getStub() - Получить загрузчик PHP или загрузчик заглушки Phar-архива

# Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Распаковывает весь Phar-архив

### Описание

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

В случае с phar-архивами, основанными на tar или phar, этот метод распаковывает весь архив.

В случае с phar-архивами, основанными на zip, вызов данного метода потерпит неудачу и будет брошено исключение. Для распаковки архива, сжатого по алгоритму gzip, должен быть включён модуль zlib; для распаковки архива, сжатого по алгоритму bzip2, должен быть включён модуль bzip2. Как и в случае с другим функционалом, модифицирующим содержание phar-архива, для успешной работы данного метода необходимо, чтобы INI-переменная phar.readonly была отключена.

Кроме того, этот метод автоматически меняет расширения файла архива: по умолчанию `.phar` для phar-архивов и `.phar.tar` для phar-архивов, основанных на tar. В качестве альтернативы расширение файла может быть задано с помощью второго параметра.

### Список параметров

`extension`

  Расширениями распакованного файла по умолчанию являются `.phar` и `.phar.tar`. Этот параметр может быть использован для задания другого расширения распакованного файла. Имейте в виду, что все исполняемые phar-архивы должны содержать `.phar` в имени файла.

### Возвращаемые значения

Возвращает объект Phar в случае успешного выполнения и `null` в случае возникновения ошибки.

### Ошибки

Выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, модуль zlib не доступен или модуль bzip2 не включён.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `extension` теперь допускает значение null.

### Примеры

Пример #1 Пример использования Phar::decompress()

    <?php
    $p = new Phar('/путь/к/my.phar', 0, 'my.phar.gz');
    $p['myfile.txt'] = 'привет';
    $p['myfile2.txt'] = 'привет';
    $p3 = $p2->decompress(); // создаст /путь/к/my.phar
    ?>

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве

# Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — Распаковывает все файлы в текущем Phar-архиве

### Описание

public function Phar::decompressFiles(): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

При работе с phar-архивами на основе формата tar метод выбрасывает исключение BadMethodCallException, поскольку сжатие отдельных файлов внутри tar-архива не поддерживается форматом файла. Для сжатия целого phar-архива на основе формата tar пользуются методом Phar::compress().

При работе с phar-архивами на основе форматов zip или phar метод распаковывает все файлы в Phar-архиве. Для распаковки файлов этим методом потребуется включить модуль zlib или bzip2, если файлы внутри архива сжали методом bzip2 или zlib. Как и в случае с другим функционалом, который модифицирует содержание phar-архива, для успешной работы метода потребуется отключить INI-переменную phar.readonly.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, модуль zlib недоступен или если файлы внутри архива сжали методом bzip2, а модуль bzip2 отключён.

### Примеры

Пример #1 Пример распаковки phar-архива методом Phar::decompressFiles()

    <?php

    $p = new Phar('/путь/к/my.phar', 0, 'my.phar');

    $p['myfile.txt'] = 'привет';
    $p['myfile2.txt'] = 'привет';

    $p->compressFiles(Phar::GZ);

    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }

    $p->decompressFiles();

    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }

    ?>

Результат выполнения приведённого примера:

    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив

# Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — Удаляет глобальные метаданные в phar-архиве

### Описание

public function Phar::delMetadata(): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Метод удаляет глобальные метаданные в phar-архиве.

### Список параметров

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение PharException, если при сохранении изменений на диск возникла ошибка.

### Примеры

Пример #1 Пример удаления глобальных метаданных в phar-архиве методом Phar::delMetaData()

    <?php

    try {
        $phar = new Phar('myphar.phar');

        var_dump($phar->getMetadata());

        $phar->setMetadata("hi there");
        var_dump($phar->getMetadata());

        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // Обработка ошибок
    }

    ?>

Результат выполнения приведённого примера:

    NULL
    string(8) "hi there"
    NULL

### Смотрите также

- Phar::getMetadata() - Извлечь метаданные phar-архива
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные

# Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — Удаляет файл в phar-архиве

### Описание

public function Phar::delete(string `$localName`): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Метод удаляет файл из архива. Метод аналогичен вызову функции unlink() на обёртке потока, как показывает пример на этой странице.

### Список параметров

`localName`

  Путь в архиве, по которому требуется удалить файл.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение PharException, если на диск возникли ошибки во время записи изменений.

### Примеры

Пример #1 Пример удаления файла внутри phar-архива методом Phar::delete()

    <?php

    try {
        $phar = new Phar('myphar.phar');

        $phar->delete('unlink/me.php');

        // Это эквивалентно вызову функции unlink()
        unlink('phar://myphar.phar/unlink/me.php');
    } catch (Exception $e) {
        // Обработка ошибок
    }
    ?>

### Смотрите также

- PharData::delete() - Удаляет файл в tar- или zip-архиве
- Phar::unlinkArchive() - Удаляет архив из памяти и с диска

# Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — Уничтожает объект архива Phar

### Описание

public function Phar::__destruct()

### Список параметров

Сигнатура функции не содержит параметров.

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — Извлечь содержимое phar-архива в директорию

### Описание

public function Phar::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Извлекает все файлы phar-архива на диск. Извлечённые файлы и директории сохраняют все разрешения, которые у них были. Опциональные параметры позволяют контролировать, какие именно файлы извлекать и нужно ли перезаписывать уже существующие. Второй параметр `files` может быть как именем файла, так и путём директории, которые надо извлекать. По умолчанию уже существующие на диске файлы перезаписываться не будут. Для указания, что нужно использовать перезапись, используется третий параметр. Этот метод аналогичен методу ZipArchive::extractTo().

### Список параметров

`directory`

  Путь, по которому необходимо сохраните извлечённые файлы (`files`)

`files`

  Имя файла или директории, которые надо извлечь или архив с именами файлов/директорий. `null` для пропуска этого параметра.

`overwrite`

  Установите в `true`, если необходимо перезаписывать уже существующие файлы

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения. Но лучше использовать механизм перехвата исключений для контроля успешности.

### Ошибки

Выбрасывает исключение PharException в случае возникновения ошибки записи на диск.

### Примеры

Пример #1 Пример использования Phar::extractTo()

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->extractTo('/full/path'); // извлечь все файлы
        $phar->extractTo('/another/path', 'file.txt'); // извлечь только file.txt
        $phar->extractTo('/this/path',
            array('file1.txt', 'file2.txt')); // извлечь два указанных файла
        $phar->extractTo('/third/path', null, true); // извлечь все файлы, использовать перезапись
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Примечания

> Замечание: Файловые системы Windows NTFS не поддерживают некоторые символы в именах файлов — `<|>*?":`. Имена файлов с точкой в конце также не поддерживаются. В отличие от ряда инструментов извлечения, метод не поддерживает замену этих символов на подчёркивание, а вместо этого возникает ошибка при извлечении таких файлов.

### Смотрите также

- PharData::extractTo() - Извлечь содержимое tar/zip-архива в директорию

# Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Получить псевдоним для Phar

### Описание

public function Phar::getAlias(): ?string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает псевдоним или `null` в случае его отсутствия.

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — Извлечь метаданные phar-архива

### Описание

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Возвращает метаданные phar-архива. Метаданными может быть любая переменная PHP, которая может быть сериализована.

Предостережение

Доступ к метаданным вызовет десериализацию, которая может привести к выполнению произвольного PHP-кода. Не используйте этот метод для недоверенных phar-архивов или настройте параметр `unserializeOptions` безопасным образом.

### Список параметров

Без параметров.

### Возвращаемые значения

Любое значение PHP, которое может быть сериализовано и хранится как метаданные для архива Phar, либо `null`, если метаданные отсутствуют.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Добавлен параметр `unserializeOptions`.

### Примеры

Пример #1 Пример использования Phar::getMetadata()

    <?php
    // Убедимся, что архив не существует
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "hello";';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Не удалось изменить phar:', $e;
    }
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Смотрите также

- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::delMetadata() - Удаляет глобальные метаданные в phar-архиве
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные

# Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — Определить, изменялся phar-архив

### Описание

public function Phar::getModified(): bool

Этот метод используется для определения, изменялось ли что-либо в phar-архиве.

### Список параметров

Без параметров.

### Возвращаемые значения

`true`, если архив после открытия изменялся и `false`, в противном случае.

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Получить реальный путь к Phar-архиву на диске

### Описание

public function Phar::getPath(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива

### Описание

public function Phar::getSignature(): array|false

Возвращает проверочную подпись phar-архива в виде строки шестнадцатеричных цифр.

### Список параметров

### Возвращаемые значения

Массив, содержащий цифровую подпись открытого архива по ключу `hash`, и `MD5`, `SHA-1`, `SHA-256`, `SHA-512` или `OpenSSL` по ключу `hash_type`. Подпись - это хеш, вычисленный от содержимого архива, которую можно использовать для проверки его целостности. Корректная подпись требуется для всех запускаемых phar-архивов, если разрешена INI-переменная phar.require_hash. Если сигнатуры нет, функция возвращает `false`.

# Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Получить загрузчик PHP или загрузчик заглушки Phar-архива

### Описание

public function Phar::getStub(): string

Phar-архивы содержат начальную загрузку или заглушку (`stub`), написанную на PHP, который запускается при запуске архива, когда его подключают через include:

    <?php
    include 'myphar.phar';
    ?>

или просто запускают:

    php myphar.phar

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку с содержанием начального загрузчика (заглушки) текущего Phar-архива.

### Ошибки

Выбрасывает исключение RuntimeException, если по каким-либо причинам не может получить текст загрузчика.

### Примеры

Пример #1 Пример использования Phar::getStub()

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    echo $p->getStub();
    echo "==NEXT==\n";
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER(); ?>");
    echo $p->getStub();
    ?>

Результат выполнения приведённого примера:

    <?php __HALT_COMPILER(); ?>
    ==NEXT==
    <?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER(); ?>

### Смотрите также

- Phar::setStub() - Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP
- Phar::createDefaultStub() - Создать заглушку в формате phar-архива

# Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — Возвращает массив поддерживаемых алгоритмов сжатия

### Описание

final public static function Phar::getSupportedCompression(): array

### Список параметров

Нет параметров.

### Возвращаемые значения

Возвращает массив, содержащий любые из значений `Phar::GZ` или `Phar::BZ2` в зависимости от доступности модулей zlib и bz2.

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве

# Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — Получить массив поддерживаемых алгоритмов подписи архива

### Описание

final public static function Phar::getSupportedSignatures(): array

Возвращает массив поддерживаемых алгоритмов подписи архива

### Список параметров

Без параметров.

### Возвращаемые значения

Возвращает массив примерно такого содержания: `MD5`, `SHA-1`, `SHA-256`, `SHA-512`, `OpenSSL`.

### Смотрите также

- Phar::getSignature() - Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива
- Phar::setSignatureAlgorithm() - Установить алгоритм подписания phar-архива и применение его

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Получить версию Phar-архива

### Описание

public function Phar::getVersion(): string

Возвращает версию API открытого Phar-архива.

### Список параметров

### Возвращаемые значения

Версия API открытого архива. Не перепутайте с версией API загруженного модуля phar. Каждый Phar-архив имеет жёстко прописанную версию API, с помощью которого его создавали, в манифесте. Подробную документацию можно почитать на странице Формат файла Phar.

### Смотрите также

- Phar::apiVersion() - Возвращает версию API

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — Проверить, содержит ли phar-архив глобальные метаданные

### Описание

public function Phar::hasMetadata(): bool

Проверяет, содержит ли phar-архив глобальные метаданные.

### Список параметров

Без параметров.

### Возвращаемые значения

Возвращает `true` или `false`.

### Примеры

Пример #1 Пример использования Phar::hasMetadata()

    <?php
    try {
        $phar = new Phar('myphar.phar');
        var_dump($phar->hasMetadata());
        $phar->setMetadata(array('thing' => 'hi'));
        var_dump($phar->hasMetadata());
        $phar->delMetadata();
        var_dump($phar->hasMetadata());
    } catch (Exception $e) {
        // handle error
    }
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- Phar::getMetadata() - Извлечь метаданные phar-архива
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::delMetadata() - Удаляет глобальные метаданные в phar-архиве

# Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — Указывает phar перехватывать fopen, file_get_contents, opendir и все stat-функции

### Описание

final public static function Phar::interceptFileFuncs(): void

Указывает phar перехватывать fopen(), readfile(), file_get_contents(), opendir() и все stat-функции. Если какая-либо из этих функций будет вызвана из phar-архива с относительным путём, то вызов будет модифицирован для доступа к содержимому архива. В случае с абсолютными путями будут работать штатные функции доступа к файловой системе.

Эта функция позволяет писать приложения работающие не привязанные к жёсткому диску.

### Список параметров

No parameters.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования Phar::interceptFileFuncs()

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/file.php';
    ?>

Предположим, что у нас есть `/path/to/myphar.phar` и в нем содержатся файлы `file.php` и `file2.txt`. `file.php` содержит такой код:

Пример #2 Пример использования Phar::interceptFileFuncs()

    <?php
    echo file_get_contents('file2.txt');
    ?>

В обычном режиме PHP будет искать `file2.txt` в текущей директории, являющейся директорией запуска file.php, либо текущей директорией в случае использования командной строки. Phar::interceptFileFuncs() укажет PHP, что текущая директория - это `phar:///path/to/myphar.phar/` и, для примера выше, будет открыт файл `phar:///path/to/myphar.phar/file2.txt`.

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Проверить, будут ли операции с Phar-архивом буферизованы или записаны напрямую на диск

### Описание

public function Phar::isBuffering(): bool

Проверяет, будут ли операции с Phar-архивом сразу записаны на диск или для этого надо вызывать Phar::stopBuffering().

Настройки буферизации индивидуальны для каждого архива. Включённая буферизация для `foo.phar` никак не влияет на режим работы с `bar.phar`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false`.

### Примеры

Пример #1 Пример использования Phar::isBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p2 = new Phar('existingphar.phar');
    $p['file1.txt'] = 'hi';
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>
    =2=
    <?php
    $p->startBuffering();
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    $p->stopBuffering();
    ?>
    =3=
    <?php
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### Смотрите также

- Phar::startBuffering() - Запускает буферизацию операций записи, отключая запись изменений Phar-архива на диск
- Phar::stopBuffering() - Останавливает буферизацию и записывает все изменения на диск

# Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)

### Описание

public function Phar::isCompressed(): int|false

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее). Phar-архивы, основанные на zip, не могут быть сжаты целиком, поэтому этот метод всегда возвращает `false`, если он был вызван на phar-архиве, основанном на zip.

### Список параметров

Нет параметров.

### Возвращаемые значения

`Phar::GZ`, `Phar::BZ2` или `false`.

### Примеры

Пример #1 Пример использования Phar::isCompressed()

    <?php
    try {
        $phar1 = new Phar('myphar.zip.phar');
        var_dump($phar1->isCompressed());
        $phar2 = new Phar('myuncompressed.tar.phar');
        var_dump($phar2->isCompressed());
        $phar2->compress(Phar::GZ);
        var_dump($phar2->isCompressed() == Phar::GZ);
    } catch (Exception $e) {
    }
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия

# Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — Проверить, что phar-архив имеет заданный формат (tar/phar/zip)

### Описание

public function Phar::isFileFormat(int `$format`): bool

### Список параметров

`format`

  `Phar::PHAR`, `Phar::TAR` или `Phar::ZIP`, в зависимости от проверяемого формата.

### Возвращаемые значения

Возвращает `true`, если phar-архив имеет указанный формат

### Ошибки

В случае задания некорректного формата выбрасывается исключение PharException.

### Смотрите также

- Phar::convertToExecutable() - Конвертирует phar-архив в другой исполняемый формат файла
- Phar::convertToData() - Конвертирует phar-архив в неисполняемый tar- или zip-файл

# Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — Проверяет, что заданное имя файла является корректным именем phar-архива

### Описание

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

Проверяет, что заданное имя файла является корректным именем phar-архива. Можно использовать для проверки имени файла до момента его непосредственного создания, чтобы избежать нежелательных исключений.

### Список параметров

`filename`

  Имя или полный путь до файла, который ещё не создан

`executable`

  Этот параметр определяет, должен ли файл опознаваться как запускаемый phar-архив, или как незапускаемый архив с данными

### Возвращаемые значения

Возвращает `true` или `false`.

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — Проверяет, можно ли модифицировать phar-архив

### Описание

public function Phar::isWritable(): bool

Этот метод возвращает `true`, если `phar.readonly` установлен в `0`, архив существует и доступен для записи.

### Список параметров

Параметров нет.

### Возвращаемые значения

Возвращает `true`, если архив можно модифицировать

### Смотрите также

- Phar::canWrite() - Проверяет, поддерживает ли модуль phar сохранение и создание phar-архивов
- PharData::isWritable() - Проверить, можно ли модифицировать tar/zip-архив

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — Загрузить phar-архив с псевдонимом

### Описание

final public static function Phar::loadPhar(string `$filename`, ?string `$alias` = `null`): bool

Может использоваться для загрузки внешнего Phar-архива. То, что для phar-архива назначается псевдоним, позволяет в дальнейшем использовать более короткие ссылки для доступа к нему или же для загрузки архивов Phar, содержащих только данные и не предназначенных для выполнения.

### Список параметров

`filename`

  Путь к загружаемому phar-архиву

`alias`

  Псевдоним для доступа к архиву. Обратите внимание, что многие phar-архивы имеют свой явно заданный псевдоним и, при задании нового псевдонима, будет выброшено исключение PharException.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если задан параметр с псевдонимом, а загружаемый архив уже имеет псевдоним, то будет выброшено исключение PharException

### Примеры

Пример #1 Пример использования Phar::loadPhar()

Phar::loadPhar можно использовать где угодно, тогда как Phar::mapPhar только в загрузчике (stub) Phar-архива.

    <?php
    try {
        Phar::loadPhar('/path/to/phar.phar', 'my.phar');
        echo file_get_contents('phar://my.phar/file.txt');
    } catch (PharException $e) {
        echo $e;
    }
    ?>

### Смотрите также

- Phar::mapPhar() - Прочитать текущий запущенный phar-архив и зарегистрировать его манифест

# Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — Прочитать текущий запущенный phar-архив и зарегистрировать его манифест

### Описание

final public static function Phar::mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool

Этот статический метод можно использовать только в заглушке загрузчика Phar-архива в целях его инициализации, когда он запущен напрямую, либо включён в другой скрипт.

### Список параметров

`alias`

  Псевдоним можно использовать в обёртках `phar://`, ссылаясь на этот архив, вместо использования полного пути.

`offset`

  Неиспользуемая переменная. Существует только для совместимости с PEAR-пакетом PHP_Archive.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Выбрасывается исключение PharException, если вызывается из скрипта, в котором не обнаружено токена __HALT_COMPILER();, либо если файл недоступен для чтения.

### Примеры

Пример #1 Пример использования Phar::mapPhar()

Phar::mapPhar следует использовать только внутри загрузчика заглушки Phar-архива. Используйте loadPhar для загрузки внешнего phar в память.

Простой загрузчик Phar, использующий mapPhar.

    <?php
    function __autoload($class)
    {
        include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
    }
    try {
        Phar::mapPhar('me.phar');
        include 'phar://me.phar/startup.php';
    } catch (PharException $e) {
        echo $e->getMessage();
        die('Cannot initialize Phar');
    }
    __HALT_COMPILER();

### Смотрите также

- Phar::loadPhar() - Загрузить phar-архив с псевдонимом

# Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — Монтирование внешнего путь или файла к виртуальному пути в phar-архиве

### Описание

final public static function Phar::mount(string `$pharPath`, string `$externalPath`): void

Очень похоже на концепцию файловой системы unix по монтированию внешнего устройства в существующее дерево директорий. Phar::mount() позволяет ссылаться на внешние файлы и директории, как будто они находятся внутри архива. Это позволяет повысить уровень абстракции обращаясь ко внешним конфигурационным файлам так, как будто они являются частью архива.

### Список параметров

`pharPath`

  Внутренний путь в архиве, по которому необходимо примонтировать внешний путь. Это должен быть несуществующий относительный путь внутри архива.

`externalPath`

  Путь или URL внешнего файла или директории

### Возвращаемые значения

Ничего не возвращает. В случае возникновения ошибки выбрасывает исключение PharException.

### Ошибки

Выбрасывает исключение PharException при возникновении ошибок.

### Примеры

Пример #1 Пример использования Phar::mount()

В следующем примере демонстрируется доступ к внешнему конфигурационному файлу, как будто он находится внутри архива.

Для начала код, содержащийся в архиве:

    <?php
    $configuration = simplexml_load_string(file_get_contents(
        Phar::running(false) . '/config.xml'));
    ?>

Далее внешний код, монтирующий файл в архив:

    <?php
    // для начала настроим ассоциацию между абстрактным config.xml
    // и конкретным файлом на диске
    Phar::mount('phar://config.xml', '/home/example/config.xml');
    // а теперь запускаем приложение
    include '/path/to/archive.phar';
    ?>

Другой метод - поместить монтирующий код в заглушку (stub) Phar-архива. Пример использования конфигурационного файла по умолчанию, если пользовательский файл конфигурации не задан:

    <?php
    // для начала настроим связь между абстрактным config.xml
    // и конкретным файлом на диске
    if (defined('EXTERNAL_CONFIG')) {
        Phar::mount('config.xml', EXTERNAL_CONFIG);
        if (file_exists(__DIR__ . '/extra_config.xml')) {
            Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
        }
    } else {
        Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
        Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
    }
    // а теперь запускаем приложение
    include 'phar://' . __FILE__ . '/index.php';
    __HALT_COMPILER();
    ?>

... и код для загрузки этого phar-архива:

    <?php
    define('EXTERNAL_CONFIG', '/home/example/config.xml');
    // а теперь запускаем приложение
    include '/path/to/archive.phar';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — Определить список до четырёх $_SERVER-переменных, которые должны быть изменены для запуска

### Описание

final public static function Phar::mungServer(array `$variables`): void

Функция Phar::mungServer() должна вызываться только в загрузчике.

Определяет список до четырёх $_SERVER-переменных, которые необходимо модифицировать для запуска. Модификация заключается в удалении следов запуска из phar-архива для переменных `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` и `SCRIPT_FILENAME`.

Сам по себе этот метод ничего не делает. Эффект достигается только в комбинации с Phar::webPhar() и только если запрошенный файл является PHP-файлом для разбора. Обратите внимание, что переменные `PATH_INFO` и `PATH_TRANSLATED` всегда модифицированы.

Оригинальные значения изменяемых переменных будут сохранены в массиве SERVER с префиксами `PHAR_`. Например, оригинальное значение `SCRIPT_NAME` будет записано в `PHAR_SCRIPT_NAME`.

### Список параметров

`variables`

  Массив любой из строк: `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` и `SCRIPT_FILENAME`. Любые другие значения вызовут исключение. Обратите внимание, что функция Phar::mungServer() чувствительна к регистру символов.

### Возвращаемые значения

Ничего не возвращает.

### Ошибки

Выбрасывает исключение UnexpectedValueException, если входные данные некорректны.

### Примеры

Пример #1 Пример использования Phar::mungServer()

    <?php
    // пример загрузчика
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### Смотрите также

- Phar::webPhar() - Направляет запрос из браузера во внутренний файл в phar-архиве
- Phar::setStub() - Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP

# Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — Определить, есть ли файл в архиве

### Описание

public function Phar::offsetExists(string `$localName`): bool

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым Phar-архива в стиле доступа к элементам массива.

offsetExists() запускается каждый раз, когда вызывается isset().

### Список параметров

`localName`

  Имя файла (относительный путь).

### Возвращаемые значения

Возвращает `true`, если файл присутствует в архиве и `false` в противном случае.

### Примеры

Пример #1 Пример использования Phar::offsetExists()

    <?php
    $p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
    $p['firstfile.txt'] = 'первый файл';
    $p['secondfile.txt'] = 'второй файл';
    // в следующих строках offsetExists() вызывается косвенно
    var_dump(isset($p['firstfile.txt']));
    var_dump(isset($p['nothere.txt']));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

### Смотрите также

- Phar::offsetGet() - Получить объект PharFileInfo для конкретного файла
- Phar::offsetSet() - Изменение содержимого файла
- Phar::offsetUnset() - Удалить файл из phar-архива

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — Получить объект PharFileInfo для конкретного файла

### Описание

public function Phar::offsetGet(string `$localName`): SplFileInfo

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым Phar-архива в стиле доступа к элементам массива. Phar::offsetGet() используется для извлечения файлов из архива.

### Список параметров

`localName`

  Имя файла (относительный путь).

### Возвращаемые значения

Объект класса PharFileInfo. Можно использовать для получения информации о файле и для извлечения контента через итерирование.

### Ошибки

Выбрасывает исключение BadMethodCallException, если такого файла нет.

### Примеры

Пример #1 Пример использования Phar::offsetGet()

Как и для любого другого класса, реализующего ArrayAccess, метод Phar::offsetGet() будет вызван автоматически при использовании оператора `[]`.

    <?php
    $p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
    $p['exists.txt'] = "file exists\n";
    try {
        // автоматический вызов offsetGet()
        echo $p['exists.txt'];
        echo $p['doesnotexist.txt'];
    } catch (BadMethodCallException $e) {
        echo $e;
    }
    ?>

Результат выполнения приведённого примера:

    file exists
    Entry doesnotexist.txt does not exist

### Смотрите также

- Phar::offsetExists() - Определить, есть ли файл в архиве
- Phar::offsetSet() - Изменение содержимого файла
- Phar::offsetUnset() - Удалить файл из phar-архива

# Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — Изменение содержимого файла

### Описание

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым Phar-архива в стиле доступа к элементам массива. offsetSet используется для изменения контента существующего файла, либо для создания нового.

### Список параметров

`localName`

  Имя файла (относительный путь).

`value`

  Содержимое файла.

### Возвращаемые значения

Ничего не возвращает.

### Ошибки

Если опция phar.readonly установлен в `1`, то будет выброшено исключение BadMethodCallException, так как модифицировать Phar-архив можно только, если phar.readonly равен `0`. Если возникнут какие либо проблемы с записью на диск - выбрасывается исключение PharException.

### Примеры

Пример #1 Пример использования Phar::offsetSet()

offsetSet не нужно вызывать напрямую. Используйте синтаксис `[]`.

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    try {
        // вызов offsetSet
        $p['file.txt'] = 'Hi there';
    } catch (Exception $e) {
        echo 'Не могу изменить file.txt:', $e;
    }
    ?>

### Примечания

> Замечание: Phar::addFile(), Phar::addFromString() и Phar::offsetSet() сохраняет новый phar-архив каждый раз при их вызове. Если производительность вызывает беспокойство, вместо этого следует использовать Phar::buildFromDirectory() или Phar::buildFromIterator().

### Смотрите также

- Phar::offsetExists() - Определить, есть ли файл в архиве
- Phar::offsetGet() - Получить объект PharFileInfo для конкретного файла
- Phar::offsetUnset() - Удалить файл из phar-архива

# Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — Удалить файл из phar-архива

### Описание

public function Phar::offsetUnset(string `$localName`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым Phar-архива в стиле доступа к элементам массива. offsetUnset используется для удаления файлов и запускается каждый раз, когда используется конструкция unset().

### Список параметров

`localName`

  Имя файла (относительный путь).

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Если опция phar.readonly установлен в `1`, то будет выброшено исключение BadMethodCallException, так как модифицировать Phar-архив можно только, если phar.readonly равен `0`. Если возникнут какие-либо проблемы с записью на диск - выбрасывается исключение PharException.

### Примеры

Пример #1 Пример использования Phar::offsetUnset()

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    try {
        // удаляет file.txt из my.phar путём вызова offsetUnset
        unset($p['file.txt']);
    } catch (Exception $e) {
        echo 'Не удалось удалить file.txt: ', $e;
    }
    ?>

### Смотрите также

- Phar::offsetExists() - Определить, есть ли файл в архиве
- Phar::offsetGet() - Получить объект PharFileInfo для конкретного файла
- Phar::offsetSet() - Изменение содержимого файла
- Phar::unlinkArchive() - Удаляет архив из памяти и с диска
- Phar::delete() - Удаляет файл в phar-архиве

# Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — Получить полный путь на диске, либо полный URL запущенного Phar-архива

### Описание

final public static function Phar::running(bool `$returnPhar` = `true`): string

Возвращает полный путь запущенного phar-архива. Используется для того же, для чего используется константа `__FILE__` и работает только внутри запущенного phar-архива.

При запуске Phar::running() из загрузчика результат будет `""`. Внутри загрузчика используйте константу `__FILE__`.

### Список параметров

`returnPhar`

  Если `false`, то будет возвращён полный дисковый путь к phar-архиву. Если `true`, то будет возвращён полный URL.

### Возвращаемые значения

Вернёт путь, если он корректен, либо пустую строку.

### Примеры

Пример #1 Пример использования Phar::running()

Для следующего примера предположим, что архив находится по пути `/path/to/phar/my.phar`.

    <?php
    $a = Phar::running(); // $a равно "phar:///path/to/my.phar"
    $b = Phar::running(false); // $b равно "/path/to/my.phar"
    ?>

# Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Установить псевдоним для Phar-архива

### Описание

public function Phar::setAlias(string `$alias`): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Устанавливает псевдоним для Phar-архива и записывает его как постоянный псевдоним для этого архива. Псевдоним можно использовать внутри phar-архива для уверенности в том, что доступ через потоковую обёртку `phar` для доступа к внутренним файлам будет работать всегда, независимо от местоположения phar-архива на файловой системе. Другой альтернативой является надежда на перехват include или использование Phar::interceptFileFuncs() совместно с относительными путями.

### Список параметров

`alias`

  Короткое имя, которое можно будет использовать с доступом через потоковую обёртку `phar`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Выбрасывает исключение UnexpectedValueException, если доступ запрещён и PharException, если псевдоним уже используется, или возникли проблемы с записью на диск.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод Phar::setAlias() теперь возвращает предварительное значение true.

### Примеры

Пример #1 Пример использования Phar::setAlias()

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setAlias('myp.phar');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::__construct() - Создаёт объект Phar-архива
- Phar::interceptFileFuncs() - Указывает phar перехватывать fopen, file_get_contents, opendir и все stat-функции

# Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Установить загрузчик PHP или начальную заглушку Phar-архива в загрузчик по умолчанию

### Описание

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Этот метод комбинирует функциональность двух других методов, Phar::createDefaultStub() и Phar::setStub().

### Список параметров

`index`

  Относительный путь в phar-архиве для запуска при доступе из командной строки

`webIndex`

  Относительный путь в phar-архиве для запуска при доступе из веб-браузера

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Будет выброшено исключение UnexpectedValueException, если phar.readonly разрешено в php.ini. В случае проблем с записью на диск будет выброшено исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод Phar::setDefaultStub() теперь возвращает предварительное значение true.
8.0.0 | `webIndex` теперь допускает значение null.

### Примеры

Пример #1 Пример использования Phar::setDefaultStub()

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setDefaultStub('cli.php', 'web/index.php');
        // это аналогично такому коду:
        // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::setStub() - Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP
- Phar::createDefaultStub() - Создать заглушку в формате phar-архива

# Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — Установить метаданные phar-архива

### Описание

public function Phar::setMetadata(mixed `$metadata`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Функция Phar::setMetadata() используется для сохранения данных, характеризующих phar-архив в целом. PharFileInfo::setMetadata() используется для установки метаданных для конкретного файла. Если метаданных будет много, то это может снизить скорость загрузки phar-архива.

Метаданные можно использовать, например, для указания, какой файл должен исполняться при загрузке, или для указания местоположения манифеста, типа package.xml для модуля » PEAR. В общем, любые полезные в контексте phar-архива данные.

### Список параметров

`metadata`

  Любая переменная PHP, содержащая необходимую информацию

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования Phar::setMetadata()

    <?php
    // удалим, на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "привет"';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Не могу создать/изменить phar:', $e;
    }
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Смотрите также

- Phar::getMetadata() - Извлечь метаданные phar-архива
- Phar::delMetadata() - Удаляет глобальные метаданные в phar-архиве
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные

# Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его

### Описание

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Устанавливает алгоритм подписания phar-архива и применяет его. Доступны следующие алгоритмы подписания: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` и `Phar::OPENSSL`.

Обратите внимание, что для всех исполняемых phar-архивов подпись создаётся автоматически, с использованием по умолчанию `SHA1`. Архивы с данными на основе tar или zip (созданные с помощью класса PharData) должны иметь явно созданную с помощью Phar::setSignatureAlgorithm() подпись.

### Список параметров

`algo`

  Одна из констант: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` или `Phar::OPENSSL`

`privateKey`

  Секретный ключ OpenSSL, извлечённый из сертификата, либо файл с ключом OpenSSL:

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  Подробности об именовании и размещении файла открытого ключа смотрите в разделе Введение в phar.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает исключение UnexpectedValueException при любых ошибках, кроме ошибок записи на диск. При ошибках записи на диск выбрасывает исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `privateKey` теперь допускает значение null.

### Смотрите также

- Phar::getSupportedSignatures() - Получить массив поддерживаемых алгоритмов подписи архива
- Phar::getSignature() - Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP

### Описание

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Метод устанавливает заглушку — начальный загрузчик — в Phar-архив: в новый архив добавляет, а в текущем — заменяет.

Загрузочная заглушка срабатывает при каждом включении Phar-архива:

    <?php

    include 'myphar.phar';

и при выполнении из командной строки:

    php myphar.phar

При включении файла через потоковую обёртку `phar` загрузчик не запускается:

    <?php

    include 'phar://myphar.phar/somefile.php';

### Список параметров

`stub`

  Строка или дескриптор открытого потока; при включении архива код заглушки выполняется как начальный загрузчик.

`length`
  Количество байтов, которое требуется прочитать из потока; параметр учитывается, только если в аргументе `stub` передали ресурс.
  Внимание

  С PHP 8.3.0 вызов метода с ресурсом (resource) в первом аргументе УСТАРЕЛ, поэтому вместо передачи ресурса и аргумента `length` теперь вызывают: `$phar->setStub(stream_get_contents($resource))`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

При вызове метода с включённой в файле php.ini директивой phar.readonly выбрасывается исключение UnexpectedValueException. При ошибке сброса изменений на диск выбрасывается исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.
8.3.0 | Вызов метода Phar::setStub() с ресурсом (resource) в первом аргументе УСТАРЕЛ. Вместо передачи ресурса и аргумента `length` теперь вызывают: `$phar->setStub(stream_get_contents($resource));`.

### Примеры

Пример #1 Пример установки начальной загрузочной заглушки методом Phar::setStub()

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');

        $p['a.php'] = '<?php var_dump("Привет,");';
        $p->setStub('<?php var_dump("Первый загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump(" мир!");';
        $p->setStub('<?php var_dump("Второй загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'При записи операций в архив brandnewphar.phar возникла ошибка: ', $e;
    }

Результат выполнения приведённого примера:

    string(13) "Привет,"
    string(108) "<?php var_dump("Первый загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
    string(8) " мир!"
    string(108) "<?php var_dump("Второй загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

### Смотрите также

- Phar::getStub() - Получить загрузчик PHP или загрузчик заглушки Phar-архива
- Phar::createDefaultStub() - Создать заглушку в формате phar-архива

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Запускает буферизацию операций записи, отключая запись изменений Phar-архива на диск

### Описание

public function Phar::startBuffering(): void

Метод Phar::startBuffering() может дать значительный прирост производительности при создании, либо модификации phar-архива с большим количеством файлов. Обычно, когда добавляется новый файл, либо изменяется существующий, запускается операция пересоздания phar-архива. С включённой буферизацией архив будет пересоздан один раз в самом конце внесения изменений.

Эта концепция работает аналогично транзакции в базе данных, что позволяет сделать вне необходимые изменения и применить их одновременно, в рамках одной операции. Такое поведение обеспечивает пара методов Phar::startBuffering()/Phar::stopBuffering().

Настройки буферизации индивидуальны для каждого архива. Включённая буферизация для `foo.phar` никак не влияет на режим работы с `bar.phar`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования Phar::startBuffering()

    <?php
    // удалим на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'не могу создать phar:', $e;
    }
    echo 'В новом phar содержится ' . $p->count() . " записей\n";
    $p->startBuffering();
    $p['file.txt'] = 'hi';
    $p['file2.txt'] = 'there';
    $p['file2.txt']->setCompressedGZ();
    $p['file3.txt'] = 'babyface';
    $p['file3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### Смотрите также

- Phar::stopBuffering() - Останавливает буферизацию и записывает все изменения на диск
- Phar::isBuffering() - Проверить, будут ли операции с Phar-архивом буферизованы или записаны напрямую на диск

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Останавливает буферизацию и записывает все изменения на диск

### Описание

public function Phar::stopBuffering(): void

Метод Phar::stopBuffering() используется совместно с методом Phar::startBuffering(). Phar::startBuffering() может дать значительный прирост производительности при создании, либо модификации phar-архива с большим количеством файлов. Обычно, когда добавляется новый файл, либо изменяется существующий, запускается операция пересоздания phar-архива. С включённой буферизацией архив будет пересоздан один раз в самом конце внесения изменений.

Эта концепция работает аналогично транзакции в базе данных, что позволяет сделать вне необходимые изменения и применить их одновременно, в рамках одной операции. Такое поведение обеспечивает пара методов Phar::startBuffering()/Phar::stopBuffering().

Настройки буферизации индивидуальны для каждого архива. Включённая буферизация для `foo.phar` никак не влияет на режим работы с `bar.phar`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

В случае проблем с записью на диск будет выброшено исключение PharException.

### Примеры

Пример #1 Пример использования Phar::stopBuffering()

    <?php
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file1.txt'] = 'hi';
    $p->startBuffering();
    var_dump($p->getStub());
    $p->setStub("<?php
    function __autoload(\$class)
    {
        include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
    }
    Phar::mapPhar('brandnewphar.phar');
    include 'phar://brandnewphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    var_dump($p->getStub());
    ?>

Результат выполнения приведённого примера:

    string(24) "<?php __HALT_COMPILER();"
    string(195) "<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('brandnewphar.phar');
    include 'phar://brandnewphar.phar/startup.php';
    __HALT_COMPILER();"

### Смотрите также

- Phar::startBuffering() - Запускает буферизацию операций записи, отключая запись изменений Phar-архива на диск
- Phar::isBuffering() - Проверить, будут ли операции с Phar-архивом буферизованы или записаны напрямую на диск

# Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — Удаляет архив из памяти и с диска

### Описание

final public static function Phar::unlinkArchive(string `$filename`): true

Метод удаляет архив из памяти и с диска.

### Список параметров

`filename`

  Путь к архиву в файловой системе.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение PharException, если в коде остаются открытые файловые указатели на phar-архив или объекты Phar, PharData, PharFileInfo, которые ссылаются на этот архив.

### Примеры

Пример #1 Пример удаления архива из памяти и с диска методом Phar::unlinkArchive()

    <?php

    // Простой пример удаления архивного файла
    Phar::unlinkArchive('/path/to/my.phar');

    // Более распространённый пример
    $p = new Phar('my.phar');

    $fp = fopen('phar://my.phar/file.txt', 'r');

    // Создаём архив 'my.phar.gz'
    $gp = $p->compress(Phar::GZ);

    // Удаляем ссылки на архив
    unset($p);
    fclose($fp);

    // Удаляем следы существования архива
    Phar::unlinkArchive('my.phar');

    ?>

### Смотрите также

- Phar::delete() - Удаляет файл в phar-архиве
- Phar::offsetUnset() - Удалить файл из phar-архива

# Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — Направляет запрос из браузера во внутренний файл в phar-архиве

### Описание

final public static function Phar::webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void

Phar::webPhar() служит Phar::mapPhar() для веб-архивов phar. Метод анализирует $_SERVER['REQUEST_URI'] и направляет запрос из браузера во внутренний файл в phar-архиве. Он имитирует веб-сервер, направляет запросы к нужному файлу, отображает правильные заголовки и анализирует файлы PHP по мере необходимости. В сочетании с Phar::mungServer() и Phar::interceptFileFuncs(), любое веб-приложение можно использовать без изменений из phar-архива.

Phar::webPhar() должен вызываться только из заглушки (stub) phar-архива (о том, что такое заглушка и как с ним работать, читайте тут).

### Список параметров

`alias`

  Псевдоним для использования в обёртках `phar://`.

`index`

  Местоположение в phar-архиве индексного файла.

`fileNotFoundScript`

  Местоположение скрипта, отвечающего за обработку ошибки HTTP 404. Скрипт должен возвращать корректные заголовки для этой ошибки.

`mimeTypes`

  Массив сопоставления расширений файлов типам MIME. Если достаточно сопоставления по умолчанию, то передайте сюда пустой массив. По умолчанию используются такие сопоставления:

      <?php
      $mimes = array(
          'phps' => Phar::PHPS, // передаётся в highlight_file()
          'c' => 'text/plain',
          'cc' => 'text/plain',
          'cpp' => 'text/plain',
          'c++' => 'text/plain',
          'dtd' => 'text/plain',
          'h' => 'text/plain',
          'log' => 'text/plain',
          'rng' => 'text/plain',
          'txt' => 'text/plain',
          'xsd' => 'text/plain',
          'php' => Phar::PHP, // разбирается как PHP
          'inc' => Phar::PHP, // разбирается как PHP
          'avi' => 'video/avi',
          'bmp' => 'image/bmp',
          'css' => 'text/css',
          'gif' => 'image/gif',
          'htm' => 'text/html',
          'html' => 'text/html',
          'htmls' => 'text/html',
          'ico' => 'image/x-ico',
          'jpe' => 'image/jpeg',
          'jpg' => 'image/jpeg',
          'jpeg' => 'image/jpeg',
          'js' => 'application/x-javascript',
          'midi' => 'audio/midi',
          'mid' => 'audio/midi',
          'mod' => 'audio/mod',
          'mov' => 'movie/quicktime',
          'mp3' => 'audio/mp3',
          'mpg' => 'video/mpeg',
          'mpeg' => 'video/mpeg',
          'pdf' => 'application/pdf',
          'png' => 'image/png',
          'swf' => 'application/shockwave-flash',
          'tif' => 'image/tiff',
          'tiff' => 'image/tiff',
          'wav' => 'audio/wav',
          'xbm' => 'image/xbm',
          'xml' => 'text/xml',
      );
      ?>

`rewrite`

  Функция перезаписи, которой передаётся единственный строковый параметр и которая должна также вернуть строку, либо `false`.

  Если вы используете fast-cgi или cgi, то параметром, передаваемым в эту функцию будет значение переменной $_SERVER['PATH_INFO']. В ином случае передаваться будет значение переменной $_SERVER['REQUEST_URI'].

  Если будет возвращена строка, то она будет использована как путь к файлу внутри архива. Если вернётся `false`, то webPhar() пошлёт код ошибки HTTP 403.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбросит исключение PharException, если будет невозможно открыть какой-либо файл, либо если вызывать её не из заглушки. Если в параметре `mimeTypes` указать некорректный MIME-тип, или в `rewrite` будет передана некорректная функция обратного вызова, то будет выброшено исключение UnexpectedValueException.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `fileNotFoundScript` и `rewrite` теперь допускают значение `null`.

### Примеры

Пример #1 Пример использования Phar::webPhar()

В примере ниже, созданный phar отобразит `Hello World` при обращении из браузера к `/myphar.phar/index.php` или к `/myphar.phar`, и отобразит исходный код `index.phps` при обращении к `/myphar.phar/index.phps`.

    <?php
    // создаём архив:
    try {
        $phar = new Phar('myphar.phar');
        $phar['index.php'] = '<?php echo "Hello World"; ?>';
        $phar['index.phps'] = '<?php echo "Hello World"; ?>';
        $phar->setStub('<?php
    Phar::webPhar();
    __HALT_COMPILER(); ?>');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::mungServer() - Определить список до четырёх $_SERVER-переменных, которые должны быть изменены для запуска
- Phar::interceptFileFuncs() - Указывает phar перехватывать fopen, file_get_contents, opendir и все stat-функции

## Содержание

- Phar::addEmptyDir — Добавляет в phar-архив пустую директорию
- Phar::addFile — Добавляет в phar-архив файл из файловой системы
- Phar::addFromString — Добавляет в phar-архив файл из строки
- Phar::apiVersion — Возвращает версию API
- Phar::buildFromDirectory — Создаёт phar-архив из файлов, расположенных внутри директории
- Phar::buildFromIterator — Создаёт phar-архив из итератора
- Phar::canCompress — Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::canWrite — Проверяет, поддерживает ли модуль phar сохранение и создание phar-архивов
- Phar::compress — Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::compressFiles — Сжимает все файлы в текущем Phar-архиве
- Phar::__construct — Создаёт объект Phar-архива
- Phar::convertToData — Конвертирует phar-архив в неисполняемый tar- или zip-файл
- Phar::convertToExecutable — Конвертирует phar-архив в другой исполняемый формат файла
- Phar::copy — Копирует файл внутри phar-архива в новый файл внутри phar-архива
- Phar::count — Возвращает количество записей (файлов) в Phar-архиве
- Phar::createDefaultStub — Создать заглушку в формате phar-архива
- Phar::decompress — Распаковывает весь Phar-архив
- Phar::decompressFiles — Распаковывает все файлы в текущем Phar-архиве
- Phar::delMetadata — Удаляет глобальные метаданные в phar-архиве
- Phar::delete — Удаляет файл в phar-архиве
- Phar::__destruct — Уничтожает объект архива Phar
- Phar::extractTo — Извлечь содержимое phar-архива в директорию
- Phar::getAlias — Получить псевдоним для Phar
- Phar::getMetadata — Извлечь метаданные phar-архива
- Phar::getModified — Определить, изменялся phar-архив
- Phar::getPath — Получить реальный путь к Phar-архиву на диске
- Phar::getSignature — Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива
- Phar::getStub — Получить загрузчик PHP или загрузчик заглушки Phar-архива
- Phar::getSupportedCompression — Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::getSupportedSignatures — Получить массив поддерживаемых алгоритмов подписи архива
- Phar::getVersion — Получить версию Phar-архива
- Phar::hasMetadata — Проверить, содержит ли phar-архив глобальные метаданные
- Phar::interceptFileFuncs — Указывает phar перехватывать fopen, file_get_contents, opendir и все stat-функции
- Phar::isBuffering — Проверить, будут ли операции с Phar-архивом буферизованы или записаны напрямую на диск
- Phar::isCompressed — Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::isFileFormat — Проверить, что phar-архив имеет заданный формат (tar/phar/zip)
- Phar::isValidPharFilename — Проверяет, что заданное имя файла является корректным именем phar-архива
- Phar::isWritable — Проверяет, можно ли модифицировать phar-архив
- Phar::loadPhar — Загрузить phar-архив с псевдонимом
- Phar::mapPhar — Прочитать текущий запущенный phar-архив и зарегистрировать его манифест
- Phar::mount — Монтирование внешнего путь или файла к виртуальному пути в phar-архиве
- Phar::mungServer — Определить список до четырёх $_SERVER-переменных, которые должны быть изменены для запуска
- Phar::offsetExists — Определить, есть ли файл в архиве
- Phar::offsetGet — Получить объект PharFileInfo для конкретного файла
- Phar::offsetSet — Изменение содержимого файла
- Phar::offsetUnset — Удалить файл из phar-архива
- Phar::running — Получить полный путь на диске, либо полный URL запущенного Phar-архива
- Phar::setAlias — Установить псевдоним для Phar-архива
- Phar::setDefaultStub — Установить загрузчик PHP или начальную заглушку Phar-архива в загрузчик по умолчанию
- Phar::setMetadata — Установить метаданные phar-архива
- Phar::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его
- Phar::setStub — Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP
- Phar::startBuffering — Запускает буферизацию операций записи, отключая запись изменений Phar-архива на диск
- Phar::stopBuffering — Останавливает буферизацию и записывает все изменения на диск
- Phar::unlinkArchive — Удаляет архив из памяти и с диска
- Phar::webPhar — Направляет запрос из браузера во внутренний файл в phar-архиве

# Класс PharData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

## Введение

Класс PharData предоставляет высокоуровневый интерфейс доступа и создания неисполняемых tar- и zip-архивов. Поскольку архивы этих типов не содержат заглушку и не могут быть выполнены модулем Phar, есть возможность создавать и обрабатывать обычные zip- и tar-файлы, используя класс PharData, даже если параметр `phar.readonly` в php.ini равен `1`.

## Обзор класса

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Наследуемые константы */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Методы */
public function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* Наследуемые методы */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — Добавить пустую директорию в tar/zip-архив

### Описание

public function PharData::addEmptyDir(string `$directory`): void

С помощью этого места можно создать директорию по пути `dirname`. Этот метод аналогичен ZipArchive::addEmptyDir().

### Список параметров

`directory`

  Путь создаваемой директории

### Возвращаемые значения

Ничего не возвращает. В случае ошибок выбрасывает исключение.

### Примеры

Пример #1 Пример использования PharData::addEmptyDir()

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addEmptyDir('/full/path/to/file');
        // показывает, как хранится файл
        $b = $a['full/path/to/file']->isDir();
    } catch (Exception $e) {
        // обрабатываем ошибки
    }
    ?>

### Смотрите также

- Phar::addEmptyDir() - Добавляет в phar-архив пустую директорию
- PharData::addFile() - Добавить существующие файлы к tar/zip-архиву
- PharData::addFromString() - Добавляет файл из строки в архив tar/zip

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — Добавить существующие файлы к tar/zip-архиву

### Описание

public function PharData::addFile(string `$filename`, ?string `$localName` = `null`): void

С помощью этого метода можно добавить к архиву любые файлы или URL. Если задан опциональный параметр `localname`, то файл будет добавлен в архив с указанным именем, иначе будет использовано оригинальное имя из параметра `file`. Для URL локальное имя должно быть указано в обязательном порядке, иначе будет выброшено исключение. Метод аналогичен ZipArchive::addFile().

### Список параметров

`filename`

  Полный или относительный путь до файла на диске.

`localName`

  Путь, по которому файл необходимо добавить в архив.

### Возвращаемые значения

Ничего не возвращает, а в случае возникновения ошибки выбрасывает исключение.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `localName` теперь допускает значение null.

### Примеры

Пример #1 Пример использования PharData::addFile()

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addFile('/full/path/to/file');
        // добавление файла
        $b = $a['full/path/to/file']->getContent();

        $a->addFile('/full/path/to/file', 'my/file.txt');
        $c = $a['my/file.txt']->getContent();

        // добавление URL
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Примечания

> Замечание: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### Смотрите также

- PharData::offsetSet() - Изменение содержимого файла
- Phar::addFile() - Добавляет в phar-архив файл из файловой системы
- PharData::addFromString() - Добавляет файл из строки в архив tar/zip
- PharData::addEmptyDir() - Добавить пустую директорию в tar/zip-архив

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — Добавляет файл из строки в архив tar/zip

### Описание

public function PharData::addFromString(string `$localName`, string `$contents`): void

Этот метод позволяет создать внутри архива файл с заданным текстом. Файл будет сохранён по пути `localname`. Этот метод аналогичен ZipArchive::addFromString().

### Список параметров

`localName`

  Путь создаваемого файла.

`contents`

  Содержимое файла в виде строки

### Возвращаемые значения

Ничего не возвращает, в случае возникновения ошибки выбрасывает исключение.

### Примеры

Пример #1 Пример использования PharData::addFromString()

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addFromString('path/to/file.txt', 'my simple file');
        $b = $a['path/to/file.txt']->getContent();

        // Для добавления содержимого через потоковую обёртку для больших файлов, используйте offsetSet()
        $c = fopen('/path/to/hugefile.bin');
        $a['largefile.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Примечания

> Замечание: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### Смотрите также

- PharData::offsetSet() - Изменение содержимого файла
- Phar::addFromString() - Добавляет в phar-архив файл из строки
- PharData::addFile() - Добавить существующие файлы к tar/zip-архиву
- PharData::addEmptyDir() - Добавить пустую директорию в tar/zip-архив

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — Создаёт tar/zip-архив из файлов в директории

### Описание

public function PharData::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

Наполняет tar/zip-архив содержимым директории. Второй опциональный параметр является регулярным выражением (pcre). Файлы, имена которых подходят под регулярное выражение, будут включены в архив, а все остальные нет. Если при создании архива нужна большая избирательность, то используйте метод PharData::buildFromIterator().

### Список параметров

`directory`

  Полный или относительный путь до директории, файлы из которой будут добавлены в архив.

`pattern`

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

### Возвращаемые значения

Phar::buildFromDirectory() возвращает ассоциативный массив, связывающий путь к файлу внутри архива с полным путём к файлу на диске или `false`, если возникла ошибка.

### Ошибки

Выбрасывает исключение BadMethodCallException, если не удаётся инициализировать внутренние итераторы директории. Исключение PharException выбрасывается при ошибках записи на диск.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | PharData::buildFromDirectory() больше не возвращает значение `false`.

### Примеры

Пример #1 Пример использования PharData::buildFromDirectory()

    <?php
    $phar = new PharData('project.tar');
    // добавим все файлы в проект
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');

    $phar2 = new PharData('project2.zip');
    // добавим в проект только .php файлы
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    ?>

### Смотрите также

- Phar::buildFromDirectory() - Создаёт phar-архив из файлов, расположенных внутри директории
- PharData::buildFromIterator() - Создание tar/zip-архива с помощью итератора

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — Создание tar/zip-архива с помощью итератора

### Описание

public function PharData::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

Наполнение архив tar или zip с помощью итератора. Поддерживаются два типа итераторов: итератор, связывающий файл на диске с файлом внутри архива и итератор в стиле DirectoryIterator, который возвращает объекты SplFileInfo. Для итераторов, возвращающих объекты SplFileInfo, второй параметр является обязательным.

### Список параметров

`iterator`

  Итератор, предоставляющий связки ключ=>значение, либо объекты SplFileInfo

`baseDirectory`

  Для итераторов, возвращающих объекты SplFileInfo, часть полного пути добавляемых файлов, которая будет удаляться из полного пути внутри архива.

### Возвращаемые значения

PharData::buildFromIterator() возвращает ассоциативный массив, связывающий путь к файлу внутри архива с полным путём к файлу на диске.

### Ошибки

Метод выбрасывает исключение UnexpectedValueException, если итератор вернул некорректное значение, например целочисленный ключ вместо строки. Исключение BadMethodCallException выбрасывается когда задан итератор, возвращающий объекты SplFileInfo без задания параметра `baseDirectory`. В случае проблем с записью на диск бросается исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | PharData::buildFromIterator() больше не возвращает значение `false`.
8.0.0 | `baseDirectory` теперь допускает значение null.

### Примеры

Пример #1 Пример использования PharData::buildFromIterator() с SplFileInfo

Для большинства tar/zip-архивов, структура отражает имеющееся дерево директорий на файловой системе. К примеру, для создания tar/zip-архива, содержащего следующую структуру директорий и файлов:

    /path/to/project/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

Нужно использовать такой код, для создания архива "project.tar":

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/path/to/project')),
        '/path/to/project');
    ?>

Файл `project.tar` можно использовать сразу же после его создания. PharData::buildFromIterator() не производит настройки сжатия или добавления метаданных. Эти действия необходимо произвести самостоятельно, после создания архива.

Интересное замечание: PharData::buildFromIterator() также можно использовать для копирования контента уже существующего phar, tar или zip-архива, так как объект PharData наследует от DirectoryIterator:

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/path/to/anotherphar.phar')),
        'phar:///path/to/anotherphar.phar/path/to/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Пример #2 Пример использования PharData::buildFromIterator() с другим итератором

Можно использовать итераторы, возвращающие связку "ключ" => "значение", например ArrayIterator:

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'internal/file.php' => dirname(__FILE__) . '/somefile.php',
            'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
         )));
    ?>

### Смотрите также

- Phar::buildFromIterator() - Создаёт phar-архив из итератора

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2

### Описание

public function PharData::compress(int `$compression`, ?string `$extension` = `null`): ?PharData

Для tar-архивов, этот метод произведёт сжатие всего архива с помощью gzip или bzip2. Результирующий файл можно распаковать с помощью команд gunzip или bunzip, либо использовать напрямую через модуль Phar.

Для zip-архивов этот метод выбросит исключение. Для gzip-сжатия должен быть доступен модуль zlib. Для bzip2-сжатия должен быть доступен модуль bzip2.

Этот метод переименовывает архив, добавляя к его имени расширение `.gz`, `.bz2` или наоборот, убирающее его, если параметр типа сжатия задан как `Phar::NONE`. Также можно явно указать, какое расширение будет иметь файл.

### Список параметров

`compression`

  Одна из констант: `Phar::GZ`, `Phar::BZ2`, или `Phar::NONE` для отключения компрессии.

`extension`

  По умолчанию файлу назначится расширение `.tar.gz` или `.tar.bz2` для сжатия и `.tar`, если сжатие отключено.

### Возвращаемые значения

Возвращает объект PharData в случае успешного выполнения или `null` в случае возникновения ошибки.

### Ошибки

Выбрасывает исключение BadMethodCallException, если недоступен модуль zlib или выключен модуль bzip2.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `extension` теперь допускает значение null.

### Примеры

Пример #1 Пример использования PharData::compress()

    <?php
    $p = new PharData('/path/to/my.tar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p1 = $p->compress(Phar::GZ); // copies to /path/to/my.tar.gz
    $p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.tar.bz2
    $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.tar already exists
    ?>

### Смотрите также

- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — Сжать все файлы в текущем tar/zip-архиве

### Описание

public function PharData::compressFiles(int `$compression`): void

Для tar-архивов данный метод выбросит исключение BadMethodCallException, так как сжатие отдельных файлов в tar-архиве не поддерживается форматом файла. Используйте PharData::compress() для сжатия всего tar-архива.

Для Zip-архивов этот метод сожмёт все файлы используя заданный тип сжатия. Для корректной работы требуются включённые модули zlib или bzip2, в зависимости от типа сжатия. Также, если некоторые файлы уже были сжаты, то необходимо, чтобы соответствующий модуль был включён, иначе не удастся обработать.

### Список параметров

`compression`

  Одна из констант: `Phar::GZ`, `Phar::BZ2` или `Phar::NONE`, для отмены сжатия.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает исключение BadMethodCallException если выключена INI-опция phar.readonly, если отсутствует необходимый модуль zlib или bzip2.

### Примеры

Пример #1 Пример использования PharData::compressFiles()

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Результат выполнения приведённого примера:

    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- PharData::decompressFiles() - Распаковывает все файлы в текущем zip-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- PharData::decompress() - Распаковать весь Phar-архив

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — Конструктор объекта PharData

### Описание

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### Список параметров

`filename`

  Путь либо к существующему tar/zip-архиву, либо к вновь создаваемому

`flags`

  Флаги для передачи родительскому классу Phar RecursiveDirectoryIterator.

`alias`

  Псевдоним, который необходимо назначить phar-архиву для использования в потоковых обёртках.

`format`

  Одна из констант формата файлов доступная для класса Phar.

### Ошибки

Выбрасывает исключение BadMethodCallException, если вызван дважды; Выбрасывает исключение UnexpectedValueException, если Phar-архив невозможно открыть.

### Примеры

Пример #1 Пример использования PharData::__construct()

    <?php
    try {
        $p = new PharData('/path/to/my.tar', Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME);
    } catch (UnexpectedValueException $e) {
        die('Не удалось открыть my.tar');
    } catch (BadMethodCallException $e) {
        echo 'Технически, это никогда не произойдёт';
    }
    echo file_get_contents('phar:///path/to/my.tar/example.txt');
    ?>

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — Конвертация phar-архива в незапускаемый tar/zip-архив

### Описание

public function PharData::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

Этот метод используется для преобразования незапускаемого tar/zip-архива в другой незапускаемый формат.

Если не указано никаких изменений, то будет выброшено исключение BadMethodCallException. Этот метод можно использовать для преобразования tar-архива в zip-архив и наоборот. Несмотря на то что, что можно изменить сжатие для tar-архива с помощью этого метода, для этих целей лучше использовать метод PharData::compress().

В случае успешного выполнения будет создан новый архив на диске и возвращён объект PharData. Старый архив удаляться не будет.

### Список параметров

`format`

  Одна из констант: `Phar::TAR` или `Phar::ZIP`. Если задать как `null`, то будет использован текущий формат.

`compression`

  Одна из констант: `Phar::NONE` (для отключения сжатия всего архива), `Phar::GZ` (для zlib-сжатия), `Phar::BZ2` (для bzip-сжатия).

`extension`

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

  По умолчанию для tar-архивов используются расширения: `.tar`, `.tar.gz` и `.tar.bz2`. Для zip-архивов: `.zip`.

### Возвращаемые значения

Метод возвращает объект PharData или `null` в случае возникновения ошибки.

### Ошибки

Метод выбрасывает исключениеBadMethodCallException когда не может произвести сжатие, когда задан неизвестный метод сжатия, для архива включена буферизация с помощью Phar::startBuffering(), и не отключена при помощи Phar::stopBuffering(). Исключение PharException выбрасывается при любых проблемах создания phar-архива.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `format`, `compression` и `extension` теперь допускают значение null.

### Примеры

Пример #1 Пример использования PharData::convertToData()

Использование PharData::convertToData():

    <?php
    try {
        $tarphar = new PharData('myphar.tar');
        // обратите внимание, что myphar.tar *не* удаляется
        // создаём myphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // создаём myphar.tbz
        $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // создаём myphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // выбрасывает исключение
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::convertToExecutable() - Конвертирует phar-архив в другой исполняемый формат файла
- Phar::convertToData() - Конвертирует phar-архив в неисполняемый tar- или zip-файл
- PharData::convertToExecutable() - Конвертация tar/zip-архива с данными в запускаемый phar-архив

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — Конвертация tar/zip-архива с данными в запускаемый phar-архив

### Описание

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Этот метод используется для конвертации незапускаемого tar/zip-архива а запускаемый phar-архив. Может быть использован любой из трёх запускаемых форматов (phar, tar или zip). Также допустимо сжатие архива целиком.

Если изменения не указаны, этот метод бросает исключение BadMethodCallException.

В случае успешного выполнения, этот метод создаёт новый архив на диске и возвращает объект Phar. Старый архив остаётся нетронутым.

### Список параметров

`format`

  Одна из констант: `Phar::PHAR`, `Phar::TAR`, или `Phar::ZIP`. Если задано `null`, то будет сохранён текущий формат.

`compression`

  Одна из констант: `Phar::NONE` (без сжатия всего архива), `Phar::GZ` (zlib сжатие), `Phar::BZ2` (bzip сжатие).

`extension`

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

  При конвертации в phar-архива, расширение по умолчанию `.phar`, `.phar.gz` или `.phar.bz2`, в зависимости от заданного типа сжатия. Для tar-архивов, расширение по умолчанию `.phar.tar`, `.phar.tar.gz`, и `.phar.tar.bz2`. Для zip-архивов расширение по умолчанию `.phar.zip`.

### Возвращаемые значения

Этот метод возвращает объект Phar и `null` в случае возникновения ошибки.

### Ошибки

Метод выбрасывает исключение BadMethodCallException если не может произвести сжатие, либо если задан неизвестный алгоритм сжатия, для архива включена буферизация с помощью Phar::startBuffering(), а метод Phar::stopBuffering() не вызывался. Выбрасывается исключение UnexpectedValueException, если запись запрещена. И выбрасывается PharException, если возникли проблемы записи на диск.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `format`, `compression` и `localName` теперь допускают значение null.

### Примеры

Пример #1 Пример использования PharData::convertToExecutable()

Используем PharData::convertToExecutable():

    <?php
    try {
        $tarphar = new PharData('myphar.tar');
        // конвертируем в формат phar
        // обратите внимание, что myphar.tar *не* удаляется
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // создаём myphar.phar.tgz
        $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Смотрите также

- Phar::convertToExecutable() - Конвертирует phar-архив в другой исполняемый формат файла
- Phar::convertToData() - Конвертирует phar-архив в неисполняемый tar- или zip-файл
- PharData::convertToData() - Конвертация phar-архива в незапускаемый tar/zip-архив

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — Копирует файл внутри tar- или zip-архива в новый файл внутри того же архива

### Описание

public function PharData::copy(string `$from`, string `$to`): true

Метод копирует файл из tar- или zip-архива в новый файл внутри того же архива. Это объектно-ориентированная альтернатива функции copy() с обёрткой потока phar.

### Список параметров

`from`

`to`

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение UnexpectedValueException, если исходный файл не существует, целевой файл уже существует, доступ на запись запретили, если хотя бы один файл невозможно открыть или невозможно прочитать исходный файл, или выбрасывает исключение PharException, если в phar-файл невозможно записать изменения.

### Примеры

Пример #1 Пример копирования файла внутри tar- или zip-архива методом PharData::copy()

Пример показывает работу метода PharData::copy() и эквивалентной ему по функциональности обёртки потока для решения одной и той же задачи. Основная разница между подходами состоит в обработке ошибок. Методы класса PharData выбрасывают исключения, а обёртка потока использует функцию trigger_error().

    <?php

    try {
        $phar = new PharData('myphar.tar');

        $phar['a'] = 'привет';
        $phar->copy('a', 'b');

        echo $phar['b']; // Выводит "phar://myphar.tar/b"
    } catch (Exception $e) {
        // Обработка ошибок
    }

    // Обёртка потока эквивалентна приведённому коду.
    // Вместо исключения срабатывает ошибка уровня E_WARNING
    copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
    echo file_get_contents('phar://myphar.tar/c'); // Выведет "привет"

    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Распаковать весь Phar-архив

### Описание

public function PharData::decompress(?string `$extension` = `null`): ?PharData

Для архивов типа tar, этот метод распаковывает весь архив.

Для архивов типа Zip этот метод выбросит исключение. Для разжатия gzip-архивов должен быть включён модуль zlib, а для bzip2, соответственно, модуль bzip2.

Также этот метод автоматически меняет расширение файла, по умолчанию `.tar`. Расширение можно указать явно с помощью параметра `extension`.

### Список параметров

`extension`

  По умолчанию при распаковке файлу меняется расширение на `.tar`. С помощью этого параметра можно явно указать новое расширение. Будьте осторожны, только запускаемые архивы могут содержать `.phar` в своих именах.

### Возвращаемые значения

Возвращает объект типа PharData в случае успешного выполнения и `null` в случае возникновения ошибки.

### Ошибки

Выбрасывает исключение BadMethodCallException, если отсутствует модуль, необходимый для распаковки: zlib или bzip2.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `extension` теперь допускает значение null.

### Примеры

Пример #1 Пример использования PharData::decompress()

    <?php
    $p = new PharData('/path/to/my.tar.gz');
    $p->decompress(); // creates /path/to/my.tar
    ?>

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- PharData::compressFiles() - Сжать все файлы в текущем tar/zip-архиве
- PharData::decompressFiles() - Распаковывает все файлы в текущем zip-архиве

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — Распаковывает все файлы в текущем zip-архиве

### Описание

public function PharData::decompressFiles(): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

При распаковке файлов в tar-архиве метод выбрасывает исключение BadMethodCallException, поскольку сжатие отдельных файлов в tar-архиве не поддерживается форматом файла. Для сжатия tar-архива пользуются методом PharData::compress().

В zip-архиве метод распаковывает все файлы. Для сжатия файлов методом bzip2 или zlib потребуется включить модуль, который соответствует формату сжатия, — bzip2 или zlib.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение BadMethodCallException, если модуль zlib недоступен, или если хотя бы один файл сжат методом bzip2, а модуль bzip2 не включили.

### Примеры

Пример #1 Пример распаковки всех файло в zip-архиве методом PharData::decompressFiles()

    <?php

    $p = new PharData('/path/to/my.zip');

    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';

    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }

    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }

    ?>

Результат выполнения приведённого примера:

    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- PharData::compressFiles() - Сжать все файлы в текущем tar/zip-архиве
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- PharData::compress() - Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- PharData::decompress() - Распаковать весь Phar-архив

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — Удаляет глобальные метаданные zip-архива

### Описание

public function PharData::delMetadata(): true

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Метод удаляет глобальные метаданные zip-архива.

### Список параметров

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение PharException, если возникла ошибка при сохранении изменений на диск.

### Примеры

Пример #1 Пример удаления глобальных метаданных zip-архива методом PharData::delMetaData()

    <?php

    try {
        $phar = new PharData('myphar.zip');

        var_dump($phar->getMetadata());

        $phar->setMetadata("привет");
        var_dump($phar->getMetadata());

        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // Обработка ошибок
    }

    ?>

Результат выполнения приведённого примера:

    NULL
    string(8) "привет"
    NULL

### Смотрите также

- Phar::delMetadata() - Удаляет глобальные метаданные в phar-архиве

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — Удаляет файл в tar- или zip-архиве

### Описание

public function PharData::delete(string `$localName`): true

Метод удаляет файл в архиве. Функционально метод эквивалентен вызову функции unlink() на обёртке эквивалентного потока, как показывает пример на этой странице.

### Список параметров

`localName`

  Путь в архиве, по которому требуется удалить файл.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение PharException, если возникла ошибка при сохранении изменений на диск.

### Примеры

Пример #1 Пример удаления файла в tar- или zip-архиве методом PharData::delete()

    <?php

    try {
        $phar = new PharData('myphar.zip');

        $phar->delete('unlink/me.php');

        // Это эквивалентно вызову функции unlink()
        unlink('phar://myphar.phar/unlink/me.php');
    } catch (Exception $e) {
        // Обработка ошибок
    }

    ?>

### Смотрите также

- Phar::delete() - Удаляет файл в phar-архиве

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — Уничтожает неисполняемый объект архива tar или zip

### Описание

public function PharData::__destruct()

### Список параметров

Сигнатура функции не содержит параметров.

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — Извлечь содержимое tar/zip-архива в директорию

### Описание

public function PharData::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Извлекает все файлы tar/zip-архива на диск. Извлечённые файлы и директории сохраняют все разрешения, которые у них были. Опциональные параметры позволяют контролировать, какие именно файлы извлекать и нужно ли перезаписывать уже существующие. Второй параметр `files` может быть как именем файла, так и путём директории, которые надо извлекать. По умолчанию уже существующие на диске файлы перезаписываться не будут. Для указания, что нужно использовать перезапись, используется третий параметр. Этот метод аналогичен методу ZipArchive::extractTo().

### Список параметров

`directory`

  Путь, по которому необходимо сохраните извлечённые файлы (`files`)

`files`

  Имя файла или директории, которые надо извлечь. Либо архив с именами файлов/директорий

`overwrite`

  Установите в `true`, если необходимо перезаписывать уже существующие файлы

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения. Но лучше использовать механизм перехвата исключений для контроля успешности.

### Ошибки

Выбрасывает исключение PharException в случае возникновения ошибки записи на диск.

### Примеры

Пример #1 Пример использования PharData::extractTo()

    <?php
    try {
        $phar = new PharData('myphar.tar');
        $phar->extractTo('/full/path'); // извлечь все файлы
        $phar->extractTo('/another/path', 'file.txt'); // извлечь только file.txt
        $phar->extractTo('/this/path',
            array('file1.txt', 'file2.txt')); // извлечь два указанных файла
        $phar->extractTo('/third/path', null, true); // извлечь все файлы, использовать перезапись
    } catch (Exception $e) {
        // обработка ошибок
    }
    ?>

### Примечания

> Замечание: Файловые системы Windows NTFS не поддерживают некоторые символы в именах файлов — `<|>*?":`. Имена файлов с точкой в конце также не поддерживаются. В отличие от ряда инструментов извлечения, метод не поддерживает замену этих символов на подчёркивание, а вместо этого возникает ошибка при извлечении таких файлов.

### Смотрите также

- Phar::extractTo() - Извлечь содержимое phar-архива в директорию

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — Проверить, можно ли модифицировать tar/zip-архив

### Описание

public function PharData::isWritable(): bool

Этот метод возвращает `true`, если tar/zip-архив существует и доступен для записи. В отличие от Phar::isWritable(), tar/zip-архивы с данными можно менять даже если `phar.readonly` установлен в `1`.

### Список параметров

Параметры отсутствуют.

### Возвращаемые значения

Возвращает `true` или `false`

### Смотрите также

- Phar::canWrite() - Проверяет, поддерживает ли модуль phar сохранение и создание phar-архивов
- Phar::isWritable() - Проверяет, можно ли модифицировать phar-архив

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — Изменение содержимого файла

### Описание

public function PharData::offsetSet(string `$localName`, resource|string `$value`): void

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым tar/zip-архива в стиле доступа к элементам массива. offsetSet используется для изменения контента существующего файла, либо для создания нового.

### Список параметров

`localName`

  Имя файла (относительный путь).

`value`

  Содержимое файла.

### Возвращаемые значения

Ничего не возвращает.

### Ошибки

Выбрасывает исключение PharException в случае проблем с записью на диск.

### Примеры

Пример #1 Пример использования PharData::offsetSet()

offsetSet не нужно вызывать напрямую. Используйте синтаксис `[]`.

    <?php
    $p = new PharData('/path/to/my.tar');
    try {
        // вызов offsetSet
        $p['file.txt'] = 'Привет';
    } catch (Exception $e) {
        echo 'Не удалось изменить file.txt:', $e;
    }
    ?>

### Примечания

> Замечание: PharData::addFile(), PharData::addFromString() and PharData::offsetSet() save a new phar archive each time they are called. If performance is a concern, PharData::buildFromDirectory() or PharData::buildFromIterator() should be used instead.

### Смотрите также

- Phar::offsetSet() - Изменение содержимого файла

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — Удалить файл из tar/zip-архива

### Описание

public function PharData::offsetUnset(string `$localName`): void

Это реализация интерфейса ArrayAccess, позволяющая манипулировать содержимым tar/zip-архива в стиле доступа к элементам массива. offsetUnset используется для удаления файлов и запускается каждый раз, когда используется конструкция unset().

### Список параметров

`localName`

  Имя файла (относительный путь).

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает исключение PharException в случае проблем с записью на диск.

### Примеры

Пример #1 Пример использования PharData::offsetUnset()

    <?php
    $p = new PharData('/path/to/my.zip');
    try {
        // удаление file.txt из my.zip путём вызова offsetUnset
        unset($p['file.txt']);
    } catch (Exception $e) {
        echo 'Не удалось удалить file.txt: ', $e;
    }
    ?>

### Смотрите также

- Phar::offsetUnset() - Удалить файл из phar-архива

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — Функция заглушка (Phar::setAlias нельзя использовать для PharData)

### Описание

public function PharData::setAlias(string `$alias`): bool

Незапускаемые tar/zip-архивы не могут иметь псевдонима, так что этот метод просто выбрасывает исключение.

### Список параметров

`alias`

  Параметр игнорируется.

### Возвращаемые значения

### Ошибки

Выбрасывает исключение PharException

### Смотрите также

- Phar::setAlias() - Установить псевдоним для Phar-архива

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — Функция заглушка (Phar::setDefaultStub нельзя использовать для PharData)

### Описание

public function PharData::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool

Незапускаемые tar/zip-архивы не могут иметь заглушку, так что этот метод просто выбрасывает исключение.

### Список параметров

`index`

  Относительный путь в phar-архиве для запуска при доступе из командной строки

`webIndex`

  Относительный путь в phar-архиве для запуска при доступе через браузер

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Выбрасывает исключение PharException

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `webIndex` теперь допускает значение null.

### Смотрите также

- Phar::setDefaultStub() - Установить загрузчик PHP или начальную заглушку Phar-архива в загрузчик по умолчанию

# PharData::setMetadata

(No version information available, might only be in Git)

PharData::setMetadata — Установить метаданные phar-архива

### Описание

public function PharData::setMetadata(mixed `$metadata`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Функция Phar::setMetadata() используется для сохранения данных, характеризующих phar-архив в целом. PharFileInfo::setMetadata() используется для установки метаданных для конкретного файла. Если метаданных будет много, то это может снизить скорость загрузки phar-архива.

Метаданные можно использовать, например, для указания, какой файл должен исполняться при загрузке, или для указания местоположения манифеста, типа package.xml для модуля » PEAR. В общем, любые полезные в контексте phar-архива данные.

### Список параметров

`metadata`

  Любая переменная PHP, содержащая необходимую информацию

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования Phar::setMetadata()

    <?php
    // удаляем, на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "hello"';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Не удалось создать и/или изменить phar:', $e;
    }
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Смотрите также

- Phar::getMetadata() - Извлечь метаданные phar-архива
- Phar::delMetadata() - Удаляет глобальные метаданные в phar-архиве
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные

# PharData::setSignatureAlgorithm

(No version information available, might only be in Git)

PharData::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его

### Описание

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы `phar.readonly` в файле php.ini значение `0`, иначе метод выбросит исключение PharException.

Устанавливает алгоритм подписания phar-архива и применяет его. Доступны следующие алгоритмы подписания: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` и `Phar::OPENSSL`. (pgp пока не поддерживается, вместо него используется SHA-1).

### Список параметров

`algo`

  Одна из констант: `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512` или `Phar::OPENSSL`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Выбрасывает исключение UnexpectedValueException для большинства ошибок. Для архивов на основе zip или tar выбрасывает исключение BadMethodCallException. При ошибках записи на диск выбрасывает исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `privateKey` теперь допускает значение null.

### Смотрите также

- Phar::getSupportedSignatures() - Получить массив поддерживаемых алгоритмов подписи архива
- Phar::getSignature() - Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — Функция-пустышка: метод setStub допустим только для объектов Phar, но не PharData

### Описание

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

Неисполняемым tar- и zip-архивам нельзя содержать загрузочную заглушку, поэтому метод только выбрасывает исключение.

### Список параметров

`stub`
  Формально, строка или дескриптор открытого потока; при включении архива код заглушки выполняется как начальный загрузчик. Параметр игнорируется.
`length`
  Формально, количество байтов, которое требуется прочитать из потока, если в аргументе `stub` передали ресурс. Параметр игнорируется.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

При вызове метод выбрасывает исключение PharException.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Смотрите также

- Phar::setStub() - Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP

## Содержание

- PharData::addEmptyDir — Добавить пустую директорию в tar/zip-архив
- PharData::addFile — Добавить существующие файлы к tar/zip-архиву
- PharData::addFromString — Добавляет файл из строки в архив tar/zip
- PharData::buildFromDirectory — Создаёт tar/zip-архив из файлов в директории
- PharData::buildFromIterator — Создание tar/zip-архива с помощью итератора
- PharData::compress — Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
- PharData::compressFiles — Сжать все файлы в текущем tar/zip-архиве
- PharData::__construct — Конструктор объекта PharData
- PharData::convertToData — Конвертация phar-архива в незапускаемый tar/zip-архив
- PharData::convertToExecutable — Конвертация tar/zip-архива с данными в запускаемый phar-архив
- PharData::copy — Копирует файл внутри tar- или zip-архива в новый файл внутри того же архива
- PharData::decompress — Распаковать весь Phar-архив
- PharData::decompressFiles — Распаковывает все файлы в текущем zip-архиве
- PharData::delMetadata — Удаляет глобальные метаданные zip-архива
- PharData::delete — Удаляет файл в tar- или zip-архиве
- PharData::__destruct — Уничтожает неисполняемый объект архива tar или zip
- PharData::extractTo — Извлечь содержимое tar/zip-архива в директорию
- PharData::isWritable — Проверить, можно ли модифицировать tar/zip-архив
- PharData::offsetSet — Изменение содержимого файла
- PharData::offsetUnset — Удалить файл из tar/zip-архива
- PharData::setAlias — Функция заглушка (Phar::setAlias нельзя использовать для PharData)
- PharData::setDefaultStub — Функция заглушка (Phar::setDefaultStub нельзя использовать для PharData)
- PharData::setMetadata — Установить метаданные phar-архива
- PharData::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его
- PharData::setStub — Функция-пустышка: метод setStub допустим только для объектов Phar, но не PharData

# Класс PharFileInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Введение

Класс PharFileInfo предоставляет высокоуровневый интерфейс к содержимому и атрибутам отдельного файла в phar-архиве.

## Обзор класса

class PharFileInfo extends SplFileInfo {
/* Методы */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* Наследуемые методы */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — Установка прав доступа

### Описание

public function PharFileInfo::chmod(int `$perms`): void

PharFileInfo::chmod() позволяет устанавливать биты разрешений на запуск и чтение для файлов. Биты записи игнорируются, поскольку настраиваются во время исполнения на основании значения INI-переменной phar.readonly. Как и для любого другого функционала, модифицирующего phar-архив, необходимо, чтобы переменная phar.readonly была отключена для успешного изменения прав на файл в архиве Phar. Архивы PharData не имеют таких ограничений.

### Список параметров

`perms`

  Разрешения (смотрите описание функции chmod())

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования PharFileInfo::chmod()

    <?php
    // удалим, на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar('brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.sh'] = '#!/usr/local/lib/php
        <?php echo "привет"; ?>';
        // установим бит исполнрения
        $p['file.sh']->chmod(0555);
        var_dump($p['file.sh']->isExecutable());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    bool(true)

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — Сжимает текущий файл методом zlib или bzip2

### Описание

public function PharFileInfo::compress(int `$compression`): true

Метод сжимает файл в phar-архиве методом сжатия bzip2 или zlib. Для работы метода потребуется включить модуль bzip2 или zlib. Для распаковки уже сжатого файла также потребуется включить модуль, который соответствует методу сжатия. Как и с остальными функциями, которые изменяют содержимое phar-архива, для сжатия файла в Phar-архиве потребуется отключить INI-переменную phar.readonly; директива не ограничивает обработку архивов, с которыми работает класс PharData.

### Список параметров

`compression`

  Параметр принимает только два вида сжатия: `Phar::GZ` и `Phar::BZ2`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, или если модуль bzip2 или zlib недоступен.

### Примеры

Пример #1 Пример сжатия файла методом PharFileInfo::compress()

    <?php

    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');

        $p['myfile.txt'] = 'hi';

        $file = $p['myfile.txt'];
        var_dump($file->isCompressed(Phar::BZ2));

        $p['myfile.txt']->compress(Phar::BZ2);
        var_dump($file->isCompressed(Phar::BZ2));
    } catch (Exception $e) {
        echo 'При попытке создать или модифицировать файл my.phar возникла ошибка: ', $e;
    }

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Конструктор объекта PharFileInfo

### Описание

public function PharFileInfo::__construct(string `$filename`)

Не должен вызываться напрямую. Объект PharFileInfo следует инициализировать с помощью Phar::offsetGet(), используя синтаксис доступа к массиву.

### Список параметров

`filename`

  Полный URL файла. Если вы хотите извлечь файл `my/file.php` из архива `boo.phar`, необходимо задать `phar://boo.phar/my/file.php`.

### Ошибки

Выбрасывает исключение BadMethodCallException, если __construct() вызван дважды. Выбрасывает исключение UnexpectedValueException, если запрошенный URL некорректен, phar-архив невозможно открыть либо если указанный файл отсутствует в архиве.

### Примеры

Пример #1 Пример использования PharFileInfo::__construct()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['testfile.txt'] = "hi\nthere\ndude";
        $file = $p['testfile.txt'];
        foreach ($file as $line => $text) {
            echo "номер строки $line: $text";
        }
        // так то же работает
        $file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt');
        foreach ($file as $line => $text) {
            echo "номер строки $line: $text";
        }
    } catch (Exception $e) {
        echo 'Операции Phar завершились ошибкой: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    номер строки 1: hi
    номер строки 2: there
    номер строки 3: dude
    номер строки 1: hi
    номер строки 2: there
    номер строки 3: dude

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — Распаковывает Phar-файл в phar-архиве

### Описание

public function PharFileInfo::decompress(): true

Метод распаковывает файл в phar-архиве. Для работы функции потребуется включить модуль bzip2 или zlib, в зависимости от метода сжатия файла внутри архива. Как и с остальными функциями, которые изменяют содержимое phar-архива, для распаковки файла в Phar-архиве потребуется отключить INI-переменную phar.readonly; директива не ограничивает обработку архивов, с которыми работает класс PharData.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает исключение BadMethodCallException, если INI-переменная phar.readonly включена, или если модуль bzip2 или zlib недоступен.

### Примеры

Пример #1 Пример распаковки файла в phar-архиве методом PharFileInfo::decompress()

    <?php

    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');

        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];

        $file->compress(Phar::GZ);
        var_dump($file->isCompressed());

        $p['myfile.txt']->decompress();
        var_dump($file->isCompressed());
    } catch (Exception $e) {
        echo 'При попытке создать или модифицировать файл my.phar возникла ошибка: ', $e;
    }

    ?>

Результат выполнения приведённого примера:

    int(4096)
    bool(false)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия

# PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — Удаляет метаданные отдельного файла в архиве

### Описание

public function PharFileInfo::delMetadata(): true

Метод удаляет метаданные конкретного файла, если файл содержит метаданные.

### Список параметров

У метода нет параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`. Как и с остальными функциями, которые изменяют содержимое phar-архива, для удаления метаданных файла в Phar-архиве потребуется отключить INI-переменную phar.readonly; директива не ограничивает обработку архивов, с которыми работает класс PharData.

### Ошибки

Метод выбрасывает исключение PharException, если возникла ошибка при записи изменений диск, и исключение BadMethodCallException, если доступ на запись запретили.

### Примеры

Пример #1 Пример удаляет метаданные отдельной записи архива методом PharFileInfo::delMetaData()

    <?php

    try {
        $a = new Phar('myphar.phar');

        $a['hi'] = 'hi';

        var_dump($a['hi']->delMetadata());

        $a['hi']->setMetadata('there');
        var_dump($a['hi']->delMetadata());

        var_dump($a['hi']->delMetadata());
    } catch (Exception $e) {
        // Обработка ошибок
    }

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- PharFileInfo::setMetadata() - Установка метаданных для конкретного файла
- PharFileInfo::hasMetadata() - Проверить, есть ли у файла метаданные
- PharFileInfo::getMetadata() - Получить метаданные, связанные с файлом
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные
- Phar::getMetadata() - Извлечь метаданные phar-архива

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Уничтожает входной объект Phar

### Описание

public function PharFileInfo::__destruct()

### Список параметров

Сигнатура функции не содержит параметров.

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — Получить контрольную сумму CRC32

### Описание

public function PharFileInfo::getCRC32(): int

Возвращает контрольную сумму crc32() для файла в Phar-архиве.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Контрольная сумма crc32() для файла в Phar-архиве.

### Ошибки

Выбрасывает исключение BadMethodCallException, если не удалось верифицировать контрольную сумму CRC32. Этого практически невозможно добиться при обычной работе, так как контрольная сумма проверяется при чтении и записи файла.

### Примеры

Пример #1 Пример использования PharFileInfo::getCRC32()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        echo $file->getCRC32();
    } catch (Exception $e) {
        echo 'Операции записи на my.phar завершились ошибкой: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    3633523372

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Получить реальный занимаемый файлом размер на диске с учётом сжатия

### Описание

public function PharFileInfo::getCompressedSize(): int

Возвращает реально занимаемое файлом место с учётом сжатия. Для несжатого файла вернётся такое же значение, что и с помощью filesize()

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Размер файла в байтах.

### Примеры

Пример #1 Пример использования PharFileInfo::getCompressedSize()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        echo $file->getCompressedSize();
    } catch (Exception $e) {
        echo 'Операции записи на my.phar завершились ошибкой: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    2

### Смотрите также

- PharFileInfo::isCompressed() - Проверить, сжат ли файл
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве

# PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — Получить полное содержимое файла записи

### Описание

public function PharFileInfo::getContent(): string

Эта функция ведёт себя как file_get_contents(), но для Phar.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает содержимое файла.

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — Получить метаданные, связанные с файлом

### Описание

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Возвращает метаданные, связанные с файлом.

### Список параметров

### Возвращаемые значения

Любая переменная PHP, которая может быть сериализована и сохранена в виде метаданных файла, либо `null`, если метаданных нет.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Добавлен параметр `unserializeOptions`.

### Примеры

Пример #1 Пример использования PharFileInfo::getMetadata()

    <?php
    // удалим, на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.txt'] = 'hello';
        $p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
        var_dump($p['file.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить brandnewphar.phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Смотрите также

- PharFileInfo::setMetadata() - Установка метаданных для конкретного файла
- PharFileInfo::hasMetadata() - Проверить, есть ли у файла метаданные
- PharFileInfo::delMetadata() - Удаляет метаданные отдельного файла в архиве
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные
- Phar::getMetadata() - Извлечь метаданные phar-архива

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Получить флаги файла в phar-архиве

### Описание

public function PharFileInfo::getPharFlags(): int

Возвращает набор флагов, заданных в манифесте Phar-архива. В текущей реализации всегда возвращает `0`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Флаги Phar-архива (пока всегда `0`)

### Примеры

Пример #1 Пример использования PharFileInfo::getPharFlags()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        var_dump($file->getPharFlags());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить my.phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    int(0)

# PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — Проверить, есть ли у файла метаданные

### Описание

public function PharFileInfo::hasMetadata(): bool

Проверяет, есть ли у файла метаданные.

### Список параметров

Нет параметров.

### Возвращаемые значения

Возвращает `false` или `true` (метаданные, равные `null`, считаются за отсутствие метаданных)

### Смотрите также

- PharFileInfo::setMetadata() - Установка метаданных для конкретного файла
- PharFileInfo::getMetadata() - Получить метаданные, связанные с файлом
- PharFileInfo::delMetadata() - Удаляет метаданные отдельного файла в архиве
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные
- Phar::getMetadata() - Извлечь метаданные phar-архива

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — Определить, прошёл ли файл проверку CRC

### Описание

public function PharFileInfo::isCRCChecked(): bool

Определяет, прошёл ли файл проверку CRC.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если файл прошёл проверку CRC, `false` в противном случае.

### Примеры

Пример #1 Пример использования PharFileInfo::isCRCChecked()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        var_dump($file->isCRCChecked());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить my.phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    bool(true)

# PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — Проверить, сжат ли файл

### Описание

public function PharFileInfo::isCompressed(?int `$compression` = `null`): bool

Проверяет, сжат ли файл внутри Phar-архива с помощью Gzip или Bzip2.

### Список параметров

`compression`

  Одна из констант `Phar::GZ` или `Phar::BZ2`. По умолчанию - любой тип сжатия.

### Возвращаемые значения

`true`, если файл сжат и `false` в противном случае.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `compression` теперь допускает значение null.

### Примеры

Пример #1 Пример использования PharFileInfo::isCompressed()

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $p['myfile2.txt'] = 'hi';
        $p['myfile2.txt']->setCompressedGZ();
        $file = $p['myfile.txt'];
        $file2 = $p['myfile2.txt'];
        var_dump($file->isCompressed());
        var_dump($file2->isCompressed());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить phar my.phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)

### Смотрите также

- PharFileInfo::getCompressedSize() - Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::decompress() - Распаковывает Phar-файл в phar-архиве
- PharFileInfo::compress() - Сжимает текущий файл методом zlib или bzip2
- Phar::decompress() - Распаковывает весь Phar-архив
- Phar::compress() - Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
- Phar::canCompress() - Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
- Phar::isCompressed() - Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
- Phar::getSupportedCompression() - Возвращает массив поддерживаемых алгоритмов сжатия
- Phar::decompressFiles() - Распаковывает все файлы в текущем Phar-архиве
- Phar::compressFiles() - Сжимает все файлы в текущем Phar-архиве

# PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — Установка метаданных для конкретного файла

### Описание

public function PharFileInfo::setMetadata(mixed `$metadata`): void

PharFileInfo::setMetadata() следует использовать для сохранения метаданных конкретного файла, которые нельзя хранить внутри самого файла, поскольку, если данных много, либо в принципе много файлов с метаданными - это значительно замедляет загрузку phar-архива. Важно помнить, что phar-архивы из коробки поддерживают права на файлы и их можно задать с помощью метода PharFileInfo::chmod(). Так как эта функциональность изменяет phar-архив, необходимо, чтобы опция phar.readonly была отключена, иначе внести изменения в архив Phar не получится. На архивы PharData ограничение на запись не распространяется.

Метаданные файлов можно использовать, например, для указания, какие права надо назначить файлу при экспорте его на диск, или для указания MIME-типа, который он возвращает. В общем - любая полезная информация, которой не место внутри самого файла.

### Список параметров

`metadata`

  Любая переменная PHP, содержащая необходимую информацию

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования PharFileInfo::setMetadata()

    <?php
    // удалим, на всякий случай
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.txt'] = 'hello';
        $p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
        var_dump($p['file.txt']->getMetaData());
    } catch (Exception $e) {
        echo 'Не удалось создать/изменить phar: ', $e;
    }
    ?>

Результат выполнения приведённого примера:

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Смотрите также

- PharFileInfo::hasMetadata() - Проверить, есть ли у файла метаданные
- PharFileInfo::getMetadata() - Получить метаданные, связанные с файлом
- PharFileInfo::delMetadata() - Удаляет метаданные отдельного файла в архиве
- Phar::setMetadata() - Установить метаданные phar-архива
- Phar::hasMetadata() - Проверить, содержит ли phar-архив глобальные метаданные
- Phar::getMetadata() - Извлечь метаданные phar-архива

## Содержание

- PharFileInfo::chmod — Установка прав доступа
- PharFileInfo::compress — Сжимает текущий файл методом zlib или bzip2
- PharFileInfo::__construct — Конструктор объекта PharFileInfo
- PharFileInfo::decompress — Распаковывает Phar-файл в phar-архиве
- PharFileInfo::delMetadata — Удаляет метаданные отдельного файла в архиве
- PharFileInfo::__destruct — Уничтожает входной объект Phar
- PharFileInfo::getCRC32 — Получить контрольную сумму CRC32
- PharFileInfo::getCompressedSize — Получить реальный занимаемый файлом размер на диске с учётом сжатия
- PharFileInfo::getContent — Получить полное содержимое файла записи
- PharFileInfo::getMetadata — Получить метаданные, связанные с файлом
- PharFileInfo::getPharFlags — Получить флаги файла в phar-архиве
- PharFileInfo::hasMetadata — Проверить, есть ли у файла метаданные
- PharFileInfo::isCRCChecked — Определить, прошёл ли файл проверку CRC
- PharFileInfo::isCompressed — Проверить, сжат ли файл
- PharFileInfo::setMetadata — Установка метаданных для конкретного файла

# Класс PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Введение

Класс PharException предоставляет класс исключения модуля phar для блоков try/catch.

## Обзор класса

class PharException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Использование Phar-архивов
  - Использование Phar-архивов: Введение
  - Использование Phar-архивов: обёртка потока phar
  - Использование Phar-архивов: классы Phar и PharData
- Создание Phar-архивов
  - Создание Phar-архивов: Введение
- Чем отличается phar от tar- или zip-архива?
  - Составные части всех Phar-архивов вне зависимости от формата файла
  - Заглушка Phar-файла
  - Сравнение Phar, Tar и Zip
  - Phar-архивы, основанные на tar
  - Phar-архивы, основанные на zip
  - Формат файла phar
  - Флаги глобальной битовой карты Phar
  - Описание записи файла в манифесте Phar
  - Формат подписи Phar
- Phar — Класс Phar
  - Phar::addEmptyDir — Добавляет в phar-архив пустую директорию
  - Phar::addFile — Добавляет в phar-архив файл из файловой системы
  - Phar::addFromString — Добавляет в phar-архив файл из строки
  - Phar::apiVersion — Возвращает версию API
  - Phar::buildFromDirectory — Создаёт phar-архив из файлов, расположенных внутри директории
  - Phar::buildFromIterator — Создаёт phar-архив из итератора
  - Phar::canCompress — Проверяет, поддерживает ли модуль phar сжатие с использованием zlib или bzip2
  - Phar::canWrite — Проверяет, поддерживает ли модуль phar сохранение и создание phar-архивов
  - Phar::compress — Сжимает весь Phar-архив с помощью Gzip- или Bzip2-сжатия
  - Phar::compressFiles — Сжимает все файлы в текущем Phar-архиве
  - Phar::__construct — Создаёт объект Phar-архива
  - Phar::convertToData — Конвертирует phar-архив в неисполняемый tar- или zip-файл
  - Phar::convertToExecutable — Конвертирует phar-архив в другой исполняемый формат файла
  - Phar::copy — Копирует файл внутри phar-архива в новый файл внутри phar-архива
  - Phar::count — Возвращает количество записей (файлов) в Phar-архиве
  - Phar::createDefaultStub — Создать заглушку в формате phar-архива
  - Phar::decompress — Распаковывает весь Phar-архив
  - Phar::decompressFiles — Распаковывает все файлы в текущем Phar-архиве
  - Phar::delMetadata — Удаляет глобальные метаданные в phar-архиве
  - Phar::delete — Удаляет файл в phar-архиве
  - Phar::__destruct — Уничтожает объект архива Phar
  - Phar::extractTo — Извлечь содержимое phar-архива в директорию
  - Phar::getAlias — Получить псевдоним для Phar
  - Phar::getMetadata — Извлечь метаданные phar-архива
  - Phar::getModified — Определить, изменялся phar-архив
  - Phar::getPath — Получить реальный путь к Phar-архиву на диске
  - Phar::getSignature — Получить MD5/SHA1/SHA256/SHA512/OpenSSL подпись Phar-архива
  - Phar::getStub — Получить загрузчик PHP или загрузчик заглушки Phar-архива
  - Phar::getSupportedCompression — Возвращает массив поддерживаемых алгоритмов сжатия
  - Phar::getSupportedSignatures — Получить массив поддерживаемых алгоритмов подписи архива
  - Phar::getVersion — Получить версию Phar-архива
  - Phar::hasMetadata — Проверить, содержит ли phar-архив глобальные метаданные
  - Phar::interceptFileFuncs — Указывает phar перехватывать fopen, file_get_contents, opendir и все stat-функции
  - Phar::isBuffering — Проверить, будут ли операции с Phar-архивом буферизованы или записаны напрямую на диск
  - Phar::isCompressed — Возвращает Phar::GZ или PHAR::BZ2, если phar-архив сжат целиком (.tar.gz/tar.bz и так далее)
  - Phar::isFileFormat — Проверить, что phar-архив имеет заданный формат (tar/phar/zip)
  - Phar::isValidPharFilename — Проверяет, что заданное имя файла является корректным именем phar-архива
  - Phar::isWritable — Проверяет, можно ли модифицировать phar-архив
  - Phar::loadPhar — Загрузить phar-архив с псевдонимом
  - Phar::mapPhar — Прочитать текущий запущенный phar-архив и зарегистрировать его манифест
  - Phar::mount — Монтирование внешнего путь или файла к виртуальному пути в phar-архиве
  - Phar::mungServer — Определить список до четырёх $_SERVER-переменных, которые должны быть изменены для запуска
  - Phar::offsetExists — Определить, есть ли файл в архиве
  - Phar::offsetGet — Получить объект PharFileInfo для конкретного файла
  - Phar::offsetSet — Изменение содержимого файла
  - Phar::offsetUnset — Удалить файл из phar-архива
  - Phar::running — Получить полный путь на диске, либо полный URL запущенного Phar-архива
  - Phar::setAlias — Установить псевдоним для Phar-архива
  - Phar::setDefaultStub — Установить загрузчик PHP или начальную заглушку Phar-архива в загрузчик по умолчанию
  - Phar::setMetadata — Установить метаданные phar-архива
  - Phar::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его
  - Phar::setStub — Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP
  - Phar::startBuffering — Запускает буферизацию операций записи, отключая запись изменений Phar-архива на диск
  - Phar::stopBuffering — Останавливает буферизацию и записывает все изменения на диск
  - Phar::unlinkArchive — Удаляет архив из памяти и с диска
  - Phar::webPhar — Направляет запрос из браузера во внутренний файл в phar-архиве
- PharData — Класс PharData
  - PharData::addEmptyDir — Добавить пустую директорию в tar/zip-архив
  - PharData::addFile — Добавить существующие файлы к tar/zip-архиву
  - PharData::addFromString — Добавляет файл из строки в архив tar/zip
  - PharData::buildFromDirectory — Создаёт tar/zip-архив из файлов в директории
  - PharData::buildFromIterator — Создание tar/zip-архива с помощью итератора
  - PharData::compress — Сжимает весь архив tar/zip, используя сжатие Gzip или Bzip2
  - PharData::compressFiles — Сжать все файлы в текущем tar/zip-архиве
  - PharData::__construct — Конструктор объекта PharData
  - PharData::convertToData — Конвертация phar-архива в незапускаемый tar/zip-архив
  - PharData::convertToExecutable — Конвертация tar/zip-архива с данными в запускаемый phar-архив
  - PharData::copy — Копирует файл внутри tar- или zip-архива в новый файл внутри того же архива
  - PharData::decompress — Распаковать весь Phar-архив
  - PharData::decompressFiles — Распаковывает все файлы в текущем zip-архиве
  - PharData::delMetadata — Удаляет глобальные метаданные zip-архива
  - PharData::delete — Удаляет файл в tar- или zip-архиве
  - PharData::__destruct — Уничтожает неисполняемый объект архива tar или zip
  - PharData::extractTo — Извлечь содержимое tar/zip-архива в директорию
  - PharData::isWritable — Проверить, можно ли модифицировать tar/zip-архив
  - PharData::offsetSet — Изменение содержимого файла
  - PharData::offsetUnset — Удалить файл из tar/zip-архива
  - PharData::setAlias — Функция заглушка (Phar::setAlias нельзя использовать для PharData)
  - PharData::setDefaultStub — Функция заглушка (Phar::setDefaultStub нельзя использовать для PharData)
  - PharData::setMetadata — Установить метаданные phar-архива
  - PharData::setSignatureAlgorithm — Установить алгоритм подписания phar-архива и применение его
  - PharData::setStub — Функция-пустышка: метод setStub допустим только для объектов Phar, но не PharData
- PharFileInfo — Класс PharFileInfo
  - PharFileInfo::chmod — Установка прав доступа
  - PharFileInfo::compress — Сжимает текущий файл методом zlib или bzip2
  - PharFileInfo::__construct — Конструктор объекта PharFileInfo
  - PharFileInfo::decompress — Распаковывает Phar-файл в phar-архиве
  - PharFileInfo::delMetadata — Удаляет метаданные отдельного файла в архиве
  - PharFileInfo::__destruct — Уничтожает входной объект Phar
  - PharFileInfo::getCRC32 — Получить контрольную сумму CRC32
  - PharFileInfo::getCompressedSize — Получить реальный занимаемый файлом размер на диске с учётом сжатия
  - PharFileInfo::getContent — Получить полное содержимое файла записи
  - PharFileInfo::getMetadata — Получить метаданные, связанные с файлом
  - PharFileInfo::getPharFlags — Получить флаги файла в phar-архиве
  - PharFileInfo::hasMetadata — Проверить, есть ли у файла метаданные
  - PharFileInfo::isCRCChecked — Определить, прошёл ли файл проверку CRC
  - PharFileInfo::isCompressed — Проверить, сжат ли файл
  - PharFileInfo::setMetadata — Установка метаданных для конкретного файла
- PharException — Класс PharException

# Архивирование Rar

# Введение

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

Больше информации о Rar и UnRar можно найти здесь: » http://www.rarlabs.com/.

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Модуль Rar доступен в репозитории PECL: » https://pecl.php.net/package/rar.

Можно также воспользоваться установщиком PECL, чтобы установить модуль Rar. Для этого необходимо использовать команду: pecl -v install rar.

Можно также скачать архив tar.gz и установить Rar вручную:

Пример #1 Установка модуля Rar

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Пользователям ОС Windows необходимо включить модуль php_rar.dll в файле php.ini.

## Типы ресурсов

Этот модуль использует три внутренних ресурса: дескриптор файла, который возвращает функция rar_open() — RarArchive, содержимое архива, которое возвращают функции rar_list() и rar_entry_get() – RarEntry и тип исключений RarException.

Модуль также регистрирует потоковый ресурс с названием «rar» и URL-обёртку с названием «rar wrapper» и префиксом «rar», который соответствует обёртке.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`RAR_HOST_MSDOS` (int)
  Используйте вместо неё константу `RarEntry::HOST_MSDOS`.
`RAR_HOST_OS2` (int)
  Используйте вместо неё константу `RarEntry::HOST_OS2`.
`RAR_HOST_WIN32` (int)
  Используйте вместо неё константу `RarEntry::HOST_WIN32`.
`RAR_HOST_UNIX` (int)
  Используйте вместо неё константу `RarEntry::HOST_UNIX`.
`RAR_HOST_BEOS` (int)
  Используйте вместо неё константу `RarEntry::HOST_BEOS`.

# Примеры

Смотрите также примеры по ссылке обёртка `rar://`.

Пример #1 Декомпрессия на лету

    <?php

    if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
        die("Индекс не указали или не числовой");
    $index = (int) $_GET["i"];

    $arch = RarArchive::open("example.rar");
    if ($arch === FALSE)
        die("Невозможно открыть файл example.rar");

    $entries = $arch->getEntries();
    if ($entries === FALSE)
        die("Невозможно получить записи");

    if (!array_key_exists($index, $entries))
        die("Нет такого индекса: $index");

    $orfilename = $entries[$index]->getName(); //Кодировка UTF-8

    $filesize = $entries[$index]->getUnpackedSize();

    /** В этом месте доступна проверка константы HTTP_IF_MODIFIED_SINCE и сравнение
     * со результатом вызова $entries[$index]->getFileTime(). Доступна также отправка заголовока
     * "Last modified"
     */

    $fp = $entries[$index]->getStream();
    if ($fp === FALSE)
        die("Невозможно открыть файл с индексом $index внутри архива.");

    $arch->close(); // Больше не нужен. Поток независим

    function detectUserAgent() {
        if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
            return "Other";

        $uas = $_SERVER['HTTP_USER_AGENT'];
        if (preg_match("@Opera/@", $uas))
            return "Opera";
        if (preg_match("@Firefox/@", $uas))
            return "Firefox";
        if (preg_match("@Chrome/@", $uas))
            return "Chrome";
        if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
            if (((float) $matches[1]) >= 7.0)
                return "IE";
        }

        return "Other";
    }

    /*
     * Действуют 3 опции:
     * - Для FF и Opera с поддержкой стандарта RFC 2231 пользуются этим форматом
     * - Для IE и Chrome формат attwithfnrawpctenclong
     *   (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
     * - Для других браузеров перекодируется в набор символов ISO-8859-1, если возможно
     */
    $formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
    $formatDef = 'Content-Disposition: attachment; filename="%s"';

    switch (detectUserAgent()) {
        case "Opera":
        case "Firefox":
            $orfilename = rawurlencode($orfilename);
            $format = $formatRFC2231;
            break;

        case "IE":
        case "Chrome":
            $orfilename = rawurlencode($orfilename);
            $format = $formatDef;
            break;
        default:
            if (function_exists('iconv'))
                $orfilename =
                    @iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
            $format = $formatDef;
    }

    header(sprintf($format, $orfilename));
    // Невозможна дальнейшая отправка сообщений об ошибках (PHP уже отправил заголовки)

    // Замена на реальный Content-Type, который, возможно, получилось определить по расширению файла
    $contentType = "application/octet-stream";
    header("Content-Type: $contentType");

    header("Content-Transfer-Encoding: binary");

    header("Content-Length: $filesize");

    if ($_SERVER['REQUEST_METHOD'] == "HEAD") {
        die();
    }

    while (!feof($fp)) {
        $s = @fread($fp, 8192);

        if ($s === false) {
            break; // В этом месте бесполезно отправлять сообщения об ошибках
        }

        echo $s;
    }
    ?>

Этот пример открывает RAR-файл и предоставляет запрошенный файл вне RAR-архива для загрузки клиентом.

Пример #2 Пример извлечения перечня файлов и директорий из RAR-архива

    <?php

    $rar_file = rar_open('example.rar') or die("Невозможно открыть RAR архив");

    $entries = rar_list($rar_file);

    foreach ($entries as $entry) {
        echo 'Имя файла: ' . $entry->getName() . "\n";
        echo 'Упакованный размер: ' . $entry->getPackedSize() . "\n";
        echo 'Распакованный размер: ' . $entry->getUnpackedSize() . "\n";

        $entry->extract('/dir/extract/to/');
    }

    rar_close($rar_file);

    ?>

Этот пример открывает RAR-файл и извлекает каждый объект в заданную директорию.

# Rar

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Кеш доступов и отказов обёртки URL

### Описание

function rar_wrapper_cache_stats(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- rar_wrapper_cache_stats — Кеш доступов и отказов обёртки URL

# Класс RarArchive

(PECL rar >= 2.0.0)

## Введение

Этот класс описывает RAR архив, который может состоять из нескольких томов (частей) и содержать некоторое число RAR записей (файлы, директории и другие специальные объекты, такие как символические ссылки).

Объекты этого класса могут быть заполнены перебором исходя из записей, хранящихся в соответствующем RAR архиве. Эти записи могут быть также получены с помощью методов RarArchive::getEntry() и RarArchive::getEntries().

## Обзор класса

final class RarArchive implements Traversable {
/* Методы */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Закрывает RAR архив и освобождает все ресурсы

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::close(): bool

Процедурный стиль:

function rar_close(RarArchive `$rarfile`): bool

Закрывает RAR архив и освобождает все ресурсы связанные с ним.

### Список параметров

`rarfile`
  Объект RarArchive, открытый с помощью rar_open().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 2.0.0 | Элементы архива, возвращаемые RarArchive::getEntry() и RarArchive::getEntries() теперь недействительны после вызова данного метода. Это означает, что нет гарантии правильной работы всех методов этих элементов.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Вывод приведённого примера будет похож на:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Пример #2 Процедурный стиль

    <?php
    $rar_arch = rar_open('latest_winrar.rar');
    echo $rar_arch."\n";
    rar_close($rar_arch);
    echo $rar_arch."\n";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — Получить текст комментария из архива RAR

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::getComment(): string

Процедурный стиль:

function rar_comment_get(RarArchive `$rarfile`): string

Возвращает (глобальный) комментарий, сохранённый в архиве RAR. Он может быть длиной вплоть до 64 KiB.

> Замечание: Модуль не поддерживает комментарии на уровне записей.

### Список параметров

`rarfile`
  Объект RarArchive, открытый с помощью rar_open().

### Возвращаемые значения

Возвращает комментарий или `null`, если его нет.

> Замечание: RAR в текущий момент не поддерживает комментарии в unicode. Кодировка результата не определена, но, возможно, она будет Windows-1252.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

Вывод приведённого примера будет похож на:

    This is the comment of the file commented.rar.

Пример #2 Процедурный стиль

    <?php
    $rar_arch = rar_open('commented.rar');
    echo rar_comment_get($rar_arch);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — Возвращает полный список элементов из RAR архива

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::getEntries(): array|false

Процедурный стиль:

function rar_list(RarArchive `$rarfile`): array|false

Возвращает элементы (файлы и директории) из RAR архива.

> Замечание: Если архив имеет элементы с одинаковым именем, то этот метод совместно с циклом `foreach` по RarArchive и доступом к нему как к массиву с числовыми индексами являются единственными способами получить доступ к этим элементам (т.е. RarArchive::getEntry() и `rar://` обработчик (wrapper) не помогут).

### Список параметров

`rarfile`
  Объект RarArchive открытый с помощью rar_open().

### Возвращаемые значения

rar_list() возвращает массив объектов RarEntry или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 3.0.0 | Исправлена поддержка RAR архивов с повторяющимися именами элементов.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Не смог открыть RAR архив.");

    $rar_entries = $rar_arch->getEntries();
    if ($rar_entries === FALSE)
        die("Не смог достать содержимое.");

    echo "Нашёл " . count($rar_entries) . " объектов.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    $rar_arch->close();
    ?>

Вывод приведённого примера будет похож на:

    Нашёл 2 объектов.
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

Пример #2 Процедурный стиль

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");

    $rar_entries = rar_list($rar_arch);
    if ($rar_entries === FALSE)
        die("Could retrieve entries.");

    echo "Found " . count($rar_entries) . " entries.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    rar_close($rar_arch);
    ?>

### Смотрите также

- RarArchive::getEntry() - Возвращает объект элемента из RAR архива
- `rar://` обработчик(wrapper)

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Возвращает объект элемента из RAR архива

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

Процедурный стиль:

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Возвращает объект элемента (файл или директорию) из RAR архива

> Замечание: Вы также можете получить объекты элементов с помощью RarArchive::getEntries(). Учтите, что RAR архив может иметь несколько элементов с одинаковым именем. Данный метод вернёт только первый из них.

### Список параметров

`rarfile`
  Объект RarArchive открытый с помощью rar_open().
`entryname`
  Путь до элемента RAR архива.

  > Замечание: Путь должен быть таким же, как и возвращаемый методом RarEntry::getName().

### Возвращаемые значения

Возвращает найденный объект RarEntry или `false`, если возникла ошибка.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Не смог открыть RAR архив.");
    $rar_entry = $rar_arch->getEntry('tese.txt');
    if ($rar_entry === FALSE)
        die("Не смог достать этот объект");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    $rar_arch->close();
    ?>

Вывод приведённого примера будет похож на:

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

Пример #2 Процедурный стиль

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Не смог открыть RAR архив.");
    $rar_entry = rar_entry_get($rar_arch, 'tese.txt');
    if ($rar_entry === FALSE)
        die("Не смог достать этот объект");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    rar_close($rar_arch);
    ?>

### Смотрите также

- RarArchive::getEntries() - Возвращает полный список элементов из RAR архива
- `rar://` обработчик (wrapper)

# RarArchive::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — Проверяет, не сломан ли архив (не завершён)

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::isBroken(): bool

Процедурный стиль:

function rar_broken_is(RarArchive `$rarfile`): bool

Функция определяет, является ли архив незавершённым, т.е. том обрезан или отсутствует.

### Список параметров

`rarfile`
  Объект RarArchive, открытый с помощью rar_open().

### Возвращаемые значения

Возвращает `true`, если архив сломан и `false`, если нет. Также, функция может вернуть `false`, если переданный файл уже закрыт. Единственный вариант определить точную причину - это разрешить исключения с помощью RarException::setUsingExceptions(); однако, это не так уж и важно, поскольку приложение всё равно не сможет работать с закрытым файлом.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* третий аргумент служит для подавления сообщений */
    $arch = RarArchive::open($file, null, 'retnull');
    var_dump($arch->isBroken());
    ?>

Вывод приведённого примера будет похож на:

    bool(true)

Пример #2 Процедурный стиль

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* третий аргумент служит для подавления сообщений */
    $arch = rar_open($file, null, 'retnull');
    var_dump(rar_broken_is($arch));
    ?>

### Смотрите также

- RarArchive::setAllowBroken() - Открывать ли повреждённые архивы

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — Проверить, является ли архив сплошным

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::isSolid(): bool

Процедурный стиль:

function rar_solid_is(RarArchive `$rarfile`): bool

Проверяет, является ли архив сплошным. Извлечение одного конкретного файла из сплошного архива заметно медленнее.

### Список параметров

`rarfile`
  Объект RarArchive, открытый с помощью rar_open().

### Возвращаемые значения

Возвращает `true`, если да и `false`, если нет.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $arch1 = RarArchive::open("store_method.rar");
    $arch2 = RarArchive::open("solid.rar");
    echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
    echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
    ?>

Вывод приведённого примера будет похож на:

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

Пример #2 Процедурный стиль

    <?php
    $arch1 = rar_open("store_method.rar");
    $arch2 = rar_open("solid.rar");
    echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
    echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Открывает архив RAR

### Описание

Объектно-ориентированный стиль (метод):

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Процедурный стиль:

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Открывает указанный RAR-архив и возвращает объект RarArchive, представляющий его.

> Замечание: При открытии многотомного архива путь к первому тому должен быть передан первым параметром. Иначе не будут видны все файлы.

### Список параметров

`filename`
  Путь к архиву Rar.
`password`
  Пароль, если необходимо расшифровать заголовки архива. Этот же пароль будет использоваться по умолчанию, если будут найдены зашифрованные файлы. Учтите, что файлы могут быть зашифрованы с разными паролями.
`volume_callback`
  Функция, которой передаётся единственный параметр - путь к тому, который не был найден, и возвращающая строку с правильным путём для этого тома или `null`, если данный том не существует или неизвестен. Разработчик должен быть уверен, что данная функция не приведёт к зацикливанию, так как она вызывается повторно, если путь полученный предыдущим вызовом не соответствует нужному тому. Указание этого параметра устраняет предупреждения, которые появлялись бы, если бы том не был бы найден. В случае, если функция возвращает только `null`, то не будет ни одного предупреждения.

Внимание

До версии 2.0.0 эта функция не обрабатывала правильно относительные пути. В таких случаях используйте realpath().

### Возвращаемые значения

Возвращает запрашиваемый объект RarArchive или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 3.0.0 | Был добавлен `volume_callback`.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Неудачное открытие файла");

    $entries = $rar_arch->getEntries();
    if ($entries === FALSE)
        die("Неудачное получение записей");

    echo "Найдено " . count($entries) . " файлов.\n";

    if (empty($entries))
        die("Не найдено корректных записей.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Неудачное открытие первого файла");

    $rar_arch->close();

    echo "Содержимое первого файла:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Вывод приведённого примера будет похож на:

    Найдено 2 файлов.
    Содержимое первого файла:
    Encrypted file 1 contents.

Пример #2 Процедурный стиль

    <?php
    $rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Неудачное открытие файла");

    $entries = rar_list($rar_arch);
    if ($entries === FALSE)
        die("Failed fetching entries");

    echo "Найдено " . count($entries) . " файлов.\n";

    if (empty($entries))
        die("Не найдено корректных записей.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Неудачное открытие первого файла");

    rar_close($rar_arch);

    echo "Содержимое первого файла:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Пример #3 Callback-функция для тома

    <?php
    /* В этом примере есть том с именем multi_broken.part1.rar,
     * а следующий том имеет имя multi.part2.rar */
    function resolve($vol) {
        if (preg_match('/_broken/', $vol))
            return str_replace('_broken', '', $vol);
        else
            return null;
    }
    $rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
    $entry = $rar_file1->getEntry('file2.txt');
    $entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
    ?>

### Смотрите также

- `rar://` wrapper

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Открывать ли повреждённые архивы

### Описание

Объектно-ориентированный стиль (метод):

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

Процедурный стиль:

function rar_allow_broken_set(RarArchive `$rarfile`, bool `$allow_broken`): bool

Метод определяет, можно ли пытаться читать повреждённый архив, или все операции с ним должны заканчиваться ошибкой. Повреждённые архивы - это такие архивы, которые открываются без ошибок, но при попытке прочитать записи возникают ошибки.

### Список параметров

`rarfile`
  Объект RarArchive, открытый с помощью rar_open().
`allow_broken`
  Разрешать ли работу с повреждёнными архивами (`true`) или нет (`false`).

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка. Ошибка может возникнуть только если файл уже закрыт.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* третий аргумент подавляет сообщение "volume not found" */
    $a = RarArchive::open($file, null, 'retnull');
    $a->setAllowBroken(true);
    foreach ($a->getEntries() as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

Вывод приведённого примера будет похож на:

    RarEntry for file "file1.txt" (52b28202)
    int(1)

Пример #2 Процедурный стиль

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* третий аргумент подавляет сообщение "volume not found" */
    $a = rar_open($file, null, 'retnull');
    rar_allow_broken_set($a, true);
    foreach (rar_list($a) as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

### Смотрите также

- RarArchive::isBroken() - Проверяет, не сломан ли архив (не завершён)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Получить текстовое представление

### Описание

public function RarArchive::__toString(): string

Возвращает строку, представляющую объект RarArchive. Она содержит полный путь до текущего открытого тома архива и информацию о том, корректен ли ресурс или уже закрыт с помощью RarArchive::close().

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Текстовое представление объекта RarArchive. Контент не определён.

### Примеры

Пример #1 Пример использования RarArchive::__toString()

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Вывод приведённого примера будет похож на:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## Содержание

- RarArchive::close — Закрывает RAR архив и освобождает все ресурсы
- RarArchive::getComment — Получить текст комментария из архива RAR
- RarArchive::getEntries — Возвращает полный список элементов из RAR архива
- RarArchive::getEntry — Возвращает объект элемента из RAR архива
- RarArchive::isBroken — Проверяет, не сломан ли архив (не завершён)
- RarArchive::isSolid — Проверить, является ли архив сплошным
- RarArchive::open — Открывает архив RAR
- RarArchive::setAllowBroken — Открывать ли повреждённые архивы
- RarArchive::__toString — Получить текстовое представление

# Класс RarEntry

(PECL rar >= 0.1)

## Введение

Запись RAR, представляющая директорию или сжатый файл внутри архива RAR.

## Обзор класса

final class RarEntry {
/* Константы */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* Методы */
public function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __toString(): string
}

## Предопределённые константы

`RarEntry::HOST_MSDOS`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в MS-DOS. Введена для замены `RAR_HOST_MSDOS`.
`RarEntry::HOST_OS2`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в OS/2. Введена для замены `RAR_HOST_OS2`.
`RarEntry::HOST_WIN32`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в Microsoft Windows. Введена для замены `RAR_HOST_WIN32`.
`RarEntry::HOST_UNIX`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в UNIX. Введена для замены `RAR_HOST_UNIX`.
`RarEntry::HOST_MACOS`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в Mac OS.
`RarEntry::HOST_BEOS`
  Если возвращённое значение RarEntry::getHostOs() равно этой константе, значит эта запись была добавлена в BeOS. Введена для замены `RAR_HOST_BEOS`.
`RarEntry::ATTRIBUTE_WIN_READONLY`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "read-only" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_HIDDEN`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "hidden" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_SYSTEM`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "system" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_DIRECTORY`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "directory" (является директорией) для записей Windows. Также смотрите описание метода RarEntry::isDirectory(), который также работает с записями, добавленными не через WinRAR.
`RarEntry::ATTRIBUTE_WIN_ARCHIVE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "archive" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_DEVICE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "device" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_NORMAL`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "normal file" (НЕ является директорией) для записей Windows. Также смотрите описание метода RarEntry::isDirectory(), который также работает с записями, добавленными не через WinRAR.
`RarEntry::ATTRIBUTE_WIN_TEMPORARY`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "temporary" для записей Windows.
`RarEntry::ATTRIBUTE_WIN_SPARSE_FILE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "sparse file" (разреженный файл NTFS) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_REPARSE_POINT`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "reparse point" (файл точки повторной обработки NTFS, т.е. пересечение директорий или точка монтирования файловой системы) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_COMPRESSED`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "compressed" (только NTFS) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_OFFLINE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "offline" (запись отключена и недоступна) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "not content indexed" (запись должна быть проиндексирована) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_ENCRYPTED`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "encrypted" (только NTFS) для записей Windows.
`RarEntry::ATTRIBUTE_WIN_VIRTUAL`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "virtual" (только NTFS) для записей Windows.
`RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "executable" для всех для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "writable" для всех для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_READ`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "readable" для всех для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "executable" для группы для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "writable" для группы для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_READ`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "readable" для группы для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "executable" для владельца для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "writable" для владельца для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_READ`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с атрибутом "readable" для владельца для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_STICKY`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с установленным "sticky bit" для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETGID`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с установленным "setgid" для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETUID`
  Используется с RarEntry::getAttr(). Бит, представляющий запись с установленным "setuid" для записей UNIX.
`RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`
  Маска для изоляции четырёх последних бит (полубайт) для атрибутов UNIX (_S_IFMT, тип файловой маски). Используется с RarEntry::getAttr() и константами `RarEntry::ATTRIBUTE_UNIX_FIFO`, `RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`, `RarEntry::ATTRIBUTE_UNIX_DIRECTORY`, `RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`, `RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`, `RarEntry::ATTRIBUTE_UNIX_SYM_LINK` и `RarEntry::ATTRIBUTE_UNIX_SOCKET`.
`RarEntry::ATTRIBUTE_UNIX_FIFO`
  Специальные файлы FIFO в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`
  Специальные файлы символьных устройств в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_DIRECTORY`
  Директории в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Также смотрите описание метода RarEntry::isDirectory(), который также работает с записями добавленными в других операционных системах.
`RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`
  Специальные файлы блочных устройств в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`
  Обычные файлы (не директории) в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. Также смотрите описание метода RarEntry::isDirectory(), который также работает с записями добавленными в других операционных системах.
`RarEntry::ATTRIBUTE_UNIX_SYM_LINK`
  Символические ссылки в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_SOCKET`
  Специальные файлы сокетов в Unix будут иметь это значение в четырёх последних битах. Используется с RarEntry::getAttr() и константой `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.

# RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — Извлекает элемент из архива

### Описание

public function RarEntry::extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool

RarEntry::extract() извлекает содержимое элемента. При этом создаётся новый файл в указанной директории `dir` с именем совпадающим с именем элемента, если только не задан второй аргумент. Смотрите подробнее ниже.

### Список параметров

`dir`
  Путь к директории, куда необходимо извлечь файлы. Этот параметр учитывается только если не указан параметр `filepath`. Если оба параметра не указаны, то файлы извлекаются в текущую директорию.
`filepath`
  Путь (полный или относительный) содержит директорию и имя извлекаемого файла. Этот параметр переопределяет и параметр `dir` и оригинальное имя файла.
`password`
  Пароль используется для расшифровки текущего элемента. Если элемент не зашифрован, то этот параметр не будет использован и его можно не указывать. Если же этот параметр не указан, а элемент зашифрован, то будет использован пароль, переданный функции rar_open(), если её вызывали. Если передан неверный пароль, явно или неявно через rar_open(), то проверка CRC будет неудачной и будет возвращён `false`. Вы можете проверить является ли элемент зашифрованным с помощью RarEntry::isEncrypted().
`extended_data`
  Если `true`, то в извлекаемый файл будет добавлена дополнительная информация, такая как NTFS ACL и владелец в системе Unix, если они присутствовали в архиве.

Внимание

До версии 2.0.0, не обрабатывала относительные пути корректно. Используйте для этой ситуации realpath().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 3.0.0 | Был добавлен параметр `extended_data`.
PECL rar 3.0.0 | Исправлена поддержка RAR архивов с повторяющимися именами элементов.

### Примеры

Пример #1 Пример использования RarEntry::extract()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    $entry->extract('/dir/to'); // создание /dir/to/Dir/file.txt
    $entry->extract(false, '/dir/to/new_name.txt'); // создание /dir/to/new_name.txt

    ?>

Пример #2 Как извлечь все файлы из архива:

    <?php

    /* Пример от Erik Jenssen aka erix */

    $filename = "foobar.rar";
    $filepath = "/home/foo/bar/";

    $rar_file = rar_open($filepath.$filename);
    $list = rar_list($rar_file);
    foreach($list as $file) {
        $entry = rar_entry_get($rar_file, $file);
        $entry->extract("."); // извлечь в текущий каталог
    }
    rar_close($rar_file);

    ?>

### Смотрите также

- RarEntry::getStream() - Получить обработчик для записи
- `rar://` wrapper

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Возвращает атрибуты элемента архива

### Описание

public function RarEntry::getAttr(): int

Возвращает атрибуты элемента архива, зависящие от операционной системы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает атрибуты или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования RarEntry::getAttr()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Не удалось найти такую запись");

    $host_os = $entry->getHostOs();
    $attr = $entry->getAttr();

    switch($host_os) {
        case RAR_HOST_MSDOS:
        case RAR_HOST_OS2:
        case RAR_HOST_WIN32:
        case RAR_HOST_MACOS:
            printf("%c%c%c%c%c%c\n",
                    ($attr & 0x08) ? 'V' : '.',
                    ($attr & 0x10) ? 'D' : '.',
                    ($attr & 0x01) ? 'R' : '.',
                    ($attr & 0x02) ? 'H' : '.',
                    ($attr & 0x04) ? 'S' : '.',
                    ($attr & 0x20) ? 'A' : '.');
            break;
        case RAR_HOST_UNIX:
        case RAR_HOST_BEOS:
            switch ($attr & 0xF000)
            {
                case 0x4000:
                    printf("d");
                    break;
                case 0xA000:
                    printf("l");
                    break;
                default:
                    printf("-");
                    break;
            }
            printf("%c%c%c%c%c%c%c%c%c\n",
                    ($attr & 0x0100) ? 'r' : '-',
                    ($attr & 0x0080) ? 'w' : '-',
                    ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                    ($attr & 0x0020) ? 'r' : '-',
                    ($attr & 0x0010) ? 'w' : '-',
                    ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                    ($attr & 0x0004) ? 'r' : '-',
                    ($attr & 0x0002) ? 'w' : '-',
                    ($attr & 0x0001) ? 'x' : '-');
            break;
    }

    rar_close($rar_file);

    ?>

### Смотрите также

- RarEntry::getHostOs() - Возвращает оригинальную ОС элемента
- Константы RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Возвращает CRC элемента архива

### Описание

public function RarEntry::getCrc(): string

Возвращает шестнадцатеричное строковое представление CRC элемента архива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает CRC элемента архива или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 2.0.0 | Теперь этот метод возвращает корректные значения для многотомных архивов.

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — Возвращает последнее время изменения элемента

### Описание

public function RarEntry::getFileTime(): string

Метод возвращает время последнего изменения элемента.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает в виде строки в формате `YYYY-MM-DD HH:II:SS` время последнего изменения элемента, или `false`, если возникла ошибка.

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — Возвращает оригинальную ОС элемента

### Описание

public function RarEntry::getHostOs(): int

Возвращает код оригинальной операционной системы, в которой был создан элемент архива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код ОС, или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования RarEntry::getHostOs()(версии >= 2.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    switch ($entry->getHostOs()) {
        case RarEntry::HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RarEntry::HOST_OS2:
            echo "OS2\n";
            break;
        case RarEntry::HOST_WIN32:
            echo "Win32\n";
            break;
        case RarEntry::HOST_MACOS:
            echo "MacOS\n";
            break;
        case RarEntry::HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RarEntry::HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

Пример #2 Пример использования RarEntry::getHostOs() (версии <= 1.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    switch ($entry->getHostOs()) {
        case RAR_HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RAR_HOST_OS2:
            echo "OS2\n";
            break;
        case RAR_HOST_WIN32:
            echo "Win32\n";
            break;
        case RAR_HOST_MACOS:
            echo "MacOS\n";
            break;
        case RAR_HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RAR_HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

### Смотрите также

- RarEntry::extract() - Извлекает элемент из архива

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Возвращает метод компрессии элемента

### Описание

public function RarEntry::getMethod(): int

Метод RarEntry::getMethod() возвращает число, которое соответствует методу компрессии, использовавшемуся при добавлении текущего элемента архива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает номер метода или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования метода RarEntry::getMethod()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    echo "Номер метода: " . $entry->getMethod();

    ?>

# RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — Возвращает имя элемента

### Описание

public function RarEntry::getName(): string

Возвращает имя элемента массива (вместе с путём).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя элемента в виде строки, или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
PECL rar 2.0.0 | Начиная с версии 2.0.0 возвращается строка в кодировке Unicode/UTF-8.

### Примеры

Пример #1 Пример использования RarEntry::getName()

    <?php

    // этот пример работает, даже если страница не в кодировке UTF-8
    // для перекодирования в UTF-8 вызывается mb_convert_encoding

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    echo "Имя элемента: " . mb_convert_encoding(
        htmlentities(
            $entry->getName(),
            ENT_COMPAT,
            "UTF-8"
        ),
        "HTML-ENTITIES",
        "UTF-8"
    );

    ?>

# RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — Возвращает размер сжатого элемента

### Описание

public function RarEntry::getPackedSize(): int

Возвращает размер сжатого элемента архива.

> Замечание: Учтите, что на платформах с 32-х битными целыми long (включая Windows x64), максимальный возвращаемый размер ограничен 2 ГБ. Проверьте константу `PHP_INT_MAX`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер сжатого элемента, или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
PECL rar 2.0.0 | Данный метод теперь возвращает правильные значения для сжатых данных больше 2 ГБ на платформах с 64-х битными целыми (int) и никогда не возвращает отрицательные значения на всех платформах.

### Примеры

Пример #1 Пример использования RarEntry::getPackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    echo "Размер сжатого элемента " . $entry->getName() . " = " . $entry->getPackedSize() . " байтов";

    ?>

# RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — Получить обработчик для записи

### Описание

public function RarEntry::getStream(string `$password` = ?): resource|false

Возвращает обработчик, поддерживающий операцию чтения. Этот обработчик умеет распаковывать запись на лету.

Обработчик не уничтожается при вызове rar_close().

Внимание

Результирующий поток не проверяется на целостность. Следовательно никак не определяется порча файла или расшифровка с неверным ключом. Проверка контрольной суммы разжатого и расшифрованного файла полностью на совести разработчика.

### Список параметров

`password`
  Пароль, использовавшийся для шифрования записи. Если запись не шифрована, то этот параметр игнорируется и в целом может быть опущен. Если же параметр опущен, а запись шифрована, то будет использован пароль заданный в функции rar_open(), если конечно он был задан. Если был задан неверный пароль, явно или неявно через rar_open(), этот метод вернёт поток с неверными данными. Если пароль не задан вообще, а он нужен, то метод вернёт `false`. Зашифрована ли запись или нет можно проверить с помощью RarEntry::isEncrypted().

### Возвращаемые значения

Обработчик или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL rar 3.0.0 | Поддержка RAR-архивов с дублирующимися именами записей теперь работает нормально.

### Примеры

Пример #1 Пример использования RarEntry::getStream()

    <?php

    $rar_file = rar_open('example.rar');
    if ($rar_file === false)
        die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt');
    if ($entry === false)
        die("Не удалось найти такую запись");

    $stream = $entry->getStream();
    if ($stream === false)
        die("Не удалось получить поток.");

    rar_close($rar_file); //поток не зависит от файла

    while (!feof($stream)) {
        $buff = fread($stream, 8192);
        if ($buff !== false)
            echo $buff;
        else
            break; //ошибка fread
    }

    fclose($stream);

    ?>

### Смотрите также

- RarEntry::extract() - Извлекает элемент из архива
- обёртка `rar://`

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Возвращает размер элемента в распакованном состоянии

### Описание

public function RarEntry::getUnpackedSize(): int

Возвращает размер элемента архива в распакованном состоянии.

> Замечание: Учтите, что на платформах с 32-х битными целыми long (включая Windows x64), максимальный возвращаемый размер ограничен 2 ГБ. Проверьте константу `PHP_INT_MAX`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер распакованного элемента, или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
PECL rar 2.0.0 | Данный метод теперь возвращает правильные значения для сжатых данных больше 2 ГБ на платформах с 64-х битными целыми (int) и никогда не возвращает отрицательные значения на всех платформах.

### Возвращаемые значения

Пример #1 Пример использования RarEntry::getUnpackedSize()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    echo "Размер распакованного элемента " . $entry->getName() . " = " . $entry->getUnpackedSize() . " байтов";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — Возвращает минимальную версию программы RAR, необходимую для распаковки элемента

### Описание

public function RarEntry::getVersion(): int

Возвращает минимальную версию программы RAR (т.е. WinRAR), необходимую для распаковки элемента архива. Она закодирована в виде: 10 * основная версия + минорная версия.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает версию или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования RarEntry::getVersion()

    <?php

    $rar_file = rar_open('example.rar') or die("Не удалось открыть Rar архив");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Не удалось найти такую запись");

    echo "Версия Rar, необходимая для распаковки: " . $entry->getVersion();

    ?>

# RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — Проверяет, является ли запись директорией

### Описание

public function RarEntry::isDirectory(): bool

Проверяет, является ли текущая запись директорией.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false` в зависимости от результата.

### Примечания

Функция доступна с версии 2.0.0, а для более ранних версий можно проверять атрибуты записи (Работает только для файлов, сжатых в RAR для Windows или Unix):

    <?php
    //...
    //Откроем файл, получим запись и сохраним в переменной $e...
    //...

    $isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
        (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
    ?>

# RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — Проверяет, зашифрована ли запись

### Описание

public function RarEntry::isEncrypted(): bool

Проверяет, зашифрована ли текущая запись.

> Замечание: В одном и том же архиве для разных файлов могут использоваться разные пароли.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false` в зависимости от результата.

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — Получить текстовое представление записи

### Описание

public function RarEntry::__toString(): string

RarEntry::__toString() возвращает текстовое представление для текущей записи. Оно будет содержать информацию о том, является ли запись файлом или директорией (символические ссылки и прочие специальные объекты будут считаться файлами), имя записи в кодировке UTF-8 и её контрольная сумма (CRC). Вид и содержание этой информации в будущем может измениться, так что не стоит на них полагаться.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Текстовое представление записи.

## Содержание

- RarEntry::extract — Извлекает элемент из архива
- RarEntry::getAttr — Возвращает атрибуты элемента архива
- RarEntry::getCrc — Возвращает CRC элемента архива
- RarEntry::getFileTime — Возвращает последнее время изменения элемента
- RarEntry::getHostOs — Возвращает оригинальную ОС элемента
- RarEntry::getMethod — Возвращает метод компрессии элемента
- RarEntry::getName — Возвращает имя элемента
- RarEntry::getPackedSize — Возвращает размер сжатого элемента
- RarEntry::getStream — Получить обработчик для записи
- RarEntry::getUnpackedSize — Возвращает размер элемента в распакованном состоянии
- RarEntry::getVersion — Возвращает минимальную версию программы RAR, необходимую для распаковки элемента
- RarEntry::isDirectory — Проверяет, является ли запись директорией
- RarEntry::isEncrypted — Проверяет, зашифрована ли запись
- RarEntry::__toString — Получить текстовое представление записи

# Класс RarException

(PECL rar >= 2.0.0)

## Введение

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

Используются следующие коды ошибок:

- -1 - ошибка вне библиотеки UnRAR
- 11 - недостаточно памяти
- 12 - неправильные данные
- 13 - неправильный архив
- 14 - неизвестный формат
- 15 - ошибка открытия файла
- 16 - ошибка создания файла
- 17 - ошибка закрытия файла
- 18 - ошибка чтения
- 19 - ошибка записи
- 20 - слишком маленький буфер
- 21 - неизвестная ошибка RAR
- 22 - требуется пароль

## Обзор класса

final class RarException extends Exception {
/* Методы */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — Проверить, будут ли функции возвращать ошибки или выбрасывать исключения

### Описание

public static function RarException::isUsingExceptions(): bool

Проверяет, будут ли функции RAR выбрасывать исключения или возвращать ошибки и вызывать предупреждения в большинстве случаев (не включая некоторые программные ошибки вроде передачи аргументов некорректных типов).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если используются исключения и `false`, если нет.

### Примеры

Пример #1 Пример использования RarException::isUsingExceptions()

    <?php
    //По умолчанию исключения не используются
    var_dump(RarException::isUsingExceptions());
    ?>

Вывод приведённого примера будет похож на:

    bool(false)

### Смотрите также

- RarException::setUsingExceptions() - Включить или отключить генерацию исключений вместо возвращения ошибок

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — Включить или отключить генерацию исключений вместо возвращения ошибок

### Описание

public static function RarException::setUsingExceptions(bool `$using_exceptions`): void

Если аргумент задан как `true`, то, вместо выдачи предупреждения и возврата ошибки, библиотека UnRAR будет выбрасывать исключение типа RarException в случае возникновения ошибки.

Также исключения будут выброшены в случае следующих ошибок, произошедших вне библиотеки (их код возврата должен быть равен -1):

- попытка произведения действий с закрытым объектом RarArchive или объектом RarEntry относящегося к первому;
- попытка извлечь отсутствующую запись с помощью RarArchive::getEntry().

### Список параметров

`using_exceptions`
  `true` для активации генерации исключений, `false` для деактивации (по умолчанию).

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования RarException::setUsingExceptions()

    <?php
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch);

    RarException::setUsingExceptions(true);
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch); //not reached
    ?>

Вывод приведённого примера будет похож на:

    bool(false)

    Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
    bool(false)
    bool(true)

    Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
    Stack trace:
    #0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
    #1 {main}
      thrown in C:\php_rar\trunk\tests\test.php on line 8

### Смотрите также

- RarException::isUsingExceptions() - Проверить, будут ли функции возвращать ошибки или выбрасывать исключения

## Содержание

- RarException::isUsingExceptions — Проверить, будут ли функции возвращать ошибки или выбрасывать исключения
- RarException::setUsingExceptions — Включить или отключить генерацию исключений вместо возвращения ошибок

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Примеры
- Rar
  - rar_wrapper_cache_stats — Кеш доступов и отказов обёртки URL
- RarArchive — Класс RarArchive
  - RarArchive::close — Закрывает RAR архив и освобождает все ресурсы
  - RarArchive::getComment — Получить текст комментария из архива RAR
  - RarArchive::getEntries — Возвращает полный список элементов из RAR архива
  - RarArchive::getEntry — Возвращает объект элемента из RAR архива
  - RarArchive::isBroken — Проверяет, не сломан ли архив (не завершён)
  - RarArchive::isSolid — Проверить, является ли архив сплошным
  - RarArchive::open — Открывает архив RAR
  - RarArchive::setAllowBroken — Открывать ли повреждённые архивы
  - RarArchive::__toString — Получить текстовое представление
- RarEntry — Класс RarEntry
  - RarEntry::extract — Извлекает элемент из архива
  - RarEntry::getAttr — Возвращает атрибуты элемента архива
  - RarEntry::getCrc — Возвращает CRC элемента архива
  - RarEntry::getFileTime — Возвращает последнее время изменения элемента
  - RarEntry::getHostOs — Возвращает оригинальную ОС элемента
  - RarEntry::getMethod — Возвращает метод компрессии элемента
  - RarEntry::getName — Возвращает имя элемента
  - RarEntry::getPackedSize — Возвращает размер сжатого элемента
  - RarEntry::getStream — Получить обработчик для записи
  - RarEntry::getUnpackedSize — Возвращает размер элемента в распакованном состоянии
  - RarEntry::getVersion — Возвращает минимальную версию программы RAR, необходимую для распаковки элемента
  - RarEntry::isDirectory — Проверяет, является ли запись директорией
  - RarEntry::isEncrypted — Проверяет, зашифрована ли запись
  - RarEntry::__toString — Получить текстовое представление записи
- RarException — Класс RarException
  - RarException::isUsingExceptions — Проверить, будут ли функции возвращать ошибки или выбрасывать исключения
  - RarException::setUsingExceptions — Включить или отключить генерацию исключений вместо возвращения ошибок

# Zip

# Введение

Модуль позволяет легко читать и записывать как в сами сжатые ZIP-архивы, так и в файлы внутри них.

# Установка и настройка

## Содержание

- Требования
- Установка
- Типы ресурсов

## Требования

Для работы модуля требуется библиотека » libzip. Версию библиотеки 1.1.2 включали в PHP до версии 7.3.

Минимальная поддерживаемая версия — 0.11, но настоятельно рекомендуется использовать более новую версию.

- Для поддержки шифрования требуется версия 1.2, смотрите описание метода ZipArchive::setEncryptionIndex()
- Для поддержки прогресса требуется версия 1.3, смотрите описание метода ZipArchive::registerProgressCallback()
- Для поддержки отмены требуется версия 1.6, смотрите описание метода ZipArchive::registerCancelCallback()

## Установка

## Системы Linux

Доступ к этим функциям открывается только в PHP, который скомпилировали через параметр конфигурации --with-zip для поддержки модуля ZIP.

До PHP 7.4.0 модуль libzip входил в состав PHP, и для компиляции модуля требовался параметр конфигурации --enable-zip. Начиная с PHP 7.3.0 сборка со встроенным модулем libzip не рекомендуется, но всё ещё доступна при добавлении параметра --without-libzip.

Разработчики добавили параметр конфигурации --with-libzip=DIR, для системной установки модуля libzip. Требование к минимальной версии модуля — libzip 0.11, а рекомендуется версия 0.11.2 или новее.

## Windows

Начиная с PHP 8.2.0 модуль будет работать, только если DLL-библиотеку php_zip.dll включили в файле php.ini. Раньше этот модуль встраивался в PHP.

## Установка через репозиторий PECL

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/zip.

## Типы ресурсов

В Zip-модуле используются два типа ресурсов. Первый — директория Zip для Zip-архива, второй — Zip Entry для записей архива.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Класс ZipArchive использует константы класса. В классе предусмотрели константы разных типов, основные из которых: Глобальные флаги (префикс `AFL_`), флаги (префикс `FL_`), ошибки (префикс `ER_`) и константы режима работы (без префикса).

Режимы открытия архива
`ZipArchive::CREATE` (int)
  Создавать архив, если он не существует.
`ZipArchive::OVERWRITE` (int)
  Если архив существует, игнорировать текущее содержимое архива. Говоря по-другому, обработать его так же, как и пустой архив.
`ZipArchive::EXCL` (int)
  Выводить ошибку, если архив существует.
`ZipArchive::RDONLY` (int)
  Открыть архив в режиме только для чтения. Доступно с PHP 7.4.3 и PECL zip 1.17.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::CHECKCONS` (int)
  Выполнять дополнительные проверки согласованности архива и выдавать ошибку при неудаче.

Глобальные флаги архива
`ZipArchive::AFL_RDONLY` (int)
  Архив доступен только для чтения, очистить его нельзя. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собрано с модулем libzip ≥ 1.10.0.
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  Текущий архив записан в формате torrentzip. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собран с модулем libzip ≥ 1.10.0.
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  Запись архива в формате torrentzip. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собран с модулем libzip ≥ 1.10.0.
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  Не удалять файл, если архив пуст. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собран с модулем libzip ≥ 1.10.0.

Флаги архива
`ZipArchive::FL_NOCASE` (int)
  Игнорировать регистр символов в именах элементов архива.
`ZipArchive::FL_NODIR` (int)
  Не учитывать пути директорий в архиве.
`ZipArchive::FL_COMPRESSED` (int)
  Читать сжатые данные.
`ZipArchive::FL_UNCHANGED` (int)
  Использовать исходные данные, игнорируя изменения.
`ZipArchive::FL_RECOMPRESS` (int)
  Принудительно повторять сжатие данных. Доступно с PHP 8.0.0 и PECL zip 1.18.0. Объявлено устаревшим с PHP 8.3.0 и PECL zip 1.22.1, будет удалено в будущей версии модуля libzip.
`ZipArchive::FL_ENCRYPTED` (int)
  Читать зашифрованные данных (подразумевается FL_COMPRESSED). Доступно с PHP 8.0.0 и PECL zip 1.18.0.
`ZipArchive::FL_OVERWRITE` (int)
  Если файл с именем существует, перезаписать (заменить) его. Доступно с PHP 8.0.0 и PECL zip 1.18.0.
`ZipArchive::FL_LOCAL` (int)
  В локальном заголовке. Доступно с PHP 8.0.0 и PECL zip 1.18.0.
`ZipArchive::FL_CENTRAL` (int)
  В центральном каталоге. Доступно с PHP 8.0.0 и PECL zip 1.18.0.
`ZipArchive::FL_ENC_GUESS` (int)
  Угадать кодировку строки (по умолчанию). Доступно с PHP 7.0.8.
`ZipArchive::FL_ENC_RAW` (int)
  Взять немодифицированную строку. Доступно с PHP 7.0.8.
`ZipArchive::FL_ENC_STRICT` (int)
  Строго следовать спецификации. Доступно с PHP 7.0.8.
`ZipArchive::FL_ENC_UTF_8` (int)
  Строка в кодировке UTF-8. Доступно с PHP 7.0.8.
`ZipArchive::FL_ENC_CP437` (int)
  Строка в кодировке CP437. Доступно с PHP 7.0.8.
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  Открывать файл при добавлении вместо того, чтобы ждать закрытия архива. Помните о потреблении файловых дескрипторов. Доступно с PHP 8.3.0 и PECL zip 1.22.1.

Режимы сжатия
`ZipArchive::CM_DEFAULT` (int)
  Выбрать лучший метод сжатия "deflate" или "stored" (без сжатия).
`ZipArchive::CM_STORE` (int)
  Применять метод сжатия "stored" (без сжатия).
`ZipArchive::CM_SHRINK` (int)
  Применять метод сжатия "shrunk".
`ZipArchive::CM_REDUCE_1` (int)
  Применять метод сжатия "reduced" с коэффициентом 1.
`ZipArchive::CM_REDUCE_2` (int)
  Применять метод сжатия "reduced" с коэффициентом 2.
`ZipArchive::CM_REDUCE_3` (int)
  Применять метод сжатия "reduced" с коэффициентом 3.
`ZipArchive::CM_REDUCE_4` (int)
  Применять метод сжатия "reduced" с коэффициентом 4.
`ZipArchive::CM_IMPLODE` (int)
  Применять метод сжатия "imploded".
`ZipArchive::CM_DEFLATE` (int)
  Применять метод сжатия "deflated".
`ZipArchive::CM_DEFLATE64` (int)
  Применять метод сжатия "deflate64".
`ZipArchive::CM_PKWARE_IMPLODE` (int)
  Применять метод сжатия "PKWARE imploding".
`ZipArchive::CM_BZIP2` (int)
  Применять метод сжатия алгоритмом BZIP2.
`ZipArchive::CM_LZMA` (int)
  Применять метод сжатия алгоритмом LZMA.
`ZipArchive::CM_LZMA2` (int)
  Применять метод сжатия алгоритмом LZMA2. Доступно с PHP 7.4.3 и PECL zip 1.16.0, соответственно, если скомпилировано с модулем libzip ≥ 1.6.0.
`ZipArchive::CM_ZSTD` (int)
  Применять метод сжатия алгоритмом Zstandard. Доступно с PHP 8.0.0 и PECL zip 1.19.1, соответственно, если скомпилировано с модулем libzip ≥ 1.8.0.
`ZipArchive::CM_XZ` (int)
  Применять метод сжатия алгоритмом XZ. Доступно с PHP 7.4.3 и PECL zip 1.16.0, соответственно, если скомпилировано с модулем libzip ≥ 1.6.0.
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

Ошибки
`ZipArchive::ER_OK` (int)
  Нет ошибок.
`ZipArchive::ER_MULTIDISK` (int)
  Многотомный ZIP-архив не поддерживается.
`ZipArchive::ER_RENAME` (int)
  Переименование временного файла не удалось.
`ZipArchive::ER_CLOSE` (int)
  Закрытие ZIP-архива не удалось.
`ZipArchive::ER_SEEK` (int)
  Ошибка поиска.
`ZipArchive::ER_READ` (int)
  Ошибка чтения.
`ZipArchive::ER_WRITE` (int)
  Ошибка записи.
`ZipArchive::ER_CRC` (int)
  Ошибка контрольной суммы.
`ZipArchive::ER_ZIPCLOSED` (int)
  Открытый ZIP-архив был закрыт.
`ZipArchive::ER_NOENT` (int)
  Нет такого файла.
`ZipArchive::ER_EXISTS` (int)
  Файл уже существует.
`ZipArchive::ER_OPEN` (int)
  Невозможно открыть файл.
`ZipArchive::ER_TMPOPEN` (int)
  Не удалось создать временный файл.
`ZipArchive::ER_ZLIB` (int)
  Ошибка Zlib.
`ZipArchive::ER_MEMORY` (int)
  Ошибка выделения памяти.
`ZipArchive::ER_CHANGED` (int)
  Запись была изменена.
`ZipArchive::ER_COMPNOTSUPP` (int)
  Метод сжатия не поддерживается.
`ZipArchive::ER_EOF` (int)
  Преждевременный конец файла.
`ZipArchive::ER_INVAL` (int)
  Недопустимый аргумент.
`ZipArchive::ER_NOZIP` (int)
  Не ZIP-архив.
`ZipArchive::ER_INTERNAL` (int)
  Внутренняя ошибка.
`ZipArchive::ER_INCONS` (int)
  ZIP-архив несовместим.
`ZipArchive::ER_REMOVE` (int)
  Невозможно удалить файл.
`ZipArchive::ER_DELETED` (int)
  Запись была удалена.
`ZipArchive::ER_ENCRNOTSUPP` (int)
  Метод шифрования не поддерживается. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно.
`ZipArchive::ER_RDONLY` (int)
  Архив только для чтения. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно.
`ZipArchive::ER_NOPASSWD` (int)
  Пароль не указан. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно.
`ZipArchive::ER_WRONGPASSWD` (int)
  Предоставлен неверный пароль. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно.
`ZipArchive::ER_OPNOTSUPP` (int)
  Операция не поддерживается. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::ER_INUSE` (int)
  Ресурс всё ещё используется. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::ER_TELL` (int)
  Указана ошибка. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::ER_COMPRESSED_DATA` (int)
  Сжатые данные неверны. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::ER_CANCELLED` (int)
  Операция отменена. Доступно с PHP 7.4.3 и PECL zip 1.16.1, соответственно, если скомпилировано с модулем libzip ≥ 1.0.0.
`ZipArchive::ER_DATA_LENGTH` (int)
  Неожиданная длина данных. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собран с модулем libzip ≥ 1.10.0.
`ZipArchive::ER_NOT_ALLOWED` (int)
  Не допускается в torrentzip. Доступно с PHP 8.3.0 и PECL zip 1.22.0, соответственно, если собран с модулем libzip ≥ 1.10.0.
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  Возможно, усеченный или поврежденный zip-архив. Константа доступна с PHP 8.4.0 и PECL-модуля zip 1.22.4, если модуль собрали с библиотекой libzip ≥ 1.11.1.

Режимы шифрования
`ZipArchive::EM_NONE` (int)
  Без шифрования. Доступно с PHP 7.2.0 и PECL zip 1.14.0, соответственно, если скомпилировано с модулем libzip ≥ 1.2.0.
`ZipArchive::EM_TRAD_PKWARE` (int)
  Традиционное шифрование PKWARE. Доступно с PHP 8.0.0 и PECL zip 1.19.0.
`ZipArchive::EM_AES_128` (int)
  Шифрование AES 128. Доступно с PHP 7.2.0 и PECL zip 1.14.0, соответственно, если скомпилировано с модулем libzip ≥ 1.2.0.
`ZipArchive::EM_AES_192` (int)
  Шифрование AES 192. Доступно с PHP 7.2.0 и PECL zip 1.14.0, соответственно, если скомпилировано с модулем libzip ≥ 1.2.0.
`ZipArchive::EM_AES_256` (int)
  Шифрование AES 256. Доступно с PHP 7.2.0 и PECL zip 1.14.0, соответственно, если скомпилировано с модулем libzip ≥ 1.2.0.
`ZipArchive::EM_UNKNOWN` (int)
  Без шифрования. Доступно с PHP 8.0.0 и PECL zip 1.19.0.

Константы параметров длины
`ZipArchive::LENGTH_TO_END` (int)
  Использовать размер файла, если файл увеличивается, дополнительные данные будут проигнорированы, если файл уменьшается, возникнет ошибка (`ZipArchive::ER_DATA_LENGTH`). Доступно с PHP 8.3.0 и PECL zip 1.22.2.
`ZipArchive::LENGTH_UNCHECKED` (int)
  Использовать все доступные данные. Доступно с PHP 8.3.0 и PECL zip 1.22.2, если собрано с модулем libzip ≥ 1.10.1.

Другие константы
`ZipArchive::LIBZIP_VERSION` (string)
  Версия библиотеки Zip. Доступно с PHP 7.4.3 и PECL zip 1.16.0.

Константы операционной системы для внешних атрибутов
`ZipArchive::OPSYS_DOS` (int)
`ZipArchive::OPSYS_AMIGA` (int)
`ZipArchive::OPSYS_OPENVMS` (int)
`ZipArchive::OPSYS_UNIX` (int)
`ZipArchive::OPSYS_VM_CMS` (int)
`ZipArchive::OPSYS_ATARI_ST` (int)
`ZipArchive::OPSYS_OS_2` (int)
`ZipArchive::OPSYS_MACINTOSH` (int)
`ZipArchive::OPSYS_Z_SYSTEM` (int)
`ZipArchive::OPSYS_CPM` (int)
`ZipArchive::OPSYS_WINDOWS_NTFS` (int)
`ZipArchive::OPSYS_MVS` (int)
`ZipArchive::OPSYS_VSE` (int)
`ZipArchive::OPSYS_ACORN_RISC` (int)
`ZipArchive::OPSYS_VFAT` (int)
`ZipArchive::OPSYS_ALTERNATE_MVS` (int)
`ZipArchive::OPSYS_BEOS` (int)
`ZipArchive::OPSYS_TANDEM` (int)
`ZipArchive::OPSYS_OS_400` (int)
`ZipArchive::OPSYS_OS_X` (int)
`ZipArchive::OPSYS_DEFAULT` (int)
  Начиная с PECL zip 1.12.4

# Примеры

Пример #1 Создание Zip-архива

    <?php

    $zip = new ZipArchive();
    $filename = "./test112.zip";

    if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
        exit("Невозможно открыть <$filename>\n");
    }

    $zip->addFromString("testfilephp.txt" . time(), "#1 Это тестовая строка добавляется в качестве testfilephp.txt.\n");
    $zip->addFromString("testfilephp2.txt" . time(), "#2 Это тестовая строка добавляется в качестве testfilephp2.txt.\n");
    $zip->addFile($thisdir . "/too.php","/testfromfile.php");
    echo "numfiles: " . $zip->numFiles . "\n";
    echo "status:" . $zip->status . "\n";
    $zip->close();
    ?>

Пример #2 Собрать и отобразить подробную информацию об архиве

    <?php
    $za = new ZipArchive();

    $za->open('test_with_comment.zip');
    print_r($za);
    var_dump($za);
    echo "numFiles: " . $za->numFiles . "\n";
    echo "status: " . $za->status  . "\n";
    echo "statusSys: " . $za->statusSys . "\n";
    echo "filename: " . $za->filename . "\n";
    echo "comment: " . $za->comment . "\n";

    for ($i=0; $i<$za->numFiles;$i++) {
        echo "index: $i\n";
        print_r($za->statIndex($i));
    }
    echo "numFile:" . $za->numFiles . "\n";
    ?>

Пример #3 Использование обёртки потока Zip, чтение метаинформации OpenOffice

    <?php
    $reader = new XMLReader();

    $reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
    $odt_meta = array();
    while ($reader->read()) {
        if ($reader->nodeType == XMLREADER::ELEMENT) {
            $elm = $reader->name;
        } else {
            if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
                break;
            }
            if (!trim($reader->value)) {
                continue;
            }
            $odt_meta[$elm] = $reader->value;
        }
    }
    print_r($odt_meta);
    ?>

Этот пример использует старую версию API (PHP 4), он открывает ZIP-архив, читает каждый файл в архиве и выводит его содержимое. Архив test2.zip, использованный в этом примере, является одним из тестовых архивов исходного дистрибутива ZZIPlib.

Пример #4 Пример использования Zip

    <?php

    $zip = zip_open("/tmp/test2.zip");

    if ($zip) {
        while ($zip_entry = zip_read($zip)) {
            echo "Название:         " . zip_entry_name($zip_entry) . "\n";
            echo "Исходный размер:  " . zip_entry_filesize($zip_entry) . "\n";
            echo "Сжатый размер:    " . zip_entry_compressedsize($zip_entry) . "\n";
            echo "Метод сжатия:     " . zip_entry_compressionmethod($zip_entry) . "\n";

            if (zip_entry_open($zip, $zip_entry, "r")) {
                echo "Содержимое файла:\n";
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                echo "$buf\n";

                zip_entry_close($zip_entry);
            }
            echo "\n";

        }

        zip_close($zip);

    }
    ?>

# Класс ZipArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## Введение

Файловый архив, сжатый Zip.

## Обзор класса

class ZipArchive implements Countable {
/* Константы */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int ER_TRUNCATED_ZIP;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* Свойства */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* Методы */
public function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter]string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function unchangeName(string `$name`): bool
}

## Свойства

lastId
  Значение индекса последней добавленной записи (файл или каталог). Доступно с PHP 8.0.0 и PECL zip 1.18.0.
status
  Статус Zip-архива. Доступно для закрытого архива, начиная с PHP 8.0.0 и PECL zip 1.18.0.
statusSys
  Системный статус Zip-архива. Доступно для закрытого архива, начиная с PHP 8.0.0 и PECL zip 1.18.0.
numFiles
  Количество файлов в архиве
filename
  Имя файла в файловой системе
comment
  Комментарий к архиву

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Добавляет новую директорию

### Описание

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Метод добавляет пустую директорию в архив.

### Список параметров

`dirname`
  Директория, которую требуется добавить.
`flags`
  Битовая маска, которая состоит из следующих констант: `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Поведение констант описыват страница «ZIP-константы».

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL-модуль zip 1.18.0 | Добавили параметр `flags`.

### Примеры

Пример #1 Пример добавления новой директории в архив

    <?php

    $zip = new ZipArchive();

    if ($zip->open('test.zip') === true) {
        if ($zip->addEmptyDir('newDirectory')) {
            echo 'Создана новая директория';
        } else {
            echo 'Невозможно создать директорию';
        }

        $zip->close();
    } else {
        echo 'ошибка';
    }

    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Добавляет в ZIP-архив файл по заданному пути

### Описание

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Добавляет в ZIP-архив файл по заданному пути.

> Замечание: Для максимальной переносимости, рекомендуется всегда пользоваться прямыми слешами `/` как разделителями директорий в именах файлов.

### Список параметров

`filepath`
  Путь к файлу, который требуется добавить.
`entryname`
  Имя файла внутри ZIP-архива. Параметр переопределит параметр `filepath`.
`start`
  Начальная позиция для частичного копирования.
`length`
  Длина, которую требуется скопировать при частичном копировании. Метод использует размер файла, если указали значение `ZipArchive::LENGTH_TO_END` (0). Метод использует весь файл начиная со значения параметра `start`, если указали значение `ZipArchive::LENGTH_UNCHECKED`.
`flags`
  Битовая маска из следующих значений: `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Поведение констант описывает страница «ZIP-константы».

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL-модуль zip 1.18.0 | Добавили параметр `flags`.
8.3.0, PECL-модуль zip 1.22.1 | Добавили константу `ZipArchive::FL_OPEN_FILE_NOW`.
8.3.0, PECL-модуль zip 1.22.2 | Добавили константы, которые устанавливают значение длины: `ZipArchive::LENGTH_TO_END` и `ZipArchive::LENGTH_UNCHECKED`.

### Примеры

В примере открывается файл ZIP-архива test.zip и в архив добавляется файл /path/to/index.txt с именем newname.txt.

Пример #1 Открыть и добавить

    <?php

    $zip = new ZipArchive();

    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/path/to/index.txt', 'newname.txt');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }

    ?>

### Примечания

> Замечание: При добавлении файла в архив PHP заблокирует файл. Разблокировка произойдёт только после закрытия объекта ZipArchive, путём вызова ZipArchive::close() или уничтожения объекта ZipArchive. Это предотвращает удаление файла, который только что добавили в архив, до того, как PHP разблокирует файл.

### Смотрите также

- ZipArchive::replaceFile() - Заменяет файл в ZIP-архиве файлом по заданному пути

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — Добавляет содержимое в ZIP-архив как файл

### Описание

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Метод добавляет содержимое в ZIP-архив как файл.

> Замечание: Для максимальной переносимости, рекомендуется всегда пользоваться прямыми слешами `/` как разделителями директорий в именах файлов.

### Список параметров

`name`
  Название записи, которую требуется создать.
`content`
  Содержимое в двоично безопасном режиме, из которого метод создаст файл в архиве.
`flags`
  Битовая маска из следующих констант: `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Поведение констант описывает страница «ZIP-константы».

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL-модуль zip 1.18.0 | Добавили параметр `flags`.

### Примеры

Пример #1 Пример добавления записи в новый архив

    <?php

    $zip = new ZipArchive();

    $res = $zip->open('test.zip', ZipArchive::CREATE);

    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'В этом аргументе передаётся содержимое файла');
        $zip->close();
        echo 'Готово';
    } else {
        echo 'Ошибка';
    }

    ?>

Пример #2 Пример добавления файла в каталог внутри архива

    <?php

    $zip = new ZipArchive();

    if ($zip->open('test.zip') === TRUE) {
        $zip->addFromString('dir/test.txt', 'В этом аргументе передаётся содержимое файла');
        $zip->close();
        echo 'Готово';
    } else {
        echo 'Ошибка';
    }

    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — Добавляет файлы из директории по glob-шаблону

### Описание

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Метод добавляет файлы из каталога, имена которых совпадают с glob-шаблоном `pattern`.

> Замечание: Для максимальной переносимости, рекомендуется всегда пользоваться прямыми слешами `/` как разделителями директорий в именах файлов.

### Список параметров

`pattern`
  Шаблон, с которым работает функция glob(), с которым метод сопоставит файлы.
`flags`
  Битовая маска флагов, с которыми работает функция `glob()`.
`options`

  Ассоциативный массив опций. Параметр принимает следующие значения:

  - `"add_path"` Префикс, который добавляется в начало при переводе в локальный путь файла в архиве. Метод применяет префикс после операций удаления, которые определили опциями `"remove_path"` или `"remove_all_path"`.
  - `"remove_path"` Префикс, который требуется удалить из путей файлов перед добавлением в архив.
  - `"remove_all_path"` Со значением `true` метод возьмёт только имя файла и добавит его в корень архива.
  - `"flags"` Битовая маска из следующих констант: `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Поведение констант описывает страница «ZIP-константы».
  - `"comp_method"` Метод сжатия. Опция принимает одну из констант `ZipArchive::CM_*`.
  - `"comp_flags"` Уровень сжатия.
  - `"enc_method"` Метод шифрования. Опция принимает одну из констант `ZipArchive::EM_*`.
  - `"enc_password"` Пароль для шифрования.

### Возвращаемые значения

В случае успешного выполнения метод возвращает массив (array) файлов, которые добавил в архив, или `false`, если возникла ошибка Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL-модуль zip 1.18.0 | Добавили опцию `"flags"` в параметр `options`.
8.0.0, PECL-модуль zip 1.18.1 | Добавили опции `"comp_method"`, `"comp_flags"`, `"enc_method"` и `"enc_password"` в параметр `options`.
8.3.0, PECL-модуль zip 1.22.1 | Добавили константу `ZipArchive::FL_OPEN_FILE_NOW`.

### Примеры

Пример #1 Пример добавления файлав архив по glob-шаблону методом ZipArchive::addGlob()

Добавить в архив PHP-скрипты и текстовые файлы из текущей директории.

    <?php

    $zip = new ZipArchive();

    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);

    if ($ret !== TRUE) {
        printf('Возникла ошибка с кодом %d', $ret);
    } else {
        $options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
        $zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
        $zip->close();
    }

    ?>

### Смотрите также

- ZipArchive::addFile() - Добавляет в ZIP-архив файл по заданному пути
- ZipArchive::addPattern() - Добавить файлы из директории в соответствии с шаблоном регулярного выражения PCRE

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — Добавить файлы из директории в соответствии с шаблоном регулярного выражения PCRE

### Описание

public function ZipArchive::addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false

Добавляет файлы из директории в соответствии с шаблоном регулярного выражения `pattern`. Операция не рекурсивна. Шаблон применяется только к именам файлов.

### Список параметров

`pattern`
  Шаблон PCRE.
`path`
  Директория для сканирования. По умолчанию выбирается текущая директория.
`options`
  Ассоциативный массив параметров, принимаемых ZipArchive::addGlob().

### Возвращаемые значения

Массив (array) добавленных файлов в случае успешного выполнения или `false`, если возникла ошибка

### Примеры

Пример #1 Пример использования ZipArchive::addPattern()

Добавить к архиву все текстовые файлы и файлы скриптов PHP из текущей директории

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Ошибка с кодом %d', $ret);
    } else {
        $directory = realpath('.');
        $options = array('add_path' => 'sources/', 'remove_path' => $directory);
        $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
        $zip->close();
    }
    ?>

### Смотрите также

- ZipArchive::addFile() - Добавляет в ZIP-архив файл по заданному пути
- ZipArchive::addGlob() - Добавляет файлы из директории по glob-шаблону

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — Удаляет сообщение об ошибке статуса, системные и/или сообщения модуля zip

### Описание

public function ZipArchive::clearError(): void

Удаляет сообщение об ошибке статуса, системные и/или сообщения модуля zip.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- ZipArchive::getStatusString() - Возвращает сообщение об ошибке состояния, сообщения системы и (или) ZIP-архива

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Закрывает активный архив (открытый или вновь созданный)

### Описание

public function ZipArchive::close(): bool

Метод закрывает открытый или созданный архив и сохраняет изменения. Метод автоматически вызывается в конце выполнения скрипта.

Если архив не содержит файлов, файл по умолчанию полностью удаляется (пустой архив не записывается) в соответствии со значением глобального флага `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ZipArchive::setArchiveFlag() - Устанавливает глобальный флаг ZIP-архива

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Подсчитывает количество файлов в архиве

### Описание

public function ZipArchive::count(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество файлов в архиве.

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — Удаляет элемент в архиве, используя его индекс

### Описание

public function ZipArchive::deleteIndex(int `$index`): bool

Удаляет элемент (файл или каталог) в архиве, используя его индекс.

### Список параметров

`index`
  Индекс элемента для удаления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Удалить файл из архива, используя его индекс

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Удаляет элемент в архиве, используя его имя

### Описание

public function ZipArchive::deleteName(string `$name`): bool

Удаляет элемент (файл или каталог) в архиве, используя его имя.

### Список параметров

`name`
  Имя элемента для удаления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Удалить файл и каталог из архива, используя имена

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — Извлекает содержимое архива

### Описание

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

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

Внимание

Разрешения по умолчанию для извлечённых файлов и каталогов дают максимально широкий доступ. Это можно ограничить, установив текущую маску разрешений umask функцией umask().

По соображениям безопасности исходные разрешения не восстанавливаются. Примеры того, как их восстановить, показаны на странице с описанием метода ZipArchive::getExternalAttributesIndex().

### Список параметров

`pathto`
  Директория, в которую нужно извлекать файлы.
`files`
  Элементы для извлечения. Может принимать как одно значение, так и массив записей.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Извлечь всё содержимое

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/my/destination/dir/');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

Пример #2 Извлечь два элемента

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

### Примечания

> Замечание: Файловые системы Windows NTFS не поддерживают некоторые символы в именах файлов — `<|>*?":`. Имена файлов с точкой в конце также не поддерживаются. В отличие от ряда инструментов извлечения, метод не поддерживает замену этих символов на подчёркивание, а вместо этого возникает ошибка при извлечении таких файлов.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Возвращает комментарий ZIP-архива

### Описание

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Возвращает комментарий ZIP-архива.

### Список параметров

`flags`
  Если флаг установлен в `ZipArchive::FL_UNCHANGED`, возвращается оригинальный неизмененный комментарий.

### Возвращаемые значения

Возвращает комментарий ZIP-архива или `false`, если возникла ошибка.

### Примеры

Пример #1 Вывести комментарий архива

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_with_comment.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* Или используя свойство */
        var_dump($zip->comment);
    } else {
        echo 'Ошибка с кодом:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Возвращает значение глобального флага ZIP-архива

### Описание

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

Метод возвращает значение глобального флага ZIP-архива.

### Список параметров

`flag`

  Глобальный флаг, который нужно получить, — значение из следующих `AFL_*`-констант:

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  Метод вернёт исходный неизменённый флаг, если значение флагов в параметре `flags` примет значение константы `ZipArchive::FL_UNCHANGED`.

### Возвращаемые значения

Метод возвращает 1, если флаг для архива установлен, 0, если нет, и -1 при ошибке.

### Примеры

Пример #1 Пример проверки того, содержится ли архив в формате torrentzip

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip');

    if ($res === true) {
        var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
    } else {
        echo 'Ошибка, код: ' . $res;
    }

    ?>

### Смотрите также

- ZipArchive::setArchiveFlag() - Устанавливает глобальный флаг ZIP-архива

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Возвращает комментарий элемента, используя его индекс

### Описание

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Возвращает комментарий элемента, используя его индекс.

### Список параметров

`index`
  Индекс записи.
`flags`
  Если флаг установлен в `ZipArchive::FL_UNCHANGED`, возвращается оригинальный неизмененный комментарий.

### Возвращаемые значения

Возвращает комментарий при успехе или `false`, если возникла ошибка.

### Примеры

Пример #1 Вывести комментарий элемента

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'Ошибка с кодом:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Возвращает комментарий элемента, используя его имя

### Описание

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Возвращает комментарий элемента, используя его имя.

### Список параметров

`name`
  Имя элемента.
`flags`
  Если флаг установлен в `ZipArchive::FL_UNCHANGED`, возвращается оригинальный неизмененный комментарий.

### Возвращаемые значения

Возвращает комментарий при успехе или `false`, если возникла ошибка.

### Примеры

Пример #1 Вывести комментарий элемента

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/entry1.txt'));
    } else {
        echo 'Ошибка с кодом:' . $res;
    }
    ?>

# ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — Извлекает внешние атрибуты записи по её индексу

### Описание

public function ZipArchive::getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Извлекает внешние атрибуты записи по её индексу.

### Список параметров

`index`
  Индекс записи.
`opsys`
  В случае успешного выполнения сюда записывается код операционной системы, заданный одной из констант ZipArchive::OPSYS_.
`attr`
  В случае успешного выполнения сюда записываются внешние атрибуты. Значения зависят от операционной системы.
`flags`
  Если задано как `ZipArchive::FL_UNCHANGED`, будут возвращены оригинальные неизмененные атрибуты.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

В этом примере метод извлекает все файлы из ZIP-архива test.zip и устанавливает им права Unix, полученные из внешних атрибутов.

Пример #1 Извлекаем все записи с их правами Unix

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip') === TRUE) {
        for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
            if ($zip->extractTo('.', $s['name'])) {
                if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
                    && $opsys==ZipArchive::OPSYS_UNIX) {
                   chmod($s['name'], ($attr >> 16) & 0777);
                }
            }
        }
        $zip->close();
        echo "готово\n";
    } else {
        echo "ошибка\n";
    }
    ?>

# ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — Извлечь внешние атрибуты записи по её имени

### Описание

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Извлекает внешние атрибуты записи по её имени.

### Список параметров

`name`
  Имя записи.
`opsys`
  В случае успешного выполнения сюда записывается код операционной системы, заданный одной из констант ZipArchive::OPSYS_.
`attr`
  В случае успешного выполнения сюда записываются внешние атрибуты. Значения зависят от операционной системы.
`flags`
  Если задано как `ZipArchive::FL_UNCHANGED`, будут возвращены оригинальные неизмененные атрибуты.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Возвращает содержимое элемента по его индексу

### Описание

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Возвращает содержимое элемента по его индексу.

### Список параметров

`index`
  Индекс элемента.
`len`
  Размер читаемых данных из элемента. Если `0`, содержимое читается полностью.
`flags`

  Флаги используемые для открытия архива. Может быть установлено только одно нижеприведённое значение.

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`

### Возвращаемые значения

Возвращает содержимое элемента при успехе или `false`, если возникла ошибка.

### Примеры

Пример #1 Получить содержимое файла

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'ошибка';
    }
    ?>

### Смотрите также

- ZipArchive::getFromName() - Возвращает содержимое элемента по его имени

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Возвращает содержимое элемента по его имени

### Описание

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Возвращает содержимое элемента по его имени.

### Список параметров

`name`
  Имя элемента.
`len`
  Размер читаемых данных из элемента. Если `0`, содержимое читается полностью.
`flags`

  Флаги используемые для поиска записи. Следующие значения могут быть присоединены (побитовое ИЛИ).

  - `ZipArchive::FL_UNCHANGED`
  - `ZipArchive::FL_COMPRESSED`
  - `ZipArchive::FL_NOCASE`

### Возвращаемые значения

Возвращает содержимое элемента при успехе или `false`, если возникла ошибка.

### Примеры

Пример #1 Получить содержимое файла

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'ошибка';
    }
    ?>

Пример #2 Преобразовать изображении из ZIP-элемента

    <?php
    $z = new ZipArchive();
    if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
        $im_string = $z->getFromName("pear_item.gif");
        $im = imagecreatefromstring($im_string);
        imagepng($im, 'b.png');
    }
    ?>

### Смотрите также

- ZipArchive::getFromIndex() - Возвращает содержимое элемента по его индексу

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Возвращает имя элемента по его индексу

### Описание

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Возвращает имя элемента по его индексу.

### Список параметров

`index`
  Индекс элемента.
`flags`
  Если флаг установлен в `ZipArchive::FL_UNCHANGED`, возвращается оригинальное неизмененное имя.

### Возвращаемые значения

Возвращает имя при успехе или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования ZipArchive::getNameIndex()

    <?php
    if ($zip->open('test.zip') == TRUE) {
     for ($i = 0; $i < $zip->numFiles; $i++) {
         $filename = $zip->getNameIndex($i);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — Возвращает сообщение об ошибке состояния, сообщения системы и (или) ZIP-архива

### Описание

public function ZipArchive::getStatusString(): string

Метод возвращает сообщение об ошибке состояния, сообщения системы и (или) ZIP-архива

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строку (string) с сообщением о состоянии.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL-модуль zip 1.18.0 | Разрешили вызвать метод на закрытом архиве.
8.0.0, PECL-модуль zip 1.18.0 | Метод больше не возвращает `false`, если возникла ошибка.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Получить дескриптор файла элемента, определённый по имени элемента (только для чтения)

### Описание

public function ZipArchive::getStream(string `$name`): resource|false

Получить дескриптор файла, определённый по имени элемента. На данный момент поддерживаются только операции чтения.

### Список параметров

`name`
  Используемое имя элемента.

### Возвращаемые значения

Возвращает файловый указатель (ресурс) в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Получить содержимое элемента при помощи fread() и сохранить его

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("ошибка\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "готово.\n";
    }
    ?>

Пример #2 То же, что и в предыдущем примере, но используя fopen() и через обёртку zip-потока

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("Не получается открыть\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "Готово.\n";
    ?>

Пример #3 ZIP-поток и изображение могут быть использованы также в функции XML

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### Смотрите также

- ZipArchive::getStreamIndex() - Получает обработчик файла для записи, определённой её индексом (только для чтения)
- ZipArchive::getStreamName() - Получает обработчик файла для записи, определённой её именем (только для чтения)
- Сжатые потоки

# ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — Получает обработчик файла для записи, определённой её индексом (только для чтения)

### Описание

public function ZipArchive::getStreamIndex(int `$index`, int `$flags` = 0): resource|false

Получает обработчик файла для записи, определённой её индексом. На данный момент метод поддерживает только операции чтения.

### Список параметров

`index`
  Индекс записи.
`flags`
  Если в flags установлена константа `ZipArchive::FL_UNCHANGED`, возвращается исходный неизмененный поток.

### Возвращаемые значения

В случае успешного выполнения возвращает указатель на файл (ресурс) или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение и сохранение содержимого записи с помощью fread()

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Смотрите также

- ZipArchive::getStreamName() - Получает обработчик файла для записи, определённой её именем (только для чтения)

# ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — Получает обработчик файла для записи, определённой её именем (только для чтения)

### Описание

public function ZipArchive::getStreamName(string `$name`, int `$flags` = 0): resource|false

Получает обработчик файла для записи, определённой её именем. На данный момент метод поддерживает только операции чтения.

### Список параметров

`name`
  Имя записи для использования.
`flags`
  Если в flags установлена константа `ZipArchive::FL_UNCHANGED`, возвращается исходный неизмененный поток.

### Возвращаемые значения

В случае успешного выполнения возвращает указатель на файл (ресурс) или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение и сохранение содержимого записи с помощью fread()

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Смотрите также

- ZipArchive::getStreamIndex() - Получает обработчик файла для записи, определённой её индексом (только для чтения)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — Проверяет, поддерживается ли метод сжатия libzip

### Описание

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Проверяет, поддерживается ли метод сжатия libzip.

### Список параметров

`method`
  Метод сжатия, одна из констант `ZipArchive::CM_*`.
`enc`
  Если `true` проверка на сжатие, иначе проверка на декомпрессию.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание: Функция доступна только в том случае, если PHP собран с libzip ≥ 1.7.0.

### Смотрите также

- ZipArchive::setCompressionIndex() - Устанавливает метод сжатия записи по индексу
- ZipArchive::setCompressionName() - Установить метод сжатия записи, заданной по имени

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — Проверяет, поддерживается ли метод шифрования libzip

### Описание

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Проверяет, поддерживается ли метод шифрования libzip.

### Список параметров

`method`
  Метод шифрования, одна из констант `ZipArchive::EM_*`.
`enc`
  Если `true` проверка шифрования, иначе проверка расшифровки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание: Функция доступна только в том случае, если PHP собран с libzip ≥ 1.7.0.

### Смотрите также

- ZipArchive::setEncryptionIndex() - Устанавливает метод шифрования записи по индексу
- ZipArchive::setEncryptionName() - Устанавливает метод шифрования записи по имени

# ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — Возвращает индекс элемента в архиве

### Описание

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Находит элемент по имени.

### Список параметров

`name`
  Имя элемента для поиска.
`flags`

  Флаги — значение, которое определили следующими константами через побитовое ИЛИ, или 0 ни для одного из них.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`

### Возвращаемые значения

Метод возвращает индекс элемента в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Создать архив, а затем вызвать метод ZipArchive::locateName()

    <?php

    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('Ошибка');
    }

    $zip->addFromString('entry1.txt', 'entry #1');
    $zip->addFromString('entry2.txt', 'entry #2');
    $zip->addFromString('dir/entry2d.txt', 'entry #2');

    if ($zip->status !== ZipArchive::ER_OK) {
        echo "Ошибка записи в zip-файл\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('Ошибка');
    }

    echo $zip->locateName('entry1.txt') . "\n";
    echo $zip->locateName('eNtry2.txt') . "\n";
    echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

Результат выполнения приведённого примера:

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Открывает ZIP-архив

### Описание

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Метод открывает новый или существующий ZIP-архив для чтения, записи или изменения.

Начиная с libzip 1.6.0 метод оценивает пустой файл как недопустимый архив.

### Список параметров

`filename`
  Имя ZIP-архива для открытия.
`flags`

  Используемый режим открытия файлов.

  - `ZipArchive::OVERWRITE`
  - `ZipArchive::CREATE`
  - `ZipArchive::RDONLY`
  - `ZipArchive::EXCL`
  - `ZipArchive::CHECKCONS`

### Возвращаемые значения

Метод возвращает `true` в случае успешного выполнения, `false` или код ошибки из следующих констант:

`ZipArchive::ER_EXISTS`
  Файл уже существует.
`ZipArchive::ER_INCONS`
  Несовместимый ZIP-архив.
`ZipArchive::ER_INVAL`
  Недопустимый аргумент.
`ZipArchive::ER_MEMORY`
  Ошибка динамического выделения памяти.
`ZipArchive::ER_NOENT`
  Нет такого файла.
`ZipArchive::ER_NOZIP`
  Не является ZIP-архивом.
`ZipArchive::ER_OPEN`
  Невозможно открыть файл.
`ZipArchive::ER_READ`
  Ошибка чтения.
`ZipArchive::ER_SEEK`
  Ошибка поиска.

### Примеры

Пример #1 Открыть и извлечь

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip');

    if ($res === true) {
        echo 'Готово';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'Ошибка, код:' . $res;
    }

    ?>

Пример #2 Создать архив

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip', ZipArchive::CREATE);

    if ($res === true) {
        $zip->addFromString('test.txt', 'содержимое файла');
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'Готово';
    } else {
        echo 'Ошибка';
    }

    ?>

Пример #3 Создать временный архив

    <?php

    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive();
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* Усечение, поскольку пустой файл недопустим */

    if ($res === true) {
        $zip->addFile('data.txt', 'entryname.txt');
        $zip->close();
        echo 'Готово';
    } else {
        echo 'Ошибка';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Регистрирует callback-функцию для разрешения отмены во время закрытия архива

### Описание

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Регистрирует `callback`-функцию для разрешения отмены во время закрытия архива.

### Список параметров

`callback`
  Если функция вернёт 0, операция продолжится, при другом значении она будет отменена.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

В этом примере создаётся ZIP-архив php.zip и отменяется операция при некоторых условиях запуска.

Пример #1 Архивация файла

    <?php
    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerCancelCallback(function () {
            return ($someruncondition ? -1 : 0);
        });
        $zip->close();
    }

### Примечания

> Замечание: Функция доступна, если PHP скомпилирован с libzip ≥ 1.6.0.

### Смотрите также

- ZipArchive::registerProgressCallback() - Регистрирует callback-функцию для предоставления обновлений при закрытии архива

# ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — Регистрирует callback-функцию для предоставления обновлений при закрытии архива

### Описание

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Регистрирует `callback`-функцию для предоставления обновлений при закрытии архива.

### Список параметров

`rate`
  Изменение между каждым вызовом callback-функции (от 0,0 до 1,0).
`callback`
  Функция будет получать текущее состояние (`state`) в виде числа с плавающей точкой (float) (от 0,0 до 1,0).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

В этом примере создаётся ZIP-архив php.zip и отображается прогрессия.

Пример #1 Архивация файла

    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerProgressCallback(0.05, function ($r) {
            printf("%d%%\n", $r * 100);
        });
        $zip->close();
    }

### Примечания

> Замечание: Функция доступна, если PHP скомпилирован с libzip ≥ 1.6.0.

### Смотрите также

- ZipArchive::registerCancelCallback() - Регистрирует callback-функцию для разрешения отмены во время закрытия архива

# ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — Переименовывает элемент по его индексу

### Описание

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Переименовывает элемент по его индексу.

### Список параметров

`index`
  Индекс элемента для переименования.
`new_name`
  Новое имя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Переименование одного элемента

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'newname.txt');
        $zip->close();
    } else {
        echo 'ошибка с кодом:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Переименовывает элемент по его имени

### Описание

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Переименовывает элемент, заданный по имени.

### Список параметров

`name`
  Имя элемента для переименования.
`new_name`
  Новое имя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Переименование одного элемента

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('currentname.txt','newname.txt');
        $zip->close();
    } else {
        echo 'ошибка с кодом:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Заменяет файл в ZIP-архиве файлом по заданному пути

### Описание

public function ZipArchive::replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool

Метод заменяет файл в ZIP-архиве файлом по заданному пути.

> Замечание: Для максимальной переносимости, рекомендуется всегда пользоваться прямыми слешами `/` как разделителями директорий в именах файлов.

### Список параметров

`filepath`
  Путь к файлу, который требуется добавить.
`index`
  Индекс файла, который заменит метод; метод не изменит название файла.
`start`
  Начальная позиция для частичного копирования.
`length`
  Длина, которую требуется скопировать при частичном копировании, если указали значение `ZipArchive::LENGTH_TO_END` (0), метод использует размер файла, если указали значение `ZipArchive::LENGTH_UNCHECKED`, метод использует весь файл начиная со значения параметра `start`.
`flags`
  Битовая маска из следующих значений: `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Поведение констант описывает страница «ZIP-константы».

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0, PECL-модуль zip 1.22.1 | Добавили константу `ZipArchive::FL_OPEN_FILE_NOW`.
8.3.0, PECL-модуль zip 1.22.2 | Добавили константы, которые задают значение длины: `ZipArchive::LENGTH_TO_END` и `ZipArchive::LENGTH_UNCHECKED`.

### Примеры

В примере открывается файл ZIP-архива test.zip и запись с индексом 1 заменяется на файл по пути /path/to/index.txt.

Пример #1 Пример открытия и замены файла

    <?php

    $zip = new ZipArchive();

    if ($zip->open('test.zip') === TRUE) {
        $zip->replaceFile('/path/to/index.txt', 1);
        $zip->close();
        echo 'Готово';
    } else {
        echo 'Ошибка';
    }

    ?>

### Смотрите также

- ZipArchive::addFile() - Добавляет в ZIP-архив файл по заданному пути

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Устанавливает комментарий к ZIP-архиву

### Описание

public function ZipArchive::setArchiveComment(string `$comment`): bool

Устанавливает комментарий к ZIP-архиву.

### Список параметров

`comment`
  Содержание комментария.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Создание архива и установка комментария

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'содержимое файла');
        $zip->setArchiveComment('новый комментарий архива');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Устанавливает глобальный флаг ZIP-архива

### Описание

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

Метод устанавливает глобальный флаг ZIP-архива.

### Список параметров

`flag`

  Глобальный флаг, который нужно изменить, — значение из следующих `AFL_*`-констант:

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  Новое значение флага.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Создать архив torrentzip

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip', ZipArchive::CREATE);

    if ($res === true) {
        $zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
        $zip->addFromString('test.txt', 'содержимое файла');
        $zip->close();
        echo 'Успешное выполнение';
    } else {
        echo 'Ошибка';
    }

    ?>

### Смотрите также

- ZipArchive::getArchiveFlag() - Возвращает значение глобального флага ZIP-архива

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Устанавливает комментарий к элементу по его индексу

### Описание

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Устанавливает комментарий к элементу по его индексу.

### Список параметров

`index`
  Индекс элемента.
`comment`
  Содержание комментария.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Открывает архив и устанавливает комментарий к элементу

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'новая запись комментария');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Устанавливает комментарий к элементу, заданному по имени

### Описание

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Устанавливает комментарий к элементу, заданному по имени.

### Список параметров

`name`
  Имя элемента.
`comment`
  Содержание комментария.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Открытие архива и установка комментария к элементу

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('entry1.txt', 'новая запись комментария');
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Устанавливает метод сжатия записи по индексу

### Описание

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Метод устанавливает метод сжатия записи по индексу.

### Список параметров

`index`
  Индекс записи.
`method`
  Метод сжатия, константа семейства `ZipArchive::CM_*`.
`compflags`
  Уровень сжатия.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример добавления к архиву файлов с разными методами сжатия

    <?php

    $zip = new ZipArchive();

    $res = $zip->open('test.zip', ZipArchive::CREATE);

    if ($res === TRUE) {
        $zip->addFromString('foo', 'Какой-нибудь текст');
        $zip->addFromString('bar', 'Ещё какой-нибудь текст');
        $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
        $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
        $zip->close();

        echo 'Готово';
    } else {
        echo 'Ошибка';
    }

    ?>

# ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — Установить метод сжатия записи, заданной по имени

### Описание

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Устанавливает метод сжатия записи заданной по имени.

### Список параметров

`name`
  Имя записи.
`method`
  Метод сжатия, одна из констант `ZipArchive::CM_*`.
`compflags`
  Уровень сжатия.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Добавить к архиву файлы с разными методами сжатия

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Некоторый текст');
        $zip->addFromString('bar', 'Некоторый другой текст');
        $zip->setCompressionName('foo', ZipArchive::CM_STORE);
        $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

Пример #2 Добавить файл и установить метод сжатия

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFile('foo.jpg', 'bar.jpg');
        $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
        $zip->close();
        echo 'готово';
    } else {
        echo 'ошибка';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — Устанавливает метод шифрования записи по индексу

### Описание

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Метод устанавливает метод шифрования записи по индексу.

### Список параметров

`index`
  Индекс записи.
`method`
  Метод шифрования, заданный одной из констант ZipArchive::EM_.
`password`
  Пароль. Если не указывать, то будет использован пароль по умолчанию.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `password` теперь принимает значение null.

### Примечания

> Замечание: Функция доступна только если скомпилировали с модулем libzip ≥ 1.2.0.

### Смотрите также

- ZipArchive::setPassword() - Устанавливает пароля для активного архива
- ZipArchive::setEncryptionName() - Устанавливает метод шифрования записи по имени

# ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — Устанавливает метод шифрования записи по имени

### Описание

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Метод устанавливает метод шифрования записи по имени.

### Список параметров

`name`
  Имя записи.
`method`
  Метод шифрования, который задали одной из констант ZipArchive::EM_.
`password`
  Пароль. Если не указывать, то будет использован пароль по умолчанию.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `password` теперь принимает значение null.

### Примеры

В этом примере создаётся ZIP-архив test.zip, содержащий файл test.txt, зашифрованный с помощью AES 256.

Пример #1 Архивируем и шифруем файл

    <?php

    $zip = new ZipArchive();

    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->setPassword('secret');
        $zip->addFile('text.txt');
        $zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
        $zip->close();
        echo "готово\n";
    } else {
        echo "ошибка\n";
    }

    ?>

### Примечания

> Замечание: Функция доступна только если скомпилировано с модулем libzip ≥ 1.2.0.

### Смотрите также

- ZipArchive::setPassword() - Устанавливает пароля для активного архива
- ZipArchive::setEncryptionIndex() - Устанавливает метод шифрования записи по индексу

# ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — Установить внешние атрибуты записи по её индексу

### Описание

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Устанавливает внешние атрибуты записи, заданной её индексом.

### Список параметров

`index`
  Индекс записи.
`opsys`
  Код операционной системы заданный одной из констант ZipArchive::OPSYS_.
`attr`
  Внешние атрибуты. Значения зависят от операционной системы.
`flags`
  Опциональные флаги. Не используется.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — Установка внешних атрибутов записи, заданной по имени

### Описание

public function ZipArchive::setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Установка внешних атрибутов записи, заданной по имени.

### Список параметров

`name`
  Имя записи.
`opsys`
  Код операционной системы, определяется одной из констант ZipArchive::OPSYS_.
`attr`
  Внешние атрибуты. Значение зависит от операционной системы.
`flags`
  Необязательные флаги. В настоящее время не используется.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

В этом примере открывается файл архива ZIP test.zip и к нему добавляется файл test.txt с правами Unix в виде внешних атрибутов.

Пример #1 Сжатие файла с его правами Unix

    <?php
    $zip = new ZipArchive();
    $stat = stat($filename='test.txt');
    if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile($filename);
        $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
        $zip->close();
        echo "готово\n";
    } else {
        echo "ошибка\n";
    }
    ?>

# ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — Установить время модификации файла по его индексу

### Описание

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Установить время модификации файла по его индексу.

### Список параметров

`index`
  Индекс.
`timestamp`
  Время модификации (временная метка unix) файла.
`flags`
  Необязательные флаги. В текущий момент не используются.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример создания ZIP-архива test.zip, добавления в него файла test.txt и установка времени модификации для него.

Пример #1 Архивирование файла

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Примечания

> Замечание: Функция доступна только если сборка производилась с libzip ≥ 1.0.0.

### Смотрите также

- ZipArchive::setMtimeName() - Установить время модификации файла по его имени

# ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — Установить время модификации файла по его имени

### Описание

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Установить время модификации файла по его имени.

### Список параметров

`name`
  Имя файла.
`timestamp`
  Время модификации (временная метка unix) файла.
`flags`
  Необязательные флаги. В текущий момент не используются.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример создания ZIP-архива test.zip, добавления в него файла test.txt и установка времени модификации для него.

Пример #1 Архивирование файла

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Примечания

> Замечание:

> Функция доступна только если сборка производилась с libzip ≥ 1.0.0.

### Смотрите также

- ZipArchive::setMtimeIndex() - Установить время модификации файла по его индексу

# ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — Устанавливает пароля для активного архива

### Описание

public function ZipArchive::setPassword(#[\SensitiveParameter]string `$password`): bool

Задаёт пароль для активного архива.

### Список параметров

`password`
  Пароль для архива.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание: Начиная с PHP 7.2.0 и libzip 1.2.0 пароль используется для распаковки архива, а также как пароль по умолчанию для методов ZipArchive::setEncryptionName() и ZipArchive::setEncryptionIndex(). Раньше метод устанавливал пароль только для распаковки. Метод не превращала незащищённый паролем экземпляр ZipArchive в защищённый объект ZipArchive.

### Смотрите также

- ZipArchive::setEncryptionIndex() - Устанавливает метод шифрования записи по индексу
- ZipArchive::setEncryptionName() - Устанавливает метод шифрования записи по имени

# ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — Получение детальной информации о элементе по его индексу

### Описание

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

Получение детальной информации об элементе по его индексу.

### Список параметров

`index`
  Индекс элемента.
`flags`
  `ZipArchive::FL_UNCHANGED` указывается, чтобы запросить информацию об исходном файле в архиве, игнорируя любые внесённые изменения.

### Возвращаемые значения

Возвращает массив, содержащий детальную информацию о элементе или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение статистической информации о элементе

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'Ошибка с кодом:' . $res;
    }
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — Получение детальной информации об элементе по его имени

### Описание

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

Получение детальной информации об элементе по его имени.

### Список параметров

`name`
  Имя элемента.
`flags`

  Флаг, указывающий как должен происходить поиск имени. Кроме того, может указываться `ZipArchive::FL_UNCHANGED`, чтобы запросить информацию об исходном файле в архиве, игнорируя любые внесённые изменения.

  - `ZipArchive::FL_NOCASE`
  - `ZipArchive::FL_NODIR`
  - `ZipArchive::FL_UNCHANGED`

### Возвращаемые значения

Возвращает массив, содержащий детальную информацию о элементе или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение статистической информации о элементе

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'Ошибка с кодом:' . $res;
    }
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — Отменяет все изменения, сделанные в архиве

### Описание

public function ZipArchive::unchangeAll(): bool

Отменяет все изменения, сделанные в архиве.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Возвращает все глобальные изменения, сделанные в архиве

### Описание

public function ZipArchive::unchangeArchive(): bool

Возвращает все глобальные изменения, сделанные в архиве. В данный момент только отменяет изменения в комментариях к архиву.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Отменяет все изменения у позиции с заданным индексом

### Описание

public function ZipArchive::unchangeIndex(int `$index`): bool

Отменяет все изменения у позиции с заданным индексом.

### Список параметров

`index`
  Индекс позиции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Отменяет все изменения у позиции с заданным именем

### Описание

public function ZipArchive::unchangeName(string `$name`): bool

Отменяет все изменения у позиции с заданным именем.

### Список параметров

`name`
  Имя позиции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

## Содержание

- ZipArchive::addEmptyDir — Добавляет новую директорию
- ZipArchive::addFile — Добавляет в ZIP-архив файл по заданному пути
- ZipArchive::addFromString — Добавляет содержимое в ZIP-архив как файл
- ZipArchive::addGlob — Добавляет файлы из директории по glob-шаблону
- ZipArchive::addPattern — Добавить файлы из директории в соответствии с шаблоном регулярного выражения PCRE
- ZipArchive::clearError — Удаляет сообщение об ошибке статуса, системные и/или сообщения модуля zip
- ZipArchive::close — Закрывает активный архив (открытый или вновь созданный)
- ZipArchive::count — Подсчитывает количество файлов в архиве
- ZipArchive::deleteIndex — Удаляет элемент в архиве, используя его индекс
- ZipArchive::deleteName — Удаляет элемент в архиве, используя его имя
- ZipArchive::extractTo — Извлекает содержимое архива
- ZipArchive::getArchiveComment — Возвращает комментарий ZIP-архива
- ZipArchive::getArchiveFlag — Возвращает значение глобального флага ZIP-архива
- ZipArchive::getCommentIndex — Возвращает комментарий элемента, используя его индекс
- ZipArchive::getCommentName — Возвращает комментарий элемента, используя его имя
- ZipArchive::getExternalAttributesIndex — Извлекает внешние атрибуты записи по её индексу
- ZipArchive::getExternalAttributesName — Извлечь внешние атрибуты записи по её имени
- ZipArchive::getFromIndex — Возвращает содержимое элемента по его индексу
- ZipArchive::getFromName — Возвращает содержимое элемента по его имени
- ZipArchive::getNameIndex — Возвращает имя элемента по его индексу
- ZipArchive::getStatusString — Возвращает сообщение об ошибке состояния, сообщения системы и (или) ZIP-архива
- ZipArchive::getStream — Получить дескриптор файла элемента, определённый по имени элемента (только для чтения)
- ZipArchive::getStreamIndex — Получает обработчик файла для записи, определённой её индексом (только для чтения)
- ZipArchive::getStreamName — Получает обработчик файла для записи, определённой её именем (только для чтения)
- ZipArchive::isCompressionMethodSupported — Проверяет, поддерживается ли метод сжатия libzip
- ZipArchive::isEncryptionMethodSupported — Проверяет, поддерживается ли метод шифрования libzip
- ZipArchive::locateName — Возвращает индекс элемента в архиве
- ZipArchive::open — Открывает ZIP-архив
- ZipArchive::registerCancelCallback — Регистрирует callback-функцию для разрешения отмены во время закрытия архива
- ZipArchive::registerProgressCallback — Регистрирует callback-функцию для предоставления обновлений при закрытии архива
- ZipArchive::renameIndex — Переименовывает элемент по его индексу
- ZipArchive::renameName — Переименовывает элемент по его имени
- ZipArchive::replaceFile — Заменяет файл в ZIP-архиве файлом по заданному пути
- ZipArchive::setArchiveComment — Устанавливает комментарий к ZIP-архиву
- ZipArchive::setArchiveFlag — Устанавливает глобальный флаг ZIP-архива
- ZipArchive::setCommentIndex — Устанавливает комментарий к элементу по его индексу
- ZipArchive::setCommentName — Устанавливает комментарий к элементу, заданному по имени
- ZipArchive::setCompressionIndex — Устанавливает метод сжатия записи по индексу
- ZipArchive::setCompressionName — Установить метод сжатия записи, заданной по имени
- ZipArchive::setEncryptionIndex — Устанавливает метод шифрования записи по индексу
- ZipArchive::setEncryptionName — Устанавливает метод шифрования записи по имени
- ZipArchive::setExternalAttributesIndex — Установить внешние атрибуты записи по её индексу
- ZipArchive::setExternalAttributesName — Установка внешних атрибутов записи, заданной по имени
- ZipArchive::setMtimeIndex — Установить время модификации файла по его индексу
- ZipArchive::setMtimeName — Установить время модификации файла по его имени
- ZipArchive::setPassword — Устанавливает пароля для активного архива
- ZipArchive::statIndex — Получение детальной информации о элементе по его индексу
- ZipArchive::statName — Получение детальной информации об элементе по его имени
- ZipArchive::unchangeAll — Отменяет все изменения, сделанные в архиве
- ZipArchive::unchangeArchive — Возвращает все глобальные изменения, сделанные в архиве
- ZipArchive::unchangeIndex — Отменяет все изменения у позиции с заданным индексом
- ZipArchive::unchangeName — Отменяет все изменения у позиции с заданным именем

# Функции Zip

Внимание

Процедурный API устарел с PHP 8.0.0. Вместо него следует использовать ZipArchive.

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — Закрывает дескриптор ZIP-архива

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_close(resource `$zip`): void

Функция закрывает дескриптор ZIP-архива.

### Список параметров

`zip`
  ZIP-файл, который прежде открыли функцией zip_open().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::close().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_read() - Считывает следующую запись в ZIP-архиве

# zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — Закрывает дескриптор директории

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

Функция закрывает заданный дескриптор директории.

### Список параметров

`zip_entry`
  Дескриптор директории, который прежде открыли функцией zip_entry_open().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API.

### Смотрите также

- zip_entry_open() - Открывает директорию для чтения
- zip_entry_read() - Считывает данные из открытого прежде дескриптора каталога

# zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — Возвращает сжатый размер файла для дескриптора директории

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

Функция возвращает сжатый размер заданного дескриптора директории.

### Список параметров

`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().

### Возвращаемые значения

Функция возвращает сжатый размер дескриптора директории или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::statIndex().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_read() - Считывает следующую запись в ZIP-архиве

# zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — Возвращает метод сжатия дескриптора директории

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

Функция возвращает метод сжатия дескриптора директории, который указали в аргументе `zip_entry`.

### Список параметров

`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().

### Возвращаемые значения

Метод сжатия или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::statIndex().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_read() - Считывает следующую запись в ZIP-архиве

# zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — Возвращает реальный размер файла для дескриптора директории

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

Функция возвращает реальный размер заданного дескриптора директории.

### Список параметров

`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().

### Возвращаемые значения

Функция возвращает реальный размер дескриптора директории или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::statIndex().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_read() - Считывает следующую запись в ZIP-архиве

# zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — Получает имя дескриптора директории

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

Функция возвращает имя заданного дескриптора директории.

### Список параметров

`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().

### Возвращаемые значения

Функция возвращает имя дескриптора директории или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::statIndex().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_read() - Считывает следующую запись в ZIP-архиве

# zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — Открывает директорию для чтения

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

Функция открывает директорию в ZIP-архиве для чтения.

### Список параметров

`zip_dp`
  Дескриптор, который возвращает функция zip_open().
`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().
`mode`
  Доступные режимы приводит документация к функции fopen().

  > Замечание: Функция пока игнорирует параметр `mode`, а значение параметра всегда равно `"rb"`. Это связано с тем, что ZIP в PHP поддерживается только в режиме чтения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

> Замечание: В отличие от функции fopen() и других подобных функций, значение, которое возвращает функция zip_entry_open(), указывает только результат операции и не требуется для чтения или закрытия дескриптора каталога.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API.

### Смотрите также

- zip_entry_close() - Закрывает дескриптор директории
- zip_entry_read() - Считывает данные из открытого прежде дескриптора каталога

# zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — Считывает данные из открытого прежде дескриптора каталога

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

Функция считывает данные из открытого прежде дескриптора каталога.

### Список параметров

`zip_entry`
  Дескриптор директории, который возвращает функция zip_read().
`len`
  Число байтов, которое требуется считать.

  > Замечание: В параметре указывают объём данных, который требуется считать, без учёта сжатия.

### Возвращаемые значения

Функция возвращает данные, которые считала, пустую строку, если достигла конца файла, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::getFromIndex().

### Смотрите также

- zip_entry_open() - Открывает директорию для чтения
- zip_entry_close() - Закрывает дескриптор директории
- zip_entry_filesize() - Возвращает реальный размер файла для дескриптора директории

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Открывает ZIP-архив

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

Функция открывает ZIP-архив для чтения.

### Список параметров

`filename`
  Название файла ZIP-архива, который требуется открыть.

### Возвращаемые значения

Функция возвращает ссылку на ресурс для передачи в функции zip_read() и zip_close() или возвращает номер ошибки, если файл `filename` не существует или возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::open().

### Смотрите также

- zip_read() - Считывает следующую запись в ZIP-архиве
- zip_close() - Закрывает дескриптор ZIP-архива

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Считывает следующую запись в ZIP-архиве

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

Функция считывает следующую запись в ZIP-архиве.

### Список параметров

`zip`
  ZIP-файл, который прежде открыли функцией zip_open().

### Возвращаемые значения

Функция возвращает запись каталога для передачи в функции семейства `zip_entry_*` или `false`, если записей для чтения не осталось, или код ошибки, если она возникла.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу объектно-ориентированного API, смотрите описание метода ZipArchive::statIndex().

### Смотрите также

- zip_open() - Открывает ZIP-архив
- zip_close() - Закрывает дескриптор ZIP-архива
- zip_entry_open() - Открывает директорию для чтения
- zip_entry_read() - Считывает данные из открытого прежде дескриптора каталога

## Содержание

- zip_close — Закрывает дескриптор ZIP-архива
- zip_entry_close — Закрывает дескриптор директории
- zip_entry_compressedsize — Возвращает сжатый размер файла для дескриптора директории
- zip_entry_compressionmethod — Возвращает метод сжатия дескриптора директории
- zip_entry_filesize — Возвращает реальный размер файла для дескриптора директории
- zip_entry_name — Получает имя дескриптора директории
- zip_entry_open — Открывает директорию для чтения
- zip_entry_read — Считывает данные из открытого прежде дескриптора каталога
- zip_open — Открывает ZIP-архив
- zip_read — Считывает следующую запись в ZIP-архиве

- Установка и настройка
  - Требования
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Примеры
- ZipArchive — Класс ZipArchive
  - ZipArchive::addEmptyDir — Добавляет новую директорию
  - ZipArchive::addFile — Добавляет в ZIP-архив файл по заданному пути
  - ZipArchive::addFromString — Добавляет содержимое в ZIP-архив как файл
  - ZipArchive::addGlob — Добавляет файлы из директории по glob-шаблону
  - ZipArchive::addPattern — Добавить файлы из директории в соответствии с шаблоном регулярного выражения PCRE
  - ZipArchive::clearError — Удаляет сообщение об ошибке статуса, системные и/или сообщения модуля zip
  - ZipArchive::close — Закрывает активный архив (открытый или вновь созданный)
  - ZipArchive::count — Подсчитывает количество файлов в архиве
  - ZipArchive::deleteIndex — Удаляет элемент в архиве, используя его индекс
  - ZipArchive::deleteName — Удаляет элемент в архиве, используя его имя
  - ZipArchive::extractTo — Извлекает содержимое архива
  - ZipArchive::getArchiveComment — Возвращает комментарий ZIP-архива
  - ZipArchive::getArchiveFlag — Возвращает значение глобального флага ZIP-архива
  - ZipArchive::getCommentIndex — Возвращает комментарий элемента, используя его индекс
  - ZipArchive::getCommentName — Возвращает комментарий элемента, используя его имя
  - ZipArchive::getExternalAttributesIndex — Извлекает внешние атрибуты записи по её индексу
  - ZipArchive::getExternalAttributesName — Извлечь внешние атрибуты записи по её имени
  - ZipArchive::getFromIndex — Возвращает содержимое элемента по его индексу
  - ZipArchive::getFromName — Возвращает содержимое элемента по его имени
  - ZipArchive::getNameIndex — Возвращает имя элемента по его индексу
  - ZipArchive::getStatusString — Возвращает сообщение об ошибке состояния, сообщения системы и (или) ZIP-архива
  - ZipArchive::getStream — Получить дескриптор файла элемента, определённый по имени элемента (только для чтения)
  - ZipArchive::getStreamIndex — Получает обработчик файла для записи, определённой её индексом (только для чтения)
  - ZipArchive::getStreamName — Получает обработчик файла для записи, определённой её именем (только для чтения)
  - ZipArchive::isCompressionMethodSupported — Проверяет, поддерживается ли метод сжатия libzip
  - ZipArchive::isEncryptionMethodSupported — Проверяет, поддерживается ли метод шифрования libzip
  - ZipArchive::locateName — Возвращает индекс элемента в архиве
  - ZipArchive::open — Открывает ZIP-архив
  - ZipArchive::registerCancelCallback — Регистрирует callback-функцию для разрешения отмены во время закрытия архива
  - ZipArchive::registerProgressCallback — Регистрирует callback-функцию для предоставления обновлений при закрытии архива
  - ZipArchive::renameIndex — Переименовывает элемент по его индексу
  - ZipArchive::renameName — Переименовывает элемент по его имени
  - ZipArchive::replaceFile — Заменяет файл в ZIP-архиве файлом по заданному пути
  - ZipArchive::setArchiveComment — Устанавливает комментарий к ZIP-архиву
  - ZipArchive::setArchiveFlag — Устанавливает глобальный флаг ZIP-архива
  - ZipArchive::setCommentIndex — Устанавливает комментарий к элементу по его индексу
  - ZipArchive::setCommentName — Устанавливает комментарий к элементу, заданному по имени
  - ZipArchive::setCompressionIndex — Устанавливает метод сжатия записи по индексу
  - ZipArchive::setCompressionName — Установить метод сжатия записи, заданной по имени
  - ZipArchive::setEncryptionIndex — Устанавливает метод шифрования записи по индексу
  - ZipArchive::setEncryptionName — Устанавливает метод шифрования записи по имени
  - ZipArchive::setExternalAttributesIndex — Установить внешние атрибуты записи по её индексу
  - ZipArchive::setExternalAttributesName — Установка внешних атрибутов записи, заданной по имени
  - ZipArchive::setMtimeIndex — Установить время модификации файла по его индексу
  - ZipArchive::setMtimeName — Установить время модификации файла по его имени
  - ZipArchive::setPassword — Устанавливает пароля для активного архива
  - ZipArchive::statIndex — Получение детальной информации о элементе по его индексу
  - ZipArchive::statName — Получение детальной информации об элементе по его имени
  - ZipArchive::unchangeAll — Отменяет все изменения, сделанные в архиве
  - ZipArchive::unchangeArchive — Возвращает все глобальные изменения, сделанные в архиве
  - ZipArchive::unchangeIndex — Отменяет все изменения у позиции с заданным индексом
  - ZipArchive::unchangeName — Отменяет все изменения у позиции с заданным именем
- Функции Zip
  - zip_close — Закрывает дескриптор ZIP-архива
  - zip_entry_close — Закрывает дескриптор директории
  - zip_entry_compressedsize — Возвращает сжатый размер файла для дескриптора директории
  - zip_entry_compressionmethod — Возвращает метод сжатия дескриптора директории
  - zip_entry_filesize — Возвращает реальный размер файла для дескриптора директории
  - zip_entry_name — Получает имя дескриптора директории
  - zip_entry_open — Открывает директорию для чтения
  - zip_entry_read — Считывает данные из открытого прежде дескриптора каталога
  - zip_open — Открывает ZIP-архив
  - zip_read — Считывает следующую запись в ZIP-архиве

# Zlib

# Введение

Модуль позволяет прозрачно читать и записывать сжатые файлы gzip (.gz), используя большинство функций файловой системы, которые работают с сжатыми файлами gzip (и несжатыми файлами тоже, но без использования сокетов).

> Замечание:

> PHP поставляется с fopen-обёрткой для .gz-файлов. Больше информации доступно в разделе о zlib://.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Модуль использует функции библиотеки » zlib, которую написали Jean-loup Gailly и Mark Adler. Начиная с PHP 8.4.0 для работы модуля требуется библиотека zlib с версией не ниже 1.2.11. До PHP 8.4.0 требовалась библиотека zlib с версией не ниже 1.2.0.4.

## Установка

Поддержка Zlib в PHP отключена по умолчанию. Чтобы её включить, используйте опцию --with-zlib[=DIR] во время сборки.

В версию PHP для Windows встроили поддержку модуля PCRE. Доступ к функциям модуля открыт без загрузки дополнительных модулей.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Модуль zlib предоставляет возможность сжатия передаваемых страниц (в т.ч. динамических) на лету, если браузер это поддерживает. За сжатие отвечают три параметра в конфигурационном файле php.ini.

Конфигурационные параметры Zlib
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`zlib.output_compression` bool/int

  Следует ли сжимать страницы. Если значение равно "On" в php.ini (или в настройках Apache), страницы будут сжиматься, если браузер посылает заголовок "Accept-Encoding: gzip" или "deflate". При этом в вывод будут добавлены заголовки "Content-Encoding: gzip" (соответственно "deflate") и "Vary: Accept-Encoding". В режиме исполнения, заголовок должен быть установлен до момента отправки.

  Эта опция также принимает целые числа вместо логических "On/Off", с помощью этого вы можете устанавливать размер выходного буфера (по умолчанию равен 4 КБ).

  > Замечание:

  > output_handler должен быть пустым, если выбрано значение 'On'! Вместо него следует использовать `zlib.output_handler`.

`zlib.output_compression_level` int

  Уровень сжатия используется для прозрачного сжатия вывода. Укажите значение между 0 (без сжатия) и 9 (максимальное сжатие). По умолчанию значение -1 позволяет серверу решать, какой уровень использовать.

`zlib.output_handler` string

  Если zlib.output_compression активирован, нельзя указывать дополнительные обработчики вывода. Этот параметр выполняет то же, что и output_handler, но в ином порядке.

## Типы ресурсов

Модуль определяет ресурс дескриптора, который возвращается функцией gzopen(). До PHP 8.0.0 также были определены ресурсы `zlib.deflate` и `zlib.inflate`.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  Алгоритм компрессии DEFLATE по стандарту RFC 1951.
`ZLIB_ENCODING_DEFLATE` (int)
  Алгоритм компрессии ZLIB по стандарту RFC 1950.
`ZLIB_ENCODING_GZIP` (int)
  Алгоритм компрессии GZIP по стандарту RFC 1952.
`ZLIB_FILTERED` (int)
`ZLIB_HUFFMAN_ONLY` (int)
`ZLIB_FIXED` (int)
`ZLIB_RLE` (int)
`ZLIB_DEFAULT_STRATEGY` (int)
`ZLIB_BLOCK` (int)
`ZLIB_NO_FLUSH` (int)
`ZLIB_PARTIAL_FLUSH` (int)
`ZLIB_SYNC_FLUSH` (int)
`ZLIB_FULL_FLUSH` (int)
`ZLIB_FINISH` (int)
`ZLIB_VERSION` (string)
  Номер версии модуля `zlib` в виде строки (string).
`ZLIB_VERNUM` (int)
  Номер версии модуля `zlib` в виде целого числа (int).
`ZLIB_OK` (int)
  Код возврата для функций сжатия и распаковки, который сообщает, что ошибки не возникали и дополнительной информации о состоянии нет.
`ZLIB_STREAM_END` (int)
  Код возврата означает, что обработка потока завершилась успешно.
`ZLIB_NEED_DICT` (int)
  Код возврата означает, что на этапе сжатия или распаковки потребовался предустановленный словарь.
`ZLIB_ERRNO` (int)
  Код возврата сообщает об ошибке, которая возникла при выполнении операции с файлом.
`ZLIB_STREAM_ERROR` (int)
  Код возврата сообщает об ошибке, которая возникла из-за несогласованного состояния потока или недопустимого параметра.
`ZLIB_DATA_ERROR` (int)
  Код возврата сообщает об ошибке, которая возникла из-за повреждённых входных данных.
`ZLIB_MEM_ERROR` (int)
  Код возврата сообщает об ошибке, которая возникла из-за недостатка памяти.
`ZLIB_BUF_ERROR` (int)
  Код возврата сообщает об ошибке, которая возникает, если прогресс невозможен из-за недостатка места в буфере или неожиданного завершения входного потока.
`ZLIB_VERSION_ERROR` (int)
  Код возврата сообщает об ошибке версии модуля `zlib`, которая оказалась несовместима с версией, которую предполагала вызывающая сторона.

# Примеры

В этом примере открывается временный файл, в него записывается строка, а затем дважды выводится содержимое.

Пример #1 Пример использования Zlib

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Только тест, тест, тест, тест, тест, тест, тест, тест!\n";

    // Открытие файла для записи с максимальным сжатием
    $zp = gzopen($filename, "w9");

    // Запись строки в файл
    gzwrite($zp, $s);

    // Закрытие файла
    gzclose($zp);

    // Открытие файла для чтения
    $zp = gzopen($filename, "r");

    // Чтение трёх символов
    echo gzread($zp, 3);

    // Вывод до конца файла, а затем закрытие файла
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // Открытие файла и вывод содержимого (во второй раз)
    if (readgzfile($filename) != strlen($s)) {
         echo "Возникла ошибка с функциями zlib!";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

Пример #2 Работа с API инкрементального компрессии и декомпрессии

    <?php

    // Выполнение компрессии GZIP:
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Данные для сжатия", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", больше данных", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, "и ещё больше данных!", ZLIB_FINISH);

    // Выполнение декомпрессии GZIP:
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

Результат выполнения приведённого примера:

    Данные для сжатия, больше данных и ещё больше данных!

# Функции Zlib

# deflate_add

(PHP 7, PHP 8)

deflate_add — Инкрементальное сжатие данных

### Описание

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Инкрементальное сжатие данных в указанном контексте.

### Список параметров

`context`

  Контекст, созданный с помощью функции deflate_init().

`data`

  Блок данных для сжатия.

`flush_mode`

  Одна из констант: `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (по умолчанию), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Обычно требуется установить `ZLIB_NO_FLUSH` для максимальной компрессии и `ZLIB_FINISH` для завершения на последнем блоке данных. Детальное описание констант смотрите в » руководстве zlib.

### Возвращаемые значения

Возвращает блок сжатых данных или `false`, если возникла ошибка.

### Ошибки

В случае некорректных аргументов будет вызвана ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` ожидает экземпляр DeflateContext; раньше, ожидался ресурс (resource).

### Смотрите также

- deflate_init() - Инициализировать контекст инкрементального сжатия

# deflate_init

(PHP 7, PHP 8)

deflate_init — Инициализировать контекст инкрементального сжатия

### Описание

function deflate_init(int `$encoding`, array|object `$options` = []): DeflateContext|false

Инициализирует контекст инкрементального сжатия с использованием указанной кодировки `encoding`.

Обратите внимание, что опция `window` задаёт только размер окна алгоритма, в отличие от фильтров zlib, где одноимённая опция также используется для установки используемой кодировки; кодировка должна быть установлена с помощью параметра `encoding`.

Ограничения: в текущий момент невозможно установить информацию заголовка для сжатого потока GZIP, которая устанавливается следующим образом: подпись GZIP (`\x1f\x8B`); метод сжатия (`\x08` == DEFLATE); 6 нулевых байтов; текущая операционная система (`\x00` = Windows, `\x03` = Unix и т.д.)

### Список параметров

`encoding`

  Одна из констант `ZLIB_ENCODING_*`.

`options`

  Ассоциативный массив, который может содержать следующие элементы:

  level

    Уровень сжатия в диапазоне -1..9; по умолчанию -1.

  memory

    Уровень памяти сжатия в диапазоне 1..9; по умолчанию 8.

  window

    Размер окна zlib (логарифмический) в диапазоне `8`..`15`; по умолчанию `15`. zlib изменяет размер окна с `8` на `9`, а с zlib 1.2.8 будет выдавать предупреждение, если запрашивается размер окна равный `8` для `ZLIB_ENCODING_RAW` или `ZLIB_ENCODING_GZIP`.

  strategy

    Одна из констант: `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` или `ZLIB_DEFAULT_STRATEGY` (по умолчанию).

  dictionary

    Строка или массив строк текущего словаря (по умолчанию предустановленного словаря нет).

### Возвращаемые значения

Возвращает ресурс контекста сжатия (`zlib.deflate`) или `false`, если возникла ошибка.

### Ошибки

Если в `options` была передана некорректная опция или контекст не может быть создан, то будет вызвана ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр DeflateContext; раньше, возвращался ресурс (resource).

### Смотрите также

- deflate_add() - Инкрементальное сжатие данных
- inflate_init() - Инициализация контекста инкрементальной распаковки

# gzclose

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

gzclose — Закрыть указатель открытого gz-файла

### Описание

function gzclose(resource `$stream`): bool

Закрывает открытый gz-файл по переданному указателю.

### Список параметров

`stream`

  Указатель на gz-файл. Должен указывать на файл, успешно открытый gzopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования gzclose()

    <?php
    $gz = gzopen('somefile.gz','w9');
    gzputs ($gz, 'Добавлено в файл somefile.gz');
    gzclose($gz);
    ?>

### Смотрите также

- gzopen() - Открыть gz-файл

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Сжать строку

### Описание

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

Данная функция сжимает строку используя формат данных `ZLIB`.

Подробнее про алгоритм сжатия ZLIB смотрите документ "» Формат сжатия ZLIB. Спецификация версии 3.3" (RFC 1950).

> Замечание:

> Это не то же самое, что и gzip-сжатие, которое включает в себя некоторые данные заголовка. Информацию о gzip-сжатии смотрите gzencode().

### Список параметров

`data`

  Данные для сжатия.

`level`

  Уровень сжатия. Целое число от 0 до 9 (0 - без сжатия, 9 - максимальное сжатие).

  Если используется значение -1, то будет установлен принятый в библиотеке zlib по умолчанию уровень сжатия, который равен 6.

`encoding`

  Одна из констант `ZLIB_ENCODING_*`.

### Возвращаемые значения

Сжатая строка или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования gzcompress()

    <?php
    $compressed = gzcompress('Сожми меня', 9);
    echo $compressed;
    ?>

### Смотрите также

- gzdeflate() - Сжимает строку
- gzinflate() - Распаковать сжатую строку
- gzuncompress() - Распаковать сжатую строку
- gzencode() - Создать сжатую строку gzip

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Декодирует строку, сжатую с помощью gzip

### Описание

function gzdecode(string `$data`, int `$max_length` = 0): string|false

Эта функция возвращает декодированную версию входных данных. `data`.

### Список параметров

`data`

  Данные для декодирования, закодированные с помощью gzencode().

`max_length`

  Максимальный размер строки для декодирования.

### Возвращаемые значения

Распакованная строка или `false`, если возникла ошибка.

### Ошибки

В случае возникновения ошибки возвращает ошибку уровня `E_WARNING`.

### Смотрите также

- gzencode() - Создать сжатую строку gzip

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Сжимает строку

### Описание

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

Данная функция сжимает строку, используя формат данных `DEFLATE`.

Подробнее об алгоритме сжатия DEFLATE смотрите "» Формат сжатия данных DEFLATE. Спецификация версии 1.3" (RFC 1951).

### Список параметров

`data`

  Данные для сжатия.

`level`

  Уровень сжатия. 0 - без сжатия, 9 - максимум. Если не указан, будет использоваться уровень сжатия по умолчанию библиотеки zlib.

`encoding`

  Одна из констант `ZLIB_ENCODING_*`.

### Возвращаемые значения

Сжатая строка или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования gzdeflate()

    <?php
    $compressed = gzdeflate('Сожми меня', 9);
    echo $compressed;
    ?>

### Смотрите также

- gzinflate() - Распаковать сжатую строку
- gzcompress() - Сжать строку
- gzuncompress() - Распаковать сжатую строку
- gzencode() - Создать сжатую строку gzip

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — Создать сжатую строку gzip

### Описание

function gzencode(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_GZIP`): string|false

Эта функция возвращает сжатую версию входных данных `data`, аналогично выводу программы gzip.

Подробности о формате GZIP смотрите » Формат файла GZIP. Спецификация версии 4.3 (RFC 1952).

### Список параметров

`data`

  Данные для кодирования.

`level`

  Уровень сжатия. 0 - без сжатия, 9 - максимальное сжатие. Если не указано, будет использоваться уровень сжатия по умолчанию библиотеки zlib.

`encoding`

  Режим сжатия, может быть `FORCE_GZIP` (по умолчанию) или `FORCE_DEFLATE`.

  Использование константы `FORCE_DEFLATE` генерирует вывод, совместимый с RFC 1950, состоящий из заголовка zlib, сжатых данных и контрольной суммы Adler.

### Возвращаемые значения

Сжатая строка или `false` в случае возникновения ошибки.

### Примеры

Возвращаемые данные будут содержать соответствующие заголовки и структуры данных как в обычном .gz-файле, например:

Пример #1 Создание файла gzip

    <?php
    $data = file_get_contents("bigfile.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("bigfile.txt.gz", $gzdata);
    ?>

### Смотрите также

- gzdecode() - Декодирует строку, сжатую с помощью gzip
- gzdeflate() - Сжимает строку
- gzinflate() - Распаковать сжатую строку
- gzuncompress() - Распаковать сжатую строку
- gzcompress() - Сжать строку
- » Спецификация ZLIB Compressed Data (RFC 1950)

# gzeof

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

gzeof — Проверяет, находится ли текущая позиция в конце (EOF) gz-файла

### Описание

function gzeof(resource `$stream`): bool

Проверяет, соответствует ли позиция указателя в GZ-файле позиции EOF (end-of-file, конец файла).

### Список параметров

`stream`

  Указатель на gz-файл. Он должен быть корректный и должен указывать на файл, успешно открытый gzopen().

### Возвращаемые значения

Возвращает `true`, если позиция указателя gz-файла соответствует EOF или возникает ошибка; иначе возвращает `false`.

### Примеры

Пример #1 Пример использования gzeof()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

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

gzfile — Считывает весь gz-файл в массив

### Описание

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

Аналогична readgzfile(), за исключением того, что она возвращает файл в массиве.

### Список параметров

`filename`

  Имя файла.

`use_include_path`
  Если установлено значение `true`, то также выполняется поиск файлов в include_path.

### Возвращаемые значения

Массив строк файла, в каждом элементе массива находится одна строка, пустые строки включаются, а переносы строк по-прежнему добавляются или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Тип параметра `use_include_path` теперь – логическое значение (bool). Ранее он был целым числом (int).

### Примеры

Пример #1 Пример использования gzfile()

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### Смотрите также

- readgzfile() - Выводит содержимое gz-файла
- gzopen() - Открыть gz-файл

# gzgetc

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

gzgetc — Получить символ из указателя на gz-файл

### Описание

function gzgetc(resource `$stream`): string|false

Возвращает строку, содержащую один символ (несжатый), считанный из заданного указателя gz-файла.

### Список параметров

`stream`

  Указатель на gz-файл. Он должен быть корректный и должен указывать на файл, успешно открытый gzopen().

### Возвращаемые значения

Символ (несжатый) или `false` в случае EOF (в отличие от gzeof()).

### Примеры

Пример #1 Пример использования gzgetc()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### Смотрите также

- gzopen() - Открыть gz-файл
- gzgets() - Получить строку из указателя файла

# gzgets

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

gzgets — Получить строку из указателя файла

### Описание

function gzgets(resource `$stream`, ?int `$length` = `null`): string|false

Получает строку (несжатую) из gz-файла, её длина ограничивается `length` - 1 байтами. Чтение заканчивается при достижении максимальной длины, конца строки или конца файла (EOF), в зависимости от того, что наступит раньше.

### Список параметров

`stream`

  Указатель на gz-файл. Он должен быть корректный и должен указывать на файл, успешно открытый gzopen().

`length`

  Максимальный размер возвращаемых данных.

### Возвращаемые значения

Распакованная строка или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `length` теперь допускает значение null; ранее значение по умолчанию было `1024`.

### Примеры

Пример #1 Пример использования gzgets()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Смотрите также

- gzopen() - Открыть gz-файл
- gzgetc() - Получить символ из указателя на gz-файл
- gzwrite() - Бинарная запись в gz-файл

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Возвращает строку из указателя gz-файла и удалить HTML-теги

Внимание

Начиная с PHP 7.3.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

Аналогично gzgets(), за исключением того, что gzgetss() пытается удалить любые теги HTML и PHP из считываемой строки.

### Список параметров

`zp`

  Указатель на gz-файл. Он должен быть корректный и должен указывать на файл, успешно открытый gzopen().

`length`

  Максимальный размер возвращаемых данных.

`allowable_tags`

  Используйте этот необязательный параметр, чтобы указать теги, которые не следует удалять.

### Возвращаемые значения

Несжатая очищенная строка или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования gzgetss()

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Смотрите также

- gzopen() - Открыть gz-файл
- gzgets() - Получить строку из указателя файла
- strip_tags() - Удаляет HTML- и PHP-теги из строки

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Распаковать сжатую строку

### Описание

function gzinflate(string `$data`, int `$max_length` = 0): string|false

Распаковывает сжатую строку.

### Список параметров

`data`

  Данные, сжатые функцией gzdeflate().

`max_length`

  Максимальный размер декодируемых данных.

### Возвращаемые значения

Распакованные данные или `false` в случае возникновения ошибки.

Функция вернёт ошибку, если несжатые данные в 32768 раз больше размера сжатых данных `data` или, если `max_length` не `0` и больше, чем необязательный параметр `max_length`.

### Примеры

Пример #1 Пример использования gzinflate()

    <?php
    $compressed   = gzdeflate('Сожми меня', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### Смотрите также

- gzdeflate() - Сжимает строку
- gzcompress() - Сжать строку
- gzuncompress() - Распаковать сжатую строку
- gzencode() - Создать сжатую строку gzip

# gzopen

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

gzopen — Открыть gz-файл

### Описание

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

Открывает файл gzip (.gz) для чтения или записи.

gzopen() также можно использовать для чтения несжатых файлов (то есть не в формате gzip). В этом случае gzread() будет непосредственно читать файл без какой-либо обработки.

### Список параметров

`filename`

  Имя файла.

`mode`

  Как в fopen() (`rb` или `wb`), но также может включать уровень сжатия (`wb9`) или стратегию: `f` для фильтрации данных как в `wb6f`, `h` для сжатия `только по алгоритму Хаффмана`, как в `wb1h` (Для более детальной информации о параметре стратегии смотрите описание `deflateInit2` в zlib.h).

`use_include_path`
  Если установлено значение `true`, то также выполняется поиск файлов в include_path.

### Возвращаемые значения

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

В случае возникновения ошибки функция возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Тип параметра `use_include_path` теперь – логическое значение (bool). Ранее он был целым числом (int).

### Примеры

Пример #1 Пример использования gzopen()

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### Смотрите также

- gzclose() - Закрыть указатель открытого gz-файла

# gzpassthru

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

gzpassthru — Вывод всех оставшихся данных из указателя gz-файла.

### Описание

function gzpassthru(resource `$stream`): int

Читает до конца файла (EOF) данные из указателя gz-файла, начиная с текущей позиции, и записывает результат (без сжатия) в стандартный вывод.

> Замечание:

> Используйте gzrewind(), чтобы переместить указатель на позицию в начало файла, если вы уже записывали данные в него.

Подсказка

Если вам нужно просто вывести содержимое файла без перемещения указателя на позицию или внесения изменений, используйте функцию readgzfile(), которая не требует вызова функции gzopen().

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

### Возвращаемые значения

Количество несжатых символов, прочитанных из `gz` и переданных на вход.

### Примеры

Пример #1 Пример использования gzpassthru()

    <?php
    $fp = gzopen('file.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

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

gzputs — Псевдоним gzwrite()

### Описание

Псевдоним функции gzwrite().

# gzread

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

gzread — Бинарное чтение gz-файла

### Описание

function gzread(resource `$stream`, int `$length`): string|false

gzread() читает (распаковывая) до `length` байт из gz-файла из переданного указателя gz-файла. Чтение заканчивается при достижении максимального размера `length` распакованных данных или конца файла (EOF)

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

`length`

  Количество байт (после распаковки), которые следует прочитать.

### Возвращаемые значения

Прочтённые данные или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | В случае возникновения ошибки возвращается `false`; раньше, возвращался `0`.

### Примеры

Пример #1 Пример использования gzread()

    <?php
    // поместить содержимое gz-файла в строку
    $filename = "/usr/local/something.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### Смотрите также

- gzwrite() - Бинарная запись в gz-файл
- gzopen() - Открыть gz-файл
- gzgets() - Получить строку из указателя файла
- gzgetss() - Возвращает строку из указателя gz-файла и удалить HTML-теги
- gzfile() - Считывает весь gz-файл в массив
- gzpassthru() - Вывод всех оставшихся данных из указателя gz-файла.

# gzrewind

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

gzrewind — Переместить позицию указатель gz-файла в начало

### Описание

function gzrewind(resource `$stream`): bool

Устанавливает указатель на позицию файла на начало потока этого файла.

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- gzseek() - Переместить указатель на позицию в указателе gz-файла
- gztell() - Возвращает текущую позицию чтения/записи в указателе gz-файла

# gzseek

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

gzseek — Переместить указатель на позицию в указателе gz-файла

### Описание

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Устанавливает указатель на позицию в файле, на который ссылается zp. Выполняется смещение потока этого файла на указанное количество байт. Эквивалентно вызову (в C) `gzseek(zp, offset, SEEK_SET)`.

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

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

`offset`

  Смещение.

`whence`

  Значения параметра `whence` может быть одним из следующих:

  - `SEEK_SET` - Установить абсолютную позицию в `offset` байт.
  - `SEEK_CUR` - Установить позицию относительно текущего положения, добавив к ней `offset`.

  Если `whence` не указан, по умолчанию используется `SEEK_SET`.

### Возвращаемые значения

При успешном завершении возвращает 0; иначе -1. Обратите внимание, что если установленное смещение перемещает указатель на позицию за EOF, это не является ошибкой.

### Примеры

Пример #1 Пример использования gzseek()

    <?php
    $gz = gzopen('somefile.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### Смотрите также

- gztell() - Возвращает текущую позицию чтения/записи в указателе gz-файла
- gzrewind() - Переместить позицию указатель gz-файла в начало

# gztell

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

gztell — Возвращает текущую позицию чтения/записи в указателе gz-файла

### Описание

function gztell(resource `$stream`): int|false

Функция получает позицию указателя файла, то есть смещение в потоке распакованного файла.

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

### Возвращаемые значения

Функция возвращает текущую позицию или `false`, если возникла ошибка.

### Смотрите также

- gzopen() - Открыть gz-файл
- gzseek() - Переместить указатель на позицию в указателе gz-файла
- gzrewind() - Переместить позицию указатель gz-файла в начало

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Распаковать сжатую строку

### Описание

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

Распаковывает сжатую строку.

### Список параметров

`data`

  Данные, сжатые функцией gzcompress().

`max_length`

  Максимальный размер данных для декодирования.

### Возвращаемые значения

Исходные несжатые данные или `false` в случае возникновения ошибки.

Функция также сообщит об ошибке в случае, если несжатые данные в 32768 раз больше размера сжатых данных `data` или больше параметра `max_length`.

### Примеры

Пример #1 Пример использования gzuncompress()

    <?php
    $compressed   = gzcompress('Сожми меня', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### Смотрите также

- gzcompress() - Сжать строку
- gzinflate() - Распаковать сжатую строку
- gzdeflate() - Сжимает строку
- gzencode() - Создать сжатую строку gzip

# gzwrite

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

gzwrite — Бинарная запись в gz-файл

### Описание

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() записывает содержимое `data` в данный gz-файл.

### Список параметров

`stream`

  Указатель на gz-файл, возвращённый, после его успешного открытия, функцией gzopen().

`data`

  Записываемая строка.

`length`

  Число несжатых байтов для записи. Если указано, операция завершится после записи `length` (до сжатия) байт или при достижении конца строки, в зависимости от того, что наступит раньше. `data`.

### Возвращаемые значения

Возвращает количество записанных байт (без учёта сжатия) в поток gz-файла или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `length` теперь допускает значение null; раньше значением по умолчанию был `0`.
7.4.0 | В случае возникновения ошибки функция возвращает `false`. раньше возвращался `0`.

### Примеры

Пример #1 Пример использования gzwrite()

    <?php
    $string = 'Какие-то данные для сжатия';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### Смотрите также

- gzread() - Бинарное чтение gz-файла
- gzopen() - Открыть gz-файл

# inflate_add

(PHP 7, PHP 8)

inflate_add — Инкрементальное распаковать закодированные данные

### Описание

function inflate_add(InflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Инкрементальное распаковывает закодированные данные в указанном контексте `context`.

Ограничение: информация заголовка из сжатых данных GZIP не доступны.

### Список параметров

`context`

  Контекст, созданный с помощью inflate_init().

`data`

  Блок сжатых данных.

`flush_mode`

  Одна из констант: `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (по умолчанию), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Обычно требуется установить `ZLIB_NO_FLUSH` для максимальной компрессии и `ZLIB_FINISH` для завершения работы с последним блоком данных. Детальное описание констант смотрите в » руководство zlib.

### Возвращаемые значения

Возвращает блок распакованных данных или `false`, если возникла ошибка.

### Ошибки

Если переданы некорректные параметры, распаковка требует наличие словаря, но он не задан, поток сжатых данных испорчен или имеет некорректную контрольную сумму, то генерируется ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` ожидает экземпляр InflateContext; раньше, ожидался ресурс (resource).

### Смотрите также

- inflate_init() - Инициализация контекста инкрементальной распаковки

# inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — Получает количество прочитанных байт

### Описание

function inflate_get_read_len(InflateContext `$context`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`context`

### Возвращаемые значения

Возвращает количество прочитанных байт или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` ожидает экземпляр InflateContext; раньше, ожидался ресурс (resource).

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — Получает статус декомпрессии

### Описание

function inflate_get_status(InflateContext `$context`): int

Обычно возвращает `ZLIB_OK` или `ZLIB_STREAM_END`.

### Список параметров

`context`

### Возвращаемые значения

Возвращает статус декомпрессии.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` ожидает экземпляр InflateContext; раньше, ожидался ресурс (resource).

# inflate_init

(PHP 7, PHP 8)

inflate_init — Инициализация контекста инкрементальной распаковки

### Описание

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Инициализирует контекст инкрементальной распаковки с указанной кодировкой `encoding`.

### Список параметров

`encoding`

  Одна из констант `ZLIB_ENCODING_*`.

`options`

  Ассоциативный массив, который может содержать следующие элементы:

  level

    Уровень сжатия в диапазоне -1..9; по умолчанию -1.

  memory

    Уровень памяти сжатия в диапазоне 1..9; по умолчанию 8.

  window

    Размер окна zlib (логарифмический) в диапазоне 8..15; по умолчанию 15.

  strategy

    Одна из констант: `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` или `ZLIB_DEFAULT_STRATEGY` (по умолчанию).

  dictionary

    Строка (string) или массив (array) строк текущего словаря (по умолчанию предустановленного словаря нет).

### Возвращаемые значения

Возвращает ресурс контекста распаковки (`zlib.inflate`) или `false`, если возникла ошибка.

### Ошибки

Если в `options` была передана некорректная опция, или контекст не может быть создан, то будет вызвана ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр InflateContext; раньше возвращался ресурс (resource).

### Примечания

Предостережение

В отличие от gzinflate(), контексты инкрементального расширения не ограничивают длину декодированных данных, поэтому не обеспечивают автоматической защиты от ZIP-бомб.

### Смотрите также

- inflate_add() - Инкрементальное распаковать закодированные данные
- deflate_init() - Инициализировать контекст инкрементального сжатия

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — Сжимает буфер вывода в формат gzip как callback-функция функции ob_start

### Описание

function ob_gzhandler(string `$data`, int `$flags`): string|false

Функция ob_gzhandler() играет роль callback-функции — аргумента функции ob_start(), чтобы упростить отправку gz-кодированных данных в веб-браузеры, которые поддерживают обработку сжатых веб-страниц. Прежде чем функция ob_gzhandler() отправит сжатые данные, она определит тип кодирования содержимого, который будет принимать браузер — gzip, deflate или вообще никакой, — и вернёт свой вывод. Поддерживаются все браузеры, поскольку браузер сам отправляет правильный заголовок, который сообщает, что браузер принимает сжатые веб-страницы. Функция вернёт `false`, если браузер не поддерживает сжатие страниц.

### Список параметров

`data`

`flags`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования функции ob_gzhandler()

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>HTML-страницу требуется передать как сжатые данные.</p>
    </body>
    </html>

### Примечания

> Замечание:

> Функция ob_gzhandler() работает только вместе с модулем zlib.

> Замечание:

> Нельзя одновременно вызывать функцию ob_gzhandler() и включать настройку zlib.output_compression. Обратите также внимание, лучше включить опцию конфигурации zlib.output_compression, чем вызывать функцию ob_gzhandler().

### Смотрите также

- ob_start() - Включает буферизацию вывода
- ob_end_flush() - Сбрасывает (отправляет) значение, которое вернул активный обработчик вывода, и отключает активный буфер вывода

# readgzfile

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

readgzfile — Выводит содержимое gz-файла

### Описание

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

Функция считывает, распаковывает и записывает файл в стандартный вывод.

Функция readgzfile() читает файлы не только в формате gzip; в таких случаях функция readgzfile() считывает данные из файла без распаковки.

### Список параметров

`filename`

  Название файла. Файл откроется из файловой системы и содержимое файла запишется в стандартный вывод.

`use_include_path`
  Со значением `true` функция определят путь к файлу, который требуется открыть, с учётом значения директивы include_path.

### Возвращаемые значения

Функция возвращает количество байтов в файле после распаковки, если выполнилась успешно, или `false`, если возникла ошибка

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Тип параметра `use_include_path` теперь – логическое значение (bool). Ранее он был целым числом (int).

### Смотрите также

- gzpassthru() - Вывод всех оставшихся данных из указателя gz-файла.
- gzfile() - Считывает весь gz-файл в массив
- gzopen() - Открыть gz-файл

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Распаковывает любые закодированные данные raw/gzip/zlib

### Описание

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Распаковывает любые закодированные данные raw/gzip/zlib.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`data`

`max_length`

### Возвращаемые значения

Возвращает распакованные данные или `false`, если возникла ошибка.

### Смотрите также

- zlib_encode() - Сжатие данных с указанной кодировкой

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Сжатие данных с указанной кодировкой

### Описание

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Сжимает данные с указанной кодировкой.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`data`

  Данные для сжатия.

`encoding`

  Алгоритм сжатия. Одна из констант `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` или `ZLIB_ENCODING_GZIP`.

`level`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования zlib_encode()

    <?php
    $str = 'hello world';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

Результат выполнения приведённого примера:

    789ccb48cdc9c95728cf2fca4901001a0b045d

### Смотрите также

- zlib_decode() - Распаковывает любые закодированные данные raw/gzip/zlib

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Возвращает способ кодирования, используемый для сжатия вывода

### Описание

function zlib_get_coding_type(): string|false

Возвращает способ кодирования, используемый для сжатия вывода.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возможные значения: `gzip`, `deflate` или `false`.

### Смотрите также

- Директива zlib.output_compression

## Содержание

- deflate_add — Инкрементальное сжатие данных
- deflate_init — Инициализировать контекст инкрементального сжатия
- gzclose — Закрыть указатель открытого gz-файла
- gzcompress — Сжать строку
- gzdecode — Декодирует строку, сжатую с помощью gzip
- gzdeflate — Сжимает строку
- gzencode — Создать сжатую строку gzip
- gzeof — Проверяет, находится ли текущая позиция в конце (EOF) gz-файла
- gzfile — Считывает весь gz-файл в массив
- gzgetc — Получить символ из указателя на gz-файл
- gzgets — Получить строку из указателя файла
- gzgetss — Возвращает строку из указателя gz-файла и удалить HTML-теги
- gzinflate — Распаковать сжатую строку
- gzopen — Открыть gz-файл
- gzpassthru — Вывод всех оставшихся данных из указателя gz-файла.
- gzputs — Псевдоним gzwrite
- gzread — Бинарное чтение gz-файла
- gzrewind — Переместить позицию указатель gz-файла в начало
- gzseek — Переместить указатель на позицию в указателе gz-файла
- gztell — Возвращает текущую позицию чтения/записи в указателе gz-файла
- gzuncompress — Распаковать сжатую строку
- gzwrite — Бинарная запись в gz-файл
- inflate_add — Инкрементальное распаковать закодированные данные
- inflate_get_read_len — Получает количество прочитанных байт
- inflate_get_status — Получает статус декомпрессии
- inflate_init — Инициализация контекста инкрементальной распаковки
- ob_gzhandler — Сжимает буфер вывода в формат gzip как callback-функция функции ob_start
- readgzfile — Выводит содержимое gz-файла
- zlib_decode — Распаковывает любые закодированные данные raw/gzip/zlib
- zlib_encode — Сжатие данных с указанной кодировкой
- zlib_get_coding_type — Возвращает способ кодирования, используемый для сжатия вывода

# Класс DeflateContext

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `zlib.deflate` в PHP 8.0.0.

## Обзор класса

final class DeflateContext {
}

# Класс InflateContext

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `zlib.inflate` в PHP 8.0.0.

## Обзор класса

final class InflateContext {
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Примеры
- Функции Zlib
  - deflate_add — Инкрементальное сжатие данных
  - deflate_init — Инициализировать контекст инкрементального сжатия
  - gzclose — Закрыть указатель открытого gz-файла
  - gzcompress — Сжать строку
  - gzdecode — Декодирует строку, сжатую с помощью gzip
  - gzdeflate — Сжимает строку
  - gzencode — Создать сжатую строку gzip
  - gzeof — Проверяет, находится ли текущая позиция в конце (EOF) gz-файла
  - gzfile — Считывает весь gz-файл в массив
  - gzgetc — Получить символ из указателя на gz-файл
  - gzgets — Получить строку из указателя файла
  - gzgetss — Возвращает строку из указателя gz-файла и удалить HTML-теги
  - gzinflate — Распаковать сжатую строку
  - gzopen — Открыть gz-файл
  - gzpassthru — Вывод всех оставшихся данных из указателя gz-файла.
  - gzputs — Псевдоним gzwrite
  - gzread — Бинарное чтение gz-файла
  - gzrewind — Переместить позицию указатель gz-файла в начало
  - gzseek — Переместить указатель на позицию в указателе gz-файла
  - gztell — Возвращает текущую позицию чтения/записи в указателе gz-файла
  - gzuncompress — Распаковать сжатую строку
  - gzwrite — Бинарная запись в gz-файл
  - inflate_add — Инкрементальное распаковать закодированные данные
  - inflate_get_read_len — Получает количество прочитанных байт
  - inflate_get_status — Получает статус декомпрессии
  - inflate_init — Инициализация контекста инкрементальной распаковки
  - ob_gzhandler — Сжимает буфер вывода в формат gzip как callback-функция функции ob_start
  - readgzfile — Выводит содержимое gz-файла
  - zlib_decode — Распаковывает любые закодированные данные raw/gzip/zlib
  - zlib_encode — Сжатие данных с указанной кодировкой
  - zlib_get_coding_type — Возвращает способ кодирования, используемый для сжатия вывода
- DeflateContext — Класс DeflateContext
- InflateContext — Класс InflateContext

- Bzip2
  - Установка и настройка
  - Примеры
  - Функции Bzip2
- LZF
  - Установка и настройка
  - Функции LZF
- Phar
  - Установка и настройка
  - Предопределённые константы
  - Использование Phar-архивов
  - Создание Phar-архивов
  - Чем отличается phar от tar- или zip-архива?
  - Phar — Класс Phar
  - PharData — Класс PharData
  - PharFileInfo — Класс PharFileInfo
  - PharException — Класс PharException
- Rar — Архивирование Rar
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Rar
  - RarArchive — Класс RarArchive
  - RarEntry — Класс RarEntry
  - RarException — Класс RarException
- Zip
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - ZipArchive — Класс ZipArchive
  - Функции Zip
- Zlib
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Zlib
  - DeflateContext — Класс DeflateContext
  - InflateContext — Класс InflateContext

# Криптографические модули

# Фреймворк HASH для дайджеста сообщений

# Введение

Функции модуля напрямую или инкрементно обрабатывают сообщения произвольной длины через алгоритмы хеширования, включая генерацию HMAC-значений и производных ключей, которые включают HKDF- и PBKDF2-ключи.

Подробный список алгоритмов приводит описание функции hash_algos(), а алгоритмы хеширования входят в три условные категории:

- Алгоритмы контрольной суммы наподобие `crc32b` или `adler32`: вычисляют контрольные суммы, которые приносят пользу, когда требуется обнаружить ошибки передачи. Алгоритмы этой категории часто работают очень быстро. Эти алгоритмы часто генерируют значения, которые «легко угадать» или которыми иногда манипулируют, чтобы создавать коллизии, поэтому они непригодны в криптографических целях.
- Некриптографические алгоритмы наподобие алгоритмов семейства xxHash: этими алгоритмами часто вычисляют хеш-значения для хеш-таблиц, поскольку алгоритмы этой категории дают хорошее распределение по произвольным строковым входным данным. Они также в общем быстрые, но также непригодны в криптографических целях.
- Криптографические алгоритмы наподобие семейства SHA-2: получают хеш-значения, которые представляют входные данные, но не поддаются угадыванию и не создают коллизии. Производительность часто играет второстепенную роль, но современное оборудование часто поддерживает обработку этих алгоритмов, которую PHP пытается использовать, когда она доступна. Центр ресурсов компьютерной безопасности (Computer Security Resource Center) Национального института стандартов и технологий США (NIST) » объясняет алгоритмы, которые одобрили федеральные стандарты обработки информации США (US FIPS)).

  Испытания доказали, что ранние криптографические алгоритмы наподобие `md4`, `md5` и `sha1` оказались подвержены коллизионным атакам, и часто рекомендуется больше не использовать их для криптографических приложений.

Смотрите также FAQ по безопасному хешированию паролей, которые дают информацию о лучших практиках работы с хеш-функциями при обработке паролей.

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Модуль Hash стал частью ядра PHP, поэтому функции модуля доступны по умолчанию.

До PHP 7.4.0 модуль Hash интегрировался и компилировался в составе PHP по умолчанию, а отключался командой --disable-hash.

До 5.1.2 модуль Hash устанавливался как » PECL-модуль.

## Типы ресурсов

Модуль определяет ресурс контекста хеширования, который возвращает функция hash_init().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`HASH_HMAC` (int)
  Необязательный флаг для hash_init().

# Класс HashContext

(PHP 7 >= 7.2.0, PHP 8)

## Введение

## Обзор класса

final class HashContext {
/* Методы */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — Закрытый конструктор для запрета непосредственного создания объекта

### Описание

private function HashContext::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Возвращает отладочную информацию о контексте хеширования

### Описание

public function HashContext::__debugInfo(): array

Метод спроектировали не для прямого вызова; метод вызывается функциями наподобие var_dump() при инспектировании объекта HashContext.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает ассоциативный массив с отладочной информацией. Массив содержит элемент с ключом `algo`, в котором хранится название алгоритма текущего контекста хеширования.

### Примеры

Пример #1 Пример вывода отладочной информации о контексте хеширования методом HashContext::__debugInfo()

    <?php

    $ctx = hash_init('sha256');
    var_dump($ctx);

Результат выполнения приведённого примера:

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- var_dump() - Выводит информацию о переменной

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — Сериализует объект HashContext

### Описание

public function HashContext::__serialize(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — Десериализует параметр `data` в объект HashContext

### Описание

public function HashContext::__unserialize(array `$data`): void

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`data`

  Десериализуемое значение.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- HashContext::__construct — Закрытый конструктор для запрета непосредственного создания объекта
- HashContext::__debugInfo — Возвращает отладочную информацию о контексте хеширования
- HashContext::__serialize — Сериализует объект HashContext
- HashContext::__unserialize — Десериализует параметр data в объект HashContext

# Функции Hash

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — Генерирует хеш-значение (подпись сообщения)

### Описание

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список алгоритмов, которые поддерживает функция, приводит описание функции hash_algos().

`data`

  Сообщение, которое требуется захешировать.

`binary`

  Функция выводит необработанные двоичные данные, если для параметра установили значение `true`. Функция выводит символы в шестнадцатеричной кодировке в нижнем регистре, если для параметра установили значение `false`.

`options`

  Массив опций для алгоритмов хеширования. Пока вариантами функций хеширования MurmurHash поддерживается только параметр `"seed"`.

### Возвращаемые значения

Функция возвращает строку, которая содержит вычисленную хеш-подпись сообщения в виде строчных шестнадцатеричных символов в нижнем регистре, если только для параметра `binary` не установили значение `true`, тогда возвращается необработанное двоичное представление хеш-подписи сообщения.

### Ошибки

Функция выбрасывает исключение ValueError, если алгоритм `algo` неизвестен.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Добавили параметр `options`.
8.0.0 | Функция теперь выбрасывает исключение ValueError, если алгоритм `algo` неизвестен; раньше вместо этого возвращалось значение `false` и выдавалось сообщение об ошибке уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции hash()

    <?php

    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    ?>

Результат выполнения приведённого примера:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_file() - Генерирует хеш-значение на основе содержимого файла
- hash_hmac() - Генерирует хеш-код на основе ключа через метод HMAC

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — Возвращает список зарегистрированных алгоритмов хеширования

### Описание

function hash_algos(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив, который содержит список поддерживаемых алгоритмов хеширования.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Добавили поддержку алгоритмов MurmurHash3 и xxHash.
7.4.0 | Добавили поддержку алгоритма crc32c.
7.1.0 | Добавили поддержку алгоритмов sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 и sha3-512.

### Примеры

Пример #1 Пример использования функции hash_algos()

Начиная с PHP 8.1.0 функция hash_algos() возвращает следующий список названий алгоритмов хеширования.

    <?php

    print_r(hash_algos());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => adler32
        [30] => crc32
        [31] => crc32b
        [32] => crc32c
        [33] => fnv132
        [34] => fnv1a32
        [35] => fnv164
        [36] => fnv1a64
        [37] => joaat
        [38] => murmur3a
        [39] => murmur3c
        [40] => murmur3f
        [41] => xxh32
        [42] => xxh64
        [43] => xxh3
        [44] => xxh128
        [45] => haval128,3
        [46] => haval160,3
        [47] => haval192,3
        [48] => haval224,3
        [49] => haval256,3
        [50] => haval128,4
        [51] => haval160,4
        [52] => haval192,4
        [53] => haval224,4
        [54] => haval256,4
        [55] => haval128,5
        [56] => haval160,5
        [57] => haval192,5
        [58] => haval224,5
        [59] => haval256,5
    )

### Смотрите также

- hash() - Генерирует хеш-значение (подпись сообщения)
- hash_hmac_algos() - Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — Копирует контекст хеширования

### Описание

function hash_copy(HashContext `$context`): HashContext

### Список параметров

`context`

  Контекст хеширования, возвращённый hash_init().

### Возвращаемые значения

Возвращает копию контекста хеширования.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Принимает и возвращает HashContext, а не ресурс.

### Примеры

Пример #1 Пример использования hash_copy()

    <?php
    $context = hash_init("sha256");
    hash_update($context, "Наглый коричневый лисёнок");

    /* копия контекста для дальнейшего использования */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "прыгает вокруг ленивой собаки.");
    echo hash_final($copy_context), "\n";
    ?>

Результат выполнения приведённого примера:

    49fd7dddcdc0e0e6b2252f966b750d78536e8cd2677bf84db0c605652f7f1699
    8b0ec9465a2a0befe6b45bc081e32e4629a7f3e39dcf1fda31af101b8d85145b

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — Сравнивает строки без риска атаки по времени

### Описание

function hash_equals(#[\SensitiveParameter]string `$known_string`, #[\SensitiveParameter]string `$user_string`): bool

Функция сравнивает две строки на идентичность так, что значение параметра `known_string` нельзя раскрыть методами, которые основаны на знании времени исполнения функции.

Эту функцию можно вызывать для снижения риска атак по времени. Обычное сравнение через оператор `===` будет занимать разное время в зависимости от того, разные это значения или нет и в какой позиции первое отличие будет найдено, так раскрывается значение параметра `known_string`.

Предостережение

Внимание! Передавать полученную от пользователя строку необходимо во второй параметр, а не в первый.

### Список параметров

`known_string`

  Известная строка (string), которая должна держаться в секрете.

`user_string`

  Пользовательская строка (string) для сравнения.

### Возвращаемые значения

Функция возвращает `true`, если строки идентичны, и `false`, если нет.

### Примеры

Пример #1 Пример использования функции hash_equals()

    <?php

    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // Значение и подпись предоставляются пользователем, например, внутри URL-адреса,
    // и были извлечены из суперглобальной переменной $_GET.
    $value = 'username=rasmuslerdorf';
    $signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

    if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
        echo "Значение подписали правильно.", PHP_EOL;
    } else {
        echo "Значение подделали.", PHP_EOL;
    }

    ?>

Результат выполнения приведённого примера:

    Значение подписали правильно.

### Примечания

> Замечание:

> Для успешного сравнения оба аргумента должны быть одинаковой длины. Если передали аргументы разной длины, функция сразу возвращает `false`, и длина известной строки может быть раскрыта при атаке по времени.

### Смотрите также

- hash_hmac() - Генерирует хеш-код на основе ключа через метод HMAC

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — Генерирует хеш-значение на основе содержимого файла

### Описание

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список поддерживаемых алгоритмов даёт описание функции hash_algos().

`filename`

  URL-адрес, который описывает расположение файла, который требуется захешировать; поддерживаются обёртки, с которыми работает функция fopen().

`binary`

  Функция выводит необработанные двоичные данные, если для параметра установили значение `true`. Функция выводит символы в шестнадцатеричной кодировке в нижнем регистре, если для параметра установили значение `false`.

`options`

  Массив опций для алгоритмов хеширования. Пока вариантами функций хеширования MurmurHash поддерживается только параметр `"seed"`.

### Возвращаемые значения

Функция возвращает строку, которая содержит вычисленную хеш-подпись сообщения в виде строчных шестнадцатеричных символов в нижнем регистре, если только для параметра `binary` не установили значение `true`, тогда возвращается необработанное двоичное представление хеш-подписи сообщения, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Добавили параметр `options`.

### Примеры

Пример #1 Пример использования функции hash_file()

    <?php

    /* Создаём файл, чтобы вычислить его хеш */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_file('sha256', 'example.txt');

    ?>

Результат выполнения приведённого примера:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_hmac_file() - Генерирует хеш-значение на основе ключа через метод HMAC и содержимое файла

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода

### Описание

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### Список параметров

`context`

  Контекст хеширования, возвращённый hash_init().

`binary`

  Когда установлено в `true`, выводит необработанные двоичные данные. При `false` выводит данные в шестнадцатеричной кодировке в нижнем регистре.

### Возвращаемые значения

Возвращает строку содержащую вычисленный хеш-код в шестнадцатеричной кодировке в нижнем регистре. Если `binary` задан как `true`, то возвращается хеш-код в виде бинарных данных.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Принимает HashContext, а не ресурс.

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_update() - Добавляет данные в активный контекст хеширования
- hash_update_stream() - Добавляет данные из открытого потока в активный контекст хеширования
- hash_update_file() - Добавляет данные из файла в активный контекст хеширования

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Формирует HKDF-ключ из исходного ключа

### Описание

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter]string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### Список параметров

`algo`

  Название алгоритма хеширования, например `"sha256"`. Список алгоритмов, которые поддерживает функция, приводит описание функции hash_hmac_algos().

  > Замечание:

  > Некриптографические хеширующие функции не допускаются.

`key`

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

`length`

  Длина вывода в байтах. Нельзя превышать размер хеш-функции более чем в 255 раз.

  При передаче в параметр `length` значения `0` длина вывода по умолчанию приравнивается к размеру хеш-значения, которое возвращает заданная в первом параметре хеш-функция.

`info`

  Информационная строка, специфичная для приложения или контекста.

`salt`

  Соль для формирования ключа.

  Добавление произвольной соли значительно повышает прочность HKDF-ключа, хотя параметр и необязателен.

### Возвращаемые значения

Функция возвращает строку, которая содержит необработанное двоичное представление производного ключа, которое также знают как выходной ключевой материал (англ. Output Keying Material, OKM).

### Ошибки

Функция выбрасывает исключение ValueError, если параметр `key` пуст, в параметре `algo` указали неизвестный или некриптографический алгоритм, параметр `length` меньше `0` или чрезмерно большой — больше чем в 255 раз превышает размер хеш-функции.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция при ошибке теперь выбрасывает ошибку ValueError; раньше выдавалась ошибка уровня `E_WARNING` и возвращалось значение `false`.

### Примеры

В приведённом примере создаётся пара отдельных ключей, которые подходят для создания конструкции «зашифровать, затем сформировать ключ HMAC» через алгоритм AES-256 для шифрования и алгоритм SHA-256 для аутентификации.

Пример #1 Пример формирования HKDF-ключ из исходного функцией hash_hkdf()

    <?php

    // Генерируем случайный ключ и соль для усиления процесса формирования
    $inputKey = random_bytes(32);
    $salt = random_bytes(16);

    // Формируем пару разных ключей с одними и теми же входными данными
    $encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
    $authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

    var_dump($encryptionKey !== $authenticationKey); // bool(true)

    ?>

### Смотрите также

- hash_pbkdf2() - Генерирует PBKDF2-ключ на основе исходного пароля
- » RFC 5869
- » Пользовательская реализация функции

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — Генерирует хеш-код на основе ключа через метод HMAC

### Описание

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список поддерживаемых алгоритмов возвращает функция hash_hmac_algos().

  > Замечание:

  > Некриптографические хеш-функции не допускаются.

`data`

  Сообщение для хеширования.

`key`

  Общий секретный ключ для генерации хеш-кода методом HMAC.

`binary`

  Функция выводит необработанные двоичные данные, если для параметра установили значение `true`. При значении `false` функция выводит данные в шестнадцатеричной кодировке в нижнем регистре.

### Возвращаемые значения

Функция возвращает строку, которая содержит вычисленный хеш-код в шестнадцатеричной кодировке в нижнем регистре. Функция возвращает хеш-код в виде бинарных данных, если для параметра `binary` установили значение `true`.

### Ошибки

Функция выбрасывает ошибку ValueError, если в аргументе `algo` указали название неизвестной или некриптографической хеш-функции.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь выбрасывает ошибку ValueError, если в параметр `algo` передали название неизвестной или некриптографической хеш-функции; раньше вместо этого возвращалось значение `false` и выдавалось сообщение об ошибке уровня `E_WARNING`.
7.2.0 | Генерацию хеш-строки через некриптографические хеш-функции наподобие adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat запретили.

### Примеры

Пример #1 Пример генерации хеш-кода функцией hash_hmac()

    <?php

    echo hash_hmac('sha256', 'Съешь же ещё этих мягких французских булок, да выпей чаю.', 'secret');

Результат выполнения приведённого примера:

    d6f502c51167410320e6f85de2a66f04ed961c04396275cf808ed43828663a9d

### Смотрите также

- hash_hmac_algos() - Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac
- hash_hmac_file() - Генерирует хеш-значение на основе ключа через метод HMAC и содержимое файла
- hash_equals() - Сравнивает строки без риска атаки по времени

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac

### Описание

function hash_hmac_algos(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает индексированный массив со списком поддерживаемых функцией hash_hmac() алгоритмов хеширования.

### Примеры

Пример #1 Пример использования hash_hmac_algos()

    <?php
    print_r(hash_hmac_algos());

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => haval128,3
        [30] => haval160,3
        [31] => haval192,3
        [32] => haval224,3
        [33] => haval256,3
        [34] => haval128,4
        [35] => haval160,4
        [36] => haval192,4
        [37] => haval224,4
        [38] => haval256,4
        [39] => haval128,5
        [40] => haval160,5
        [41] => haval192,5
        [42] => haval224,5
        [43] => haval256,5
    )

### Примечания

> Замечание:

> До PHP 7.2.0 единственным вариантом получить список поддерживаемых алгоритмов было вызвать функцию hash_algos(), которая также возвращала алгоритмы не поддерживаемые hash_hmac().

### Смотрите также

- hash_hmac() - Генерирует хеш-код на основе ключа через метод HMAC
- hash_algos() - Возвращает список зарегистрированных алгоритмов хеширования

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — Генерирует хеш-значение на основе ключа через метод HMAC и содержимое файла

### Описание

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string|false

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список алгоритмов, которые поддерживает функция, приводит описание функции hash_hmac_algos().

  > Замечание:

  > Некриптографические хеш-функции не допускаются.

`filename`

  URL-адрес, который описывает местоположение файла, который требуется захешировать; поддерживаются обёртки fopen.

`key`

  Общий секретный ключ для генерации варианта HMAC-ключа хеш-подписи.

`binary`

  Функция выводит необработанные двоичные данные, если для параметра установили значение `true`. Если `false` — функция выводит символы в шестнадцатеричной кодировке в нижнем регистре.

### Возвращаемые значения

Функция возвращает строку, которая содержит вычисленную хеш-подпись сообщения в виде строчных шестнадцатеричных символов в нижнем регистре, если только для параметра `binary` не установили значение `true`, тогда возвращается необработанное двоичное представление хеш-подписи сообщения. Функция возвращает `false`, если файл `filename` недоступен для чтения.

### Ошибки

Функция выбрасывает исключение ValueError, если параметр `algo` неизвестен или не криптографическая хеш-функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь выбрасывает исключение ValueError, если алгоритм `algo` неизвестен или не криптографическая хеш-функция; раньше вместо этого возвращалось значение `false` и выдавалось сообщение об ошибке уровня `E_WARNING`.
7.2.0 | Запретили некриптографические хеш-функции (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat).

### Примеры

Пример #1 Пример использования функции hash_hmac_file()

    <?php

    /* Создаём файл, чтобы вычислить хеш файла */
    file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

    echo hash_hmac_file('sha256', 'example.txt', 'secret');

    ?>

Результат выполнения приведённого примера:

    9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

### Смотрите также

- hash_hmac() - Генерирует хеш-код на основе ключа через метод HMAC
- hash_hmac_algos() - Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac
- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_equals() - Сравнивает строки без риска атаки по времени

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — Инициализирует контекст инкрементного хеширования

### Описание

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter]string `$key` = "",
array `$options` = []
): HashContext

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список алгоритмов, которые поддерживает функция, приводит описание функции hash_hmac_algos().

  > Замечание:

  > Некриптографические хеш-функции не допускаются, если указали флаг `HASH_HMAC`.

`flags`

  Необязательные настройки для генерации хеша, пока поддерживается только один вариант: `HASH_HMAC`. При этом параметр `key` должен быть указан.

`key`

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

`options`

  Массив опций для алгоритмов хеширования. Пока вариантами функций хеширования MurmurHash поддерживается только параметр `"seed"`.

### Возвращаемые значения

Функция возвращает контекст хеширования для передачи в функции hash_update(), hash_update_stream(), hash_update_file() и hash_final().

### Ошибки

- Функция выбрасывает ошибку ValueError, если в параметре `algo` указали неизвестную или некриптографическую хеш-функцию, или если параметр `key` пуст.
- При передаче в аргументе `options` параметров конфигурации неверного типа теперь выдаётся ошибка уровня `E_DEPRECATED`, поскольку такие параметры иногда интерпретируются неправильно. В будущем это станет выбрасывать ошибку ValueError.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Передача параметров неверного типа устарела.
8.1.0 | Добавили параметр `options`.
8.0.0 | Теперь функция выбрасывает исключение ValueError, если параметр `algo` неизвестен или не криптографическая хеш-функция, или если параметр `key` пуст; раньше возвращалось значение `false` и выдавалась ошибка уровня `E_WARNING`. emitted.
7.2.0 | Запретили некриптографические хеш-функции (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) с константой `HASH_HMAC`.
7.2.0 | Функция возвращает объект класса HashContext, а не ресурс.

### Примеры

Пример #1 Пример инкрементного хеширования

    <?php

    $hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'The quick brown fox ');
    hash_update($ctx, 'jumped over the lazy dog.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);

    ?>

Результат выполнения приведённого примера:

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
    bool(true)

### Смотрите также

- hash_algos() - Возвращает список зарегистрированных алгоритмов хеширования
- hash_update() - Добавляет данные в активный контекст хеширования
- hash_update_file() - Добавляет данные из файла в активный контекст хеширования
- hash_update_stream() - Добавляет данные из открытого потока в активный контекст хеширования
- hash_final() - Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Генерирует PBKDF2-ключ на основе исходного пароля

### Описание

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### Список параметров

`algo`

  Название алгоритма хеширования (например, `"sha256"`). Список алгоритмов, которые поддерживает функция, приводит описание функции hash_hmac_algos().

  > Замечание:

  > Некриптографические хеш-функции не допускаются.

`password`

  Пароль для деривации.

`salt`

  Соль для формирования ключа. Требуется сгенерировать случайное значение.

`iterations`

  Количество внутренних итераций для преобразования исходного пароля в хеш-ключ.

`length`

  Длина строки вывода. Если параметр `binary` задали как `true`, значение этого параметра соответствует длине ключа в байтах, если для параметра `binary` установили значение `false` — соответствует удвоенной длине ключа в байтах, поскольку каждый байт ключа возвращается в виде двух шестнадцатеричных символов.

  Со значением `0` функция вернёт весь вывод заданного алгоритма.

`binary`

  Функция выводит необработанные двоичные данные, если значение параметра равно `true`. Если `false` — выводятся шестнадцатеричные строчные буквы в нижнем регистре.

`options`

  Массив опций для алгоритмов хеширования. Пока вариантами функций хеширования MurmurHash поддерживается только параметр `"seed"`.

### Возвращаемые значения

Функция возвращает строку, которая содержит сформированный ключ в виде строки шестнадцатеричных чисел в нижнем регистре, если только для параметра `binary` не установили значение `true`, тогда возвращаются необработанные двоичные данные.

### Ошибки

Функция выбрасывает исключение ValueError, если алгоритм неизвестен, параметр `iterations` меньше или равен `0`, параметр `length` меньше `0` или параметр `salt` чрезмерно длинный (больше значения выражения `INT_MAX``- 4`).

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь выбрасывается исключение ValueError, если возникла ошибка; раньше функция возвращала `false` и выдавала ошибку уровня `E_WARNING`.
7.2.0 | Запретили некриптографические хеш-функции (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat).

### Примеры

Пример #1 Пример базового использования функции hash_pbkdf2()

    <?php

    $password = "password";
    $iterations = 600000;

    // Создаём криптографически безопасную случайную соль функцией random_bytes()
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // Для необработанного двоичного файла параметр $length требуется уменьшить вдвое, чтобы получить аналогичные результаты
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));

    ?>

Вывод приведённого примера будет похож на:

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### Примечания

Предостережение

Метод PBKDF2 может использовать для хеширования паролей в целях хранения. Однако следует отметить, что функция password_hash() или функция crypt() с типом хеша `CRYPT_BLOWFISH` лучше для хранения паролей.

### Смотрите также

- password_hash() - Создаёт хеш пароля
- hash_hkdf() - Формирует HKDF-ключ из исходного ключа
- sodium_crypto_pwhash() - Получает ключ из пароля алгоритмом Argon2

# hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — Добавляет данные в активный контекст хеширования

### Описание

function hash_update(HashContext `$context`, string `$data`): true

### Список параметров

`context`

  Контекст хеширования, возвращаемый hash_init().

`data`

  Сообщение, которое должно быть включено в хеш.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает значение true вместо логического значения (bool).
7.2.0 | Принимает HashContext, а не ресурс.

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_update_file() - Добавляет данные из файла в активный контекст хеширования
- hash_update_stream() - Добавляет данные из открытого потока в активный контекст хеширования
- hash_final() - Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — Добавляет данные из файла в активный контекст хеширования

### Описание

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### Список параметров

`context`

  Контекст хеширования, который возвращает функция hash_init().

`filename`

  URL-адрес, который описывает расположение файла, который требуется захешировать; поддерживаются обёртки, с которыми работает функция fopen().

`stream_context`

  Контекст потока, который возвращает функция stream_context_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `stream_context` теперь принимает значение null.
7.2.0 | Функция принимает объект класса HashContext, а не ресурс.

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_update() - Добавляет данные в активный контекст хеширования
- hash_update_stream() - Добавляет данные из открытого потока в активный контекст хеширования
- hash_final() - Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода
- hash_file() - Генерирует хеш-значение на основе содержимого файла

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — Добавляет данные из открытого потока в активный контекст хеширования

### Описание

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### Список параметров

`context`

  Контекст хеширования, который возвращает функция hash_init().

`stream`

  Дескриптор открытого файла, который возвращют функции, которыми создают потоки.

`length`

  Максимальное число символов для копирования из потока `stream` в контекст хеширования.

### Возвращаемые значения

Функция возвращает фактическое количество байтов, которое добавилось в контекст хеширования из потока `stream`.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Функция вместо ресурса теперь принимает объект класса HashContext.

### Примеры

Пример #1 Пример добавления данных в активный контекст хеширования функцией hash_update_stream()

    <?php

    $fp = tmpfile();
    fwrite($fp, 'прыгает вокруг ленивой собаки.');

    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'Наглый коричневый лисёнок ');

    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);

    ?>

Результат выполнения приведённого примера:

    199f52fc9f2492c64449ed96003f135f8ea428e353e50c40b0c1a16b9c16f571

### Смотрите также

- hash_init() - Инициализирует контекст инкрементного хеширования
- hash_update() - Добавляет данные в активный контекст хеширования
- hash_final() - Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода

## Содержание

- hash — Генерирует хеш-значение (подпись сообщения)
- hash_algos — Возвращает список зарегистрированных алгоритмов хеширования
- hash_copy — Копирует контекст хеширования
- hash_equals — Сравнивает строки без риска атаки по времени
- hash_file — Генерирует хеш-значение на основе содержимого файла
- hash_final — Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода
- hash_hkdf — Формирует HKDF-ключ из исходного ключа
- hash_hmac — Генерирует хеш-код на основе ключа через метод HMAC
- hash_hmac_algos — Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac
- hash_hmac_file — Генерирует хеш-значение на основе ключа через метод HMAC и содержимое файла
- hash_init — Инициализирует контекст инкрементного хеширования
- hash_pbkdf2 — Генерирует PBKDF2-ключ на основе исходного пароля
- hash_update — Добавляет данные в активный контекст хеширования
- hash_update_file — Добавляет данные из файла в активный контекст хеширования
- hash_update_stream — Добавляет данные из открытого потока в активный контекст хеширования

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- HashContext — Класс HashContext
  - HashContext::__construct — Закрытый конструктор для запрета непосредственного создания объекта
  - HashContext::__debugInfo — Возвращает отладочную информацию о контексте хеширования
  - HashContext::__serialize — Сериализует объект HashContext
  - HashContext::__unserialize — Десериализует параметр data в объект HashContext
- Функции Hash
  - hash — Генерирует хеш-значение (подпись сообщения)
  - hash_algos — Возвращает список зарегистрированных алгоритмов хеширования
  - hash_copy — Копирует контекст хеширования
  - hash_equals — Сравнивает строки без риска атаки по времени
  - hash_file — Генерирует хеш-значение на основе содержимого файла
  - hash_final — Завершает инкрементальное хеширование и возвращает результат в виде хеш-кода
  - hash_hkdf — Формирует HKDF-ключ из исходного ключа
  - hash_hmac — Генерирует хеш-код на основе ключа через метод HMAC
  - hash_hmac_algos — Возвращает список зарегистрированных алгоритмов хеширования, применимых для hash_hmac
  - hash_hmac_file — Генерирует хеш-значение на основе ключа через метод HMAC и содержимое файла
  - hash_init — Инициализирует контекст инкрементного хеширования
  - hash_pbkdf2 — Генерирует PBKDF2-ключ на основе исходного пароля
  - hash_update — Добавляет данные в активный контекст хеширования
  - hash_update_file — Добавляет данные из файла в активный контекст хеширования
  - hash_update_stream — Добавляет данные из открытого потока в активный контекст хеширования

# Mcrypt

# Введение

Внимание

Эта функциональность объявлена УСТАРЕВШЕЙ в PHP 7.1.0 и УДАЛЕНА в PHP 7.2.0.

Разработчикам доступны следующие альтернативы:

- Sodium (доступен с PHP 7.2.0)
- OpenSSL

> Замечание: Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 7.2.0.

Это интерфейс к библиотеке mcrypt, которая поддерживает широкий спектр блочных алгоритмов, таких как DES, TripleDES, Blowfish (по умолчанию), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 и GOST с режимами шифрования CBC, OFB, CFB и ECB. Дополнительно поддерживаются RC6 и IDEA, которые являются "не свободными". CFB/OFB по умолчанию 8-битный.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Эти функции работают используя » mcrypt. Для того, чтобы использовать их, загрузите libmcrypt-x.x.tar.gz из » http://mcrypt.sourceforge.net/ и следуйте инструкциям по установке.

Вам понадобится libmcrypt версии 2.5.6 или выше.

Пользователи Windows могут найти библиотеку в бинарном релизе PHP 5.2 для Windows. Бинарный релиз PHP 5.3 для Windows использует статическую версию библиотеки MCrypt, DLL-файл не нужен.

Если вы используете libmcrypt 2.4.x или выше, поддерживаются следующие дополнительные блочные алгоритмы: CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT, и следующие шифры потоков: ENIGMA (crypt), PANAMA, RC4 and WAKE. С libmcrypt 2.4.x или выше также доступен другой режим шифрования: nOFB.

## Установка

Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 7.2.0

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/mcrypt.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Mcrypt
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`mcrypt.algorithms_dir` string
  Директория, содержащая алгоритмы. По умолчанию соответствует директориям, скомпилированным вместе с libmcrypt, обычно /usr/local/lib/libmcrypt. Смотрите mcrypt_list_algorithms() для дополнительной информации.
`mcrypt.modes_dir` string
  Директория, содержащая режимы. По умолчанию соответствует директориям, скомпилированным вместе с libmcrypt, обычно /usr/local/lib/libmcrypt. Смотрите mcrypt_list_modes() для дополнительной информации.

## Типы ресурсов

mcrypt_module_open() возвращает дескриптор шифрования.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Mcrypt может работать в четырёх режимах блочного шифрования (`CBC`, `OFB`, `CFB` и `ECB`). Если слинковано с libmcrypt-2.4.x или выше, функции также могут работать в режимах `nOFB` и `STREAM`. Ниже вы найдёте список всех поддерживаемых режимов шифрования вместе с константами, которые определены для них. Более подробно читайте Applied Cryptography by Schneier (ISBN 0-471-11709-9).

- `MCRYPT_MODE_ECB` (`electronic codebook`) - это режим блочного шифрования, который в целом непригоден для большинства задач. Использование этого режима не рекомендовано.
- `MCRYPT_MODE_CBC` (`cipher block chaining`) - это режим блочного шифрования, который немногим лучше `ECB`.
- `MCRYPT_MODE_CFB` (`cipher feedback, в 8-битном режиме`) - это режим потокового шифрования. Рекомендуется использовать режим `NCFB`, а не `CFB`.
- `MCRYPT_MODE_OFB` (`output feedback, в 8-битном режиме`) - это режим потокового шифрования сравнимый с `CFB`, но может использоваться в приложениях, нетерпимых к распространению ошибок. Рекомендуется использовать режим `NOFB` вместо `OFB`.
- `MCRYPT_MODE_NOFB` (`output feedback, в N-битном режиме`) - сравним с режимом `OFB`, но оперирует полным размером блока алгоритма.
- `MCRYPT_MODE_STREAM` - это дополнительный режим для подключения некоторых потоковых алгоритмов, таких как `"WAKE"` или `"RC4"`.

Mcrypt поддерживает некоторые другие режимы работы для которых нет предопределённых констант. Их можно задавать с помощью строки вместо константы.

- `"ctr"` (`counter mode`) - режим потокового шифрования.
- `"ncfb"` (`cipher feedback, в N-битном режиме`) - сравним с режимом `CFB`, но оперирует полным размером блока алгоритма.

Некоторые другие режимы и константы генераторов случайных чисел:

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Шифры Mcrypt

Здесь перечислены шифры, поддерживаемые модулем mcrypt. Для полного списка поддерживаемых шифров смотрите список в конце файла mcrypt.h. Главное правило API mcrypt-2.2.x API состоит в том, что доступ к шифрам из PHP осуществляется путём использования констант MCRYPT_имя_шифра. Эти константы также работают с AI libmcrypt-2.4.x и libmcrypt-2.5.x, но также можно задать шифр по имени с помощью функции mcrypt_module_open().

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (только для libmcrypt > 2.4.x)
- MCRYPT_ARCFOUR (только для libmcrypt > 2.4.x)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (только для libmcrypt 2.2.x)
- MCRYPT_ENIGMA (только для libmcrypt > 2.4.x, псевдоним для MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (не свободный)
- MCRYPT_LOKI97 (только для libmcrypt > 2.4.x)
- MCRYPT_MARS (только для libmcrypt > 2.4.x, не свободный)
- MCRYPT_PANAMA (только для libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_128 (только для libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_192 (только для libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_256 (только для libmcrypt > 2.4.x)
- MCRYPT_RC2
- MCRYPT_RC4 (только для libmcrypt 2.2.x)
- MCRYPT_RC6 (только для libmcrypt > 2.4.x)
- MCRYPT_RC6_128 (только для libmcrypt 2.2.x)
- MCRYPT_RC6_192 (только для libmcrypt 2.2.x)
- MCRYPT_RC6_256 (только для libmcrypt 2.2.x)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (только для libmcrypt > 2.4.x)
- MCRYPT_SERPENT(только для libmcrypt > 2.4.x)
- MCRYPT_SERPENT_128 (только для libmcrypt 2.2.x)
- MCRYPT_SERPENT_192 (только для libmcrypt 2.2.x)
- MCRYPT_SERPENT_256 (только для libmcrypt 2.2.x)
- MCRYPT_SKIPJACK (только для libmcrypt > 2.4.x)
- MCRYPT_TEAN (только для libmcrypt 2.2.x)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (только для libmcrypt > 2.4.x)
- MCRYPT_TWOFISH (для старых версий mcrypt 2.x или mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx доступен в новых версиях 2.x, но не в 2.4.x)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (только для libmcrypt > 2.4.x)
- MCRYPT_XTEA (только для libmcrypt > 2.4.x)

Вы должны (в режимах `CFB` и `OFB`) или можете (в режиме `CBC`) предоставить инициализирующий вектор (IV) для выбранной функции шифрования. IV должен быть уникальным и должен быть одинаковым для шифрования и дешифрования. Для данных, которые хранятся в шифрованном виде вы можете получить вывод функции для индекса, под которым данные были сохранены (например, MD5 хеш имени файла). Или вы можете передать IV вместе с зашифрованными данными (смотрите раздел 9.3 Applied Cryptography by Schneier (ISBN 0-471-11709-9)).

# Mcrypt

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Создаёт инициализирующий вектор (Initialization Vector или IV) из случайного источника

Внимание

Функция УСТАРЕЛА с PHP 7.1.0, а в PHP 7.2.0 функцию УДАЛИЛИ.

Разработчикам доступны следующие альтернативы:

- random_bytes()

### Описание

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

Функция создаёт инициализирующий вектор из случайного источника.

Источник IV предназначен только для задания альтернативного начального случайного числа для процедур шифрования. Источник IV не обязательно должен быть секретным, хотя это и желательно. Разрешается даже отправить его вместе со своим зашифрованным текстом, не теряя при этом в безопасности.

### Список параметров

`size`
  Размер IV.
`source`
  Источник IV. Источник может быть задан одной из констант: `MCRYPT_RAND` (системный генератор случайных чисел), `MCRYPT_DEV_RANDOM` (читает данные из /dev/random) или `MCRYPT_DEV_URANDOM` (читает данные из /dev/urandom). До версии 5.3.0, на Windows поддерживался только `MCRYPT_RAND`. Обратите внимание, что до PHP 5.6.0 значением по умолчанию было `MCRYPT_DEV_RANDOM`.

  > Замечание: Обратите внимание, что `MCRYPT_DEV_RANDOM` может блокироваться до появления достаточной энтропии.

### Возвращаемые значения

Функция возвращает инициализирующий вектор или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции mcrypt_create_iv()

    <?php

    $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
    $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);

    ?>

### Смотрите также

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Applied Cryptography by Schneier (ISBN 0-471-11709-9), раздел 9.3
- random_bytes() - Генерирует криптографически безопасные случайные байты

# mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Расшифровывает данные с заданными параметрами

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Расшифровывает `data` и возвращает полученное значение.

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`key`
  Ключ, с которым шифровались данные. Если длина заданного ключа не подходит к указанному шифру, то функция выдаст предупреждение и вернёт `false`
`data`
  Данные, которые надо расшифровать с использованием шифра `cipher` и режима `mode`. Если размер данных не кратен размеру блока, то они будут дополнены символами '`\0`'.
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".
`iv`
  Указывают для инициализации в режимах CBC, CFB, OFB, а также в некоторых алгоритмах в режиме STREAM. Если переданный IV размер не поддерживается режимом сцепления или IV не был передан, а режим сцепления его требует, функция сгенерирует предупреждение об ошибке и вернёт `false`.

### Возвращаемые значения

Возвращает строку с расшифрованными данными или `false`, если возникла ошибка.

### Смотрите также

- mcrypt_encrypt() - Шифрует текст с заданными параметрами

# mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Возвращает имя алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_algorithms_name(resource `$td`): string

Эта функция возвращает имя алгоритма.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает имя открытого алгоритма в виде строки.

### Примеры

Пример #1 Пример использования mcrypt_enc_get_algorithms_name()

    <?php
    $td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";

    $td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";
    ?>

Результат выполнения приведённого примера:

    CAST-256
    CAST-256

# mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Возвращает размер блока алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_block_size(resource `$td`): int

Возвращает размер блока алгоритма.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает размер блока алгоритма в байтах.

# mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — Возвращает размер инициализирующего вектора для алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_iv_size(resource `$td`): int

Эта функция возвращает размер инициализирующего вектора в байтах для алгоритма, заданного дескриптором шифрования. Инициализирующий вектор используется в режимах cbc, cfb и ofb и в некоторых алгоритмах в потоковом режиме.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает размер инициализирующего вектора для алгоритма, или 0, если в целевом алгоритме он не используется.

# mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — Возвращает максимальную допустимую длину ключа алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_key_size(resource `$td`): int

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

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

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

# mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — Возвращает имя используемого режима

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_modes_name(resource `$td`): string

Возвращает имя используемого режима.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает имя используемого режима в виде строки.

### Примеры

Пример #1 Пример использования mcrypt_enc_get_modes_name()

    <?php
    $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_modes_name($td). "\n";

    $td = mcrypt_module_open ('cast-256', '', 'ecb', '');
    echo mcrypt_enc_get_modes_name($td). "\n";
    ?>

Результат выполнения приведённого примера:

    CFB
    ECB

# mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — Возвращает массив с допустимыми размерами ключа для используемого алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

Возвращает массив с допустимыми размерами ключа для используемого алгоритма.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает массив с допустимыми размерами ключа для используемого алгоритма. В случае, когда допустимы любые размеры от 1 до mcrypt_enc_get_key_size(), то возвращается пустой массив.

### Примеры

Пример #1 Пример использования mcrypt_enc_get_supported_key_sizes()

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      int(16)
      [1]=>
      int(24)
      [2]=>
      int(32)
    }

# mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — Проверяет, использует ли алгоритм блочные режимы

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

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

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает `true`, если алгоритм является блочным или `false`, если потоковый.

# mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — Проверяет, используется ли блочный режим

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

Проверяет, используется ли блочный режим (другими словами, `false` для потоков и `true` для cbc, cfb, ofb)..

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает `true`, если используется блочный режим и `false`, если нет.

# mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — Проверяет, возвращает ли текущий режим блоки

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_is_block_mode(resource `$td`): bool

Проверяет, возвращает ли текущий режим блоки (т.е. `true` для cbc и ecb, и `false` для cfb и потока).

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает `true`, если используемый режим возвращает блоки и `false`, если возвращает байты.

# mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — Запуск самопроверки открытого модуля

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_enc_self_test(resource `$td`): int

Функция запускает самопроверку алгоритма, заданного дескриптором шифрования `td`.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Возвращает `0` в случае успешного выполнения и отрицательное int в противном случае.

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — Шифрует текст с заданными параметрами

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Шифрует данные.

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`key`
  Ключ, с которым будут шифроваться данные. Если длина ключа не соответствует требованием шифра, то будет возвращено `false` и выдано предупреждение.
`data`
  Данные, которые будут зашифрованы с помощью шифра `cipher` и режима `mode`. Если размер данных не кратен размеру блока, то они будут дополнены символами '`\0`'. Размер возвращаемого текста может быть больше размера исходных данных `data`.
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".
`iv`
  Указывают для инициализации в режимах CBC, CFB, OFB, а также в некоторых алгоритмах в режиме STREAM. Если переданный IV размер не поддерживается режимом сцепления или IV не был передан, а режим сцепления его требует, функция сгенерирует предупреждение об ошибке и вернёт `false`.

### Возвращаемые значения

Возвращает строку с зашифрованными данными или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mcrypt_encrypt()

    <?php
        # --- ШИФРОВАНИЕ ---

        # ключ должен представлять собой случайную бинарную строку.
        # Для преобразовангия строки в ключ используйте scrypt, bcrypt или PBKDF2
        # Ключ задаётся в виде строки шестнадцатеричных чисел
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # Показываем длину ключа.
        # Длина ключа должна быть 16, 24 или 32 байт для AES-128, 192 и 256 соответственно
        $key_size =  strlen($key);
        echo "Длина ключа: " . $key_size . "\n";

        $plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

        # Создаём случайный инициализирующий вектор используя режим CBC
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # Создаём шифрованный текст совместимыс с AES (размер блока = 128)
        # Подходит только для строк не заканчивающихся на 00h
        # (потому как это символ дополнения по умолчанию)
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # Добавляем инициализирующий вектор в начало, чтобы он был доступен для расшифровки
        $ciphertext = $iv . $ciphertext;

        # перекодируем зашифрованный текст в base64
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === ВНИМАНИЕ ===

        # Результирующий шифрованный текст не имеет целостности или аутентичности и не
        # защищён от атак padding oracle.

        # --- ДЕШИФРОВКА ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # Извлекаем инициализирующий вектор. Длина вектора ($iv_size) должна совпадать
        # с тем, что возвращает функция mcrypt_get_iv_size()
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # Извлекаем зашифрованный текст
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # Отбрасываем завершающие символы 00h
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

Результат выполнения приведённого примера:

    Длина ключа: 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    This string was AES-256 / CBC / ZeroBytePadding encrypted.

### Смотрите также

- mcrypt_decrypt() - Расшифровывает данные с заданными параметрами
- mcrypt_module_open() - Открывает модуль шифрования с использованием указанных алгоритма и режима

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — Функция шифрует данные

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_generic(resource `$td`, string `$data`): string

Эта функция шифрует данные. Данные будут дополнены символами "`\0`" для того, чтобы их размер стал кратен размеру блока. Эта функция возвращает зашифрованные данные. Обратите внимание, что длина возвращаемой строки может быть больше исходной из-за дополнения.

Если вы хотите хранить шифрованные данные в базе данных, убедитесь, что вы сохраняете строку полностью, как она была возвращена этой функцией, иначе вы потом не сможете её расшифровать. Если ваша оригинальная строка была 10 символов длиной, а размер блока равен 8 (используйте mcrypt_enc_get_block_size() для определения размера блока), то размер столбца базы данных должен быть как минимум 16 символов. Обратите внимание, что строка возвращаемая mdecrypt_generic() также будет размером 16 символов. В таком случае просто используйте rtrim($str, "\0") для удаления добавленных символов.

К примеру, если вы сохраните данные в MySQL, помните, что при вставке значений в поля типа VARCHAR, у них автоматически отбрасываются пробелы из конца строки. Если зашифрованные данные кончаются на пробел (ASCII 32), то они будут повреждены при такой вставке. Лучше используйте для хранения поля типа TINYBLOB/TINYTEX или больше.

### Список параметров

`td`
  Дескриптор шифрования. Обработчик шифрования всегда должен инициализироваться с помощью mcrypt_generic_init() с ключом и инициализирующим вектором перед вызовом функции. Как только шифрование завершено, необходимо освободить буферы шифрования путём вызова функции mcrypt_generic_deinit(). Смотрите пример в описании функции mcrypt_module_open().
`data`
  Данные для шифрования.

### Возвращаемые значения

Возвращает зашифрованные данные.

### Смотрите также

- mdecrypt_generic() - Дешифровка данных
- mcrypt_generic_init() - Функция инициализирует все буферы, необходимые для шифрования
- mcrypt_generic_deinit() - Эта функция деинициализирует модуль шифрования

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — Эта функция деинициализирует модуль шифрования

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_generic_deinit(resource `$td`): bool

Эта функция прерывает шифрование, заданное дескриптором шифрования (`td`). Она очищает все буферы, но не закрывает модуль. Для закрытия модуля вы должны самостоятельно вызвать mcrypt_module_close(), либо он будет автоматически закрыт по завершении работы скрипта.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mcrypt_module_open() - Открывает модуль шифрования с использованием указанных алгоритма и режима
- mcrypt_generic_init() - Функция инициализирует все буферы, необходимые для шифрования

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — Функция инициализирует все буферы, необходимые для шифрования

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

Вы должны вызывать эту функцию перед любым вызовом mcrypt_generic() или mdecrypt_generic().

### Список параметров

`td`
  Дескриптор шифрования.
`key`
  Максимальная длина ключа должна быть получена с помощью функции mcrypt_enc_get_key_size() и любое меньшее значение допустимо.
`iv`
  Обычно размер инициализирующего вектора(IV) должен совпадать с размером блока, но вы всё равно должны получить это значение с помощью функции mcrypt_enc_get_iv_size(). IV игнорируется в ECB. IV ДОЛЖЕН присутствовать в режимах CFB, CBC, STREAM, nOFB и OFB. Он должен быть случайным и уникальным (но не обязательно секретным). Один и тот же IV должен использоваться как при шифровании так и при дешифровке. Если вы не хотите его использовать - просто установите его равным нулю, но так поступать не рекомендуется.

### Возвращаемые значения

В случае возникновения ошибки эта функция возвращает отрицательное число: -3 если длина ключа некорректна, -4 если возникли проблемы с выделением памяти, а любое другое значение обозначает неизвестную ошибку. Также, в случае любой ошибки будет вызвано предупреждение. если переданы некорректные параметры, будет возвращено `false`.

### Смотрите также

- mcrypt_module_open() - Открывает модуль шифрования с использованием указанных алгоритма и режима

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — Возвращает размер блока для указанного шифра

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

Первый прототип собран с библиотекой libmcrypt 2.2.x, а второй с libmcrypt 2.4.x или 2.5.x.

mcrypt_get_block_size() используется для получения размер блока указанного `cipher` (в комбинации с режимом шифрования).

Правильнее использовать mcrypt_enc_get_block_size(), которая использует ресурс, возвращаемый mcrypt_module_open().

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".

### Возвращаемые значения

Возвращает размер блока алгоритма в байтах или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mcrypt_get_block_size()

Этот пример демонстрирует использование функции собранной с libmcrypt 2.4.x и 2.5.x.

    <?php

    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

    ?>

### Смотрите также

- mcrypt_get_key_size() - Получить размер ключа заданного шифра
- mcrypt_enc_get_block_size() - Возвращает размер блока алгоритма
- mcrypt_encrypt() - Шифрует текст с заданными параметрами

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — Получает имя указанного шифра

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

Функция mcrypt_get_cipher_name() используется для получения имени указанного шифра.

mcrypt_get_cipher_name() берет номер шифра в качестве аргумента (libmcrypt 2.2.x) или имя шифра (libmcrypt 2.4.x или выше) и возвращает имя шифра или `false`, если шифр отсутствует.

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.

### Возвращаемые значения

Функция возвращает имя шифра или `false`, если такого шифра нет.

### Примеры

Пример #1 Пример использования mcrypt_get_cipher_name()

    <?php
       $cipher = MCRYPT_TripleDES;

       echo mcrypt_get_cipher_name($cipher);
    ?>

Результат выполнения приведённого примера:

    3DES

# mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — Возвращает размер инициализирующего вектора для соответствующей комбинации шифра и режима

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

Возвращает размер инициализирующего вектора для соответствующей заданной комбинации шифра `cipher` и режима `mode`.

Правильнее будет использовать mcrypt_enc_get_iv_size(), так как она возвращает результат по существующему дескриптору шифрования, полученного с помощью mcrypt_module_open().

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream". Инициализирующий вектор игнорируется в режиме ECB, так как он там не нужен. Вам понадобится один и тот же инициализирующий вектор как для шифрования, так и для дешифровки, иначе все ваше шифрование превратится в тыкву.

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования mcrypt_get_iv_size()

    <?php
        echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

        echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### Смотрите также

- mcrypt_get_block_size() - Возвращает размер блока для указанного шифра
- mcrypt_enc_get_iv_size() - Возвращает размер инициализирующего вектора для алгоритма
- mcrypt_create_iv() - Создаёт инициализирующий вектор (Initialization Vector или IV) из случайного источника

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — Получить размер ключа заданного шифра

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

Первый прототип собран с библиотекой libmcrypt 2.2.x, а второй с libmcrypt 2.4.x или 2.5.x.

mcrypt_get_key_size() используется для получения размера ключа для указанного шифра `cipher` (в комбинации с режимом шифрования).

Правильнее будет использовать mcrypt_enc_get_key_size(), так как она возвращает результат по существующему дескриптору шифрования, полученного с помощью mcrypt_module_open().

### Список параметров

`cipher`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".

### Возвращаемые значения

Возвращает максимально допустимую длину ключа в байтах или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mcrypt_get_key_size()

    <?php
        echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

Этот пример демонстрирует использование функции собранной с libmcrypt 2.4.x и 2.5.x.

Результат выполнения приведённого примера:

    24

### Смотрите также

- mcrypt_get_block_size() - Возвращает размер блока для указанного шифра
- mcrypt_enc_get_key_size() - Возвращает максимальную допустимую длину ключа алгоритма
- mcrypt_encrypt() - Шифрует текст с заданными параметрами

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — Получить список всех поддерживаемых алгоритмов шифрования

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

Получить список всех поддерживаемых алгоритмов шифрования в заданной директории `lib_dir`.

### Список параметров

`lib_dir`
  Указывает директорию, в которой расположены алгоритмы. Если не задано, то будет использовано значение директивы `mcrypt.algorithms_dir` из php.ini.

### Возвращаемые значения

Возвращает массив поддерживаемых алгоритмов.

### Примеры

Пример #1 Пример использования mcrypt_list_algorithms()

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => cast-128
        [1] => gost
        [2] => rijndael-128
        [3] => twofish
        [4] => arcfour
        [5] => cast-256
        [6] => loki97
        [7] => rijndael-192
        [8] => saferplus
        [9] => wake
        [10] => blowfish-compat
        [11] => des
        [12] => rijndael-256
        [13] => serpent
        [14] => xtea
        [15] => blowfish
        [16] => enigma
        [17] => rc2
        [18] => tripledes
    )

# mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — Получить список всех поддерживаемых режимов шифрования

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

Получить список всех режимов шифрования из директории `lib_dir`.

### Список параметров

`lib_dir`
  Указывает директорию, в которой расположены режимы. Если не задано, то будет использовано значение директивы `mcrypt.modes_dir` из php.ini.

### Возвращаемые значения

Возвращает массив поддерживаемых режимов.

### Примеры

Пример #1 Пример использования mcrypt_list_modes()

    <?php
        $modes = mcrypt_list_modes();

        foreach ($modes as $mode) {
            echo "$mode <br />\n";
        }
    ?>

Пример выше демонстрирует получение списка всех алгоритмов из директории по умолчанию. Если директива php.ini `mcrypt.modes_dir` не задана, то будет использована директория mcrypt по умолчанию (/usr/local/lib/libmcrypt).

# mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — Закрывает модуль mcrypt

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_close(resource `$td`): bool

Закрывает указанный обработчик шифрования.

### Список параметров

`td`
  Дескриптор шифрования.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mcrypt_module_open() - Открывает модуль шифрования с использованием указанных алгоритма и режима

# mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — Возвращает размер блока указанного алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

Возвращает размер блока указанного алгоритма.

### Список параметров

`algorithm`
  Имя алгоритма.
`lib_dir`
  Опциональный параметр, в котором можно указать директорию, содержащую модуль режима.

### Возвращаемые значения

Возвращает размер блока указанного алгоритма в байтах.

# mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — Возвращает максимальный размер ключа открытого режима

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

Возвращает максимальный размер ключа открытого режима.

### Список параметров

`algorithm`
  Имя алгоритма.
`lib_dir`
  Опциональный параметр, в котором можно указать директорию, содержащую модуль режима.

### Возвращаемые значения

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

# mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — Возвращает список поддерживаемых размеров ключей для открытого алгоритма

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

Возвращает список поддерживаемых размеров ключей для открытого алгоритма. Если возвращён пустой массив, значит поддерживается любая длина ключа от 1 до значения возвращаемого mcrypt_module_get_algo_key_size().

### Список параметров

`algorithm`
  Используемый алгоритм.
`lib_dir`
  Опциональный параметр `lib_dir`, в котором можно указать директорию, содержащую модуль алгоритма.

### Возвращаемые значения

Возвращает список поддерживаемых размеров ключей для открытого алгоритма. Если возвращён пустой массив, значит поддерживается любая длина ключа от 1 до значения возвращаемого mcrypt_module_get_algo_key_size().

### Смотрите также

- mcrypt_enc_get_supported_key_sizes() - Возвращает массив с допустимыми размерами ключа для используемого алгоритма

# mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — Проверяет, является ли заданный алгоритм блочным или нет

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

Функция возвращает `true`, если алгоритм блочный, иначе возвращает `false` (потоковый).

### Список параметров

`algorithm`
  Алгоритм для проверки.
`lib_dir`
  Опциональный параметр `lib_dir`, в котором можно указать директорию, содержащую модуль алгоритма.

### Возвращаемые значения

Функция возвращает `true`, если алгоритм блочный, иначе возвращает `false` (потоковый).

# mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

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

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

Функция возвращает `true`, если режим используется с блочными алгоритмами, иначе возвращает `false`. (то есть `false` для поточных и `true` для cbc, cfb, ofb).

### Список параметров

`mode`
  Режим, который будет проверяться.
`lib_dir`
  Опциональный параметр `lib_dir`, в котором можно указать директорию, содержащую модуль алгоритма.

### Возвращаемые значения

Функция возвращает `true`, если режим используется с блочными алгоритмами, иначе возвращает `false`. (то есть `false` для поточных и `true` для cbc, cfb, ofb).

# mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — Проверить, возвращает ли указанный режим данные блоками или нет

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

Функция возвращает `true`, если данные возвращаются блоками и `false`, если побайтно. (то есть `true` для cbc и ecb, и `false` для cfb и потока).

### Список параметров

`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".
`lib_dir`
  Опциональный параметр `lib_dir`, в котором можно указать директорию, содержащую модуль алгоритма.

### Возвращаемые значения

Функция возвращает `true`, если данные возвращаются блоками и `false` если побайтно. (то есть `true` для cbc и ecb, и `false` для cfb и потока).

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — Открывает модуль шифрования с использованием указанных алгоритма и режима

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

Открывает модуль шифрования с использованием указанных алгоритма и режима. Имя алгоритма задаётся его именем, например `"twofish"`, или с помощью константы `MCRYPT_ciphername`. Закрыть модуль можно с помощью функции mcrypt_module_close().

### Список параметров

`algorithm`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`algorithm_directory`
  Параметр `algorithm_directory` используется для задания местонахождения модуля шифрования. Если передать пустую строку, то (`""`), то будет использовано значение директивы `mcrypt.algorithms_dir` из php.ini. Если же оно тоже не задано, то будет использована стандартная директория с которой компилировался libmcrypt (обычно /usr/local/lib/libmcrypt).
`mode`
  Одна из констант `MCRYPT_MODE_modename`, либо одна из следующих строк: "ecb", "cbc", "cfb", "ofb", "nofb" и "stream".
`mode_directory`
  Параметр `mode_directory` используется для задания местонахождения модуля режима. Если передать пустую строку, то (`""`), то будет использовано значение директивы `mcrypt.modes_dir` из php.ini. Если же оно тоже не задано, то будет использована стандартная директория, с которой компилировался libmcrypt (обычно /usr/local/lib/libmcrypt).

### Возвращаемые значения

Обычно возвращается дескриптор шифрования или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования mcrypt_module_open()

    <?php
        $td = mcrypt_module_open(MCRYPT_DES, '',
            MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

В первой строке примера мы пробуем открыть шифр `DES` из директории по умолчанию и использовать режим `ECB` из директории /usr/lib/mcrypt-modes. Во втором примере используем строковые имена шифра и режима, что работает только с модулем, собранным с библиотекой libmcrypt 2.4.x or 2.5.x.

Пример #2 Пример использования mcrypt_module_open()

    <?php
        /* Открываем модуль шифрования */
        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

        /* Создаём инициализирующий вектор и определяем длину ключа.
         * Для ОС Windows указываем MCRYPT_RAND */
        $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
        $ks = mcrypt_enc_get_key_size($td);

         /* Создаём ключ (только как пример: алгортим MD5 — плохой алгоритм хеширования для хранения секретов) */
        $key = substr(hash('md5', 'very secret key'), 0, $ks);

        /* Инициализируем шифрование */
        mcrypt_generic_init($td, $key, $iv);

        /* Шифруем данные */
        $encrypted = mcrypt_generic($td, 'This is very important data');

        /* Деинициализируем обработчик шифрования */
        mcrypt_generic_deinit($td);

        /* Инициализируем модуль дешифровки */
        mcrypt_generic_init($td, $key, $iv);

        /* Дешифруем данные */
        $decrypted = mdecrypt_generic($td, $encrypted);

        /* Деинициализируем обработчик дешифровки и закрываем модуль */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);

        /* Печатаем строку */
        echo trim($decrypted) . "\n";
    ?>

### Смотрите также

- mcrypt_module_close() - Закрывает модуль mcrypt
- mcrypt_generic() - Функция шифрует данные
- mdecrypt_generic() - Дешифровка данных
- mcrypt_generic_init() - Функция инициализирует все буферы, необходимые для шифрования
- mcrypt_generic_deinit() - Эта функция деинициализирует модуль шифрования

# mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — Функция запускает самопроверку указанного модуля

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

Эта функция запускает самопроверку указанного алгоритма.

### Список параметров

`algorithm`
  Одна из констант `MCRYPT_ciphername` или название алгоритма в виде строки.
`lib_dir`
  Опциональный параметр `lib_dir`, в котором можно указать директорию, содержащую модуль алгоритма.

### Возвращаемые значения

Эта функция возвращает `true` если самопроверка завершилась успешно и `false`, если нет.

### Примеры

Пример #1 Пример использования mcrypt_module_self_test()

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

# mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — Дешифровка данных

Внимание

Начиная с PHP 7.1.0 функция УСТАРЕЛА, а в PHP 7.2.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function mdecrypt_generic(resource `$td`, string `$data`): string

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

### Список параметров

`td`
  Дескриптор шифрования, возвращаемый mcrypt_module_open()
`data`
  Зашифрованные данные.

### Возвращаемые значения

Возвращает расшифрованную строку.

### Примеры

Пример #1 Пример использования mdecrypt_generic()

    <?php
        /* Данные */
        $key = 'Это очень длинный ключ. Сильно больше, чем нужен шифру.';
        $plain_text = 'очень важные данные';

        /* Открываем модуль и создаём инициализирующий вектор */
        $td = mcrypt_module_open('des', '', 'ecb', '');
        $key = substr($key, 0, mcrypt_enc_get_key_size($td));
        $iv_size = mcrypt_enc_get_iv_size($td);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        /* Инициализируем обработчик шифрования */
        if (mcrypt_generic_init($td, $key, $iv) != -1) {

            /* Шифруем данные */
            $c_t = mcrypt_generic($td, $plain_text);
            mcrypt_generic_deinit($td);

            /* Переинициализируем буферы для дешифровки */
            mcrypt_generic_init($td, $key, $iv);
            $p_t = mdecrypt_generic($td, $c_t);

            /* Убираем мусор */
            mcrypt_generic_deinit($td);
            mcrypt_module_close($td);
        }

        if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
            echo "ок\n";
        } else {
            echo "ошибка\n";
        }
    ?>

Пример выше показывает, как проверить, что данные до шифрования совпадают с данными после дешифрования. Крайне важно переинициализировать буферы шифрования с помощью mcrypt_generic_init() перед дешифровкой данных.

Обработчик дешифрования всегда должен инициализироваться с помощью mcrypt_generic_init() с ключом и инициализирующим вектором перед вызовом функции. Как только шифрование завершено, необходимо освободить буферы шифрования путём вызова функции mcrypt_generic_deinit(). Смотрите пример в описании функции mcrypt_module_open().

### Смотрите также

- mcrypt_generic() - Функция шифрует данные
- mcrypt_generic_init() - Функция инициализирует все буферы, необходимые для шифрования
- mcrypt_generic_deinit() - Эта функция деинициализирует модуль шифрования

## Содержание

- mcrypt_create_iv — Создаёт инициализирующий вектор (Initialization Vector или IV) из случайного источника
- mcrypt_decrypt — Расшифровывает данные с заданными параметрами
- mcrypt_enc_get_algorithms_name — Возвращает имя алгоритма
- mcrypt_enc_get_block_size — Возвращает размер блока алгоритма
- mcrypt_enc_get_iv_size — Возвращает размер инициализирующего вектора для алгоритма
- mcrypt_enc_get_key_size — Возвращает максимальную допустимую длину ключа алгоритма
- mcrypt_enc_get_modes_name — Возвращает имя используемого режима
- mcrypt_enc_get_supported_key_sizes — Возвращает массив с допустимыми размерами ключа для используемого алгоритма
- mcrypt_enc_is_block_algorithm — Проверяет, использует ли алгоритм блочные режимы
- mcrypt_enc_is_block_algorithm_mode — Проверяет, используется ли блочный режим
- mcrypt_enc_is_block_mode — Проверяет, возвращает ли текущий режим блоки
- mcrypt_enc_self_test — Запуск самопроверки открытого модуля
- mcrypt_encrypt — Шифрует текст с заданными параметрами
- mcrypt_generic — Функция шифрует данные
- mcrypt_generic_deinit — Эта функция деинициализирует модуль шифрования
- mcrypt_generic_init — Функция инициализирует все буферы, необходимые для шифрования
- mcrypt_get_block_size — Возвращает размер блока для указанного шифра
- mcrypt_get_cipher_name — Получает имя указанного шифра
- mcrypt_get_iv_size — Возвращает размер инициализирующего вектора для соответствующей комбинации шифра и режима
- mcrypt_get_key_size — Получить размер ключа заданного шифра
- mcrypt_list_algorithms — Получить список всех поддерживаемых алгоритмов шифрования
- mcrypt_list_modes — Получить список всех поддерживаемых режимов шифрования
- mcrypt_module_close — Закрывает модуль mcrypt
- mcrypt_module_get_algo_block_size — Возвращает размер блока указанного алгоритма
- mcrypt_module_get_algo_key_size — Возвращает максимальный размер ключа открытого режима
- mcrypt_module_get_supported_key_sizes — Возвращает список поддерживаемых размеров ключей для открытого алгоритма
- mcrypt_module_is_block_algorithm — Проверяет, является ли заданный алгоритм блочным или нет
- mcrypt_module_is_block_algorithm_mode — Проверяет, является ли заданный модуль блочным или нет
- mcrypt_module_is_block_mode — Проверить, возвращает ли указанный режим данные блоками или нет
- mcrypt_module_open — Открывает модуль шифрования с использованием указанных алгоритма и режима
- mcrypt_module_self_test — Функция запускает самопроверку указанного модуля
- mdecrypt_generic — Дешифровка данных

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Шифры Mcrypt
- Mcrypt
  - mcrypt_create_iv — Создаёт инициализирующий вектор (Initialization Vector или IV) из случайного источника
  - mcrypt_decrypt — Расшифровывает данные с заданными параметрами
  - mcrypt_enc_get_algorithms_name — Возвращает имя алгоритма
  - mcrypt_enc_get_block_size — Возвращает размер блока алгоритма
  - mcrypt_enc_get_iv_size — Возвращает размер инициализирующего вектора для алгоритма
  - mcrypt_enc_get_key_size — Возвращает максимальную допустимую длину ключа алгоритма
  - mcrypt_enc_get_modes_name — Возвращает имя используемого режима
  - mcrypt_enc_get_supported_key_sizes — Возвращает массив с допустимыми размерами ключа для используемого алгоритма
  - mcrypt_enc_is_block_algorithm — Проверяет, использует ли алгоритм блочные режимы
  - mcrypt_enc_is_block_algorithm_mode — Проверяет, используется ли блочный режим
  - mcrypt_enc_is_block_mode — Проверяет, возвращает ли текущий режим блоки
  - mcrypt_enc_self_test — Запуск самопроверки открытого модуля
  - mcrypt_encrypt — Шифрует текст с заданными параметрами
  - mcrypt_generic — Функция шифрует данные
  - mcrypt_generic_deinit — Эта функция деинициализирует модуль шифрования
  - mcrypt_generic_init — Функция инициализирует все буферы, необходимые для шифрования
  - mcrypt_get_block_size — Возвращает размер блока для указанного шифра
  - mcrypt_get_cipher_name — Получает имя указанного шифра
  - mcrypt_get_iv_size — Возвращает размер инициализирующего вектора для соответствующей комбинации шифра и режима
  - mcrypt_get_key_size — Получить размер ключа заданного шифра
  - mcrypt_list_algorithms — Получить список всех поддерживаемых алгоритмов шифрования
  - mcrypt_list_modes — Получить список всех поддерживаемых режимов шифрования
  - mcrypt_module_close — Закрывает модуль mcrypt
  - mcrypt_module_get_algo_block_size — Возвращает размер блока указанного алгоритма
  - mcrypt_module_get_algo_key_size — Возвращает максимальный размер ключа открытого режима
  - mcrypt_module_get_supported_key_sizes — Возвращает список поддерживаемых размеров ключей для открытого алгоритма
  - mcrypt_module_is_block_algorithm — Проверяет, является ли заданный алгоритм блочным или нет
  - mcrypt_module_is_block_algorithm_mode — Проверяет, является ли заданный модуль блочным или нет
  - mcrypt_module_is_block_mode — Проверить, возвращает ли указанный режим данные блоками или нет
  - mcrypt_module_open — Открывает модуль шифрования с использованием указанных алгоритма и режима
  - mcrypt_module_self_test — Функция запускает самопроверку указанного модуля
  - mdecrypt_generic — Дешифровка данных

# Mhash

# Введение

Эти функции предназначены для работы с » mhash. Mhash может использоваться для подсчёта контрольных сумм, хеш-сумм, кодов идентификации сообщений и так далее.

Это интерфейс для библиотеки mhash. Mhash поддерживает большое количество алгоритмов шифрования, таких как MD5, SHA1, GOST и многих других. Для полного списка поддерживаемых алгоритмов шифрования перейдите на страницу с константами. Для получения доступа к определённому алгоритму из PHP нужно использовать `MHASH_hashname`. Например, чтобы получить доступ к TIGER необходимо использовать константу `MHASH_TIGER`.

> Замечание:

> Данный модуль устарел, в качестве замены используйте Hash.

> Замечание:

> Начиная с PHP 7.0.0, модуль Mhash полностью интегрирован в модуль Hash. Таким образом, теперь нельзя определить доступность поддержки Mhash с помощью функции extension_loaded(); вместо неё используйте function_exists(). Кроме того, Mhash больше не будет выводиться с помощью get_loaded_extensions() и подобных функций.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Скачайте дистрибутив mhash » с этого сайта и следуйте инструкциям.

## Установка

Необходимо скомпилировать PHP с опцией --with-mhash[=DIR]. Можно принудительно указать директорию с mhash.

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

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Здесь представлен список поддерживаемых mhash-хешей. Если хеша нет в этом списке, но есть в документации по модулю mhash, смело полагают, что хеш есть.

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  Доступен начиная с PHP 7.4.0.
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  Доступен начиная с 8.1.0.
`MHASH_MURMUR3C` (int)
  Доступен начиная с 8.1.0.
`MHASH_MURMUR3F` (int)
  Доступен начиная с 8.1.0.
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)
`MHASH_XXH32` (int)
`MHASH_XXH64` (int)
`MHASH_XXH3` (int)
`MHASH_XXH128` (int)

# Примеры

Пример #1 Вычисление MD5 и HMAC и печать их в шестнадцатеричном виде

    <?php
    $input = "what do ya want for nothing?";
    $hash = mhash(MHASH_MD5, $input);
    echo "Хеш MD5 - " . bin2hex($hash) . "<br />\n";
    $hash = mhash(MHASH_MD5, $input, "Jefe");
    echo "Хеш HMAC - " . bin2hex($hash) . "<br />\n";
    ?>

Результат выполнения приведённого примера:

    Хеш MD5 - d03cb659cbf9192dcd066272249f8412
    Хеш HMAC - 750c783e6ab0b503eaa86e310a5db738

# Функции Mhash

# mhash

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

mhash — Вычисляет хеш

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = null): string|false

Функция mhash() применяет к данным `data` хеш-функцию, которую указали в аргументе `algo`.

### Список параметров

`algo`

  Идентификатор хеша. Константа семейства `MHASH_*`.

`data`

  Строка с пользовательскими данными.

`key`

  С этим параметром вместо хеша функция вернёт HMAC-код. HMAC — код аутентификации сообщений, который включает криптографическую хеш-функцию и секретный ключ, или проще — дайджест сообщения, который зависит от конкретного ключа. Не каждый алгоритм, который поддерживается функцией mhash, доступен для формирования кода в режиме HMAC.

### Возвращаемые значения

Функция возвращает строку либо с хешем, или дайджестом, либо с HMAC-кодом. Функция возвращает `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функциями семейства функции `hash_*()`.
8.0.0 | Параметр `key` теперь принимает значение `null`.

# mhash_count

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

mhash_count — Получает наибольший доступный идентификатор хеша

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function mhash_count(): int

Функция возвращает наибольший доступный идентификатор хеша.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает наибольший доступный идентификатор хеша. Хеши нумеруются от 0 до этого идентификатора хеша.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функциями семейства функции `hash_*()`.

### Примеры

Пример #1 Обход всех хешей

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("Размер блока хеша %s - %d\n",
            mhash_get_hash_name($i),
            mhash_get_block_size($i))
        ;
    }

    ?>

# mhash_get_block_size

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

mhash_get_block_size — Получает размер блока хеша

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Функция возвращает размер блока хеша, идентификатор которого указали в аргументе `algo`.

### Список параметров

`algo`

  Идентификатор хеша. Константа семейства `MHASH_*`.

### Возвращаемые значения

Функция возвращает размер в байтах или `false`, если в аргументе `algo` передали недопустимое значение.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функциями семейства функции `hash_*()`.

### Примеры

Пример #1 Пример получения размера блока хеша функцией mhash_get_block_size()

    <?php

    echo mhash_get_block_size(MHASH_MD5); // 16

    ?>

# mhash_get_hash_name

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

mhash_get_hash_name — Получает имя хеша

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Функция возвращает имя хеша, идентификатор которого указали в аргументе `algo`.

### Список параметров

`algo`

  Идентификатор хеша. Константа семейства `MHASH_*`.

### Возвращаемые значения

Функция возвращает строку с названием или `false`, если такого хеша нет.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функциями семейства функции `hash_*()`.

### Примеры

Пример #1 Пример получения названия хеша функцией mhash_get_hash_name()

    <?php

    echo mhash_get_hash_name(MHASH_MD5); // MD5

    ?>

# mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — Генерирует ключ

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function mhash_keygen_s2k(
int `$algo`,
string `$password`,
string `$salt`,
int `$length`
): string|false

Функция генерирует ключ в соответствии с идентификатором хеша, который передали в аргументе `algo`, и пользовательским паролем, который передали в аргументе `password`.

Для генерации ключа функция использует алгоритм Salted S2K, как описывает документ OpenPGP » RFC 2440.

Помните, что пользовательские пароли не рекомендуют использовать как ключи в криптографических алгоритмах, поскольку пользователи часто выбирают ключи, которые доступны для набора на клавиатуре. Такие пароли используют только 6-7 битов на символ, а иногда меньше. Поэтому пользовательский ключ настоятельно рекомендуют преобразовывать функциями наподобие этой.

### Список параметров

`algo`

  Идентификатор хеша с которым создаётся ключ. Константа семейства `MHASH_*`.

`password`

  Пользовательский пароль.

`salt`

  Для параметра рекомендуют устанавливать разную и достаточно случайную соль для каждого ключа, который генерирует функция. Поскольку значение соли `salt` должно быть известно при проверке ключей, то лучше добавлять соль в начало ключа. Длина соли фиксирована и составляет 8 байтов, функция дополнит соль нулями, если размер значения в аргументе окажется короче.

`length`

  Длина ключа в байтах.

### Возвращаемые значения

Функция возвращает строку с ключом или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функциями семейства функции `hash_*()`.

## Содержание

- mhash — Вычисляет хеш
- mhash_count — Получает наибольший доступный идентификатор хеша
- mhash_get_block_size — Получает размер блока хеша
- mhash_get_hash_name — Получает имя хеша
- mhash_keygen_s2k — Генерирует ключ

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Примеры
- Функции Mhash
  - mhash — Вычисляет хеш
  - mhash_count — Получает наибольший доступный идентификатор хеша
  - mhash_get_block_size — Получает размер блока хеша
  - mhash_get_hash_name — Получает имя хеша
  - mhash_keygen_s2k — Генерирует ключ

# OpenSSL

# Введение

Модуль связывает функции библиотеки » OpenSSL для симметричного и асимметричного шифрования и дешифрования, поддерживает операции по правилам стандартов PBKDF2, PKCS7, PKCS12, X509 и другие криптографические операции. Модуль также реализует потоки TLS.

Библиотека OpenSSL предлагает функции, которые модуль пока не поддерживает. Отдельные функций, если потребуется, добавят в будущем.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для использования функций OpenSSL вам необходимо установить библиотеку » OpenSSL. Для версии PHP 7.0 требуется OpenSSL >= 0.9.8, < 1.2. Для версии PHP 7.1-8.0 требуется OpenSSL >= 1.0.1, < 3.0. Для версии PHP >= 8.1 требуется OpenSSL >= 1.0.2, < 4.0. Для версии PHP >= 8.4 требуется OpenSSL >= 1.1.1, < 4.0.

Внимание

Настоятельно рекомендуем использовать поддерживаемую версию OpenSSL, в противном случае ваш веб-сервер может быть уязвим для атак.

## Установка

Для поддержки библиотеки OpenSSL в PHP необходимо скомпилировать библиотеку с опцией --with-openssl.

Также библиотека OpenSSL устанавливает дополнительные требования для нормальной работы во время исполнения. Самое главное, библиотеке OpenSSL требуется доступ к генераторам случайных и псевдослучайных чисел; на большинстве систем Unix или Linux, это означает доступ к устройствам `/dev/urandom` или `/dev/random`.

Опция конфигурации --with-system-ciphers заставляет PHP использовать системный список шифров вместо жёстко заданного по умолчанию.

> Замечание: Замечания для пользователей Win32

> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libeay32.dll или начиная с OpenSSL 1.1 libcrypto-*.dll.

> Дополнительно, если вы собираетесь использовать функции генерации ключей и подписи сертификатов, вам придётся установить в системе корректный файл openssl.cnf. Мы включили демонстрационный конфигурационный файл в бинарную поставку под win32. Он лежит в директории extras/ssl.

> PHP будет искать файл openssl.cnf по следующей логике:

> - Переменная окружения `OPENSSL_CONF`. Если установили, то должна содержать путь (включая имя файла) до конфигурационного файла.
> - переменная окружения `SSLEAY_CONF`. Если установлена, то должна содержать путь (включая имя файла) до конфигурационного файла.
> - Поиск файла openssl.cnf будет выполняться по стандартному пути для сертификатов, который задали при компиляции DLL-библиотеки. Обычно файл задают как C:\Program Files\Common Files\SSL\openssl.cnf (x64) или C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86), или как C:\usr\local\ssl\openssl.cnf до PHP 7.4.0.
> При установке требуется определить, устанавливать ли файл по стандартному пути или хранить файл в другом месте и задать путь к файлу через переменные окружения, что полезно на виртуальных хостах. Обратите внимание, что путь по умолчанию разрешается переопределить в скрипте через параметр `options` функции, которой требуется этот файл.
> Предостережение

> Убедитесь, что непривилегированным пользователям не разрешено изменять файл openssl.cnf.

> C OpenSSL 3.0.0, который с PHP 8.2.0 используется в Windows по умолчанию, ряд алгоритмов устарел. Такие алгоритмы выходят из употребления, криптографическое сообщество признаёт такие алгоритмы небезопасными. Эти алгоритмы по-прежнему доступны через устаревшего поставщика — файл extras/ssl/legacy.dll; работу с поставщиком описывает раздел OpenSSL-руководства » о конфигурации поставщика.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Опция конфигурации --with-openssl[=DIR] больше не принимает аргумент каталога в пользу настройки переменной PKG_CONFIG_PATH команды pkg-config в положение OpenSSL или путём указания переменных OPENSSL_LIBS и OPENSSL_CFLAGS.
7.4.0 | Конфигурационный путь библиотеки OpenSSL по умолчанию изменили с C:\usr\local\ssl на C:\Program Files\Common Files\SSL или C:\Program Files (x86)\Common Files\SSL, соответственно.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки openssl
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |
openssl.libctx | "custom" | `INI_PERDIR` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`openssl.cafile` string

  Местоположение файла Certificate Authority на локальной файловой системе, который должен использоваться с опцией контекста verify_peer для аутентификации удалённой точки.

`openssl.capath` string

  Если cafile не задан или сертификат не найден, то директория, указанная в capath будет использована для поиска сертификата. capath должна быть корректно хешированной директорией сертификата.

`openssl.libctx` string
  Указывает тип контекста библиотеки OpenSSL, который будет использоваться. Значение по умолчанию, `custom`, создаёт отдельный контекст библиотеки для каждого рабочего процесса или потока. Улучшает изоляцию от других библиотек, использующих OpenSSL, а в сборках ZTS увеличивает разделение между потоками. Также можно использовать значение `default`, которое заставляет PHP использовать глобальный контекст библиотеки OpenSSL по умолчанию.

Также смотрите опции контекста потока SSL.

## Типы ресурсов

До PHP 8.0.0 в модуле OpenSSL было определено 3 типа ресурсов:

- `OpenSSL ключ`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# Предопределённые константы

## Содержание

- Флаги проверки
- Флаги заполнения для ассиметричного шифрования
- Типы ключей
- Константы-флаги структур PKCS7
- Константы-флаги стуктур CMS
- Алгоритмы подписи
- Алгоритмы шифрования
- Константы версий
- Константа SNI (Server Name Indication)
- Другие константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

## Флаги проверки

`X509_PURPOSE_SSL_CLIENT` (int)
`X509_PURPOSE_SSL_SERVER` (int)
`X509_PURPOSE_NS_SSL_SERVER` (int)
`X509_PURPOSE_SMIME_SIGN` (int)
`X509_PURPOSE_SMIME_ENCRYPT` (int)
`X509_PURPOSE_CRL_SIGN` (int)
`X509_PURPOSE_ANY` (int)
`X509_PURPOSE_OCSP_HELPER` (int)
  Проверяет сертификат на пригодность для использования в качестве помощника OCSP-ответчика. Доступна, начиная с PHP 8.4.0.
`X509_PURPOSE_TIMESTAMP_SIGN` (int)
  Проверяет сертификат на пригодность для использования в качестве доверенного подписанта меток времени. Доступна, начиная с PHP 8.4.0.

## Флаги заполнения для ассиметричного шифрования

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)
`OPENSSL_PKCS1_PSS_PADDING` (int)
  Дополнение по схеме RSA-PSS. Флаг доступен с PHP 8.5.0.

## Типы ключей

`OPENSSL_KEYTYPE_RSA` (int)
  RSA key type.
`OPENSSL_KEYTYPE_DSA` (int)
  DSA key type.
`OPENSSL_KEYTYPE_DH` (int)
  DH (Diffie-Hellman) key type.
`OPENSSL_KEYTYPE_EC` (int)
  Тип ключа эллиптической кривой.
`OPENSSL_KEYTYPE_X25519` (int)
  Тип ключа кривой X25519. Константа доступна только в том случае, если PHP скомпилирован с OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED25519` (int)
  Тип ключа кривой Ed25519. Константа доступна только в том случае, если PHP скомпилирован с OpenSSL 3.0+.
`OPENSSL_KEYTYPE_X448` (int)
  Тип ключа кривой X448. Константа доступна только в том случае, если PHP скомпилирован с OpenSSL 3.0+.
`OPENSSL_KEYTYPE_ED448` (int)
  Тип ключа кривой Ed448. Константа доступна только в том случае, если PHP скомпилирован с OpenSSL 3.0+.

## Константы-флаги структур PKCS7

The S/MIME functions make use of flags which are specified using a bitfield which can include one or more of the following values:

Константы PKCS7
Константа | Описание
--- | ---
`PKCS7_TEXT` (int) | Добавляет к зашифрованному и (или) подписанному сообщению группу заголовков с типом содержимого `text/plain`. При расшифровке или проверке подписанного сообщения заголовки удаляются из вывода, и если после извлечения содержимое сообщения не соответствует MIME-типу `text/plain`, возникает ошибка.
`PKCS7_BINARY` (int) | По умолчанию входное сообщение преобразовывается в «канонический» формат, в котором по требованию спецификации S/MIME одиночные символы перевода строки заменяются последовательностью символов `CR` и `LF`. При установке флага сообщение не преобразовывается. Форматирование отключают при обработке двоичных данных или данных, которые уже соответствуют каноническому MIME-формату.
`PKCS7_NOINTERN` (int) | При проверке сообщения функцией openssl_pkcs7_verify() поиск сертификата подписи выполняется среди сертификатов параметра `untrusted_certificates_filename` и сертификатов сообщения, если сообщение содержит сертификаты. С опцией поиск ведётся только по сертификатам параметра, центры сертификации которых по-прежнему интерпретируются как недоверенные.
`PKCS7_NOVERIFY` (int) | Флаг отключает проверку сертификата отправителя подписанного сообщения.
`PKCS7_NOCHAIN` (int) | Флаг отключает проверку цепочки сертификатов отправителя: то есть исключает сертификаты в подписанном сообщении (кроме сертификата отправителя) как сертификаты недоверенных центров сертификации.
`PKCS7_NOCERTS` (int) | При подписании сообщения сертификат отправителя обычно включается в сообщение, тогда как с этой опцией сертификат не добавляется. Это уменьшит размер подписанного сообщения, но получателю потребуется доступ к локальной копии сертификата отправителя, которую передают, например, через параметр `untrusted_certificates_filename` функции openssl_pkcs7_verify().
`PKCS7_NOATTR` (int) | При подписании в сообщение обычно включается набор атрибутов, который содержит время подписания и список симметричных алгоритмов, которые поддерживает S/MIME-протокол. С этой опцией атрибуты не включаются.
`PKCS7_DETACHED` (int) | При подписании сообщения функция прикрепляет подпись в виде открытого текста с MIME-типом `multipart/signed`. Это значение по умолчанию, если только не указали флаги для параметра `flags` функции openssl_pkcs7_sign(). Без этой опции функция подпишет сообщение непрозрачной подписью, которая более устойчива к пересылке сообщений почтовыми ретрансляторами, но недоступна для прочтения почтовыми агентами, которые не поддерживают стандарт S/MIME.
`PKCS7_NOSIGS` (int) | Флаг отключает попытку проверки подписей в сообщениях.
`PKCS7_NOOLDMIMETYPE` (int) | Флаг доступен с PHP 8.3.0. При шифровании сообщения для заголовка Content-Type вместо `application/x-pkcs7-mime` устанавливается значение `application/pkcs7-mime`.
`PKCS7_NOSMIMECAP` (int) | Флаг доступен с PHP 8.5.0. Опция исключает из S/MIME-подписи атрибут SMIMECapabilities со сведениями о поддерживаемых алгоритмах шифрования.
`PKCS7_CRLFEOL` (int) | Флаг доступен с PHP 8.5.0. С опцией конец строки в выводе обозначается последовательностью `CRLF`.
`PKCS7_NOCRL` (int) | Флаг доступен с PHP 8.5.0. Опция исключает из PKCS7-структуры списки отзыва сертификатов (англ. Certificate Revocation List, сокр. CRL).
`PKCS7_NO_DUAL_CONTENT` (int) | Флаг доступен с PHP 8.5.0. По умолчанию в PKCS7-структуру включаются данные и подпись данных. При установке флага данные не включаются.

## Константы-флаги стуктур CMS

Функции для работы с CMS-сообщениями принимают флаги, которые определяют как битовое поле. Поле битов включает одно или набор следующих значений:

Константы CMS
Константа | Описание
--- | ---
`OPENSSL_CMS_TEXT` (int) | Добавляет заголовки content-type text/plain в зашифрованное/подписанное сообщение. При расшифровке или проверке эти заголовки удаляются из вывода — если расшифрованное или проверенное сообщение не относится к MIME-типу text/plain, произойдёт ошибка.
`OPENSSL_CMS_BINARY` (int) | Обычно входное сообщение преобразовывается в «каноничный» формат, который эффективно использует символы `CR` и `LF` в качестве конца строки: как требует спецификация CMS. Когда присутствует эта опция, перевод не выполняется. Это полезно при обработке двоичных данных, которые могут быть не в формате CMS.
`OPENSSL_CMS_NOINTERN` (int) | При проверке сообщения сертификаты (если есть), включённые в сообщение, обычно проверяются на наличие сертификата подписи. С этой опцией используются только сертификаты, указанные в параметре `untrusted_certificates_filename` функции openssl_cms_verify(). Однако предоставленные сертификаты можно использовать как ненадёжные центры сертификации.
`OPENSSL_CMS_NOVERIFY` (int) | Не проверять сертификат подписавшего у подписанного сообщения.
`OPENSSL_CMS_NOCERTS` (int) | При подписании сообщения сертификат подписывающей стороны обычно включается — с этой опцией он исключается. Это уменьшит размер подписанного сообщения, но у проверяющего должна быть копия сертификата подписавшего, доступная локально (например, переданная в параметр `untrusted_certificates_filename` функции openssl_cms_verify()).
`OPENSSL_CMS_NOATTR` (int) | Обычно при подписании сообщения включается набор атрибутов, который включает время подписи и поддерживаемые симметричные алгоритмы. С этой опцией они не включены.
`OPENSSL_CMS_DETACHED` (int) | При подписании сообщения используйте подпись открытым текстом с MIME-типом `"multipart/signed"`. Это значение по умолчанию, если вы не укажете никаких `flags` для openssl_cms_sign(). Если вы отключите эту опцию, сообщение будет подписано с использованием непрозрачной подписи, которая более устойчива к переводу почтовыми ретрансляторами, но не может быть прочитана почтовыми агентами, не поддерживающими S/MIME.
`OPENSSL_CMS_NOSIGS` (int) | Не пытаться проверять подписи в сообщении
`OPENSSL_CMS_OLDMIMETYPE` (int) | Доступно начиная с PHP 8.3.0. Устанавливает тип содержимого `application/x-pkcs7-mime` вместо `application/pkcs7-mime` для шифрования сообщения.

## Алгоритмы подписи

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  Используется как алгоритм по умолчанию для функций openssl_sign() и openssl_verify().
`OPENSSL_ALGO_SHA224` (int)
`OPENSSL_ALGO_SHA256` (int)
`OPENSSL_ALGO_SHA384` (int)
`OPENSSL_ALGO_SHA512` (int)
`OPENSSL_ALGO_RMD160` (int)
`OPENSSL_ALGO_MD5` (int)
`OPENSSL_ALGO_MD4` (int)
`OPENSSL_ALGO_MD2` (int)
  Эта константа доступна, только если PHP скомпилирован с поддержкой MD2. Для этого необходимо при компиляции PHP передать CFLAG `-DHAVE_OPENSSL_MD2_H` и включить `enable-md2` при компиляции OpenSSL 1.0.0+.

## Алгоритмы шифрования

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  Список шифров по умолчанию.
`OPENSSL_CIPHER_RC2_40` (int)
`OPENSSL_CIPHER_RC2_128` (int)
`OPENSSL_CIPHER_RC2_64` (int)
`OPENSSL_CIPHER_DES` (int)
`OPENSSL_CIPHER_3DES` (int)

`OPENSSL_CIPHER_AES_128_CBC` (int)
`OPENSSL_CIPHER_AES_192_CBC` (int)
`OPENSSL_CIPHER_AES_256_CBC` (int)

## Константы версий

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Константа SNI (Server Name Indication)

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  Независимо от доступности SNI.

> Замечание:

> Эта константа требует PHP собранного с библиотекой OpenSSL версии 0.9.8j или выше.

## Другие константы

`OPENSSL_RAW_DATA` (int)
  Если константа `OPENSSL_RAW_DATA` передана в функции openssl_encrypt() или openssl_decrypt(), данные возвращаются как есть. Если константа не указана, вызывающей стороне возвращаются данные в кодировке Base64.
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  Не разрешает функции openssl_encrypt() дополнять ключи, длина которых короче длины ключа по умолчанию.
`OPENSSL_ZERO_PADDING` (int)
  При шифровании данные дополняются до стандартного для алгоритма размера блока, а при расшифровке дополнение проверяется и удаляется. Вызов функции openssl_encrypt() или openssl_decrypt() с флагом `OPENSSL_ZERO_PADDING` в аргументе `options` отключает обработку дополнения, но если общий объем данных для шифрования или расшифровки не кратен размеру блока, возникает ошибка.
`OPENSSL_ENCODING_SMIME` (int)
  Предписывает обрабатывать данные в формате S/MIME.
`OPENSSL_ENCODING_DER` (int)
  Предписывает обрабатывать данные в формате DER.
`OPENSSL_ENCODING_PEM` (int)
  Предписывает обрабатывать данные в формате PEM.

# Параметры ключа и сертификата

Параметры отдельных функции модуля openssl требуют аргумента в виде ключа или сертификата. Ключи и сертификаты получают следующими методами:

- Сертификаты

  1. Экземпляр класса OpenSSLCertificate (или до PHP 8.0.0 ресурс (resource), который принадлежит типу `OpenSSL X.509`), который возвращает функция openssl_x509_read().
  2. Строка в формате file://path/to/cert.pem; именованный файл должен содержать PEM-сертификат.
  3. Строка с содержимым PEM-сертификата, может начинаться с `-----BEGIN CERTIFICATE-----`.

- Запросы на подпись сертификата (Certificate Signing Requests, или CSRs)

  1. Экземпляр класса OpenSSLCertificateSigningRequest (или до PHP 8.0.0 ресурс (resource), который принадлежит типу `OpenSSL X.509 CSR`), который возвращает функция openssl_csr_new().
  2. Строка в формате file://path/to/csr.pem; именованный файл должен содержать CSR-запрос в формате PEM.
  3. Строка с содержимым CSR-запроса в формате PEM, может начинаться с `-----BEGIN CERTIFICATE REQUEST-----`.

- Открытые и закрытые ключи

  1. Экземпляр класса OpenSSLAsymmetricKey (или до PHP 8.0.0 ресурс (resource), который принадлежит типу `OpenSSL key`), который возвращает функция openssl_get_publickey() или openssl_get_privatekey().
  2. Только для открытых ключей: экземпляр класса OpenSSLCertificate (или до PHP 8.0.0 ресурс (resource), который принадлежит типу `OpenSSL X.509`).
  3. Строка в формате file://path/to/file.pem; именованный файл должен содержать сертификат/закрытый ключ в формате PEM (может содержать и ключ, и сертификат).
  4. Строка с содержимым сертификата/ключа в формате PEM, может начинаться с `-----BEGIN PUBLIC KEY-----`.
  5. Для закрытых ключей допускается синтаксис `array($key, $passphrase)`, где переменная $key — ключ, который задали строкой вида file:// или нотацией текстового содержимого, которое описывает эта страница, а переменная $passphrase — строка, которая содержит парольную фразу для заданного закрытого ключа.

# Проверка сертификата

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

# Функции OpenSSL

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — Получает длину инициализирующего вектора шифра

### Описание

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

Возвращает длину инициализирующего вектора шифра.

### Список параметров

`cipher_algo`

  Метод шифрования. Список потенциальных значений можно получить с помощью openssl_get_cipher_methods().

### Возвращаемые значения

Возвращает длину инициализирующего вектора шифра или `false`.

### Ошибки

Выдаёт ошибку уровня `E_WARNING` в случае передачи неизвестного алгоритма шифрования.

### Примеры

Пример #1 Пример использования openssl_cipher_iv_length()

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

Вывод приведённого примера будет похож на:

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Получает длину ключа шифрования

### Описание

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Получает длину ключа шифрования.

### Список параметров

`cipher_algo`

  Метод шифрования, список возможных значений смотрите в описании функции openssl_get_cipher_methods().

### Возвращаемые значения

Возвращает длину шифра в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

Выдаёт ошибку уровня `E_WARNING`, если алгоритм шифрования неизвестен.

### Примеры

Пример #1 Пример использования openssl_cipher_key_length()

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

Вывод приведённого примера будет похож на:

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Расшифровывает CMS-сообщение

### Описание

function openssl_cms_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Расшифровывает CMS-сообщение.

### Список параметров

`input_filename`

  Имя файла, который содержит зашифрованное содержимое.

`output_filename`

  Имя файла для хранения расшифрованного содержимого.

`certificate`

  Имя файла, содержащего сертификат получателя.

`private_key`

  Имя файла, содержащего ключ PKCS#8.

`encoding`

  Кодировка входного файла: `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` или `OPENSSL_ENCODING_PEM`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Зашифровывает CMS-сообщение

### Описание

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Шифрует содержимое для одного или нескольких получателей на основе переданных ему сертификатов.

### Список параметров

`input_filename`

  Файл, который нужно зашифровать.

`output_filename`

  Выходной файл.

`certificate`

  Получатели, для которых производится шифрование.

`headers`

  Заголовки, которые будут включены при использовании S/MIME.

`flags`

  Флаги, передаваемые CMS_sign.

`encoding`

  Кодировка для вывода. `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` или `OPENSSL_ENCODING_PEM`.

`cipher_algo`

  Используемый алгоритм шифрования.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Тип параметра `cipher_algo` теперь является целым числом (int) или строкой (string). Ранее он был целым числом (int).
8.1.0 | Алгоритм шифрования по умолчанию (`cipher_algo`) теперь AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Ранее использовался алгоритм PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`).

# openssl_cms_read

(PHP 8)

openssl_cms_read — Экспортирует файл CMS в массив сертификатов PEM

### Описание

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Работает аналогично openssl_pkcs7_read().

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`input_filename`

`certificates`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Подписывает файл

### Описание

function openssl_cms_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
?string `$untrusted_certificates_filename` = `null`
): bool

Функция подписывает файл сертификатом X.509 и ключом.

### Список параметров

`input_filename`

  Имя файла для подписи.

`output_filename`

  Имя файла для хранения результатов.

`certificate`

  Сертификат подписи. Смотрите параметры ключа/сертификата для получения списка допустимых значений.

`private_key`

  Ключ, который связан с `certificate`. Смотрите параметры ключа/сертификата для получения списка допустимых значений.

`headers`

  Массив заголовков для включения в вывод S/MIME.

`flags`

  Флаги, передаваемые cms_sign().

`encoding`

  Кодировка выходного файла. `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` или `OPENSSL_ENCODING_PEM`.

`untrusted_certificates_filename`

  Промежуточные сертификаты, включаемые в подпись.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции openssl_cms_sign()

    <?php

    openssl_cms_sign('input.txt', 'output.txt', 'file://cert.pem', 'file://privkey.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'chain.pem');

    ?>

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — Проверяет подпись CMS

### Описание

function openssl_cms_verify(
string `$input_filename`,
int `$flags` = 0,
?string `$certificates` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$pk7` = `null`,
?string `$sigfile` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Проверяет подпись CMS, прикреплённую или отсоединённую, с указанной кодировкой.

### Список параметров

`input_filename`

  Входной файл.

`flags`

  Флаги, передаваемые cms_verify().

`certificates`

  Файл с сертификатом подписавшего и, по выбору, промежуточными сертификатами.

`ca_info`

  Массив, содержащий самозаверенные сертификаты центра сертификации.

`untrusted_certificates_filename`

  Файл, содержащий дополнительные промежуточные сертификаты.

`content`

  Файл, указывающий на содержимое, когда подписи отсоединены.

`pk7`

`sigfile`

  Файл, в который нужно сохранить подпись.

`encoding`

  Кодировка входного файла. `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` или `OPENSSL_ENCODING_PEM`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — Экспортирует CSR в виде строки

### Описание

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() записывает запрос на подпись сертификата `csr` в формате PEM в переменную `output`, которая передаётся по ссылке.

### Список параметров

`csr`
  Для получения списка допустимых значений смотрите параметры CSR.
`output`

  В случае успешного выполнения, в этой переменной будет сохранён CSR в формате PEM.

`no_text`
  Необязательный параметр `notext` влияет на детализацию сообщений вывода; если он установлен в `false`, то в вывод добавляется дополнительная человекочитаемая информация. Значением по умолчанию `notext` является `true`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования openssl_csr_export()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha256WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $private_key, $configargs);
    openssl_csr_export($csr, $csr_string);
    echo $csr_string;
    ?>

### Смотрите также

- openssl_csr_export_to_file() - Экспортирует CSR в файл
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — Экспортирует CSR в файл

### Описание

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() записывает запрос на подпись сертификата `csr` в формате PEM в файл `output_filename`.

### Список параметров

`csr`
  Для получения списка допустимых значений смотрите параметры CSR.
`output_filename`

  Путь к файлу.

`no_text`
  Необязательный параметр `notext` влияет на детализацию сообщений вывода; если он установлен в `false`, то в вывод добавляется дополнительная человекочитаемая информация. Значением по умолчанию `notext` является `true`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования openssl_csr_export_to_file()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
    openssl_pkey_export_to_file($private_key, 'example-priv.key');
    // Наряду с объектом, CSR содержит открытый ключ, соответствующий секретному ключу
    openssl_csr_export_to_file($csr, 'example-csr.pem');
    ?>

### Смотрите также

- openssl_csr_export() - Экспортирует CSR в виде строки
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — Возвращает открытый ключ CSR

### Описание

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() извлекает открытый ключ из `csr` и подготавливает его для использования в других функциях.

### Список параметров

`csr`
  Для получения списка допустимых значений смотрите параметры CSR.
`short_names`
  Внимание

  Этот параметр игнорируется

### Возвращаемые значения

Возвращает OpenSSLAsymmetricKey в случае успешного выполнения или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения возвращает экземпляр OpenSSLAsymmetricKey; ранее возвращался ресурс (resource) типа `OpenSSL key`.
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования openssl_csr_get_public_key()

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
    $public_key = openssl_csr_get_public_key($csr);
    $info = openssl_pkey_get_details($public_key);
    echo $info['key'];
    ?>

### Смотрите также

- openssl_csr_get_subject() - Возвращает субъект CSR
- openssl_csr_new() - Генерирует CSR
- openssl_pkey_get_details() - Получает массив с детальной информацией о ключе
- openssl_pkey_export_to_file() - Записывает в файл ключ в формате PEM
- openssl_pkey_export() - Получает строку с ключом в формате PEM

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — Возвращает субъект CSR

### Описание

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() возвращает известную об субъекте информацию закодированную в `csr`, включая поля commonName (CN), organizationName (O), countryName (C) и т.д.

### Список параметров

`csr`
  Для получения списка допустимых значений смотрите параметры CSR.
`short_names`

  `short_names` определяет, как данные индексируются в массиве, если `short_names` задан как `true` (по умолчанию), то поля будут индексированы именами в коротком формате, в противном случае будут использованы длинные имена. Например, CN - короткое имя для commonName.

### Возвращаемые значения

Возвращает ассоциативный массив с описанием субъекта или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования openssl_csr_get_subject()

    <?php
    $subject = array(
        "countryName" => "CA",
        "stateOrProvinceName" => "Alberta",
        "localityName" => "Calgary",
        "organizationName" => "XYZ Widgets Inc",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha512WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $privkey, $configargs);
    print_r(openssl_csr_get_subject($csr));
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### Смотрите также

- openssl_csr_new() - Генерирует CSR
- openssl_csr_get_public_key() - Возвращает открытый ключ CSR
- openssl_x509_parse() - Разбирает сертификат X509 и получает массив с данными о нём

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — Генерирует CSR

### Описание

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter]?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

Функция openssl_csr_new() создаёт новый CSR на основе информации, которую задали в параметре `distinguished_names`.

> Замечание: Для корректной работы этой функции должен существовать правильный openssl.cnf. Для более подробной информации смотрите замечания под разделом установки.

### Список параметров

`distinguished_names`

  Уникальное имя (Distinguished Name) или поля субъекта для сертификата. Параметр `distinguished_names` — это ассоциативный массив, в котором ключи представляют имена атрибутов уникальных имён, а значения могут быть либо строками (для одного значения), либо массивами (если необходимо установить несколько значений).

`private_key`

  Для параметра `private_key` требуется установить закрытый ключ, который сгенерировала функция openssl_pkey_new() (или который вернула любая другая функция семейства openssl_pkey) или `null`. Если значение переменной `null`, то создаётся новый закрытый ключ на основе предоставленного параметра `options` и присваивается предоставленной переменной. Соответствующую открытую часть ключа функция использует, чтобы подписать CSR.

`options`

  По умолчанию для инициализации запроса используется информация из системного файла `openssl.conf`. Можно указать секцию конфигурационного файла путём задания ключа `config_section_section` в параметре `options`. Можно также задать альтернативный файл конфигурации OpenSSL путём задания ключа `config` значением пути до него. Соответствие ключей, которые указали в параметре `options`, ключам из файла `openssl.conf` дают следующие параграфы описания.

  Переопределение конфигурации
  Ключ `options` | Тип | Соответствие в `openssl.conf` | Описание
  --- | --- | --- | ---
  digest_alg | string | default_md | Один из методов openssl_get_md_methods()
  x509_extensions | string | x509_extensions | Определяет, какое расширение должно использоваться, чтобы создать сертификат x509
  req_extensions | string | req_extensions | Определяет, какое расширение должно использоваться для создания CSR
  private_key_bits | int | default_bits | Задаёт, сколько бит должно использоваться для генерации закрытого ключа
  private_key_type | int | none | Задаёт тип создаваемого закрытого ключа. Одна из констант: `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_RSA` или `OPENSSL_KEYTYPE_EC`. По умолчанию `OPENSSL_KEYTYPE_RSA`.
  encrypt_key | bool | encrypt_key | Должен ли шифроваться (паролем) экспортируемый ключ?
  encrypt_key_cipher | int | none | Одна из констант шифров.
  curve_name | string | none | Одно из openssl_get_curve_names().
  config | string | N/A | Путь до альтернативного файла конфигурации openssl.conf.

`extra_attributes`

  Параметр `extra_attributes` используется для указания дополнительных опций для CSR. Это ассоциативные массивы, в которых ключи преобразуются в OID и применяются в качестве атрибутов CSR.

### Возвращаемые значения

Функция возвращает CSR в случае успешного выполнения, `true`, в случае успешного создания CSR, но при возникновении ошибки подписания или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Ассоциативный массив `distinguished_names` теперь поддерживает массивы в качестве значений, что позволяет указывать несколько значений для одного атрибута.
8.4.0 | Параметр `extra_attributes` теперь правильно устанавливает атрибуты CSR, а не изменяет уникальное имя субъекта, как это было ранее.
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.
8.0.0 | `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey; ранее принимался ресурс (resource) типа `OpenSSL key`.
7.1.0 | Параметр `options` теперь поддерживает `curve_name`.

### Примеры

Пример #1 Создание самоподписанного сертификата

    <?php
    // для сервера сертификации SSL, commonName является доменным именем
    // для сертификатов S/MIME, commonName является владельцем расположения адреса email
    // и поля идентификации относятся к владельцу домена или электронной почты,
    // подлежащим защите
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Создание пары закрытый/открытый ключ
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Создание CSR
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Создание самоподписанного сертификата со сроком жизни 365 дней
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Сохранение закрытого ключа, CSR и самоподписанного сертификата
    openssl_csr_export($csr, $csrout) and var_dump($csrout);
    openssl_x509_export($x509, $certout) and var_dump($certout);
    openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

    // Покажем возникшие ошибки, если они были
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

Пример #2 Создание самоподписанного ECC сертификата (начиная с PHP 7.1.0)

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Создание пары закрытый/открытый ключ
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Создание CSR
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Создание самоподписанного EC сертификата
    $x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
    openssl_x509_export_to_file($x509, 'ecc-cert.pem');
    openssl_pkey_export_to_file($private_key, 'ecc-private.key');
    ?>

### Смотрите также

- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

### Описание

function openssl_csr_sign(
OpenSSLCertificateSigningRequest|string `$csr`,
OpenSSLCertificate|string|null `$ca_certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$days`,
?array `$options` = `null`,
int `$serial` = 0,
?string `$serial_hex` = `null`
): OpenSSLCertificate|false

Функция openssl_csr_sign() создаёт сертификат x509 из заданного CSR.

> Замечание: Для корректной работы этой функции должен существовать правильный openssl.cnf. Для более подробной информации смотрите замечания под разделом установки.

### Список параметров

`csr`

  CSR, который создала функция openssl_csr_new(). Также может быть путём на кодированный в PEM CSR, если задано как file://path/to/csr или экспортированной строкой, созданной с помощью openssl_csr_export().

`ca_certificate`

  Создаваемый сертификат будет подписан `ca_certificate`. Если `ca_certificate` задан как `null`, то будет сгенерирован самоподписанный сертификат.

`private_key`

  `private_key` — секретный ключ, который соответствует `ca_certificate`.

`days`

  `days` — время жизни создаваемого сертификата в днях.

`options`

  Можно тонко настроить подпись CSR через параметр `options`. Подробности даёт описание функции openssl_csr_new(), в разделе, который посвящён параметру `options`.

`serial`

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

`serial_hex`

  Необязательная шестнадцатеричная строка, представляющая серийный номер выданного сертификата. Если задана, она приоритетнее значения параметра `serial`. Если не указана или задана как `null`, вместо неё используется значение параметра `serial`.

### Возвращаемые значения

Функция возвращает экземпляр OpenSSLCertificate в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлен параметр `serial_hex`.
8.0.0 | On success, this function returns an OpenSSLCertificate instance now; previously, a resource of type `OpenSSL X.509` was returned.
8.0.0 | `csr` теперь принимает экземпляр OpenSSLCertificateSigningRequest; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.
8.0.0 | `ca_certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.
8.0.0 | `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример openssl_csr_sign() - подпись CSR (как сделать свой собственный CA)

    <?php
    // Предположим, что CSR получен из поля textarea со веб-страницы
    $csrdata = $_POST["CSR"];

    // Мы подпишем запрос с помощью сертификата собственного "центра сертификации"
    // Для подписи вы можете использовать любой сертификат, но этот процесс бесполезен, если
    // сертификат не является доверенным для ПО или пользователей, которые будут его
    // использовать

    // Нам нужен собственный CA сертификат и его секретный ключ
    $cacert = "file://path/to/ca.crt";
    $privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");

    $usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

    // Теперь напечатаем сертификат, чтобы пользователь мог его скопировать
    // и внести в свою локальную конфигурацию (например в файл хранилища SSL сертификатов)
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Покажем возникшие ошибки, если они были
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — Расшифровывает данные

### Описание

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

Функция берёт необработанную или кодированную в base64 строку и расшифровывает её заданным методом и кодовой фразой.

### Список параметров

`data`

  Данные для расшифровки.

`cipher_algo`

  Метод шифрования. Список доступных методов возвращает функция openssl_get_cipher_methods().

`passphrase`

  Кодовая фраза. Если кодовая фраза короче, чем ожидалось, она заполняется символами `NUL`; если кодовая фраза длиннее, чем ожидалось, она усекается.

  Предостережение

  Для параметра `passphrase` не используется функция извлечения ключа, как можно предположить из его названия. Единственная операция, которая используется, – это заполнение символами `NUL` или усечение, если длина отличается от ожидаемой.

`options`

  `options` можно задать одной из констант: `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING` или `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Ненулевой (non-`null`) инициализирующий вектор. Если IV короче, чем ожидалось, он заполняется символами `NUL` и выдаётся предупреждение; если кодовая фраза длиннее, чем ожидалось, он усекается и выдаётся предупреждение.

`tag`

  Тег аутентификации в режиме шифрования AEAD. Если он некорректен, то аутентификация завершится неудачей и функция вернёт `false`.

  Предостережение

  Длина `tag` не проверяется функцией. Вызывающая сторона несёт ответственность за то, чтобы длина тега соответствовала длине тега, полученного при вызове openssl_encrypt(). В противном случае дешифрование может быть успешным, если данный тег совпадает только с началом правильного тега.

`aad`

  Дополнительные аутентифицированные данные.

### Возвращаемые значения

Функция возвращает расшифрованную строку или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если в параметр `cipher_algo` передали неизвестный алгоритм шифрования.

Функция выдаёт ошибку уровня `E_WARNING`, если в параметр `iv` передали пустое значение.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `tag` теперь принимает значение null.
7.1.0 | Добавили параметры `tag` и `aad`.

### Смотрите также

- openssl_encrypt() - Шифрует данные

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — Вычисляет общий секретный ключ для значения удалённого открытого ключа DH и локального ключа DH

### Описание

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`): string|false

Общий секретный ключ, который возвращает функция openssl_dh_compute_key(), часто используется в качестве ключа шифрования для секретного взаимодействия с удалённой стороной (remote party). Это известно как алгоритм обмена ключами алгоритма Диффи-Хеллмана.

Предостережение

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

> Замечание: ECDH поддерживается только начиная с PHP 8.1.0 и OpenSSL 3.0.0.

### Список параметров

`public_key`

  Открытый ключ DH удалённой стороны.

`private_key`

  Локальный закрытый ключ DH, соответствующий открытому ключу для обмена с удалённой стороной.

### Возвращаемые значения

Функция возвращает общий секретный ключ или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey; раньше принимался ресурс (resource) типа `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Вычисление общего секретного ключа

Сначала сгенерируйте открытую/закрытую пару ключей DH локально, и удалённая сторона сделает то же самое. Нам нужно использовать утилиту командной строки `openssl`.

    # Генерация пары ключей (закрытый/открытый)
    openssl dhparam -out dhparam.pem 2048
    openssl genpkey -paramfile dhparam.pem -out privatekey.pem

    # Извлечение только открытого ключа
    openssl pkey -in privatekey.pem -pubout -out publickey.pem

Затем отправьте свой открытый ключ удалённой стороне. Используйте команду `openssl pkey` для просмотра открытого ключа, который будет отправлен удалённой стороне.

    openssl pkey -pubin -in remotepublickey.pem -text -noout

Вывод приведённого примера будет похож на:

    PKCS#3 DH Public-Key: (2048 bit)
        public-key:
            67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
            9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
            42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
            88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
            77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
            98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
            79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
            d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
            f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
            0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
            4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
            37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
            94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
            aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
            74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
            87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
            a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
            36
     [...abbreviated...]

Используйте открытый ключ в качестве параметра для openssl_dh_compute_key() для вычисления общего секретного ключа.

    <?php

    $remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

    $local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

    $shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
    echo bin2hex($shared_secret)."\n";

    ?>

Пример #2 Создание пары ключей DH (открытый/закрытый)

Сначала сгенерируйте простой число DH

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

Вывод приведённого примера будет похож на:

    PKCS#3 DH Parameters: (2048 bit)
            prime:
                00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
                4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
                d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
                e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
                12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
                78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
                55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
                34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
                f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
                4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
                7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
                fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
                a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
                9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
                40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
                cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
                22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
                62:6b
            generator: 2 (0x2)

Значения prime и generator передаются в виде параметров p и g в openssl_pkey_new()

    <?php

    $configargs = array();
    $configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
    $configargs['g'] = hex2bin('02');
    $private_key = openssl_pkey_new(array('dh' => $configargs));
    openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

    $details = openssl_pkey_get_details($private_key);
    $local_pub_key = $details['dh']['pub_key'];
    echo bin2hex($local_pub_key)."\n";// вы можете отправить свой открытый ключ удалённой стороне

    $details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
    $remote_public_key = $details['dh']['pub_key'];
    $shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
    echo bin2hex($shared_secret)."\n";

    ?>

### Смотрите также

- openssl_pkey_new() - Генерирует новый закрытый ключ
- openssl_pkey_get_details() - Получает массив с детальной информацией о ключе
- openssl_pkey_get_private() - Получает закрытый ключ
- openssl_pkey_get_public() - Извлекает открытый ключ из сертификата и подготавливает его к использованию

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — Вычисляет дайджест

### Описание

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

Функция вычисляет хеш-сумму данных заданным методом и возвращает необработанную двоичную строку или двоичную строку в шестнадцатеричном представлении.

### Список параметров

`data`

  Данные.

`digest_algo`

  Метод вычисления хеш-подписи, например sha256. Список доступных методов даёт описание функции openssl_get_md_methods().

`binary`

  Если для параметра установили значение `true`, функция вернёт необработанные данные вывода, иначе функция вернёт двоичное значение в шестнадцатеричном представлении.

### Возвращаемые значения

Функция возвращает хеш-значение или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если в параметр `digest_algo` передали неизвестный метод.

### Смотрите также

- openssl_get_md_methods() - Получает список доступных методов хеширования

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — Шифрует данные

### Описание

function openssl_encrypt(
#[\SensitiveParameter]string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
string `&$tag` = `null`,
string `$aad` = "",
int `$tag_length` = 16
): string|false

Функция шифрует данные с заданным шифром и кодовой фразой и возвращает необработанную строку, либо строку, закодированную в base64.

### Список параметров

`data`

  Данные для шифрования.

`cipher_algo`

  Метод шифрования. Список доступных методов можно получить с помощью функции openssl_get_cipher_methods().

`passphrase`

  Кодовая фраза. Если кодовая фраза укорочена, чем ожидалось, она автоматически дополняется символами `NUL`; если кодовая фраза длиннее, чем ожидалось, она автоматически усекается.

  Предостережение

  Для параметра `passphrase` не используется функция извлечения ключа, как можно предположить из его названия. Единственная операция, которая используется, – это заполнение символами `NUL` или усечение, если длина отличается от ожидаемой.

`options`

  `options` можно задать одной из констант: `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING` или `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Ненулевой (non-`null`) инициализирующий вектор. Если IV короче, чем ожидалось, он заполняется символами `NUL` и выдаётся предупреждение; если кодовая фраза длиннее, чем ожидалось, он усекается и выдаётся предупреждение.

`tag`

  Тег аутентификации, передаваемый по ссылке, в режиме шифрования AEAD (GCM или CCM).

`aad`

  Дополнительные аутентифицированные данные.

`tag_length`

  Длина параметра `tag`. Для режима GCM должно быть от 4 до 16.

### Возвращаемые значения

Функция возвращает зашифрованную строку или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если в параметр `cipher_algo` передали неизвестный алгоритм шифрования.

Функция выдаёт ошибку уровня `E_WARNING`, если в параметр `iv` передали пустое значение.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Добавили параметры `tag`, `aad` и `tag_length`.

### Примеры

Пример #1 Пример шифрования AES с аутентификацией в режиме GCM в PHP 7.1+

    <?php

    // $key должен быть сгенерирован заранее криптографически безопасным образом,
    // например, функцией openssl_random_pseudo_bytes
    $plaintext = "данные для шифрования";
    $cipher = "aes-128-gcm";

    if (in_array($cipher, openssl_get_cipher_methods()))
    {
        $ivlen = openssl_cipher_iv_length($cipher);
        $iv = openssl_random_pseudo_bytes($ivlen);
        $ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);

        // Сохраняем $cipher, $iv и $tag для дальнейшей расшифровки
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }

    ?>

Пример #2 Пример шифрования AES с аутентификацией до PHP 7.1

    <?php

    // $key должен быть сгенерирован заранее криптографически безопасным образом,
    // например, функцией openssl_random_pseudo_bytes
    $plaintext = "данные для шифрования";
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = openssl_random_pseudo_bytes($ivlen);
    $ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    $ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

    // Расшифровка....
    $c = base64_decode($ciphertext);
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = substr($c, 0, $ivlen);
    $hmac = substr($c, $ivlen, $sha2len=32);
    $ciphertext_raw = substr($c, $ivlen+$sha2len);
    $original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);

    if (hash_equals($hmac, $calcmac)) // Сравнение, которое не подвержено атаке по времени
    {
        echo $original_plaintext."\n";
    }

    ?>

### Смотрите также

- openssl_decrypt() - Расшифровывает данные

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — Возвращает сообщение об ошибке openSSL

### Описание

function openssl_error_string(): string|false

openssl_error_string() возвращает сообщение последней произошедшей ошибки библиотеки openSSL. Сообщения об ошибках находятся в очереди, так что эту функцию можно вызывать несколько раз для получения всей информации. При этом последнее сообщение самое свежее.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку с сообщением об ошибке или `false`, если сообщений больше нет.

### Примеры

Пример #1 Пример использования openssl_error_string()

    <?php
    // Предположим, что вы вызвали функцию openssl, которая завершилась неудачей
    while ($msg = openssl_error_string())
        echo $msg . "<br />\n";
    ?>

# openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — Высвобождает ресурс ключа

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

Функция openssl_free_key() удаляет из памяти ключ, который связан с идентификатором `key`.

### Список параметров

`key`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела, поскольку больше не имеет смысла.
8.0.0 | Параметр `key` теперь принимает экземпляр класса OpenSSLAsymmetricKey; раньше параметр принимал ресурс (resource) с типом `OpenSSL key`.

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — Получает доступные месторасположения сертификатов

### Описание

function openssl_get_cert_locations(): array

Функция openssl_get_cert_locations() возвращает массив с информацией о доступных хранилищах, в которых будет происходить поиск SSL-сертификатов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив с месторасположением хранилищ сертификатов.

### Примеры

Пример #1 Пример использования функции openssl_get_cert_locations()

    <?php

    var_dump(openssl_get_cert_locations());

    ?>

Результат выполнения приведённого примера:

    array(8) {
      ["default_cert_file"]=>
      string(21) "/usr/lib/ssl/cert.pem"
      ["default_cert_file_env"]=>
      string(13) "SSL_CERT_FILE"
      ["default_cert_dir"]=>
      string(18) "/usr/lib/ssl/certs"
      ["default_cert_dir_env"]=>
      string(12) "SSL_CERT_DIR"
      ["default_private_dir"]=>
      string(20) "/usr/lib/ssl/private"
      ["default_default_cert_area"]=>
      string(12) "/usr/lib/ssl"
      ["ini_cafile"]=>
      string(0) ""
      ["ini_capath"]=>
      string(0) ""
    }

# openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — Получает список доступных алгоритмов шифрования

### Описание

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

Функция возвращает список доступных алгоритмов шифрования.

### Список параметров

`aliases`

  Если требуется включить псевдонимы шифров в возвращаемый массив, для параметра устанавливают значение `true`.

### Возвращаемые значения

Функция возвращает массив (array) доступных методов шифрования. Обратите внимание, что до OpenSSL 1.1.1 методы шифрования возвращались в верхнем и нижнем регистре; с OpenSSL 1.1.1 возвращаются только строчные варианты.

### Примеры

Пример #1 Пример использования функции openssl_get_cipher_methods()

Показывает, как могут выглядеть доступные шифры и их псевдонимы.

    <?php

    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    // Режим ECB следует избегать
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    // По крайней мере, в начале августа 2016 года следующие методы объявлены слабыми:
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

    print_r($ciphers);
    print_r($cipher_aliases);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => aes-128-cbc
        [1] => aes-128-cbc-hmac-sha1
        [2] => aes-128-cbc-hmac-sha256
        [3] => aes-128-ccm
        [4] => aes-128-cfb
        [5] => aes-128-cfb1
        [6] => aes-128-cfb8
        [7] => aes-128-ctr
        [9] => aes-128-gcm
        [10] => aes-128-ocb
        [11] => aes-128-ofb
        [12] => aes-128-xts
        [13] => aes-192-cbc
        [14] => aes-192-ccm
        [15] => aes-192-cfb
        [16] => aes-192-cfb1
        [17] => aes-192-cfb8
        [18] => aes-192-ctr
        [20] => aes-192-gcm
        [21] => aes-192-ocb
        [22] => aes-192-ofb
        [23] => aes-256-cbc
        [24] => aes-256-cbc-hmac-sha1
        [25] => aes-256-cbc-hmac-sha256
        [26] => aes-256-ccm
        [27] => aes-256-cfb
        [28] => aes-256-cfb1
        [29] => aes-256-cfb8
        [30] => aes-256-ctr
        [32] => aes-256-gcm
        [33] => aes-256-ocb
        [34] => aes-256-ofb
        [35] => aes-256-xts
        [36] => aria-128-cbc
        [37] => aria-128-ccm
        [38] => aria-128-cfb
        [39] => aria-128-cfb1
        [40] => aria-128-cfb8
        [41] => aria-128-ctr
        [43] => aria-128-gcm
        [44] => aria-128-ofb
        [45] => aria-192-cbc
        [46] => aria-192-ccm
        [47] => aria-192-cfb
        [48] => aria-192-cfb1
        [49] => aria-192-cfb8
        [50] => aria-192-ctr
        [52] => aria-192-gcm
        [53] => aria-192-ofb
        [54] => aria-256-cbc
        [55] => aria-256-ccm
        [56] => aria-256-cfb
        [57] => aria-256-cfb1
        [58] => aria-256-cfb8
        [59] => aria-256-ctr
        [61] => aria-256-gcm
        [62] => aria-256-ofb
        [63] => bf-cbc
        [64] => bf-cfb
        [66] => bf-ofb
        [67] => camellia-128-cbc
        [68] => camellia-128-cfb
        [69] => camellia-128-cfb1
        [70] => camellia-128-cfb8
        [71] => camellia-128-ctr
        [73] => camellia-128-ofb
        [74] => camellia-192-cbc
        [75] => camellia-192-cfb
        [76] => camellia-192-cfb1
        [77] => camellia-192-cfb8
        [78] => camellia-192-ctr
        [80] => camellia-192-ofb
        [81] => camellia-256-cbc
        [82] => camellia-256-cfb
        [83] => camellia-256-cfb1
        [84] => camellia-256-cfb8
        [85] => camellia-256-ctr
        [87] => camellia-256-ofb
        [88] => cast5-cbc
        [89] => cast5-cfb
        [91] => cast5-ofb
        [92] => chacha20
        [93] => chacha20-poly1305
        [111] => id-aes128-CCM
        [112] => id-aes128-GCM
        [113] => id-aes128-wrap
        [114] => id-aes128-wrap-pad
        [115] => id-aes192-CCM
        [116] => id-aes192-GCM
        [117] => id-aes192-wrap
        [118] => id-aes192-wrap-pad
        [119] => id-aes256-CCM
        [120] => id-aes256-GCM
        [121] => id-aes256-wrap
        [122] => id-aes256-wrap-pad
        [124] => idea-cbc
        [125] => idea-cfb
        [127] => idea-ofb
        [137] => seed-cbc
        [138] => seed-cfb
        [140] => seed-ofb
        [141] => sm4-cbc
        [142] => sm4-cfb
        [143] => sm4-ctr
        [145] => sm4-ofb
    )
    Array
    (
        [36] => aes128
        [37] => aes128-wrap
        [38] => aes192
        [39] => aes192-wrap
        [40] => aes256
        [41] => aes256-wrap
        [69] => aria128
        [70] => aria192
        [71] => aria256
        [72] => bf
        [77] => blowfish
        [99] => camellia128
        [100] => camellia192
        [101] => camellia256
        [102] => cast
        [103] => cast-cbc
        [146] => idea
        [164] => seed
        [169] => sm4
    )

### Смотрите также

- openssl_get_md_methods() - Получает список доступных методов хеширования

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — Получает список доступных имён кривых для ECC-шифрования

### Описание

function openssl_get_curve_names(): array|false

Функция возвращает список доступных имён кривых для использования в эллиптической криптографии (ECC) для операций с открытым или закрытым ключом. Две наиболее стандартизованных или поддерживаемых кривых: prime256v1 (NIST P-256) и secp384r1 (NIST P-384).

Приближенные эквивалентности размеров ключей AES, RSA, DSA и ECC
AES размер симметричного ключа (Биты) | Размер ключа RSA и DSA (Биты) | Размер ключа ECC (Биты)
--- | --- | ---
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512

» Институт NIST рекомендует использовать кривые ECC-шифрования как минимум в 256 битов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив с доступными именами кривых или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции openssl_get_curve_names()

    <?php

    $curve_names = openssl_get_curve_names();
    print_r($curve_names);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => secp112r1
        [1] => secp112r2
        [2] => secp128r1
        [3] => secp128r2
        [4] => secp160k1
        [5] => secp160r1
        [6] => secp160r2
        [7] => secp192k1
        [8] => secp224k1
        [9] => secp224r1
        [10] => secp256k1
        [11] => secp384r1
        [12] => secp521r1
        [13] => prime192v1
        [14] => prime192v2
        [15] => prime192v3
        [16] => prime239v1
        [17] => prime239v2
        [18] => prime239v3
        [19] => prime256v1
        [20] => sect113r1
        [21] => sect113r2
        [22] => sect131r1
        [23] => sect131r2
        [24] => sect163k1
        [25] => sect163r1
        [26] => sect163r2
        [27] => sect193r1
        [28] => sect193r2
        [29] => sect233k1
        [30] => sect233r1
        [31] => sect239k1
        [32] => sect283k1
        [33] => sect283r1
        [34] => sect409k1
        [35] => sect409r1
        [36] => sect571k1
        [37] => sect571r1
        [38] => c2pnb163v1
        [39] => c2pnb163v2
        [40] => c2pnb163v3
        [41] => c2pnb176v1
        [42] => c2tnb191v1
        [43] => c2tnb191v2
        [44] => c2tnb191v3
        [45] => c2pnb208w1
        [46] => c2tnb239v1
        [47] => c2tnb239v2
        [48] => c2tnb239v3
        [49] => c2pnb272w1
        [50] => c2pnb304w1
        [51] => c2tnb359v1
        [52] => c2pnb368w1
        [53] => c2tnb431r1
        [54] => wap-wsg-idm-ecid-wtls1
        [55] => wap-wsg-idm-ecid-wtls3
        [56] => wap-wsg-idm-ecid-wtls4
        [57] => wap-wsg-idm-ecid-wtls5
        [58] => wap-wsg-idm-ecid-wtls6
        [59] => wap-wsg-idm-ecid-wtls7
        [60] => wap-wsg-idm-ecid-wtls8
        [61] => wap-wsg-idm-ecid-wtls9
        [62] => wap-wsg-idm-ecid-wtls10
        [63] => wap-wsg-idm-ecid-wtls11
        [64] => wap-wsg-idm-ecid-wtls12
        [65] => Oakley-EC2N-3
        [66] => Oakley-EC2N-4
        [67] => brainpoolP160r1
        [68] => brainpoolP160t1
        [69] => brainpoolP192r1
        [70] => brainpoolP192t1
        [71] => brainpoolP224r1
        [72] => brainpoolP224t1
        [73] => brainpoolP256r1
        [74] => brainpoolP256t1
        [75] => brainpoolP320r1
        [76] => brainpoolP320t1
        [77] => brainpoolP384r1
        [78] => brainpoolP384t1
        [79] => brainpoolP512r1
        [80] => brainpoolP512t1
    )

# openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — Получает список доступных методов хеширования

### Описание

function openssl_get_md_methods(bool `$aliases` = `false`): array

Функция возвращает список доступных методов хеширования.

### Список параметров

`aliases`

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

### Возвращаемые значения

Функция возвращает массив с доступными методами хеширования.

### Примеры

Пример #1 Пример использования функции openssl_get_md_methods()

Пример показывает, как могут выглядеть доступные методы хеширования и их псевдонимы.

    <?php

    $digests             = openssl_get_md_methods();
    $digests_and_aliases = openssl_get_md_methods(true);
    $digest_aliases      = array_diff($digests_and_aliases, $digests);

    print_r($digests);

    print_r($digest_aliases);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => DSA
        [1] => DSA-SHA
        [2] => MD2
        [3] => MD4
        [4] => MD5
        [5] => RIPEMD160
        [6] => SHA
        [7] => SHA1
        [8] => SHA224
        [9] => SHA256
        [10] => SHA384
        [11] => SHA512
        [12] => dsaEncryption
        [13] => dsaWithSHA
        [14] => ecdsa-with-SHA1
        [15] => md2
        [16] => md4
        [17] => md5
        [18] => ripemd160
        [19] => sha
        [20] => sha1
        [21] => sha224
        [22] => sha256
        [23] => sha384
        [24] => sha512
    )
    Array
    (
        [2] => DSA-SHA1
        [3] => DSA-SHA1-old
        [4] => DSS1
        [9] => RSA-MD2
        [10] => RSA-MD4
        [11] => RSA-MD5
        [12] => RSA-RIPEMD160
        [13] => RSA-SHA
        [14] => RSA-SHA1
        [15] => RSA-SHA1-2
        [16] => RSA-SHA224
        [17] => RSA-SHA256
        [18] => RSA-SHA384
        [19] => RSA-SHA512
        [28] => dsaWithSHA1
        [29] => dss1
        [32] => md2WithRSAEncryption
        [34] => md4WithRSAEncryption
        [36] => md5WithRSAEncryption
        [37] => ripemd
        [39] => ripemd160WithRSA
        [40] => rmd160
        [43] => sha1WithRSAEncryption
        [45] => sha224WithRSAEncryption
        [47] => sha256WithRSAEncryption
        [49] => sha384WithRSAEncryption
        [51] => sha512WithRSAEncryption
        [52] => shaWithRSAEncryption
        [53] => ssl2-md5
        [54] => ssl3-md5
        [55] => ssl3-sha1
    )

### Смотрите также

- openssl_digest() - Вычисляет дайджест
- openssl_get_cipher_methods() - Получает список доступных алгоритмов шифрования

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — Псевдоним openssl_pkey_get_private()

### Описание

Псевдоним функции openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — Псевдоним openssl_pkey_get_public()

### Описание

Псевдоним функции openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — Открывает запечатанные данные

### Описание

function openssl_open(
string `$data`,
#[\SensitiveParameter]string `&$output`,
string `$encrypted_key`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string `$cipher_algo`,
?string `$iv` = `null`
): bool

Функция openssl_open() открывает, или дешифрует, данные `data` ключом конверта, который получает после расшифровки зашифрованного ключа `encrypted_key` открытым ключом `private_key`. Расшифровать данные функции помогают алгоритм шифрования `cipher_algo` и вектор инициализации `iv`. Вектор инициализации требуется, только если его запрашивает метод шифрования. Функция заполняет аргумент `output` данными, которые расшифровала. Функция генерирует ключ конверта, когда данные запечатали открытым ключом, который связан с закрытым ключом. Подробнее о запечатке, или шифровании, данных рассказывает описание функции openssl_seal().

### Список параметров

`data`

  Запечатанные данные.

`output`

  Функция заполнит аргумент открытыми данными, если завершит работу без ошибок.

`encrypted_key`

  Симметричный ключ шифрования, который расшифровывают закрытым ключом `private_key`.

`private_key`

  Закрытый ключ для расшифровки зашифрованного ключа `encrypted_key`.

`cipher_algo`

  Метод шифрования для расшифровки данных `data`.

  Предостережение

  До PHP 8.0 по умолчанию параметру назначали значение `'RC4'`, которое считают небезопасным. Настоятельно рекомендуют явно указывать безопасный метод шифрования.

`iv`

  Вектор инициализации для расшифровки данных `data`. Параметр устанавливают, только если методу шифрования требуется вектор инициализации. Значение вектора узнают путём вызова функции openssl_cipher_iv_length() с алгоритмом шифрования `cipher_algo`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL key` или `OpenSSL X.509 CSR`.
8.0.0 | Параметр `cipher_algo` теперь обязателен.

### Примеры

Пример #1 Пример распечатки данных функцией openssl_open()

    <?php

    // Предположим, что переменные $sealed, $env_key и $iv содержат запечатанные данные,
    // ключ конверта и вектор инициализации, которые прислал тот, кто запечатал данные

    // Получаем закрытый ключ из файла private_key.pem
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // Расшифровываем данные и сохраняем открытые данные в аргументе $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Вот открытые данные: ", $open;
    } else {
        echo "Не удалось открыть данные";
    }

    ?>

### Смотрите также

- openssl_seal() - Запечатывает, или зашифровывает, данные

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Создаёт хеш пароля при помощи Argon2 из OpenSSL

### Описание

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

Создаёт хеш пароля при помощи реализации Argon2 из OpenSSL. Это альтернатива функции password_hash(), в которой движком выступает OpenSSL, что в некоторых системах позволяет использовать аппаратное ускорение.

Функция доступна только тогда, когда PHP скомпилирован с поддержкой OpenSSL, которая включает Argon2 (`HAVE_OPENSSL_ARGON2`).

### Список параметров

`algo`

  Алгоритм хеширования пароля. Поддерживаемые значения: `"argon2id"` и `"argon2i"`.

`password`

  Пароль пользователя.

`options`

  Ассоциативный массив (array) опций. Поддерживаемые ключи:

  - `memory_cost` — максимальный объём памяти (в КиБ), который разрешается использовать для вычисления хеша
  - `time_cost` — максимальное время, которое разрешается потратить на вычисление хеша
  - `threads` — количество потоков, которые задействуются при вычислении хеша

### Возвращаемые значения

Возвращает хеш пароля в виде строки (string).

### Ошибки

Выбрасывает исключение ValueError, если значение параметра `algo` не входит в список поддерживаемых (`"argon2i"` или `"argon2id"`).

Выбрасывает исключение Error, если операция хеширования завершается ошибкой по неизвестной причине.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция добавлена.

### Примеры

Пример #1 Пример использования функции openssl_password_hash()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

Вывод приведённого примера будет похож на:

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

Пример #2 Использование функции openssl_password_hash() с пользовательскими опциями

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### Смотрите также

- openssl_password_verify() - Проверяет соответствие пароля хешу при помощи Argon2 из OpenSSL
- password_hash() - Создаёт хеш пароля

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Проверяет соответствие пароля хешу при помощи Argon2 из OpenSSL

### Описание

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

Проверяет, соответствует ли пароль хешу, который был создан функцией openssl_password_hash().

Функция доступна только тогда, когда PHP скомпилирован с поддержкой OpenSSL, которая включает Argon2 (`HAVE_OPENSSL_ARGON2`).

### Список параметров

`algo`

  Алгоритм хеширования пароля. Поддерживаемые значения: `"argon2id"` и `"argon2i"`.

`password`

  Пароль пользователя.

`hash`

  Хеш, который создан функцией openssl_password_hash().

### Возвращаемые значения

Возвращает `true`, если пароль и хеш совпадают, или `false` в противном случае.

### Ошибки

Выбрасывает исключение ValueError, если значение параметра `algo` не входит в список поддерживаемых (`"argon2i"` или `"argon2id"`).

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция добавлена.

### Примеры

Пример #1 Пример использования функции openssl_password_verify()

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');

    if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
        echo 'Пароль совпадает.';
    } else {
        echo 'Пароль не совпадает.';
    }
    ?>

### Смотрите также

- openssl_password_hash() - Создаёт хеш пароля при помощи Argon2 из OpenSSL
- password_verify() - Проверяет, соответствует ли пароль хешу

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — Генерирует строки PKCS5 v2 PBKDF2

### Описание

function openssl_pbkdf2(
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

Функция openssl_pbkdf2() вычисляет PBKDF2 (Password-Based Key Derivation Function 2), функцию деривации ключа, определённую в PKCS5 v2.

### Список параметров

`password`

  Пароль, из которого функция сгенерирует ключ.

`salt`
  Стандарт PBKDF2 рекомендует использовать криптографическую соль длиной как минимум 128 бита (16 байтов).
`key_length`

  Длина генерируемого ключа.

`iterations`

  Количество итераций. » NIST рекомендует как минимум 1 000. По состоянию на 2023 год OWASP рекомендует 600 000 итераций для PBKDF2-HMAC-SHA256 и 210 000 для PBKDF2-HMAC-SHA512.

`digest_algo`

  Опциональный алгоритм хеширования полученный из openssl_get_md_methods(). По умолчанию SHA-1. Рекомендуется установить значение SHA-256 или SHA-512.

### Возвращаемые значения

Функция возвращает необработанную двоичную строку или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции openssl_pbkdf2()

    <?php

    $password = 'password';
    $salt = openssl_random_pseudo_bytes(16);
    $keyLength = 20;
    $iterations = 600000;
    $generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');

    echo bin2hex($generated_key)."\n";
    echo base64_encode($generated_key)."\n";

    ?>

### Смотрите также

- hash_pbkdf2() - Генерирует PBKDF2-ключ на основе исходного пароля
- openssl_get_md_methods() - Получает список доступных методов хеширования

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — Экспортирует совместимый с PKCS#12 файл хранилища сертификатов в переменную

### Описание

function openssl_pkcs12_export(
OpenSSLCertificate|string `$certificate`,
string `&$output`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

Функция openssl_pkcs12_export() сохраняет `x509` в переменную `out` в формате PKCS#12.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`output`

  В случае успешного выполнения будет содержать PKCS#12.

`private_key`

  Компонент закрытого ключа файла PKCS#12. Список допустимых значений смотрите на странице параметров открытого/закрытого ключа.

`passphrase`

  Пароль для шифрования файла PKCS#12.

`options`

  Массив опций. Не описанные здесь ключи будут проигнорированы.

  Ключ | Описание
  --- | ---
  `"extracerts"` | массив дополнительных сертификатов или один сертификат для включения в файл PKCS#12.
  `"friendly_name"` | строка для использования сертификатом и ключом

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — Экспортирует в совместимый с PKCS#12 файл хранилища сертификатов

### Описание

function openssl_pkcs12_export_to_file(
OpenSSLCertificate|string `$certificate`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export_to_file() сохраняет `certificate` в файл `output_filename` в формате PKCS#12.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`output_filename`

  Путь до файла.

`private_key`

  Закрытый компонент ключа файла PKCS#12. Допустимые значения смотрите Параметры закрытого/открытого ключа.

`passphrase`

  Пароль для разблокировки файла PKCS#12.

`options`

  Массив опций. Не описанные здесь ключи будут проигнорированы.

  Ключ | Описание
  --- | ---
  `"extracerts"` | массив дополнительных сертификатов или один сертификат для включения в файл PKCS#12.
  `"friendly_name"` | строка для использования сертификатом и ключом

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509 CSR`.
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — Разбирает хранилище сертификатов PKCS#12 в массив

### Описание

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter]string `$passphrase`): bool

Функция openssl_pkcs12_read() разбирает хранилище сертификатов PKCS#12, которое задали в параметре `pkcs12`, и помещает в массив `certificates`.

### Список параметров

`pkcs12`

  Содержимое хранилища сертификатов, а не его имя файла.

`certificates`

  В случае успешного выполнения параметр будет содержать данные хранилища сертификата (Certificate Store Data).

`passphrase`

  Пароль для расшифровки файла PKCS#12.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример разбора хранилища сертификатов функцией openssl_pkcs12_read()

    <?php

    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Ошибка: невозможно прочитать файл сертификата\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
        echo "Информация об сертификате\n";
        print_r($cert_info);
    } else {
        echo "Ошибка: невозможно прочитать хранилище сертификата.\n";
        exit;
    }

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — Расшифровывает S/MIME-сообщение

### Описание

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

Функция расшифровывает S/MIME-сообщение, которое содержится в файле `input_filename`. Для расшифровки сообщения функция использует сертификат `certificate` и закрытый ключ `private_key`, который связан с сертификатом.

### Список параметров

`input_filename`

`output_filename`

  Функция расшифрует сообщение и запишет сообщение в файл, который указали в параметре `output_filename`.

`certificate`

`private_key`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource), который принадлежал типу `OpenSSL key` или `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования функции openssl_pkcs7_decrypt()

    <?php

    // Переменные сертификата $cert и ключа $key содержат пару с личным сертификатом и закрытым ключом
    $infilename = "encrypted.msg";  // Этот файл содержит зашифрованное сообщение
    $outfilename = "decrypted.msg"; // Пользователю, который будет записывать сообщение в файл, требуются права на запись

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "Функция расшифровала сообщение!";
    } else {
        echo "Возникла ошибка при расшифровке!";
    }

    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — Шифрует сообщение по стандарту S/MIME

### Описание

function openssl_pkcs7_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Функция openssl_pkcs7_encrypt() принимает содержимое файла, название которого указали в параметре `input_filename`, и шифрует файл 40-битным шифром RC2, чтобы прочитать файл могли только конкретные получатели, которых указали в сертификате `certificate`.

### Список параметров

`input_filename`

`output_filename`

`certificate`

  Отдельный сертификат в формате X.509 или массив X.509-сертификатов.

`headers`

  Параметр `headers` — массив заголовков, которые функция добавит в начало сообщения, которое уже зашифровала.

  Заголовки `headers` — ассоциативный массив, в котором ключи — имена заголовков, или индексный массив, в котором каждый элемент содержит одну строку заголовка.

`flags`

  В необязательном параметре `flags` указывают опции, которые влияют на процесс кодирования. Список и описание флагов приводит раздел «Константы-флаги структур PKCS7».

`cipher_algo`

  Флаг шифра.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Алгоритмом шифрования по умолчанию, который принимает параметр `cipher_algo`, стал AES-128-CBC — флаг `OPENSSL_CIPHER_AES_128_CBC`. Раньше алгоритмом по умолчанию был PKCS7/CMS — флаг `OPENSSL_CIPHER_RC2_40`.
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource), который принадлежал типу `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования функции openssl_pkcs7_encrypt()

    <?php

    // Сообщение, которое требуется зашифровать и отправить секретному
    // агенту с позывным «Козодой». На локальной машинке отправителя в файле nighthawk.pem лежит сертификат получателя
    $data = <<<EOD
    Козодой,

    Совершенно секретно! После прочтения — сжечь!

    Враги приближаются! Связной с новым поддельным паспортом
    будет ждать тебя завтра в кафе в 8:30 по московскому времени.

    Пароль: «У вас ус отклеился!»
    Отзыв: «Это не ус, а борода!»

    EOD;

    // Загружаем ключ
    $key = file_get_contents("nighthawk.pem");

    // Записываем сообщение в файл
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // Шифруем сообщение
    if (openssl_pkcs7_encrypt(
        "msg.txt",
        "enc.txt",
        $key,
        array(
            "To" => "nighthawk@example.com", // Ассоциативный синтаксис
            "From: HQ <hq@example.com>", // Индексный синтаксис
            "Subject" => "Срочно! Важно!"
        )
    )) {
        // Сообщение зашифровано, отправляем!
        exec(ini_get("sendmail_path") . " < enc.txt");
    }

    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — Экспортирует PKCS7-файл в массив PEM-сертификатов

### Описание

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`data`

  Строка данных, которые требуется проанализировать (формат p7b).

`certificates`

  Массив PEM-сертификатов из входных данных p7b.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения массива PEM из файла P7B

    <?php

    $file = 'certs.p7b';

    $f = file_get_contents($file);
    $p7 = array();
    $r = openssl_pkcs7_read($f, $p7);

    if ($r === false) {
        printf("ОШИБКА: %s не является корректным файлом p7b".PHP_EOL, $file);
            for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
                printf("SSL l%d: %s".PHP_EOL, $i, $e);
        exit(1);
    }

    print_r($p7);

    ?>

### Смотрите также

- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — Подписывает сообщение S/MIME

### Описание

function openssl_pkcs7_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = `PKCS7_DETACHED`,
?string `$untrusted_certificates_filename` = `null`
): bool

Функция openssl_pkcs7_sign() принимает содержимое файла, название которого указали в параметре `input_filename`, а затем подписывает файл сертификатом `certificate` и закрытым ключом `private_key`, который соответствует сертификату.

### Список параметров

`input_filename`

  Файл, который требуется подписать цифровой подписью.

`output_filename`

  Файл, в который функция запишет цифровую подпись.

`certificate`

  Сертификат в формате X.509, которым функция подпишет файл `input_filename`. Список допустимых значений приводит раздел «Параметры ключа и сертификата».

`private_key`

  Параметр `private_key` — закрытый ключ, который соответствует сертификату (`certificate`). Список допустимых значений приводит параграф «Параметры открытого и закрытого ключа».

`headers`

  Параметр `headers` — массив заголовков, которые функция добавит в начало данных после подписания (описание функции openssl_pkcs7_encrypt() даёт дополнительную информацию о формате параметра).

`flags`

  Параметр `flags` настраивает вывод. Смотрите раздел «Константы-флаги структур PKCS7».

`untrusted_certificates_filename`

  Параметр `untrusted_certificates_filename` указывает имя файла, который содержит набор дополнительных сертификатов для добавления к подписи. Например: дополнительные сертификаты передают, чтобы помочь получателю проверить сертификат отправителя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource), который принадлежит типу `OpenSSL X.509 CSR`.
8.0.0 | Параметр `private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource), который принадлежит типу `OpenSSL key` или `OpenSSL X.509 CSR`.

### Примеры

Пример #1 Пример использования функции openssl_pkcs7_sign()

    <?php

    // Сообщение, которое требуется подписать, чтобы получатели могли
    // проверить отправителя
    $data = <<<EOD

    Разрешаю потратить на обед с контрагентом не более 100 000 ₽.

    Ваш директор.
    EOD;

    // Сохраняем сообщение в фалй
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // Шифруем
    if (openssl_pkcs7_sign(
        "msg.txt",
        "signed.txt",
        "file://mycert.pem",
        array("file://mycert.pem", "mypassphrase"),
        array(
            "To" => "joes@example.com", // Ассоциативный синтаксис
            "From: HQ <ceo@example.com>", // Индексный синтаксис
            "Subject" => "Представительские расходы"
        )
    )) {

        // Сообщение подписано, — отправляем!
        exec(ini_get("sendmail_path") . " < signed.txt");
    }

    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — Проверяет подпись S/MIME-сообщения

### Описание

function openssl_pkcs7_verify(
string `$input_filename`,
int `$flags`,
?string `$signers_certificates_filename` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$output_filename` = `null`
): bool|int

Функция openssl_pkcs7_verify() читает S/MIME-сообщение из файла и проверяет цифровую подпись сообщения.

### Список параметров

`input_filename`

  Путь к файлу с сообщением.

`flags`

  Параметр `flags` влияет на способ проверки подписи. Дополнительную информацию о флагах даёт раздел «Константы-флаги структур PKCS7».

`signers_certificates_filename`

  Параметр `signers_certificates_filename` принимает строку с именем файла, в котором хранятся PEM-сертификаты лиц, которые подписали сообщения.

`ca_info`

  Параметр `ca_info` принимает информацию о сертификатах доверенных центров сертификации, которые функция будет использовать для проверки подписи. Дополнительную информацию об этом параметре даёт раздел «Проверка сертификата».

`untrusted_certificates_filename`

  Параметр `untrusted_certificates_filename` принимает название файла, который содержит набор сертификатов, которые функция будет использовать как сертификаты недоверенных центров сертификации.

`content`

  Параметр `content` принимает имя файла, в который функция запишет содержимое данных, которые проверила, но с удалённой информацией о подписи.

`output_filename`

### Возвращаемые значения

Функция возвращает `true`, если проверила подпись, `false`, если подпись неправильная — сообщение подделали или сертификат подписи недействителен, и -1, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `signers_certificates_filename`, `untrusted_certificates_filename`, `content` и `output_filename` теперь принимают значение null.
7.2.0 | Добавили параметр `output_filename`.

### Примечания

> Замечание: Как указывает стандарт RFC 2045, длина строки параметра `input_filename` не должна превышать 76 символов.

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — Вычисляет общий секрет для открытого значения удалённого и локального ключа DH или ECDH

### Описание

function openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, int `$key_length` = 0): string|false

Функция openssl_pkey_derive() принимает набор из параметров `public_key` и `private_key` и порождает общий секрет для ключей DH или EC.

### Список параметров

`public_key`

  Открытый ключ для вывода. Список допустимых значений смотрите в разделе Параметры ключа/сертификата.

`private_key`

  Закрытый ключ для вывода. Список допустимых значений смотрите в разделе Параметры ключа/сертификата.

`key_length`

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

  Предостережение

  Параметр устарел и его не следует использовать, так как он работает не так, как ожидается. Он никогда не возвращает секрет, длина которого превышает размер первого секрета. Если желаемая длина меньше размера первого секрета, он усекает длину только для ключей ECDH, но не для ключей DH.

### Возвращаемые значения

Функция возвращает секрет в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Параметр `key_length` устарел.

### Примеры

Пример #1 Пример использования функции openssl_pkey_derive()

    <?php

    // Загрузка закрытого ключа
    $priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
    MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
    upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
    VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
    0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
    197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
    HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
    AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
    cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
    6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
    dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
    hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
    CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
    -----END PRIVATE KEY-----
    ");

    // Загрузка открытого ключа
    $pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
    MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
    BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
    MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
    t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
    GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
    VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
    ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
    ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
    ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
    vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
    c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
    dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
    -----END PUBLIC KEY-----
    ");

    // Выводит шестнадцатеричную версию произведённого ключа
    echo bin2hex(openssl_pkey_derive($pub,$priv));

    ?>

# openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — Получает строку с ключом в формате PEM

### Описание

function openssl_pkey_export(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

Функция openssl_pkey_export() экспортирует ключ `key` в виде строки в формате PEM и сохраняет его в параметре `output` (передаётся по ссылке).

> Замечание: Для корректной работы этой функции должен существовать правильный openssl.cnf. Для более подробной информации смотрите замечания под разделом установки.

### Список параметров

`key`

`output`

`passphrase`

  Ключ опционально защищается паролем `passphrase`.

`options`

  Параметр `options` можно использовать для тонкой настройки процесса экспорта путём указания, либо переопределения опций конфигурационного файла openssl. Описание функции openssl_csr_new() даёт подробную информацию о параметре `options`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — Записывает в файл ключ в формате PEM

### Описание

function openssl_pkey_export_to_file(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `$output_filename`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

Функция openssl_pkey_export_to_file() записывает ключ `key` в формате PEM в файл `output_filename`.

> Замечание: Для корректной работы этой функции должен существовать правильный openssl.cnf. Для более подробной информации смотрите замечания под разделом установки.

### Список параметров

`key`

`output_filename`

  Путь до файла.

`passphrase`

  Ключ опционально защищается паролем `passphrase`.

`options`

  Параметр `options` можно использовать для тонкой настройки процесса экспорта путём указания, либо переопределения опций конфигурационного файла openssl. Описание функции openssl_csr_new() даёт подробную информацию о параметре `options`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — Освобождает ресурс закрытого ключа

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> Замечание: Функция стала бесполезной. До PHP 8.0.0 функция закрывала ресурс.

Функция высвобождает ресурс закрытого ключа, который создали функцией openssl_pkey_new().

### Список параметров

`key`

  Ресурс, в котором содержится ключ.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела, поскольку больше ни на что не влияет.
8.0.0 | Параметр `key` теперь принимает экземпляр класса OpenSSLAsymmetricKey; раньше принимался ресурс (resource), который принадлежит типу `OpenSSL key`.

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — Получает массив с детальной информацией о ключе

### Описание

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

Эта функция возвращает массив с детальной информацией о ключе.

### Список параметров

`key`

  Ресурс, содержащий ключ.

### Возвращаемые значения

Возвращает массив с детальной информацией о ключе, либо `false`. Массив содержит следующие индексы: `bits` (количество бит), `key` (строковое представление открытого ключа) и `type` (тип ключа, одна из констант: `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448` или `-1`, если неизвестно).

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

- Для `OPENSSL_KEYTYPE_RSA` возвращается элемент с индексом `"rsa"`, содержащий данные ключа.

  Ключ | Описание
  --- | ---
  `"n"` | модуль
  `"e"` | открытая экспонента
  `"d"` | секретная экспонента
  `"p"` | первое простое число
  `"q"` | второе простое число
  `"dmp1"` | первая экспонента, d mod (p-1)
  `"dmq1"` | вторая экспонента, d mod (q-1)
  `"iqmp"` | коэффициент, (1 / q) mod p

- Для `OPENSSL_KEYTYPE_DSA` возвращается элемент с индексом `"dsa"`, содержащий данные ключа.

  Ключ | Описание
  --- | ---
  `"p"` | Простое число (публичное)
  `"q"` | 160-битное простое число, такое, что p-1 делится на q (публичное)
  `"g"` | Генератор подгрупп (публичный). Мультипликативный порядок g по модулю p равен q
  `"priv_key"` | Секретный ключ x
  `"pub_key"` | Открытый ключ y = g^x

- Для `OPENSSL_KEYTYPE_DH` возвращается элемент с индексом `"dh"`, содержащий данные ключа.

  Ключ | Описание
  --- | ---
  `"p"` | Простое число (открытое)
  `"g"` | Генератор Z_p (открытый), простое число, первообразный корень по модулю p
  `"priv_key"` | секретное DH значение x
  `"pub_key"` | открытое DH значение g^x

- `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, или `OPENSSL_KEYTYPE_ED448` дополнительный ключ массива с именем `"x25519"`, `"ed25519"`, `"x448"` или `"ed448"` соответственно, возвращается, содержащий данные ключа.

  Ключ | Описание
  --- | ---
  `"priv_key"` | закрытый ключ
  `"pub_key"` | открытый ключ

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлена поддержка ключей на основе Curve25519 и Curve448. В частности, были добавлены поля `x25519`, `ed25519`,`x448` и `ed448`.
8.0.0 | `key` теперь принимает экземпляр OpenSSLAsymmetricKey; ранее принимался ресурс (resource) типа `OpenSSL key`.

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — Получает закрытый ключ

### Описание

function openssl_pkey_get_private(#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter]?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

Функция openssl_pkey_get_private() разбирает ключ `private_key` и подготавливает его к работе в других функциях.

### Список параметров

`private_key`

  Параметр `private_key` разрешается задавать следующим образом:

  1. Строка вида file://path/to/file.pem. Файл должен содержать кодированный в PEM сертификат или закрытый ключ (может содержать и то и другое).
  2. Секретный ключ в формате PEM.
`passphrase`

  Если ключ защищён паролем, то его надо указать в параметре `passphrase`.

### Возвращаемые значения

Функция возвращает экземпляр класса OpenSSLAsymmetricKey или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр OpenSSLAsymmetricKey; раньше возвращался ресурс (resource) типа `OpenSSL key`.
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.
8.0.0 | Параметр `passphrase` теперь принимает значение null.

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — Извлекает открытый ключ из сертификата и подготавливает его к использованию

### Описание

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() извлекает открытый ключ из `public_key` и подготавливает его к использованию в других функциях.

### Список параметров

`public_key`

  `public_key` может быть одним из:

  1. экземпляр OpenSSLAsymmetricKey
  2. строка вида file://path/to/file.pem. Файл должен содержать кодированный в PEM сертификат/публичный ключ (может содержать и то и другое).
  3. Открытый ключ в формате PEM.

### Возвращаемые значения

Возвращает экземпляр OpenSSLAsymmetricKey или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр OpenSSLAsymmetricKey; ранее возвращался ресурс (resource) типа `OpenSSL key`.
8.0.0 | `public_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — Генерирует новый закрытый ключ

### Описание

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

Функция openssl_pkey_new() создаёт новый закрытый ключ. Пример на этой странице показывает, как получить открытую часть ключа.

> Замечание: Для корректной работы этой функции должен существовать правильный openssl.cnf. Для более подробной информации смотрите замечания под разделом установки.

### Список параметров

`options`

  Можно точно настроить генерацию ключей (например, указав количество бит или параметров) с помощью параметра `options`. Параметры могут быть либо специфическими для алгоритма, используемыми для генерации ключей, либо общими параметрами, используемыми также при генерации CSR, если не указано иное. Посмотрите документацию функции openssl_csr_new() для получения дополнительной информации о том, как использовать параметр `options` для CSR. Среди этих опций для генерации ключей используются только `private_key_bits`, `private_key_type`, `curve_name` и `config`. Опции, специфичные для алгоритма, используются, если ассоциативный массив содержит один из специфических ключей.

  - Ключ `"rsa"` для настройки параметров RSA.

    Опции | Тип | Формат | Обязательность | Описание
    --- | --- | --- | --- | ---
    `"n"` | string | двоичное число | да | modulus
    `"e"` | string | двоичное число | нет | public exponent
    `"d"` | string | двоичное число | да | private exponent
    `"p"` | string | двоичное число | нет | prime 1
    `"q"` | string | двоичное число | нет | prime 2
    `"dmp1"` | string | двоичное число | нет | exponent1, d mod (p-1)
    `"dmq1"` | string | двоичное число | нет | exponent2, d mod (q-1)
    `"iqmp"` | string | двоичное число | нет | coefficient, (inverse of q) mod p

  - Ключ `"dsa"` для настройки параметров DSA.

    Опции | Тип | Формат | Обязательность | Описание
    --- | --- | --- | --- | ---
    `"p"` | string | двоичное число | нет | prime number (public)
    `"q"` | string | двоичное число | нет | 160-bit subprime, q | p-1 (public)
    `"g"` | string | двоичное число | нет | generator of subgroup (public)
    `"priv_key"` | string | Ключ PEM | нет | private key x
    `"pub_key"` | string | Ключ PEM | нет | public key y = g^x

  - Ключ `"dh"` для настройки параметров DH (Diffie–Hellman key exchange).

    Опции | Тип | Формат | Обязательность | Описание
    --- | --- | --- | --- | ---
    `"p"` | string | двоичное число | нет | prime number (shared)
    `"g"` | string | двоичное число | нет | generator of Z_p (shared)
    `"priv_key"` | string | Ключ PEM | нет | private DH value x
    `"pub_key"` | string | Ключ PEM | нет | public DH value g^x

  - Ключ `"ec"` для настройки параметров Elliptic curve.

    Опции | Тип | Формат | Обязательность | Описание
    --- | --- | --- | --- | ---
    `"curve_name"` | string | name | нет | name of curve, see openssl_get_curve_names()
    `"p"` | string | двоичное число | нет | prime of the field for curve over Fp
    `"a"` | string | двоичное число | нет | coofecient a of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | двоичное число | нет | coofecient b of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | двоичное число | нет | optional random number seed used to generate coefficient b
    `"generator"` | string | binary encoded point | нет | curve generator point
    `"g_x"` | string | двоичное число | нет | curver generator point x coordinat
    `"g_y"` | string | двоичное число | нет | curver generator point y coordinat
    `"cofactor"` | string | двоичное число | нет | curve cofactor
    `"order"` | string | двоичное число | нет | curve order
    `"x"` | string | двоичное число | нет | x coordinate (public)
    `"y"` | string | двоичное число | нет | y coordinate (public)
    `"d"` | string | двоичное число | нет | private key

  - Ключи `"x25519"`, `"x448"`, `"ed25519"`, `"ed448"` для настройки параметров Curve25519 и Curve448.

    Опции | Тип | Формат | Обязательность | Описание
    --- | --- | --- | --- | ---
    `"priv_key"` | string | Ключ PEM | нет | Закрытый ключ
    `"pub_key"` | string | Ключ PEM | нет | Открытый ключ

### Возвращаемые значения

При успешном выполнении функция возвращает экземпляр класса OpenSSLAsymmetricKey для закрытого ключа или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлена поддержка ключей на основе Curve25519 и Curve448 с добавлением полей `x25519`, `ed25519`, `x448` и `ed448`.
8.3.0 | Добавлена поддержка создания ключей EC с настраиваемыми параметрами EC. В частности, с введением опций EC: `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor` и `order`.
8.0.0 | В случае успешного выполнения функция возвращает экземпляр OpenSSLAsymmetricKey; раньше возвращался ресурс (resource) типа `OpenSSL key`.
7.1.0 | Для параметра `options` добавили ключ `curve_name`, чтобы создавать EC-ключи на основе алгоритмов эллиптических кривых.

### Примеры

Пример #1 Пример получения открытой части ключа из закрытого ключа

    <?php

    $private_key = openssl_pkey_new();

    $public_key_pem = openssl_pkey_get_details($private_key)['key'];
    echo $public_key_pem, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

Вывод приведённого примера будет похож на:

    // Вывод до PHP 8.0.0; обратите внимание, функция возвращает ресурс
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    resource(6) of type (OpenSSL key)

    // Вывод с PHP 8.0.0; обратите внимание, функция возвращает объект
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

Пример #2 Создание ключа RSA из параметров

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — Расшифровывает данные закрытым ключом

### Описание

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

Функция openssl_private_decrypt() расшифровывает данные `data`, которые раньше зашифровали функцией openssl_public_encrypt(), и сохраняет результат в параметре `decrypted_data`.

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

### Список параметров

`data`

`decrypted_data`

`private_key`

  В параметр `private_key` передают закрытый ключ, который соответствует открытому ключу, которым зашифровали данные.

`padding`

  Параметр `padding` принимает значение из следующего списка: `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING`, `OPENSSL_NO_PADDING`.

`digest_algo`
  Алгоритм хеширования для схемы дополнения OAEP (англ. Optimal Asymmetric Encryption Padding — оптимальное асимметричное шифрование с дополнением). При передаче значения `null` функция выбирает алгоритм по умолчанию.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `digest_algo`.
8.0.0 | Параметр`private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

### Смотрите также

- openssl_public_encrypt() - Шифрует данные открытым ключом
- openssl_public_decrypt() - Расшифровывает данные открытым ключом

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — Шифрует данные секретным ключом

### Описание

function openssl_private_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

Функция openssl_private_encrypt() шифрует данные `data` секретным ключом `private_key` и сохраняет результат в параметре `encrypted_data`. Потом данные можно расшифровать функцией openssl_public_decrypt().

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

### Список параметров

`data`

`encrypted_data`

`private_key`

  В параметр `private_key` передают закрытый ключ, который соответствует открытому ключу для расшифровки данных.

`padding`

  В параметр `padding` передают константу `OPENSSL_PKCS1_PADDING` или `OPENSSL_NO_PADDING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `private_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

### Смотрите также

- openssl_public_encrypt() - Шифрует данные открытым ключом
- openssl_public_decrypt() - Расшифровывает данные открытым ключом

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — Расшифровывает данные открытым ключом

### Описание

function openssl_public_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

Функция openssl_public_decrypt() расшифровывает данные `data`, которые раньше зашифровали функцией openssl_private_encrypt(), и сохраняет результат в параметре `decrypted_data`.

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

### Список параметров

`data`

`decrypted_data`

`public_key`

  В параметр `public_key` передают открытый ключ, который соответствует закрытому ключу, которым зашифровали данные.

`padding`

  В параметр`padding` передают константу `OPENSSL_PKCS1_PADDING` или `OPENSSL_NO_PADDING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр`public_key` теперь принимает экземпляр OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

### Смотрите также

- openssl_private_encrypt() - Шифрует данные секретным ключом
- openssl_private_decrypt() - Расшифровывает данные закрытым ключом

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — Шифрует данные открытым ключом

### Описание

function openssl_public_encrypt(
string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

Функция openssl_public_encrypt() шифрует данные `data` открытым ключом `public_key` и сохраняет в параметре `encrypted_data`. Затем данные расшифровывают функцией openssl_private_decrypt().

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

### Список параметров

`data`

`encrypted_data`

  Функция заполнит параметр результатом шифрования.

`public_key`

  В параметр `public_key` передают открытый ключ, который соответствует закрытому ключу для расшифровки данных.

`padding`

  Параметр `padding` принимает константу из следующего списка: `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING`, `OPENSSL_NO_PADDING`.

`digest_algo`
  Алгоритм хеширования для схемы дополнения OAEP (англ. Optimal Asymmetric Encryption Padding — оптимальное асимметричное шифрование с дополнением). При передаче значения `null` функция выбирает алгоритм по умолчанию.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `digest_algo`.
8.0.0 | Параметр `public_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

### Смотрите также

- openssl_private_encrypt() - Шифрует данные секретным ключом
- openssl_private_decrypt() - Расшифровывает данные закрытым ключом

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — Генерирует псевдослучайную последовательность байт

### Описание

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

Генерирует строку псевдослучайных байт длиной `length`.

Также, если задать необязательный параметр `strong_result`, который передаётся по ссылке, то в него запишется `true` или `false`, в зависимости от того, был ли использован криптографически сильный алгоритм.

### Список параметров

`length`

  Длина генерируемой строки. Должна быть целым положительным числом, меньшим или равным `2147483647`. При использовании, PHP попытается привести этот параметр к ненулевому целому числу.

`strong_result`

  Если задано, то в переданную переменную будет записано `true` или `false`, в зависимости от того, был ли использован криптографически сильный алгоритм.

### Возвращаемые значения

Возвращает строку случайных байт.

### Ошибки

Функция openssl_random_pseudo_bytes() выбрасывает исключение Exception в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `strong_result` теперь допускает значение null.

### Примеры

Пример #1 Пример использования openssl_random_pseudo_bytes()

    <?php
    for ($i = 1; $i <= 4; $i++) {
        $bytes = openssl_random_pseudo_bytes($i, $cstrong);
        $hex   = bin2hex($bytes);

        echo "Lengths: Bytes: $i and Hex: " . strlen($hex) . PHP_EOL;
        var_dump($hex);
        var_dump($cstrong);
        echo PHP_EOL;
    }
    ?>

Вывод приведённого примера будет похож на:

    Lengths: Bytes: 1 and Hex: 2
    string(2) "42"
    bool(true)

    Lengths: Bytes: 2 and Hex: 4
    string(4) "dc6e"
    bool(true)

    Lengths: Bytes: 3 and Hex: 6
    string(6) "288591"
    bool(true)

    Lengths: Bytes: 4 and Hex: 8
    string(8) "ab86d144"
    bool(true)

### Смотрите также

- random_bytes() - Генерирует криптографически безопасные случайные байты
- bin2hex() - Преобразовывает двоичные данные в шестнадцатеричное представление
- crypt() - Хеширует строку необратимым способом
- random_int() - Получает криптографически безопасное равномерно выбранное целое число

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — Запечатывает, или зашифровывает, данные

### Описание

function openssl_seal(
string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

Функция openssl_seal() запечатывает, или шифрует, данные `data` алгоритмом `cipher_algo` со случайно сгенерированным секретным ключом. Затем функция шифрует ключ каждым открытым ключом в массиве `public_key`, и каждый зашифрованный ключ конверта возвращается массиве `encrypted_keys`. Это помогает отправлять запечатанные данные набору получателей (при условии, что открытые ключи получателей доступны). Каждый получатель получит запечатанные данные и ключ конверта, который функция зашифровала открытым ключом получателя. После чего функция генерирует вектор инициализации (англ. Initialization Vector, IV) и возвращает значение вектора в параметре `iv`.

### Список параметров

`data`

  Данные, которые требуется запечатать.

`sealed_data`

  Данные, которые запечатала функция.

`encrypted_keys`

  Массив зашифрованных ключей.

`public_key`

  Массив экземпляров класса OpenSSLAsymmetricKey, которые содержат открытые ключи.

`cipher_algo`

  Алгоритм шифрования.

  Предостережение

  До PHP 8.0 по умолчанию параметру назначали значение `'RC4'`, которое считают небезопасным. Настоятельно рекомендуют явно указывать безопасный метод шифрования.

`iv`

  Вектор инициализации для расшифровки данных `data`. Параметр устанавливают, только если методу шифрования требуется вектор инициализации. Значение вектора узнают путём вызова функции openssl_cipher_iv_length() с алгоритмом шифрования `cipher_algo`.

  Предостережение

  Вектор инициализации невозможно указать явно. Значение, которое установили в параметре, перезаписывается значением, которое функция сгенерировала случайно.

### Возвращаемые значения

Функция возвращает длину запечатанных данных или `false`. В случае успешного выполнения параметр `sealed_data` будет содержать запечатанные данные, а параметр `encrypted_keys` — зашифрованные ключи.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `public_key` теперь принимает массив (array) экземпляров класса OpenSSLAsymmetricKey; раньше принимался массив (array) ресурсов (resource) с типом `OpenSSL key`.
8.0.0 | Параметр `cipher_algo` теперь обязательный параметр.
8.0.0 | Параметр `iv` теперь принимает значение null.

### Примеры

Пример #1 Пример запечатки данных функцией openssl_seal()

    <?php

    // Переменная $data содержит данные, которые требуется запечатать
    $data = "test";

    // Получаем и подготавливаем открытые ключи получателей
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // Запечатываем сообщение; только владельцы ключей $pk1 и $pk2 расшифруют
    // запечатанные данные $sealed ключами $ekeys[0] и $ekeys[1]
    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // Запечатанные данные $sealed и значения вектора инициализации $iv сохраняют,
        // чтобы позднее использовать значения при вызове функции openssl_open
        echo "success\n";
    }

    ?>

### Смотрите также

- openssl_open() - Открывает запечатанные данные

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Генерирует подписи

### Описание

function openssl_sign(
string `$data`,
string `&$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

Функция openssl_sign() вычисляет подпись для данных `data` путём генерации закрытым ключом `private_key` криптографического цифрового слепка. Обратите внимание, что сами данные не шифруются.

### Список параметров

`data`

  Строка данных, для которых требуется получить отпечаток.

`signature`

  В случае успешного выполнения функция поместит подпись в переменную, которую задали в параметре `signature`.

`private_key`

  Экземпляр класса OpenSSLAsymmetricKey — ключ, который вернула функция openssl_get_privatekey().

  Строка (string) — ключ в формате PEM.

`algorithm`

  Целое число (int) — один из алгоритмов подписи.

  Строка (string) — корректная строка, которую вернула функция openssl_get_md_methods(), например, «sha256WithRSAEncryption» или «sha384».

`padding`
  Схема дополнения PSS (англ. Probabilistic Signature Scheme — вероятностная схема подписи) алгоритма RSA.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `padding`.
8.0.0 | Параметр `private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) типа `OpenSSL key` или `OpenSSL X.509`.

### Примеры

Пример #1 Пример генерации подписи функцией openssl_sign()

    <?php

    // Переменная $data содержит данные для генерации подписи

    // Извлекаем секретный ключ из файла и подготавливаем
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // Вычисляем подпись
    openssl_sign($data, $signature, $pkeyid);

    // Высвобождаем ресурс ключа
    openssl_free_key($pkeyid);

Пример #2 Пример генерации подписи функцией openssl_sign()

    <?php

    // Данные для генерации сигнатуры
    $data = 'my data';

    // Создаём новую пару открытый/закрытый ключ
    $new_key_pair = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    openssl_pkey_export($new_key_pair, $private_key_pem);

    $details = openssl_pkey_get_details($new_key_pair);
    $public_key_pem = $details['key'];

    // Вычисляем подпись
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    // Сохраняем
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    // Сверяем подпись
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");

    var_dump($r);

### Смотрите также

- openssl_verify() - Проверяет подпись

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом

### Описание

function openssl_spki_export(string `$spki`): string|false

Функция экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом.

### Список параметров

`spki`

  Корректный открытый ключ с вызовом.

### Возвращаемые значения

Функция возвращает открытый ключ в формате PEM или `false`, если возникла ошибка.

### Ошибки

Функция вызывает ошибку уровня `E_WARNING`, если в параметр `spki` передали некорректные данные.

### Примеры

Пример #1 Пример использования функции openssl_spki_export()

Функция возвращает открытый ключ в формате PEM или `null`, если возникла ошибка.

    <?php

    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

    if ($pubKey) {
        echo $pubKey;
    }

    ?>

Пример #2 Пример использования функции openssl_spki_export() с элементом <keygen>

Функция возвращает открытый ключ в формате PEM, который получили из элемента <keygen>

    <?php

    $spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));

    if ($spkac != NULL) {
        echo $spkac;
    } else {
        echo "Не удалось извлечь открытый ключ";
    }

    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Смотрите также

- openssl_spki_new() - Создаёт подписанный открытый ключ с вызовом
- openssl_spki_verify() - Проверяет подписанный открытый ключ и вызов
- openssl_spki_export_challenge() - Экспортирует вызов, который связан с подписанным ключом и вызовом
- openssl_get_md_methods() - Получает список доступных методов хеширования
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — Экспортирует вызов, который связан с подписанным ключом и вызовом

### Описание

function openssl_spki_export_challenge(string `$spki`): string|false

Функция экспортирует вызов из подписанного открытого ключа и вызова.

### Список параметров

`spki`

  Корректный подписанный открытый ключ с вызовом.

### Возвращаемые значения

Функция возвращает строку вызова или `false`, если возникла ошибка.

### Ошибки

Функция вызывает ошибку уровня `E_WARNING`, если в параметр `spki` передали некорректные данные.

### Примеры

Пример #1 Пример использования функции openssl_spki_export_challenge()

Функция возвращает строку вызова или `null`, если возникла ошибка.

    <?php

    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));

    ?>

Пример #2 Пример использования функции openssl_spki_export_challenge() с <keygen>

Извлечение строки вызова, которую получили из элемента <keygen>

    <?php

    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));

    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Смотрите также

- openssl_spki_new() - Создаёт подписанный открытый ключ с вызовом
- openssl_spki_verify() - Проверяет подписанный открытый ключ и вызов
- openssl_spki_export() - Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом
- openssl_get_md_methods() - Получает список доступных методов хеширования
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — Создаёт подписанный открытый ключ с вызовом

### Описание

function openssl_spki_new(OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

Функция через заданный алгоритм хеширования создаёт подписанный открытый ключ с вызовом.

### Список параметров

`private_key`

  Параметр `private_key` устанавливается закрытым ключом, который сгенерировала функция openssl_pkey_new() (или который получили другим способом из другого семейства функций openssl_pkey). Функция подпишет CSR-запрос соответствующей открытой частью ключа.

`challenge`

  Вызов, который связан с ключом SPKAC.

`digest_algo`

  Алгоритм хеширования. Смотрите описание функции openssl_get_md_method().

### Возвращаемые значения

Функция возвращает подписанный открытый ключ со строкой вызова или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если в параметре `digest_algo` указали некорректный алгоритм.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey; раньше принимался ресурс (resource) с типом `OpenSSL key`.

### Примеры

Пример #1 Пример использования функции openssl_spki_new()

Создаёт новый SPKAC-ключ с алгоритмом по умолчанию (MD5)

    <?php

    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'testing');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "Генерация SPKAC не удалась";
    }

    ?>

Вывод приведённого примера будет похож на:

    MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
    mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
    hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
    WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
    dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
    oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
    i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
    pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
    y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
    sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
    lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
    29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
    MML5G2iNVgNozAo=

### Смотрите также

- openssl_spki_verify() - Проверяет подписанный открытый ключ и вызов
- openssl_spki_export_challenge() - Экспортирует вызов, который связан с подписанным ключом и вызовом
- openssl_spki_export() - Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом
- openssl_get_md_methods() - Получает список доступных методов хеширования
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — Проверяет подписанный открытый ключ и вызов

### Описание

function openssl_spki_verify(string `$spki`): bool

Проверяет подписанный открытый ключ и вызов

### Список параметров

`spki`

  Корректный подписанный открытый ключ и вызов

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Вызывает ошибку уровня `E_WARNING`, если в параметр `spki` переданы некорректные данные.

### Примеры

Пример #1 Пример использования openssl_spki_verify()

Проверка существующего подписанного открытого ключа с вызовом

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');

    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
        echo $spkac;
    } else {
        echo "Проверка SPKAC не удалась";
    }
    ?>

Пример #2 Пример использования openssl_spki_verify() с <keygen>

Проверка существующего подписанного открытого ключа и вызова, полученного из элемента <keygen>

    <?php
    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
        echo $spkac;
    } else {
        echo "Проверка SPKAC не удалась";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Смотрите также

- openssl_spki_new() - Создаёт подписанный открытый ключ с вызовом
- openssl_spki_export_challenge() - Экспортирует вызов, который связан с подписанным ключом и вызовом
- openssl_spki_export() - Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом
- openssl_get_md_methods() - Получает список доступных методов хеширования
- openssl_csr_new() - Генерирует CSR
- openssl_csr_sign() - Подписывает CSR через другой сертификат (или им же) и создаёт сертификат

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — Проверяет подпись

### Описание

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

Функция openssl_verify() проверяет, корректна ли подпись `signature` для данных `data` и открытого ключа `public_key`. Открытый ключ должен соответствовать закрытому ключу, с которым генерировалась подпись.

### Список параметров

`data`

  Проверяемые данные.

`signature`

  Необработанная двоичная строка, которую создала функция openssl_sign() или её аналог.

`public_key`

  Переменная с типом OpenSSLAsymmetricKey, которая содержит ключ, который подготовила функция openssl_get_publickey().

  Строка с ключом в формате PEM. Примерно такого вида `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

`algorithm`

  Целое число, которое соответствует одному из алгоритмов подписи.

  Строка, которую вернула функция openssl_get_md_methods(), например «sha1WithRSAEncryption» или «sha512».

`padding`
  Схема дополнения PSS (англ. Probabilistic Signature Scheme — вероятностная схема подписи) алгоритма RSA.

### Возвращаемые значения

Функция возвращает 1, если подпись корректная, 0, если нет, и -1 или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `padding`.
8.0.0 | Параметр `public_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL key` или `OpenSSL X.509`.

### Примеры

Пример #1 Пример проверки подписи функцией openssl_verify()

    <?php

    // Переменные $data и $signature содержат данные и подпись

    // Извлекаем открытый ключ из сертификата и подготавливаем его
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // Проверяем, корректна ли подпись
    $ok = openssl_verify($data, $signature, $pubkeyid);

    if ($ok == 1) {
        echo "Подпись корректная";
    } elseif ($ok == 0) {
        echo "Подпись некорректная";
    } else {
        echo "Произошла какая-то ошибка, печаль :(";
    }

    // Высвобождаем ресурсы ключа
    openssl_free_key($pubkeyid);

Пример #2 Пример проверки подписи функцией openssl_verify()

    <?php

    // Данные для генерации подписи
    $data = 'my data';

    // Создаём новую пару открытый и закрытый ключ
    $private_key_res = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    $details = openssl_pkey_get_details($private_key_res);
    $public_key_res = openssl_pkey_get_public($details['key']);

    // Вычисляем подпись
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    // Сверяем подпись
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);

    if ($ok == 1) {
        echo "корректна";
    } elseif ($ok == 0) {
        echo "некорректна";
    } else {
        echo "ошибка: ".openssl_error_string();
    }

### Смотрите также

- openssl_sign() - Генерирует подписи

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — Проверяет, относится ли закрытый ключ к сертификату

### Описание

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

Функция проверяет, что ключ `private_key` — закрытый ключ, который соответствует сертификату `certificate`.

Внимание

Функция не проверяет, закрытый ли ключ `private_key` или нет. Функция просто сравнивает открытые данные (например, экспоненту и модуль ключа RSA) и (или) параметры ключа (например, параметры EC для EC-ключа) пары ключей.

То есть, если передать в параметр `private_key` соответствующий открытый ключ, то функция может вернуть `true`.

### Список параметров

`certificate`

  Сертификат.

`private_key`

  Ключ.

### Возвращаемые значения

Функция возвращает `true`, если закрытый ключ `private_key` — ключ, который соответствует сертификату `certificate`, иначе `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL X.509`.
8.0.0 | Параметр`private_key` теперь принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL key` или `OpenSSL X.509`.

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — Проверяет, можно ли использовать сертификат для конкретных задач

### Описание

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() проверяет сертификат, чтобы узнать, может ли он использоваться с заданной целью `purpose`.

### Список параметров

`certificate`

  Сертификат.

`purpose`

  Цели openssl_x509_checkpurpose()
  Константа | Описание
  --- | ---
  X509_PURPOSE_SSL_CLIENT | Можно ли использовать сертификат для SSL соединения на стороне клиента?
  X509_PURPOSE_SSL_SERVER | Можно ли использовать сертификат для SSL соединения на стороне сервера?
  X509_PURPOSE_NS_SSL_SERVER | Можно ли использовать для сервера Netscape SSL?
  X509_PURPOSE_SMIME_SIGN | Можно ли подписывать S/MIME email?
  X509_PURPOSE_SMIME_ENCRYPT | Можно ли шифровать S/MIME email?
  X509_PURPOSE_CRL_SIGN | Можно ли им подписывать список отзыва сертификатов (CRL)?
  X509_PURPOSE_ANY | Можно ли использовать для любых задач?

  Эти опции не являются бинарной маской - можно использовать только одно значение за раз!
`ca_info`

  `ca_info` должен содержать массив доверенных CA файлов/директорий, как описано на странице проверки сертификатов.

`untrusted_certificates_file`

  Если задано, то должно содержать путь до PEM-файла, содержащего сертификаты, которые могут быть использованы для проверки сертификата, но не являющиеся при этом доверенными.

### Возвращаемые значения

Возвращает `true`, если сертификат можно использовать по указанному назначению, `false` - если нельзя и -1 в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509`.
8.0.0 | `untrusted_certificates_file` теперь допускает значение null.

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — Экспортирует сертификат в строку

### Описание

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() сохраняет сертификат `certificate` в виде PEM строки в `output`.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`output`

  В случае успешного выполнения в этой переменной будет PEM-представление сертификата.

`no_text`
  Необязательный параметр `notext` влияет на детализацию сообщений вывода; если он установлен в `false`, то в вывод добавляется дополнительная человекочитаемая информация. Значением по умолчанию `notext` является `true`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509`.

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — Экспортирует сертификат в файл

### Описание

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() сохраняет сертификат `certificate` в файл `output_filename` в виде строки в формате PEM.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`output_filename`

  Путь к файлу.

`no_text`
  Необязательный параметр `notext` влияет на детализацию сообщений вывода; если он установлен в `false`, то в вывод добавляется дополнительная человекочитаемая информация. Значением по умолчанию `notext` является `true`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509`.

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — Вычисляет отпечаток или дайджест, заданный сертификатом X.509

### Описание

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

openssl_x509_fingerprint() возвращает дайджест `certificate` в виде строки.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`digest_algo`

  Метод хеширования. Список доступных методов можно получить с помощью openssl_get_md_methods().

`binary`

  Если установлено как `true`, будут возвращены необработанные бинарные данные. Если `false`, то выводит строку из шестнадцатеричных чисел в нижнем регистре.

### Возвращаемые значения

Возвращает отпечаток сертификата в виде строки шестнадцатеричных чисел. Если `binary` установлен в `true`, то в виде бинарных данных.

В случае возникновения ошибки возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `certificate` теперь принимает экземпляр OpenSSLCertificate; ранее принимался ресурс (resource) типа `OpenSSL X.509`.

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — Высвобождает ресурс сертификата

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> Замечание: Функция стала бесполезной. До PHP 8.0.0 функция закрывала ресурс.

Функция openssl_x509_free() удаляет сертификат с идентификатором `certificate` из памяти.

### Список параметров

`certificate`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела, поскольку больше ни на что не влияет.
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource), который принадлежит типу `OpenSSL X.509`.

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — Разбирает сертификат X509 и получает массив с данными о нём

### Описание

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

Функция openssl_x509_parse() возвращает информацию о сертификате с идентификатором `certificate`, включая такие поля, как имя субъекта, имя издателя, назначение, даты начала и окончания действия и т. д.

### Список параметров

`certificate`

  Сертификат X509. Список корректных значений даёт Параметры ключа или сертификата.

`short_names`

  Параметр `short_names` определяет, как будут индексироваться данные в итоговом массиве. Если для параметра `short_names` задать значение `true` (по умолчанию), поля будут индексироваться короткими именами, а не длинными. Например, CN — это короткое имя для commonName.

### Возвращаемые значения

Структура возвращаемого массива ещё не до конца устоялась, поэтому пока не документируется.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Разбор сертификата без секунд в UTCTime больше не допускается ни для одной версии OpenSSL. Это уже было запрещено в OpenSSL 3.3+.
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL X.509`.

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — Разбирает сертификат X.509 и возвращает для него объект

### Описание

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

Функция openssl_x509_read() извлекает сертификат из параметра `certificate` и возвращает объект класса OpenSSLCertificate для него.

### Список параметров

`certificate`

  Сертификат X509. Список корректных значений даёт страница Параметры ключей и сертификатов.

### Возвращаемые значения

Функция возвращает объект класса OpenSSLCertificate в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

Если получить сертификат X.509 не удалось, выбрасывается ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр класса OpenSSLCertificate; раньше возвращался ресурс (resource) с типом `OpenSSL X.509`.
8.0.0 | Параметр `certificate` теперь принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL X.509`.

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Проверяет цифровую подпись сертификата x509 публичным ключом

### Описание

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

Функция openssl_x509_verify() проверяет, подписан ли сертификат `certificate` закрытым ключом, который соответствует публичному ключу `public_key`.

### Список параметров

`certificate`
  Для списка корректных значений смотрите Параметры ключей или сертификатов.
`public_key`

  Экземпляр класса OpenSSLAsymmetricKey — ключ, который вернула функция openssl_get_publickey().

  Строка (string) — ключ в формате PEM вида: `-----BEGIN PUBLIC KEY----- MIIBCgK...`.

### Возвращаемые значения

Функция возвращает 1, если подпись корректна, 0, если нет, и -1, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь параметр `certificate` принимает экземпляр класса OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL X.509`.
8.0.0 | Теперь параметр `public_key` принимает экземпляр класса OpenSSLAsymmetricKey или OpenSSLCertificate; раньше принимался ресурс (resource) с типом `OpenSSL key` или `OpenSSL X.509`.

### Примеры

Пример #1 Пример использования функции openssl_x509_verify()

    <?php

    $hostname = "news.php.net";

    $ssloptions = array(
        "capture_peer_cert" => true,
        "capture_peer_cert_chain" => true,
        "allow_self_signed"=> false,
        "CN_match" => $hostname,
        "verify_peer" => true,
        "SNI_enabled" => true,
        "SNI_server_name" => $hostname,
    );

    $ctx = stream_context_create( array("ssl" => $ssloptions) );
    $result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
    $cont = stream_context_get_params($result);
    $x509 = $cont["options"]["ssl"]["peer_certificate"];
    $certparsed = openssl_x509_parse($x509);

    foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
    {
        $chainparsed = openssl_x509_parse($chaincert);
        $chain_public_key = openssl_get_publickey($chaincert);
        $r = openssl_x509_verify($x509, $chain_public_key);
        if ($r==1) {
            echo $certparsed['subject']['CN'];
            echo " was digitally signed by ";
            echo $chainparsed['subject']['CN']."\n";
        }
    }

    ?>

### Смотрите также

- openssl_verify() - Проверяет подпись
- openssl_get_publickey() - Псевдоним openssl_pkey_get_public

## Содержание

- openssl_cipher_iv_length — Получает длину инициализирующего вектора шифра
- openssl_cipher_key_length — Получает длину ключа шифрования
- openssl_cms_decrypt — Расшифровывает CMS-сообщение
- openssl_cms_encrypt — Зашифровывает CMS-сообщение
- openssl_cms_read — Экспортирует файл CMS в массив сертификатов PEM
- openssl_cms_sign — Подписывает файл
- openssl_cms_verify — Проверяет подпись CMS
- openssl_csr_export — Экспортирует CSR в виде строки
- openssl_csr_export_to_file — Экспортирует CSR в файл
- openssl_csr_get_public_key — Возвращает открытый ключ CSR
- openssl_csr_get_subject — Возвращает субъект CSR
- openssl_csr_new — Генерирует CSR
- openssl_csr_sign — Подписывает CSR через другой сертификат (или им же) и создаёт сертификат
- openssl_decrypt — Расшифровывает данные
- openssl_dh_compute_key — Вычисляет общий секретный ключ для значения удалённого открытого ключа DH и локального ключа DH
- openssl_digest — Вычисляет дайджест
- openssl_encrypt — Шифрует данные
- openssl_error_string — Возвращает сообщение об ошибке openSSL
- openssl_free_key — Высвобождает ресурс ключа
- openssl_get_cert_locations — Получает доступные месторасположения сертификатов
- openssl_get_cipher_methods — Получает список доступных алгоритмов шифрования
- openssl_get_curve_names — Получает список доступных имён кривых для ECC-шифрования
- openssl_get_md_methods — Получает список доступных методов хеширования
- openssl_get_privatekey — Псевдоним openssl_pkey_get_private
- openssl_get_publickey — Псевдоним openssl_pkey_get_public
- openssl_open — Открывает запечатанные данные
- openssl_password_hash — Создаёт хеш пароля при помощи Argon2 из OpenSSL
- openssl_password_verify — Проверяет соответствие пароля хешу при помощи Argon2 из OpenSSL
- openssl_pbkdf2 — Генерирует строки PKCS5 v2 PBKDF2
- openssl_pkcs12_export — Экспортирует совместимый с PKCS#12 файл хранилища сертификатов в переменную
- openssl_pkcs12_export_to_file — Экспортирует в совместимый с PKCS#12 файл хранилища сертификатов
- openssl_pkcs12_read — Разбирает хранилище сертификатов PKCS#12 в массив
- openssl_pkcs7_decrypt — Расшифровывает S/MIME-сообщение
- openssl_pkcs7_encrypt — Шифрует сообщение по стандарту S/MIME
- openssl_pkcs7_read — Экспортирует PKCS7-файл в массив PEM-сертификатов
- openssl_pkcs7_sign — Подписывает сообщение S/MIME
- openssl_pkcs7_verify — Проверяет подпись S/MIME-сообщения
- openssl_pkey_derive — Вычисляет общий секрет для открытого значения удалённого и локального ключа DH или ECDH
- openssl_pkey_export — Получает строку с ключом в формате PEM
- openssl_pkey_export_to_file — Записывает в файл ключ в формате PEM
- openssl_pkey_free — Освобождает ресурс закрытого ключа
- openssl_pkey_get_details — Получает массив с детальной информацией о ключе
- openssl_pkey_get_private — Получает закрытый ключ
- openssl_pkey_get_public — Извлекает открытый ключ из сертификата и подготавливает его к использованию
- openssl_pkey_new — Генерирует новый закрытый ключ
- openssl_private_decrypt — Расшифровывает данные закрытым ключом
- openssl_private_encrypt — Шифрует данные секретным ключом
- openssl_public_decrypt — Расшифровывает данные открытым ключом
- openssl_public_encrypt — Шифрует данные открытым ключом
- openssl_random_pseudo_bytes — Генерирует псевдослучайную последовательность байт
- openssl_seal — Запечатывает, или зашифровывает, данные
- openssl_sign — Генерирует подписи
- openssl_spki_export — Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом
- openssl_spki_export_challenge — Экспортирует вызов, который связан с подписанным ключом и вызовом
- openssl_spki_new — Создаёт подписанный открытый ключ с вызовом
- openssl_spki_verify — Проверяет подписанный открытый ключ и вызов
- openssl_verify — Проверяет подпись
- openssl_x509_check_private_key — Проверяет, относится ли закрытый ключ к сертификату
- openssl_x509_checkpurpose — Проверяет, можно ли использовать сертификат для конкретных задач
- openssl_x509_export — Экспортирует сертификат в строку
- openssl_x509_export_to_file — Экспортирует сертификат в файл
- openssl_x509_fingerprint — Вычисляет отпечаток или дайджест, заданный сертификатом X.509
- openssl_x509_free — Высвобождает ресурс сертификата
- openssl_x509_parse — Разбирает сертификат X509 и получает массив с данными о нём
- openssl_x509_read — Разбирает сертификат X.509 и возвращает для него объект
- openssl_x509_verify — Проверяет цифровую подпись сертификата x509 публичным ключом

# Класс OpenSSLCertificate

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `OpenSSL X.509` в PHP 8.0.0.

## Обзор класса

final class OpenSSLCertificate {
}

# Класс OpenSSLCertificateSigningRequest

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `OpenSSL X.509 CSR` в PHP 8.0.0.

## Обзор класса

final class OpenSSLCertificateSigningRequest {
}

# Класс OpenSSLAsymmetricKey

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `OpenSSL key` в PHP 8.0.0.

## Обзор класса

final class OpenSSLAsymmetricKey {
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
  - Флаги проверки
  - Флаги заполнения для ассиметричного шифрования
  - Типы ключей
  - Константы-флаги структур PKCS7
  - Константы-флаги стуктур CMS
  - Алгоритмы подписи
  - Алгоритмы шифрования
  - Константы версий
  - Константа SNI (Server Name Indication)
  - Другие константы
- Параметры ключа и сертификата
- Проверка сертификата
- Функции OpenSSL
  - openssl_cipher_iv_length — Получает длину инициализирующего вектора шифра
  - openssl_cipher_key_length — Получает длину ключа шифрования
  - openssl_cms_decrypt — Расшифровывает CMS-сообщение
  - openssl_cms_encrypt — Зашифровывает CMS-сообщение
  - openssl_cms_read — Экспортирует файл CMS в массив сертификатов PEM
  - openssl_cms_sign — Подписывает файл
  - openssl_cms_verify — Проверяет подпись CMS
  - openssl_csr_export — Экспортирует CSR в виде строки
  - openssl_csr_export_to_file — Экспортирует CSR в файл
  - openssl_csr_get_public_key — Возвращает открытый ключ CSR
  - openssl_csr_get_subject — Возвращает субъект CSR
  - openssl_csr_new — Генерирует CSR
  - openssl_csr_sign — Подписывает CSR через другой сертификат (или им же) и создаёт сертификат
  - openssl_decrypt — Расшифровывает данные
  - openssl_dh_compute_key — Вычисляет общий секретный ключ для значения удалённого открытого ключа DH и локального ключа DH
  - openssl_digest — Вычисляет дайджест
  - openssl_encrypt — Шифрует данные
  - openssl_error_string — Возвращает сообщение об ошибке openSSL
  - openssl_free_key — Высвобождает ресурс ключа
  - openssl_get_cert_locations — Получает доступные месторасположения сертификатов
  - openssl_get_cipher_methods — Получает список доступных алгоритмов шифрования
  - openssl_get_curve_names — Получает список доступных имён кривых для ECC-шифрования
  - openssl_get_md_methods — Получает список доступных методов хеширования
  - openssl_get_privatekey — Псевдоним openssl_pkey_get_private
  - openssl_get_publickey — Псевдоним openssl_pkey_get_public
  - openssl_open — Открывает запечатанные данные
  - openssl_password_hash — Создаёт хеш пароля при помощи Argon2 из OpenSSL
  - openssl_password_verify — Проверяет соответствие пароля хешу при помощи Argon2 из OpenSSL
  - openssl_pbkdf2 — Генерирует строки PKCS5 v2 PBKDF2
  - openssl_pkcs12_export — Экспортирует совместимый с PKCS#12 файл хранилища сертификатов в переменную
  - openssl_pkcs12_export_to_file — Экспортирует в совместимый с PKCS#12 файл хранилища сертификатов
  - openssl_pkcs12_read — Разбирает хранилище сертификатов PKCS#12 в массив
  - openssl_pkcs7_decrypt — Расшифровывает S/MIME-сообщение
  - openssl_pkcs7_encrypt — Шифрует сообщение по стандарту S/MIME
  - openssl_pkcs7_read — Экспортирует PKCS7-файл в массив PEM-сертификатов
  - openssl_pkcs7_sign — Подписывает сообщение S/MIME
  - openssl_pkcs7_verify — Проверяет подпись S/MIME-сообщения
  - openssl_pkey_derive — Вычисляет общий секрет для открытого значения удалённого и локального ключа DH или ECDH
  - openssl_pkey_export — Получает строку с ключом в формате PEM
  - openssl_pkey_export_to_file — Записывает в файл ключ в формате PEM
  - openssl_pkey_free — Освобождает ресурс закрытого ключа
  - openssl_pkey_get_details — Получает массив с детальной информацией о ключе
  - openssl_pkey_get_private — Получает закрытый ключ
  - openssl_pkey_get_public — Извлекает открытый ключ из сертификата и подготавливает его к использованию
  - openssl_pkey_new — Генерирует новый закрытый ключ
  - openssl_private_decrypt — Расшифровывает данные закрытым ключом
  - openssl_private_encrypt — Шифрует данные секретным ключом
  - openssl_public_decrypt — Расшифровывает данные открытым ключом
  - openssl_public_encrypt — Шифрует данные открытым ключом
  - openssl_random_pseudo_bytes — Генерирует псевдослучайную последовательность байт
  - openssl_seal — Запечатывает, или зашифровывает, данные
  - openssl_sign — Генерирует подписи
  - openssl_spki_export — Экспортирует открытый ключ в формате PEM из подписанного открытого ключа с вызовом
  - openssl_spki_export_challenge — Экспортирует вызов, который связан с подписанным ключом и вызовом
  - openssl_spki_new — Создаёт подписанный открытый ключ с вызовом
  - openssl_spki_verify — Проверяет подписанный открытый ключ и вызов
  - openssl_verify — Проверяет подпись
  - openssl_x509_check_private_key — Проверяет, относится ли закрытый ключ к сертификату
  - openssl_x509_checkpurpose — Проверяет, можно ли использовать сертификат для конкретных задач
  - openssl_x509_export — Экспортирует сертификат в строку
  - openssl_x509_export_to_file — Экспортирует сертификат в файл
  - openssl_x509_fingerprint — Вычисляет отпечаток или дайджест, заданный сертификатом X.509
  - openssl_x509_free — Высвобождает ресурс сертификата
  - openssl_x509_parse — Разбирает сертификат X509 и получает массив с данными о нём
  - openssl_x509_read — Разбирает сертификат X.509 и возвращает для него объект
  - openssl_x509_verify — Проверяет цифровую подпись сертификата x509 публичным ключом
- OpenSSLCertificate — Класс OpenSSLCertificate
- OpenSSLCertificateSigningRequest — Класс OpenSSLCertificateSigningRequest
- OpenSSLAsymmetricKey — Класс OpenSSLAsymmetricKey

# Хеширование паролей

# Введение

API хеширования паролей предоставляет простую в использовании обёртку функции crypt() и некоторых других алгоритмов хеширования пароля для лёгкого создания и управления паролями.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Модуль не требует внешних библиотек.

Для хеширования паролей алгоритмом Argon2 требуется библиотека » libargon2 или начиная с PHP 8.4.0 библиотека OpenSSL версии 3.2 или новее. Начиная с PHP 7.3.0 требуется библиотека libargon2 версии 20161029 или выше.

## Установка

Функции работают без установки, поскольку составляют часть PHP-ядра.

Но чтобы включить хеширование паролей алгоритмом Argon2 для поддержки модуля libargon2, потребуется собрать PHP с параметром конфигурации --with-password-argon2 или начиная с PHP 8.4.0 для поддержки модуля OpenSSL — с параметрами --with-openssl и --with-openssl-argon2.

До PHP 8.1.0 разрешали указывать каталог argon2 командой --with-password-argon2[=DIR].

# Предопределённые константы

Следующие константы доступны как часть ядра PHP.

`PASSWORD_BCRYPT` (string)

  Константа `PASSWORD_BCRYPT` помогает создавать новые хеши паролей по алгоритму `CRYPT_BLOWFISH`.

  Константа выдаёт хеши в формате шифрования "$2y$" длиной 60 символов.

  Константа поддерживает следующие опции:

  - `salt` (string) — ручное значение соли для хеширования пароля. Обратите внимание, значение переопределит и предотвратит автоматическую генерацию соли.

    При пропуске параметра функция password_hash() сгенерирует случайную соль для каждого пароля. Это предпочтительный способ, а с PHP 7.0.0 опцию salt объявили устаревшей.

  - `cost` (int) — алгоритмическая стоимость генерации хеша. Примеры этих значений приводит страница с описанием функции crypt().

    При пропуске параметра функция возьмёт значение по умолчанию — `12`. Это безопасная базовая стоимость, но на производительном оборудовании значение часто увеличивают.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  Константа `PASSWORD_ARGON2I` помогает создавать новые хеши паролей по алгоритму Argon2i.

  Константа поддерживает следующие опции:

  - `memory_cost` (int) - максимальный размер памяти в кибибайтах для вычисления хеша Argon2. Значение по умолчанию равняется `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) — максимальное время, которое функции разрешается потратить на вычисление хеша Argon2. Значение по умолчанию равняется `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) — количество потоков для вычисления хеша Argon2. Значение по умолчанию равняется `PASSWORD_ARGON2_DEFAULT_THREADS`. Константа доступна только с модулем libargon2, но не с реализацией через библиотеку libsodium.

  Константа доступна с PHP 7.2.0.

`PASSWORD_ARGON2ID` (string)

  Константа `PASSWORD_ARGON2ID` помогает создавать хеши паролей по алгоритму Argon2id. Поддерживаются те же опции, что и для константы `PASSWORD_ARGON2I`.

  Константа доступна с PHP 7.3.0.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (тип int)

  Объем памяти по умолчанию в байтах, который функция использует при попытке вычислить хеш.

  Константа доступна с PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Ограничение времени по умолчанию на вычисление хеша.

  Константа доступна с PHP 7.2.0.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Количество потоков по умолчанию для библиотеки Argon2lib. Константа недоступна с реализацией через библиотеку libsodium.

  Доступно с PHP 7.2.0.

`PASSWORD_ARGON2_PROVIDER` (string)

  Константа доступна с PHP 7.4.0.

`PASSWORD_DEFAULT` (string)

  Алгоритм хеширования по умолчанию, если другой алгоритм не указали принудительно. Стандартный алгоритм изменится в новых выпусках PHP, когда в язык включат поддержку новых усиленных алгоритмов хеширования.

  Из-за вероятного изменения значения константы в будущем изменится и длина результирующего хеша. Поэтому хеши, которые получили через константу `PASSWORD_DEFAULT`, лучше хранить так, чтобы сохранялись хеши произвольной длины. Ширину поля для хранения хешей рекомендуют устанавливать равной `255` байтам.

  Эта константа — псевдоним константы `PASSWORD_BCRYPT`.

##### Список изменений

Версия | Описание
--- | ---
7.4.0 | Значения идентификаторов алгоритма пароля — `PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` и `PASSWORD_DEFAULT` — стали значениями с типом string. Раньше значения принадлежали типу int.

# Функции хеширования паролей

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Получает доступные идентификаторы алгоритма хеширования пароля

### Описание

function password_algos(): array

Функция возвращает полный список зарегистрированных идентификаторов алгоритма хеширования паролей в виде массива (array) строк (string).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает доступные идентификаторы алгоритма хеширования пароля.

### Примеры

Пример #1 Пример использования функции password_algos()

    <?php

    print_r(password_algos());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — Возвращает информацию о заданном хеше

### Описание

function password_get_info(string `$hash`): array

Если передан корректный хеш, созданный поддерживаемым password_hash() алгоритмом, то эта функция вернёт информацию об этом хеше.

### Список параметров

`hash`

  Хеш, который создаёт функция password_hash().

### Возвращаемые значения

Возвращает ассоциативный массив с тремя элементами:

- `algo`, содержащий одну из констант алгоритмов паролей
- `algoName`, содержащий имя алгоритма в человекочитаемом виде
- `options`, включающий опции, переданные при вызове password_hash()

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Создаёт хеш пароля

### Описание

function password_hash(#[\SensitiveParameter]string `$password`, string|int|null `$algo`, array `$options` = []): string

Функция password_hash() создаёт хеш пароля через сильный необратимый алгоритм хеширования.

Поддерживаются следующие алгоритмы:

- `PASSWORD_DEFAULT` — алгоритм хеширования bcrypt. С PHP 5.5.0 bcrypt стал алгоритмом по умолчанию. По мере добавления в PHP новых усиленных алгоритмов значение константы изменяется и задаёт новый идентификатор алгоритма. При изменении алгоритма длина результата изменяется, часто увеличивается. Поэтому сохранять результат в базе данных лучше в столбце длиной больше 60 байтов. Длину поля устанавливают равной 255 байтам, чтобы сократить риск ошибок.
- `PASSWORD_BCRYPT` — алгоритм хеширования bcrypt. С этой константой функция генерирует стандартный хеш с идентификатором `$2y$`, совместимый с хешем, который создаёт функция crypt().
- `PASSWORD_ARGON2I` — алгоритм хеширования Argon2i. Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.
- `PASSWORD_ARGON2ID` — алгоритм хеширования Argon2id. Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.

Алгоритм `PASSWORD_BCRYPT` поддерживает следующие опции:

- `salt` (string) — пользовательская соль для хеширования пароля. Ручная установка соли переопределит поведение функции — предотвратит автоматическую генерацию соли.

  При пропуске параметра функция password_hash() сгенерирует случайную соль для каждого хешируемого пароля. Это предпочтительный режим работы.

  Внимание

  Опция salt устарела в пользу соли по умолчанию, которую функция генерирует автоматически. Начиная с PHP 8.0.0 функция игнорирует пользовательскую соль.

- `cost` (int) — алгоритмическая сложность. Пример работы с опцией доступен на странице с описанием функции crypt().

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

Алгоритмы `PASSWORD_ARGON2I` и `PASSWORD_ARGON2ID` поддерживают следующие опции:

- `memory_cost` (int) — максимальный размер памяти в килобайтах для вычисления хеша Argon2. По умолчанию функция выбирает значение константы `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

- `time_cost` (int) — предельное количество раундов, которые выполняет алгоритм Argon2 для вычисления хеша. Значение по умолчанию: `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

- `threads` (int) — количество потоков для вычисления хеша алгоритмом Argon2. Значение по умолчанию: `PASSWORD_ARGON2_DEFAULT_THREADS`.

  Внимание

  Опция доступна, только если PHP собрали с библиотекой libargon2, а не с libsodium.

### Список параметров

`password`

  Пользовательский пароль.

  Предостережение

  При хешировании пароля алгоритмом `PASSWORD_BCRYPT` значение аргумента `password` усекается до предельной длины — 72 байтов.

`algo`

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

`options`

  Ассоциативный массив с опциями. За документацией по поддерживаемым опциям для каждого алгоритма обратитесь к разделу Константы алгоритмов хеширования паролей.

### Возвращаемые значения

Функция возвращает хешированный пароль.

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

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Значение по умолчанию для опции `cost` алгоритма `PASSWORD_BCRYPT` увеличили с `10` до `12`.
8.3.0 | Функция password_hash() теперь устанавливает базовое исключение Random\RandomException в качестве значения свойства Exception::$previous, если выбрасывается ошибка ValueError из-за сбоя во время генерации соли.
8.0.0 | Функция password_hash() больше не возвращает значение `false`, если возникла ошибка. Вместо этого функция выбросит ошибку ValueError, если алгоритм хеширования пароля недействителен, или ошибку Error, если не получилось захешировать пароль из-за неизвестной ошибки.
8.0.0 | Параметр `algo` теперь принимает значение `null`.
7.4.0 | Параметр `algo` теперь ожидает строку (string), но всё ещё принимает целое число (int) для обратной совместимости.
7.4.0 | Модуль sodium обеспечивает альтернативную реализацию паролей Argon2.
7.3.0 | Ввели константу `PASSWORD_ARGON2ID`, которая добавила поддержку алгоритма хеширования паролей алгоритмом Argon2id.
7.2.0 | Ввели константу `PASSWORD_ARGON2I`, которая добавила поддержку хеширования паролей алгоритмом Argon2i.

### Примеры

Пример #1 Пример хеширования пароля функцией password_hash()

    <?php

    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

    ?>

Вывод приведённого примера будет похож на:

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Пример #2 Пример генерации хеша функцией password_hash() установкой алгоритмической сложности вручную

    <?php

    $options = [
         // Увеличиваем алгоритмическую сложность алгоритма bcrypt с 12 до 13
        'cost' => 13,
    ];

    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);

    ?>

Вывод приведённого примера будет похож на:

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Пример #3 Пример поиска оптимума показателя алгоритмической сложности для функции password_hash()

Код протестирует машину и определит показатель вычислительной сложности, с которым функция сгенерирует стойкий хеш, но не испортит пользовательский опыт и не замедлит другие операции, которые выполняет машина. Тестирование начинают с базового значения 11 и увеличивают показатель, если машина не замедляет работу под нагрузкой. Код ищет максимум, при котором хеширование не превышает 350 миллисекунд — допустимая задержка для систем авторизации пользователей.

    <?php

    $timeTarget = 0.350; // 350 миллисекунд

    $cost = 11;

    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Оптимальная стоимость: " . $cost - 1;

    ?>

Вывод приведённого примера будет похож на:

    Оптимальная стоимость: 13

Пример #4 Пример генерации хеша функцией password_hash() алгоритмом Argon2i

    <?php

    echo 'Хеш Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

    ?>

Вывод приведённого примера будет похож на:

    Хеш Argon2i: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### Примечания

Предостережение

Функция автоматически создаст безопасную соль, поэтому разработчики PHP настоятельно рекомендуют не указывать опцию salt вручную.

В PHP 7.0.0 установка значения опции `salt` вручную сгенерирует предупреждение об устаревании. В PHP 8.0.0 установку пользовательской соли удалили.

> Замечание:

> Работу функции тестируют на конкретной машине и подстраивают параметры вычислительной сложности до значений, с которыми при авторизации пользователей функция выполняется не дольше 350 миллисекунд. Скрипт в предыдущем примере помогает определить оптимум алгоритмической сложности для алгоритма bcrypt.

> Замечание: Обновление алгоритмов, которые поддерживает функция, или изменение алгоритма по умолчанию подчиняется следующим правилам:

> - С момента включения нового алгоритма в ядро до установки по умолчанию прошёл 1 полный выпуск PHP. Алгоритм, который ввели в версии 7.5.5, получит право стать алгоритмом по умолчанию только в версии 7.7, поскольку версия 7.6 станет первым полным выпуском. Но и другой алгоритм, который добавили бы в версии 7.6.0, тоже получил бы право стать алгоритмом по умолчанию в версии 7.7.0.
> - Алгоритм по умолчанию изменяется только в полном выпуске, например, 7.3.0 или 8.0.0, но не в промежуточных. Единственное исключение — критическая уязвимость безопасности, которую обнаружили в текущем алгоритме по умолчанию.

### Смотрите также

- password_verify() - Проверяет, соответствует ли пароль хешу
- password_needs_rehash() - Проверяет, что указанный хеш соответствует заданным опциям
- crypt() - Хеширует строку необратимым способом
- sodium_crypto_pwhash_str() - Получает ASCII-кодированный хеш

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — Проверяет, что указанный хеш соответствует заданным опциям

### Описание

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

Проверяет, что указанный хеш соответствует заданным опциям и заданному алгоритму. Если нет, то можно сделать вывод о том, что хеш надо пересоздать.

### Список параметров

`hash`

  Хеш, который создаёт функция password_hash().

`algo`

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

`options`

  Ассоциативный массив с опциями. За документацией по поддерживаемым опциям для каждого алгоритма обратитесь к разделу Константы алгоритмов хеширования паролей.

### Возвращаемые значения

Возвращает `true`, если пароль должен быть перехеширован с использованием алгоритма `algo` и опций `options`, или `false`, если нет.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Параметр `algo` теперь ожидает строку (string), но всё ещё принимает число (int) для обратной совместимости.

### Примеры

Пример #1 Пример использования password_needs_rehash()

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // Значение bcrypt-стоимости может измениться по мере роста производительности оборудования
    $options = ['cost' => 13];

    // Сравниваем сохранённый хеш с открытым паролем
    if (password_verify($password, $hash)) {
        // Проверяем, не изменился ли алгоритм или параметры
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // Если были изменения, перехешируем и заменяем старый хеш новым
            $newHash = password_hash($password, $algorithm, $options);

            // Обновляем запись пользователя новым $newHash
        }

        // Авторизуем пользователя
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — Проверяет, соответствует ли пароль хешу

### Описание

function password_verify(#[\SensitiveParameter]string `$password`, string `$hash`): bool

Функция проверяет, соответствует ли пароль хешу. Функция password_verify() совместима с функцией crypt(). Следовательно, хеши паролей, созданные crypt(), могут быть использованы в password_verify().

Обратите внимание, что password_hash() возвращает алгоритм, стоимость и соль как части хеша. Таким образом, вся необходимая для проверки информация включена в него. Это позволяет производить проверку без необходимости хранить все эти данные раздельно.

Эта функция безопасна для атак по времени.

### Список параметров

`password`

  Пользовательский пароль.

`hash`

  Хеш, который создаёт функция password_hash().

### Возвращаемые значения

Функция возвращает `true` или `false`, в зависимости от результатов проверки.

### Примеры

Пример #1 Пример использования функции password_verify()

Это упрощённый пример; при необходимости рекомендуется пересоздать правильный пароль; смотрите пример в описании функции password_needs_rehash().

    <?php

    // Смотрите примеры в описании функции password_hash(), чтобы понять, откуда это взялось.
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'Пароль правильный!';
    } else {
        echo 'Пароль неправильный.';
    }

    ?>

Результат выполнения приведённого примера:

    Пароль правильный!

### Смотрите также

- password_needs_rehash() - Проверяет, что указанный хеш соответствует заданным опциям
- password_hash() - Создаёт хеш пароля
- sodium_crypto_pwhash_str_verify() - Проверяет соответствие пароля хешу

## Содержание

- password_algos — Получает доступные идентификаторы алгоритма хеширования пароля
- password_get_info — Возвращает информацию о заданном хеше
- password_hash — Создаёт хеш пароля
- password_needs_rehash — Проверяет, что указанный хеш соответствует заданным опциям
- password_verify — Проверяет, соответствует ли пароль хешу

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Функции хеширования паролей
  - password_algos — Получает доступные идентификаторы алгоритма хеширования пароля
  - password_get_info — Возвращает информацию о заданном хеше
  - password_hash — Создаёт хеш пароля
  - password_needs_rehash — Проверяет, что указанный хеш соответствует заданным опциям
  - password_verify — Проверяет, соответствует ли пароль хешу

# Rnp

# Введение

Внимание

Модуль добавили как ЭКСПЕРИМЕНТАЛЬНЫЙ. Поведение модуля, названия функций и документацию к модулю изменяют в новых выпусках PHP без уведомления. Модулем пользуются на свой страх и риск.

Модуль открывает доступ к библиотеке » RNP. RNP — высокопроизводительная библиотека OpenPGP на языке программирования C++, с которой работает почтовый клиент Mozilla Thunderbird.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Чтобы использовать функции модуля RNP, необходимо установить » библиотеку RNP. Модулю требуется библиотека RNP >= 0.16.2.

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/rnp

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`RNP_KEYSTORE_GPG` (string)
  Формат хранилища ключей "GPG".
`RNP_KEYSTORE_KBX` (string)
  Формат хранилища ключей "KBX". Только для открытых ключей. Хранилище ключей - это формат файла, используемый для хранения открытых ключей вместе с метаинформацией и индексами.
`RNP_KEYSTORE_G10` (string)
  Формат хранилища ключей "G10". Для закрытых ключей.
`RNP_LOAD_SAVE_PUBLIC_KEYS` (integer)
  Загрузка или сохранение только открытых ключей. Может быть ИЛИ с константой `RNP_LOAD_SAVE_SECRET_KEYS` для загрузки открытых и закрытых ключей в контекст FFI или сохранения их из контекста.
`RNP_LOAD_SAVE_SECRET_KEYS` (integer)
  Загрузка или сохранение только секретных ключей. Может быть ИЛИ с константой `RNP_LOAD_SAVE_PUBLIC_KEYS` для загрузки открытых и закрытых ключей в контекст FFI или сохранения их из контекста.
`RNP_LOAD_SAVE_PERMISSIVE` (integer)
  Позволяет игнорировать пакеты плохих подписей/ключей/дочерних ключей при импорте ключей.
`RNP_LOAD_SAVE_SINGLE` (integer)
  Если установлено, будет загружен только первый ключ.
`RNP_LOAD_SAVE_BASE64` (integer)
  Разрешить импорт base64-кодированных ключей (autocrypt).
`RNP_FEATURE_SYMM_ALG` (string)
  Список доступных алгоритмов симметричного шифрования.
`RNP_FEATURE_AEAD_ALG` (string)
  Список доступных алгоритмов AEAD.
`RNP_FEATURE_PROT_MODE` (string)
  Список доступных режимов защиты.
`RNP_FEATURE_PK_ALG` (string)
  Список доступных алгоритмов открытых ключей.
`RNP_FEATURE_HASH_ALG` (string)
  Список доступных хеш-алгоритмов.
`RNP_FEATURE_COMP_ALG` (string)
  Список доступных алгоритмов сжатия.
`RNP_FEATURE_CURVE` (string)
  Список доступных эллиптических кривых.
`RNP_DUMP_MPI` (integer)
  Выгрузка значений MPI (многоточечных целых чисел).
`RNP_DUMP_RAW` (integer)
  Выгрузка содержимого необработанного пакета.
`RNP_DUMP_GRIP` (integer)
  Выгрузка цифрового отпечатка и захватов клавиш.
`RNP_JSON_DUMP_MPI` (integer)
  Выгрузка значений MPI (многоточечных целых чисел).
`RNP_JSON_DUMP_RAW` (integer)
  Выгрузка содержимого необработанного пакета.
`RNP_JSON_DUMP_GRIP` (integer)
  Выгрузка цифровых отпечатков пальцев и захватов клавиш.
`RNP_ENCRYPT_NOWRAP` (integer)
  Позволяет зашифровать подписанное сообщение. Сообщение не заворачивается в строчный пакет данных.
`RNP_KEY_EXPORT_ARMORED` (integer)
  Включение ASCII-преобразования экспортируемых данных.
`RNP_KEY_EXPORT_PUBLIC` (integer)
  Экспорт открытого ключа.
`RNP_KEY_EXPORT_SECRET` (integer)
  Экспорт закрытого ключа.
`RNP_KEY_EXPORT_SUBKEYS` (integer)
  Если экспортируется первичный ключ, все дочерние ключи также будут экспортированы.
`RNP_KEY_EXPORT_BASE64` (integer)
  Экспорт ключа автоматического шифрования в base64-кодировке вместо двоичной.
`RNP_KEY_REMOVE_PUBLIC` (integer)
  Удаление открытого ключа.
`RNP_KEY_REMOVE_SECRET` (integer)
  Удаление закрытого ключа.
`RNP_KEY_REMOVE_SUBKEYS` (integer)
  Если удаляется первичный ключ, все его дочерние ключи также будут удалены.

# Примеры

## Содержание

- Подписание текста

## Подписание текста

В данном примере будет подписание заданного текста.

Пример #1 Пример расчёта RNP

    <?php
    // Инициализация объекта FFI
    $ffi = rnp_ffi_create('GPG', 'GPG');

    // Генерация ключа RSA
    $key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

    // Подписание
    $data = "Пример текста для подписи";
    $signature = rnp_op_sign_cleartext($ffi, $data, array($key));

    echo $signature;

    // Уничтожение объекта FFI
    rnp_ffi_destroy($ffi);
    ?>

# Функции Rnp

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Возвращает имя библиотеки криптографического бэкенда

### Описание

function rnp_backend_string(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Строка имени бэкенда. В настоящее время поддерживаются следующие: "Botan" и "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Возвращает версию криптографической библиотеки бэкенда

### Описание

function rnp_backend_version(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает версию в виде строки.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Расшифровывает сообщение PGP

### Описание

function rnp_decrypt(RnpFFI `$ffi`, string `$input`): string|false

Закрытые ключи, используемые для расшифровки, должны быть загружены в объект FFI перед вызовом функции. Если использовалось шифрование паролем, то провайдер пароля должен быть установлен вызовом функции rnp_ffi_set_pass_provider().

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`input`
  Зашифрованное сообщение.

### Возвращаемые значения

Расшифрованное сообщение в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Выгружает информацию о потоке пакетов OpenPGP в человеко-читаемом формате

### Описание

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### Список параметров

`input`
  Входная строка, содержащая данные OpenPGP в двоичном или ASCII-закодированном формате.
`flags`
  Смотрите предопределённые константы `RNP_DUMP_*`.

### Возвращаемые значения

Текст, описывающий последовательность пакетов или `false`, если возникла ошибка.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Выгрузка информации о потоке пакетов OpenPGP в строку JSON

### Описание

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### Список параметров

`input`
  Входная строка, содержащая данные OpenPGP в двоичном или ASCII-закодированном формате.
`flags`
  Смотрите предопределённые константы `RNP_JSON_DUMP_*`.

### Возвращаемые значения

Строка JSON с выводом или `false`, если возникла ошибка.

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Создаёт объект верхнего уровня, используемый для взаимодействия с библиотекой

### Описание

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### Список параметров

`pub_format`
  Формат открытого ключа, RNP_KEYSTORE_GPG или другая константа RNP_KEYSTORE_*.
`sec_format`
  Формат закрытого ключа, RNP_KEYSTORE_GPG или другая константа RNP_KEYSTORE_*.

### Возвращаемые значения

Возвращает объект RnpFFI в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Уничтожает объект верхнего уровня, используемый для взаимодействия с библиотекой

### Описание

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().

### Возвращаемые значения

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Устанавливает callback-функцию поставщика паролей

### Описание

function rnp_ffi_set_pass_provider(RnpFFI `$ffi`, callable `$password_callback`): bool

Устанавливает callback-функцию поставщика пароля. Функция может запрашивать пароль на стандартном входе (если PHP скрипт выполняется в среде командной строки), отображать диалог GUI или предоставлять пароль любым другим возможным способом. Запрашиваемые пароли используются для шифрования или расшифровки секретных ключей или выполнения операций симметричного шифрования/дешифрования.

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`password_callback`

  Функция, которая будет вызываться для каждого запроса пароля. У неё следующая сигнатура:

  function password_callback(string `$key_fp`, string `$pgp_context`, string `&$password`): bool
  - `$key_fp` - Цифровой отпечаток, если таковой имеется. Может быть пустым.
  - `$pgp_context` - Строка, описывающая, почему запрашивается ключ.
  - `$password` - Ссылка на строку пароля, в которой должен храниться предоставленный пароль.
  Callback-функция должна возвращать `true`, если пароль был успешно установлен или `false`, если возникла ошибка.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример простой callback-функции

    <?php
    function password_callback(string $key_fp, string $pgp_context, string &$password)
    {
        $password = "password";

        return true;
    }

    $ffi = rnp_ffi_create('GPG', 'GPG');

    rnp_ffi_set_pass_provider($ffi, 'password_callback');

# rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Импортирует ключи из строки PHP в связку ключей и получает JSON с описанием новых/обновлённых ключей

### Описание

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`input`
  Пакеты OpenPGP, содержащие ключ(и), которые нужно загрузить. Могут быть бинарными или ASCII-закодированными.
`flags`
  Смотрите предопределённые константы `RNP_LOAD_SAVE_*`.

### Возвращаемые значения

JSON-строка с информацией о новых и обновлённых ключах в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Импортирует автономные подписи в связку ключей и получает JSON с описанием обновлённых ключей

### Описание

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`input`
  Пакеты OpenPGP, содержащие подписи, которые необходимо импортировать. Могут быть бинарными или ASCII-закодированными.
`flags`
  В настоящее время должно быть 0.

### Возвращаемые значения

JSON-строка с информацией об обновлённых ключах в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Экспортирует ключ

### Описание

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток ключа.
`flags`
  Смотрите предопределённые константы `RNP_KEY_EXPORT_*` (за исключением `RNP_KEY_EXPORT_BASE64`).

### Возвращаемые значения

OpenPGP-пакеты экспортированного ключа (двоичные или ASCII-закодированные) в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Экспортирует минимальный ключ для функции автоматического шифрования (всего 5 пакетов: ключ, uid, подпись, дочерний ключ шифрования, подпись)

### Описание

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток первичного ключа.
`subkey_fp`
  Дочерний ключ для экспорта. Может быть пустой строкой, чтобы выбрать первый подходящий дочерний ключ.
`uid`
  Идентификатор пользователя для экспорта. Может быть пустой строкой, если у экспортируемого ключа только один uid.
`flags`
  В настоящее время поддерживается только `RNP_KEY_EXPORT_BASE64`. Включение приведёт к экспорту данных ключа в кодировке base64 вместо двоичной.

### Возвращаемые значения

OpenPGP-пакеты экспортированного ключа в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Генерирует и экспортирует подпись отзыва первичного ключа

### Описание

function rnp_key_export_revocation(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): string|false

Примечание: чтобы отозвать ключ, вам нужно импортировать подпись в хранилище ключей или воспользоваться функцией rnp_key_revoke().

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток первичного ключа, который должен быть отозван.
`flags`
  `RNP_KEY_EXPORT_ARMORED` или 0.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"hash"` | string | Установить хеш-алгоритм, используемый при вычислении подписи.
  `"code"` | string | Код причины для кода отзыва. Возможные значения: 'no', 'supersed', 'compromised', 'retired'. Если не определено, то по умолчанию будет использоваться значение 'no'.
  `"reason"` | string | Текстовое представление причины отзыва.

### Возвращаемые значения

Экспортированная подпись отзыва в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Получает информацию о ключе

### Описание

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток ключа.

### Возвращаемые значения

Ассоциативный массив с информацией о ключе или `false`, если возникла ошибка.

Ключ | Тип данных | Описание
--- | --- | ---
`"is_primary"` | boolean | `true`, если ключ является первичным ключом.
`"is_sub"` | boolean | `true`, если этот ключ является дочерним ключом.
`"is_valid"` | boolean | `true`, если открытый ключ действителен. Сюда входит проверка подписей, сроков действия, аннулирования и так далее.
`"is_revoked"` | boolean | `true`, если ключ отозван.
`"is_superseded"` | boolean | `true`, если ключ заменён. Присутствует только в случае отзыва ключа.
`"is_compromised"` | boolean | `true`, если этот ключ скомпрометирован. Присутствует только в случае отзыва ключа.
`"is_retired"` | boolean | `true`, если данный ключ отозван. Присутствует только в случае отзыва ключа.
`"is_expired"` | boolean | `true`, если срок действия этого ключа истёк.
`"have_secret"` | boolean | `true`, если у ключа есть закрытая часть.
`"is_locked"` | boolean | `true`, если ключ в настоящее время заблокирован. Присутствует только для закрытых ключей.
`"is_protected"` | boolean | `true`, если данный ключ защищён. Присутствует только для закрытых ключей. Защищённый ключ - это ключ, который зашифрован и может безопасно храниться в памяти и блокируется/разблокируется по мере необходимости.
`"have_public"` | boolean | `true`, если у ключа есть открытая часть. Как правило, у всех ключей есть открытую часть.
`"valid_till"` | integer | Метка времени, до которой ключ считается действительным. Примечание: при этом учитывается не только истечение срока действия ключа, но и его отзыв. Для подключаемого дочернего ключа также будет проверяться время действия первичного ключа.
`"bits"` | integer | Количество битов в ключе. Для ключей на основе EC, будет содержаться размер кривой.
`"alg"` | string | Имя алгоритма ключа.
`"subkeys"` | array | Индексированный массив, содержащий строки цифровых отпечатков дочерних ключей. Присутствует только для первичных ключей. Может быть пустым, если у первичного ключа нет дочерних ключей.
`"uids"` | array | Индексированный массив, содержащий строки идентификаторов пользователей. Присутствует только для первичных ключей. Может быть пустым, если первичный ключ не содержит идентификаторов пользователей.

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Удаляет ключ из связки (связок)

### Описание

function rnp_key_remove(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): bool

Примечание: необходимо вызвать функцию rnp_save_keys() для записи обновлённых связок ключей.

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток ключа.
`flags`
  Смотрите константы `RNP_KEY_REMOVE_*`. Флаг `RNP_KEY_REMOVE_SUBKEYS` будет работать только для первичного ключа и удалит также все его подключи.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Отзывает ключ или дочерний ключ путём создания и добавления подписи отзыва

### Описание

function rnp_key_revoke(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): bool

Примечание: необходимо вызвать функцию rnp_save_keys() для записи обновлённых связок ключей.

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`key_fp`
  Цифровой отпечаток ключа.
`flags`
  В настоящее время должно быть 0.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"hash"` | string | Установить хеш-алгоритм, используемый при вычислении подписи.
  `"code"` | string | Код причины для кода отзыва. Возможные значения: 'no', 'supersed', 'compromised', 'retired'. Если не определено, то по умолчанию будет использоваться значение 'no'.
  `"reason"` | string | Текстовое представление причины отзыва.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Перечисляет все ключи, присутствующие в связке ключей, по указанному типу идентификатора

### Описание

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`identifier_type`
  Тип идентификатора ключа ("userid", "keyid", "grip", "fingerprint").

### Возвращаемые значения

Ассоциативный массив, где ключ - строка идентификатора, а значение - цифровой отпечаток ключа PGP или `false`, если возникла ошибка.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Загружает ключи из строки PHP

### Описание

function rnp_load_keys(
RnpFFI `$ffi`,
string `$format`,
string `$input`,
int `$flags`
): bool

Обратите внимание, что для G10 входными данными должен быть каталог (который должен уже существовать).

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`format`
  Формат ключа данных (GPG, KBX, G10).
`input`
  Пакеты OpenPGP, содержащие ключ(и), которые нужно загрузить. Могут быть бинарными или ASCII-закодированными.
`flags`
  Смотрите описание флагов `RNP_LOAD_SAVE_*`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Загружает ключи из указанного пути

### Описание

function rnp_load_keys_from_path(
RnpFFI `$ffi`,
string `$format`,
string `$input_path`,
int `$flags`
): bool

Обратите внимание, что для G10 входными данными должен быть каталог (который должен уже существовать).

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`format`
  Формат ключа данных (GPG, KBX, G10).
`input_path`
  Файл или каталог, содержащий ключи.
`flags`
  Смотрите описание флагов `RNP_LOAD_SAVE_*`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Поиск ключа

### Описание

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Примечание: при поиске по userid проверяются только действительные имена пользователей.

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`identifier_type`
  Строка типа идентификатора: "userid", "keyid", "fingerprint", "grip".
`identifier`
  PGP идентификатор пользователя (имя и e-mail) для типа "userid", шестнадцатеричная строка, которая представляет собой идентификатор ключа, цифровой отпечаток или захват ключа соответственно.

### Возвращаемые значения

Возвращает шестнадцатеричный цифровой отпечаток ключа, найденного в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Шифрует сообщение

### Описание

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`message`
  Сообщение, которое необходимо зашифровать.
`recipient_keys_fp`
  Массив с отпечатками ключей получателя. Должен присутствовать хотя бы один ключ.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"compression_alg"` | string | Алгоритм сжатия. Для включения сжатия данных должны быть заданы как `"compression_alg"`, так и `"compression_level"`.
  `"compression_level"` | integer | Уровень сжатия, 0-9. 0 отключает сжатие.
  `"armor"` | boolean | Включает ASCII-защищённый вывод. По умолчанию отключён.
  `"add_signature"` | boolean | Зашифрованное сообщение будет также подписано.
  `"hash"` | string | Устанавливает хеш-алгоритм, используемый при вычислении подписи. Опции "add_signature" должно быть установлено значение `true`.
  `"creation_time"` | integer | Устанавливает время создания подписи в секундах с 1 января 1970 года по Гринвичу. По умолчанию используется текущее время.
  `"expiration_time"` | integer | Устанавливает время истечения срока действия подписи в секундах с момента создания. Значение 0 используется для пометки подписи как не истекающей (значение по умолчанию).
  `"password"` | string | Добавляет пароль, который используется для шифрования данных.
  `"cipher"` | string | Устанавливает алгоритм симметричного шифрования. Возможные значения: "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256", "SM4".
  `"aead"` | string | Устанавливает алгоритм режима AEAD. Возможные значения: "None" для отключения AEAD, "EAX", "OCB".
  `"aead_bits"` | integer | Устанавливает длину ячейки для режима AEAD через количество битов размера ячейки. Должно быть от 0 до 56.
  `"flags"` | integer | Устанавливает дополнительные флаги шифрования. Поддерживаемые флаги: RNP_ENCRYPT_NOWRAP - не заворачивать данные в литеральный пакет данных. Это позволит шифровать уже подписанные данные.
  `"file_name"` | string | Устанавливает внутреннее имя файла для шифруемых данных. Специальное значение _CONSOLE может использоваться для пометки сообщения как "только для ваших глаз", т.е. оно не должно нигде храниться, а только отображаться получателю. По умолчанию используется пустая строка.
  `"file_mtime"` | integer | Устанавливает дату модификации входного файла в секундах с 1 января 1970 года по Гринвичу.

### Возвращаемые значения

Зашифрованные данные в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Генерирует ключ

### Описание

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`userid`
  PGP User ID - текст, предназначенный для представления имени и адреса электронной почты владельца ключа.
`key_alg`
  Алгоритм первичного ключа (например, 'RSA', 'DSA' и т.д.).
`sub_alg`
  Алгоритм дочернего ключа. Если значение не задано, то дочерний ключ генерироваться не будет.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"bits"` | integer | Размер первичного ключа в битах. Применяется только для ключей RSA, DSA и El-Gamal.
  `"hash"` | string | Хеш-алгоритм, используемый в самоподписи или подписи с привязкой к дочернему ключу.
  `"dsa_qbits"` | integer | Устанавливает размер параметра `q` для DSA-ключа. Примечание: в зависимости от разрядности ключа будет установлено соответствующее значение по умолчанию. Однако при необходимости его можно переопределить.
  `"curve"` | string | Установка кривой, используемой для ключа ECC. Примечание: это применимо только для ключей ECDSA, ECDH и SM2.
  `"request_password"` | boolean | Включает запрос пароля через провайдера паролей. Этот пароль будет использоваться для шифрования ключа. Callback-функция провайдера паролей должна быть задана заранее вызовом функции rnp_ffi_set_pass_provider(). Примечание: данная настройка будет проигнорирована, если пароль был задан через с помощью `"password"`.
  `"password"` | string | Устанавливает пароль, используемый для шифрования данных секретного ключа.
  `"expiration"` | integer | Устанавливает время истечения срока действия ключей и дочерних ключей в секундах.
  `"sub_bits"` | integer | Размер дочернего ключа в битах. Применяется только для ключей RSA, DSA и El-Gamal.
  `"sub_hash"` | string | Хеш-алгоритм, используемый в самоподписи дочернего ключа или в подписи с привязкой к дочернему ключу.
  `"sub_curve"` | string | Устанавливает кривую, используемую для дочернего ключа ECC. Примечание: это применимо только для ключей ECDSA, ECDH и SM2.

### Возвращаемые значения

Отпечаток сгенерированного первичного ключа или `false`, если возникла ошибка. Этот отпечаток может быть использован в дальнейшем для ссылки на ключ в операциях подписи и шифрования. Данные ключа хранятся в контексте памяти FFI и могут быть сохранены с помощью функции rnp_save_keys() или rnp_save_keys_to_path().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Выполняет операцию подписания бинарных данных, возвращает присоединённую подпись (подписи)

### Описание

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`data`
  Данные для подписи.
`keys_fp`
  Массив с цифровыми отпечатками ключей. Должен быть указан хотя бы один ключ. Ключи должны присутствовать в параметре `ffi`.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"compression_alg"` | string | Алгоритм сжатия. Для включения сжатия данных должны быть заданы как `"compression_alg"`, так и `"compression_level"`.
  `"compression_level"` | integer | Уровень сжатия, 0-9. 0 отключает сжатие.
  `"armor"` | boolean | Включает ASCII-защищённый вывод. По умолчанию отключён.
  `"hash"` | string | Устанавливает хеш-алгоритм, используемый при вычислении подписи.
  `"creation_time"` | integer | Устанавливает время создания подписи в секундах с 1 января 1970 года по Гринвичу. По умолчанию используется текущее время.
  `"expiration_time"` | integer | Устанавливает время истечения срока действия подписи в секундах с момента создания. Значение 0 используется для пометки подписи как не истекающей (значение по умолчанию).
  `"file_name"` | string | Устанавливает внутреннее имя файла для шифруемых данных. Специальное значение _CONSOLE может использоваться для пометки сообщения как "только для ваших глаз", т.е. оно не должно нигде храниться, а только отображаться получателю. По умолчанию используется пустая строка.
  `"file_mtime"` | integer | Устанавливает дату модификации входного файла в секундах с 1 января 1970 года по Гринвичу.

### Возвращаемые значения

Возвращает данные с присоединённой подписью (подписями) в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Выполняет операцию подписания текстовых данных, возвращая подписанный открытый текст сообщения

### Описание

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`data`
  Данные для подписи.
`keys_fp`
  Массив с цифровыми отпечатками ключей. Должен быть указан хотя бы один ключ. Ключи должны присутствовать в параметре `ffi`.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"armor"` | boolean | Включает ASCII-защищённый вывод. По умолчанию отключён.
  `"hash"` | string | Устанавливает хеш-алгоритм, используемый при вычислении подписи.
  `"creation_time"` | integer | Устанавливает время создания подписи в секундах с 1 января 1970 года по Гринвичу. По умолчанию используется текущее время.
  `"expiration_time"` | integer | Устанавливает время истечения срока действия подписи в секундах с момента создания. Значение 0 используется для пометки подписи как не истекающей (значение по умолчанию).

### Возвращаемые значения

Подписанный открытый текст, содержащий исходные данные с дополнительными заголовками и ASCII-защищённой подписью в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Выполняет операцию подписания, возвращает отсоединённую подпись (подписи)

### Описание

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`data`
  Данные для подписи.
`keys_fp`
  Массив с цифровыми отпечатками ключей. Должен быть указан хотя бы один ключ. Ключи должны присутствовать в параметре `ffi`.
`options`
  Ассоциативный массив с опциями.

  Ключ | Тип данных | Описание
  --- | --- | ---
  `"armor"` | boolean | Включает ASCII-защищённый вывод. По умолчанию отключён.
  `"hash"` | string | Устанавливает хеш-алгоритм, используемый при вычислении подписи.
  `"creation_time"` | integer | Устанавливает время создания подписи в секундах с 1 января 1970 года по Гринвичу. По умолчанию используется текущее время.
  `"expiration_time"` | integer | Устанавливает время истечения срока действия подписи в секундах с момента создания. Значение 0 используется для пометки подписи как не истекающей (значение по умолчанию).

### Возвращаемые значения

Возвращает данные с отсоединённой подписью (подписями) в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Проверяет присоединённую подпись или подпись открытого текста

### Описание

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`data`
  Подписанные данные.

### Возвращаемые значения

Ассоциативный массив, содержащий информацию о результатах проверки или `false`, если возникла ошибка.

Key | Data type | Описание
--- | --- | ---
`"verification_status"` | string | Общий результат проверки, либо строка "Success", либо соответствующее сообщение об ошибке. Результат "Success" устанавливается, если хотя бы одна подпись является действительной и успешно проверена. Индивидуальные результаты проверки для каждой подписи можно проверить в массиве "signatures".
`"file_name"` | string | Имя файла.
`"file_mtime"` | integer | Время изменения файла.
`"mode"` | string | Режим защиты данных (шифрования), используемый в обрабатываемом сообщении. В настоящее время определены следующие значения: "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Симметричный шифр, используемый для шифрования данных.
`"valid_integrity"` | boolean | `true`, если использовалась защита целостности сообщения (т.е. MDC или AEAD) и она была успешно подтверждена.
`"signatures"` | array | Ассоциативный массив, описывающий каждую найденную подпись. Смотрите описание ниже.

Дочерний массив "signatures".

Ключ | Тип данных | Описание
--- | --- | ---
"verification_status" | string | Статус проверки подписи, либо строка "Success", либо соответствующее сообщение об ошибке.
"creation_time" | integer | Время создания подписи в секундах с 1 января 1970 года по Гринвичу.
"expiration_time" | integer | Время истечения срока действия подписи в секундах с момента создания или 0, если срок действия подписи не истекает.
"hash" | string | Алгоритм хеш-функции, используемый для вычисления подписи.
"signing_key" | string | Цифровой отпечаток ключа, используемого для подписи. Может иметь значение "Not found", если соответствующий открытый ключ не загружен в объект FFI.
"signature_type" | string | Тип подписи. В настоящее время определены следующие значения: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Проверяет отсоединённые подписи

### Описание

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`data`
  Исходные данные.
`signature`
  Данные отсоединённой подписи.

### Возвращаемые значения

Ассоциативный массив, содержащий информацию о результатах проверки или `false`, если возникла ошибка.

Ключ | Тип данных | Описание
--- | --- | ---
`"verification_status"` | string | Общий результат проверки, либо строка "Success", либо соответствующее сообщение об ошибке. Результат "Success" устанавливается, если хотя бы одна подпись является действительной и успешно проверена. Индивидуальные результаты проверки для каждой подписи можно проверить в массиве "signatures".
`"file_name"` | string | Имя файла.
`"file_mtime"` | integer | Время изменения файла.
`"mode"` | string | Режим защиты данных (шифрования), используемый в обрабатываемом сообщении. В настоящее время определены следующие значения: "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Симметричный шифр, используемый для шифрования данных.
`"valid_integrity"` | boolean | `true`, если использовалась защита целостности сообщения (т.е. MDC или AEAD) и она была успешно подтверждена.
`"signatures"` | array | Ассоциативный массив, описывающий каждую найденную подпись. Смотрите описание ниже.

Дочерний массив "signatures".

Ключ | Тип данных | Описание
--- | --- | ---
"verification_status" | string | Статус проверки подписи, либо строка "Success", либо соответствующее сообщение об ошибке.
"creation_time" | integer | Время создания подписи в секундах с 1 января 1970 года по Гринвичу.
"expiration_time" | integer | Время истечения срока действия подписи в секундах с момента создания или 0, если срок действия подписи не истекает.
"hash" | string | Алгоритм хеш-функции, используемый для вычисления подписи.
"signing_key" | string | Цифровой отпечаток ключа, используемого для подписи. Может иметь значение "Not found", если соответствующий открытый ключ не загружен в объект FFI.
"signature_type" | string | Тип подписи. В настоящее время определены следующие значения: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Сохраняет ключи в строке PHP

### Описание

function rnp_save_keys(
RnpFFI `$ffi`,
string `$format`,
string `&$output`,
int `$flags`
): bool

Обратите внимание, что для G10 значением `output` должен быть каталог (который уже должен существовать).

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`format`
  Формат ключа данных (GPG, KBX, G10).
`output`
  Ключевые пакеты будут сохранены в строке, на которую ссылается `output`.
`flags`
  Смотрите описание флагов `RNP_LOAD_SAVE_*`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Сохраняет ключи по указанному пути

### Описание

function rnp_save_keys_to_path(
RnpFFI `$ffi`,
string `$format`,
string `$output_path`,
int `$flags`
): bool

Сохраняет ключи, присутствующие в объекте FFI (загруженном или сгенерированном), в указанном файле или каталоге.

### Список параметров

`ffi`
  FFI-объект, который возвращает функция rnp_ffi_create().
`format`
  Формат ключа данных (GPG, KBX, G10).
`output_path`
  Путь к файлу или каталогу, в который должны быть сохранены ключи.
`flags`
  Смотрите описание флагов `RNP_LOAD_SAVE_*`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Получает поддерживаемые функции в формате JSON

### Описание

function rnp_supported_features(string `$type`): string|false

Получение строки в формате JSON, содержащей массив поддерживаемых значений признаков rnp (алгоритмов, кривых и т.д.) по типам.

### Список параметров

`type`
  Поддерживаемые значения смотрите в константах RNP_FEATURE_*.

### Возвращаемые значения

Возвращает строку, содержащую JSON-форматированный массив поддерживаемых алгоритмов, кривых и т.д. или `false`, если возникла ошибка.

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — Возвращает строку версии библиотеки RNP

### Описание

function rnp_version_string(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку версии библиотеки RNP.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — Возвращает строку полной версии библиотеки RNP

### Описание

function rnp_version_string_full(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку полной версии библиотеки RNP.

## Содержание

- rnp_backend_string — Возвращает имя библиотеки криптографического бэкенда
- rnp_backend_version — Возвращает версию криптографической библиотеки бэкенда
- rnp_decrypt — Расшифровывает сообщение PGP
- rnp_dump_packets — Выгружает информацию о потоке пакетов OpenPGP в человеко-читаемом формате
- rnp_dump_packets_to_json — Выгрузка информации о потоке пакетов OpenPGP в строку JSON
- rnp_ffi_create — Создаёт объект верхнего уровня, используемый для взаимодействия с библиотекой
- rnp_ffi_destroy — Уничтожает объект верхнего уровня, используемый для взаимодействия с библиотекой
- rnp_ffi_set_pass_provider — Устанавливает callback-функцию поставщика паролей
- rnp_import_keys — Импортирует ключи из строки PHP в связку ключей и получает JSON с описанием новых/обновлённых ключей
- rnp_import_signatures — Импортирует автономные подписи в связку ключей и получает JSON с описанием обновлённых ключей
- rnp_key_export — Экспортирует ключ
- rnp_key_export_autocrypt — Экспортирует минимальный ключ для функции автоматического шифрования (всего 5 пакетов: ключ, uid, подпись, дочерний ключ шифрования, подпись)
- rnp_key_export_revocation — Генерирует и экспортирует подпись отзыва первичного ключа
- rnp_key_get_info — Получает информацию о ключе
- rnp_key_remove — Удаляет ключ из связки (связок)
- rnp_key_revoke — Отзывает ключ или дочерний ключ путём создания и добавления подписи отзыва
- rnp_list_keys — Перечисляет все ключи, присутствующие в связке ключей, по указанному типу идентификатора
- rnp_load_keys — Загружает ключи из строки PHP
- rnp_load_keys_from_path — Загружает ключи из указанного пути
- rnp_locate_key — Поиск ключа
- rnp_op_encrypt — Шифрует сообщение
- rnp_op_generate_key — Генерирует ключ
- rnp_op_sign — Выполняет операцию подписания бинарных данных, возвращает присоединённую подпись (подписи)
- rnp_op_sign_cleartext — Выполняет операцию подписания текстовых данных, возвращая подписанный открытый текст сообщения
- rnp_op_sign_detached — Выполняет операцию подписания, возвращает отсоединённую подпись (подписи)
- rnp_op_verify — Проверяет присоединённую подпись или подпись открытого текста
- rnp_op_verify_detached — Проверяет отсоединённые подписи
- rnp_save_keys — Сохраняет ключи в строке PHP
- rnp_save_keys_to_path — Сохраняет ключи по указанному пути
- rnp_supported_features — Получает поддерживаемые функции в формате JSON
- rnp_version_string — Возвращает строку версии библиотеки RNP
- rnp_version_string_full — Возвращает строку полной версии библиотеки RNP

# Класс RnpFFI

(PECL rnp >= 0.1.1)

## Введение

## Обзор класса

class RnpFFI {
}

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Примеры
  - Подписание текста
- Функции Rnp
  - rnp_backend_string — Возвращает имя библиотеки криптографического бэкенда
  - rnp_backend_version — Возвращает версию криптографической библиотеки бэкенда
  - rnp_decrypt — Расшифровывает сообщение PGP
  - rnp_dump_packets — Выгружает информацию о потоке пакетов OpenPGP в человеко-читаемом формате
  - rnp_dump_packets_to_json — Выгрузка информации о потоке пакетов OpenPGP в строку JSON
  - rnp_ffi_create — Создаёт объект верхнего уровня, используемый для взаимодействия с библиотекой
  - rnp_ffi_destroy — Уничтожает объект верхнего уровня, используемый для взаимодействия с библиотекой
  - rnp_ffi_set_pass_provider — Устанавливает callback-функцию поставщика паролей
  - rnp_import_keys — Импортирует ключи из строки PHP в связку ключей и получает JSON с описанием новых/обновлённых ключей
  - rnp_import_signatures — Импортирует автономные подписи в связку ключей и получает JSON с описанием обновлённых ключей
  - rnp_key_export — Экспортирует ключ
  - rnp_key_export_autocrypt — Экспортирует минимальный ключ для функции автоматического шифрования (всего 5 пакетов: ключ, uid, подпись, дочерний ключ шифрования, подпись)
  - rnp_key_export_revocation — Генерирует и экспортирует подпись отзыва первичного ключа
  - rnp_key_get_info — Получает информацию о ключе
  - rnp_key_remove — Удаляет ключ из связки (связок)
  - rnp_key_revoke — Отзывает ключ или дочерний ключ путём создания и добавления подписи отзыва
  - rnp_list_keys — Перечисляет все ключи, присутствующие в связке ключей, по указанному типу идентификатора
  - rnp_load_keys — Загружает ключи из строки PHP
  - rnp_load_keys_from_path — Загружает ключи из указанного пути
  - rnp_locate_key — Поиск ключа
  - rnp_op_encrypt — Шифрует сообщение
  - rnp_op_generate_key — Генерирует ключ
  - rnp_op_sign — Выполняет операцию подписания бинарных данных, возвращает присоединённую подпись (подписи)
  - rnp_op_sign_cleartext — Выполняет операцию подписания текстовых данных, возвращая подписанный открытый текст сообщения
  - rnp_op_sign_detached — Выполняет операцию подписания, возвращает отсоединённую подпись (подписи)
  - rnp_op_verify — Проверяет присоединённую подпись или подпись открытого текста
  - rnp_op_verify_detached — Проверяет отсоединённые подписи
  - rnp_save_keys — Сохраняет ключи в строке PHP
  - rnp_save_keys_to_path — Сохраняет ключи по указанному пути
  - rnp_supported_features — Получает поддерживаемые функции в формате JSON
  - rnp_version_string — Возвращает строку версии библиотеки RNP
  - rnp_version_string_full — Возвращает строку полной версии библиотеки RNP
- RnpFFI — Класс RnpFFI

# Sodium

# Введение

Sodium — современная, простая в работе программная библиотека для шифрования и дешифрования данных, выполнения операций с подписями, хеширования паролей и других криптографических целей. Цель библиотеки — дать доступ к операциям, которые создают необходимые криптографические инструменты повышенного уровня.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Для работы модуля требуется библиотека » libsodium ≥ 1.0.8.

## Установка

Начиная с PHP 7.2.0 модуль включается в PHP. Для более старых версий PHP модуль доступен для скачивания через репозиторий PECL.

## Linux Systems

Функции модуля будут доступны, только если скомпилировать PHP с поддержкой модуля sodium через конфигурационную опцию --with-sodium[=DIR].

## Windows

Чтобы использовать модуль в ОС Windows, требуется добавить в файл php.ini строку `extension=php_sodium.dll`.

## Установка из репозитория PECL

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/libsodium

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`SODIUM_LIBRARY_VERSION` (string)
`SODIUM_LIBRARY_MAJOR_VERSION` (int)
`SODIUM_LIBRARY_MINOR_VERSION` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` (int)
`SODIUM_BASE64_VARIANT_URLSAFE` (int)
`SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` (int)
`SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Доступно, начиная с PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AUTH_BYTES` (int)
`SODIUM_CRYPTO_AUTH_KEYBYTES` (int)
`SODIUM_CRYPTO_BOX_SEALBYTES` (int)
`SODIUM_CRYPTO_BOX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_BOX_MACBYTES` (int)
`SODIUM_CRYPTO_BOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_BOX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KDF_BYTES_MIN` (int)
`SODIUM_CRYPTO_KDF_BYTES_MAX` (int)
`SODIUM_CRYPTO_KDF_CONTEXTBYTES` (int)
`SODIUM_CRYPTO_KDF_KEYBYTES` (int)
`SODIUM_CRYPTO_KX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KX_SESSIONKEYBYTES` (int)
`SODIUM_CRYPTO_KX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_KX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_KX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (int)
`SODIUM_CRYPTO_PWHASH_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_SHORTHASH_BYTES` (int)
`SODIUM_CRYPTO_SHORTHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_MACBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY` (int)
`SODIUM_CRYPTO_SIGN_BYTES` (int)
`SODIUM_CRYPTO_SIGN_SEEDBYTES` (int)
`SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_STREAM_NONCEBYTES` (int)
`SODIUM_CRYPTO_STREAM_KEYBYTES` (int)
`SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES` (int)
  Доступно, начиная с PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Доступно, начиная с PHP 8.1.0.

# Функции Sodium

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Добавляет большие числа

### Описание

function sodium_add(string `&$string1`, string `$string2`): void

Добавляет параметр `string2` к `string1`, перезаписывая значение, хранящееся в `string1`. Функция предполагает, что оба параметра являются двоичными строками, которые представляют целые числа без знака в обратном порядке байтов.

### Список параметров

`string1`
  Строка, представляющая целое число произвольной длины без знака в обратном порядке байтов. Этот параметр передаётся по ссылке и будет содержать сумму двух параметров.
`string2`
  Строка, представляющая целое число произвольной длины без знака в обратном порядке байтов.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Преобразовывает строку в кодировке base64 в необработанный двоичный файл

### Описание

function sodium_base642bin(#[\SensitiveParameter]string `$string`, int `$id`, string `$ignore` = ""): string

Функция преобразовывает строку в кодировке base64 в необработанный двоичный файл. В отличие от функции base64_decode(), функция sodium_base642bin() постоянна по времени (свойство, которое важно для любого кода, который касается криптографических входных данных, таких как простые тексты или ключи) и поддерживает несколько наборов символов.

### Список параметров

`string`
  Строка (string); Закодированная строка.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` для стандартного (`A-Za-z0-9/\+`). Кодировка Base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` для стандартного (`A-Za-z0-9/\+`) Кодировка Base64 без дополнительных символов `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` для URL-безопасного (`A-Za-z0-9\-_`). Кодировка Base64.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` for URL-safe (`A-Za-z0-9\-_`). Кодировка Base64 без дополнительных символов `=`.
`ignore`
  Символы, которые следует игнорировать во время преобразования (например, символы пробела).

### Возвращаемые значения

Функция возвращает преобразованную строку.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Кодирует необработанную двоичную строку в формат base64

### Описание

function sodium_bin2base64(#[\SensitiveParameter]string `$string`, int `$id`): string

Функция преобразовывает необработанную двоичную строку в base64-строку. В отличие от функции base64_encode(), функция sodium_bin2base64() постоянна по времени (свойство, которое важно для любого кода, который касается криптографических входных данных, таких, как простые тексты или ключи), и поддерживает несколько наборов символов.

### Список параметров

`string`
  Необработанная двоичная строка.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` для стандартного (`A-Za-z0-9/\+`) Кодировка Base64.
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` for standard (`A-Za-z0-9/\+`) Кодировка Base64 без дополнительных символов `=`.
  - `SODIUM_BASE64_VARIANT_URLSAFE` для URL-безопасного (`A-Za-z0-9\-_`) Кодировка Base64.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` для URL-безопасного (`A-Za-z0-9\-_`) Кодировка Base64 без дополнительных символов `=`.

### Возвращаемые значения

Функция возвращает строку в формате Base64.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Кодирует в шестнадцатеричное представление

### Описание

function sodium_bin2hex(#[\SensitiveParameter]string `$string`): string

Функция преобразовывает необработанную двоичную строку в строку в шестнадцатеричной кодировке. В отличие от стандартной функции шестнадцатеричного кодирования, функция sodium_bin2hex() постоянна по времени (свойство, которое важно для кода, который касается криптографических данных наподобие текстов или ключей).

### Список параметров

`string`
  Необработанная двоичная строка.

### Возвращаемые значения

Функция возвращает строку в шестнадцатеричном коде.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Сравнивает большие числа

### Описание

function sodium_compare(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

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

### Список параметров

`string1`
  Левый операнд.
`string2`
  Правый операнд.

### Возвращаемые значения

Функция возвращает `-1`, если значение `string1` меньше значения `string2`.

Функция возвращает `1`, если значение `string1` больше значения `string2`.

Функция возвращает `0`, если строки равны.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L

### Описание

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Функция проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L.

### Список параметров

`ciphertext`
  Строка в формате, который возвращает функция sodium_crypto_aead_aegis128l_encrypt().
`additional_data`
  Дополнительные аутентифицированные данные, которые помогают методу проверять тег аутентификации, который добавляется в конец зашифрованного текста, но который не шифруются и не хранятся в зашифрованном тексте.
`nonce`
  Одноразовое число для сообщения.
`key`
  128-битный ключ шифрования.

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст, который расшифровала, или `false`, если возникла ошибка.

### Смотрите также

- sodium_crypto_aead_aegis128l_encrypt() - Шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Генерирует случайный ключ по алгоритму AEGIS-128L

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L

### Описание

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Функция шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L.

### Список параметров

`message`
  Сообщение в виде открытого текста, которое требуется зашифровать.
`additional_data`
  Дополнительные аутентифицированные данные, которые помогают методу проверять тег аутентификации, который добавляется в конец зашифрованного текста, но который не шифруются и не хранятся в зашифрованном тексте.
`nonce`
  Одноразовое число для сообщения.
`key`
  128-битный ключ шифрования.

### Возвращаемые значения

Функция возвращает зашифрованный текст и тег аутентификации в виде строки необработанных двоичных байтов.

### Смотрите также

- sodium_crypto_aead_aegis128l_decrypt() - Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Генерирует случайный ключ по алгоритму AEGIS-128L

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — Генерирует случайный ключ по алгоритму AEGIS-128L

### Описание

function sodium_crypto_aead_aegis128l_keygen(): string

Функция генерирует случайный ключ, который затем передают в функции sodium_crypto_aead_aegis128l_encrypt() и sodium_crypto_aead_aegis128l_decrypt().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает 128-битный случайный ключ.

### Смотрите также

- sodium_crypto_aead_aegis128l_decrypt() - Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt() - Шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256

### Описание

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Функция проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256.

### Список параметров

`ciphertext`
  Строка в формате, который возвращает функция sodium_crypto_aead_aegis256_encrypt().
`additional_data`
  Дополнительные аутентифицированные данные, которые помогают методу проверять тег аутентификации, который добавляется в конец зашифрованного текста, но который не шифруются и не хранятся в зашифрованном тексте.
`nonce`
  Одноразовое число для сообщения.
`key`
  128-битный ключ шифрования.

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст, который расшифровала, или `false`, если возникла ошибка.

### Смотрите также

- sodium_crypto_aead_aegis256_encrypt() - Шифрует и аутентифицирует сообщение по алгоритму AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Генерирует случайный ключ по алгоритму AEGIS-256

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-256

### Описание

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Функция шифрует и аутентифицирует сообщение по алгоритму AEGIS-256.

### Список параметров

`message`
  Сообщение в виде открытого текста, которое требуется зашифровать.
`additional_data`
  Дополнительные аутентифицированные данные, которые помогают методу проверять тег аутентификации, который добавляется в конец зашифрованного текста, но который не шифруются и не хранятся в зашифрованном тексте.
`nonce`
  Одноразовое число для сообщения.
`key`
  256-битный ключ шифрования.

### Возвращаемые значения

Функция возвращает зашифрованный текст и тег аутентификации в виде строки необработанных двоичных байтов.

### Смотрите также

- sodium_crypto_aead_aegis256_decrypt() - Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Генерирует случайный ключ по алгоритму AEGIS-256

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — Генерирует случайный ключ по алгоритму AEGIS-256

### Описание

function sodium_crypto_aead_aegis256_keygen(): string

Функция генерирует случайный ключ, который затем передают в функции sodium_crypto_aead_aegis256_encrypt() и sodium_crypto_aead_aegis256_decrypt().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает 256-битный случайный ключ.

### Смотрите также

- sodium_crypto_aead_aegis256_decrypt() - Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256
- sodium_crypto_aead_aegis256_encrypt() - Шифрует и аутентифицирует сообщение по алгоритму AEGIS-256

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Проверяет и расшифровывает сообщение алгоритмом AES-256-GCM

### Описание

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Функция проверяет и расшифровывает сообщение алгоритмом AES-256-GCM. Функция доступна, только если функция sodium_crypto_aead_aes256gcm_is_available() возвращает `true`.

### Список параметров

`ciphertext`
  Параметр должен быть в формате, который предоставила функция sodium_crypto_aead_aes256gcm_encrypt() (зашифрованный текст и тег, объединённые).
`additional_data`
  Дополнительные проверенные данные. Это используется при проверке тега аутентификации, добавленного к зашифрованному тексту, но он не шифруется и не сохраняется в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 12 байт.
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст или `false`, если возникла ошибка.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Шифрует, а затем проверяет подлинность алгоритмом AES-256-GCM

### Описание

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Шифрует, а затем проверяет подлинность алгоритмом AES-256-GCM. Функция доступна, только если функция sodium_crypto_aead_aes256gcm_is_available() возвращает `true`.

### Список параметров

`message`
  Текстовое сообщение, которое нужно зашифровать.
`additional_data`
  Дополнительные проверенные данные. Это используется при проверке тега подлинности, добавленного к зашифрованному тексту, но он не шифруется и не сохраняется в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 12 байт.
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

Функция возвращает зашифрованный текст и тег проверки подлинности в виде строки необработанных двоичных байтов. (Формат: зашифрованный текст, затем тег.)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Проверяет, поддерживает ли оборудование алгоритм AES256-GCM

### Описание

function sodium_crypto_aead_aes256gcm_is_available(): bool

Значение, которое возвращает функция, зависит от того, поддерживает ли оборудование аппаратное ускорение AES.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если шифрование алгоритмом AES-256-GCM безопасно, иначе `false`.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Создаёт случайный ключ AES-256-GCM

### Описание

function sodium_crypto_aead_aes256gcm_keygen(): string

Создаёт случайный ключ для использования в sodium_crypto_aead_aes256gcm_encrypt() и sodium_crypto_aead_aes256gcm_decrypt().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 256-битный случайный ключ.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Проверяет, затем расшифровывает алгоритмом ChaCha20-Poly1305

### Описание

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Функция проверяет, затем расшифровывает алгоритмом ChaCha20-Poly1305.

### Список параметров

`ciphertext`
  Параметр должен быть в формате, который предоставила функция sodium_crypto_aead_chacha20poly1305_encrypt() (зашифрованный текст и тег, объединённые).
`additional_data`
  Дополнительные проверенные данные. Это используется при проверке тега подлинности, добавленного к зашифрованному тексту, но он не шифруется и не сохраняется в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 8 байт.
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст или `false`, если возникла ошибка.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Шифрует, а затем проверяет подлинность алгоритмом ChaCha20-Poly1305

### Описание

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Функция шифрует, а затем проверяет подлинность алгоритмом ChaCha20-Poly1305.

### Список параметров

`message`
  Текстовое сообщение, которое требуется зашифровать.
`additional_data`
  Дополнительные проверенные данные. Функция использует значение при проверке тега подлинности, который добавили к зашифрованному тексту, но не шифрует и не сохраняет в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 8 байтов.
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

В случае успешного выполнения функция возвращает зашифрованный текст и тег или `false`, если возникла ошибка.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Проверяет, содержит ли зашифрованный текст допустимый тег

### Описание

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Функция проверяет, а затем расшифровывает алгоритмом ChaCha20-Poly1305 (вариант совета IETF).

Вариант совета IETF использует 96-битные одноразовые номера и 32-битные внутренние счётчики вместо 64-битных и для того и для другого.

### Список параметров

`ciphertext`
  Параметр должен быть в формате, который предоставила функция sodium_crypto_aead_chacha20poly1305_ietf_encrypt() (зашифрованный текст и тег, объединённые).
`additional_data`
  Дополнительные проверенные данные. Функция использует значение при проверке тега подлинности, который добавили к зашифрованному тексту, но не шифрует и не сохраняет в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 12 байтов.
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст или `false`, если возникла ошибка.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Шифрует сообщение

### Описание

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Функция шифрует, а затем проверяет подлинность алгоритмом ChaCha20-Poly1305 (вариант совета IETF).

Вариант совета IETF использует 96-битные одноразовые номера и 32-битные внутренние счётчики вместо 64-битных и для того и для другого.

### Список параметров

`message`
  Текстовое сообщение, которое нужно зашифровать.
`additional_data`
  Дополнительные проверенные данные. Функция использует значение при проверке тега подлинности, который добавили к зашифрованному тексту, но он не шифрует и не сохраняет в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 12 байт.
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

В случае успешного выполнения функция возвращает зашифрованный текст и тег или `false`, если возникла ошибка.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Создаёт случайный ключ ChaCha20-Poly1305 (IETF)

### Описание

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Создаёт случайный ключ для использования в sodium_crypto_aead_chacha20poly1305_ietf_encrypt() и sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 256-битный случайный ключ.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Создаёт случайный ключ ChaCha20-Poly1305

### Описание

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Создаёт случайный ключ для использования в sodium_crypto_aead_chacha20poly1305_encrypt() и sodium_crypto_aead_chacha20poly1305_decrypt().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 256-битный случайный ключ.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Предпочтительно) Проверяет, затем расшифровывает алгоритмом XChaCha20-Poly1305

### Описание

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

(Предпочтительно) Функция проверяет, затем расшифровывает алгоритмом XChaCha20-Poly1305

Как правило, алгоритм XChaCha20-Poly1305 — лучший из имеющихся режимов AEAD.

### Список параметров

`ciphertext`
  Параметр принимает значение в формате, который предоставила функция sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() (зашифрованный текст и тег, объединённые).
`additional_data`
  Дополнительные проверенные данные. Функция использует значение при проверке тега подлинности, который добавили к зашифрованному тексту, но не шифрует и не сохраняет в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайным образом (то есть функцией random_bytes()).
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

В случае успешного выполнения функция возвращает текст или `false`, если возникла ошибка.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Предпочтительно) Шифрует, а затем проверяет подлинность алгоритмом XChaCha20-Poly1305

### Описание

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Функция шифрует, а затем проверяет подлинность алгоритмом XChaCha20-Poly1305(вариант eXtended-nonce).

Как правило, алгоритм XChaCha20-Poly1305 — лучший из имеющихся режимов AEAD.

### Список параметров

`message`
  Текстовое сообщение, которое нужно зашифровать.
`additional_data`
  Дополнительные проверенные данные. Функция использует значение при проверке тега подлинности, который добавили к зашифрованному тексту, но не шифрует и не сохраняет в зашифрованном тексте.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы её случайным образом (то есть функцией random_bytes()).
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

В случае успешного выполнения функция возвращает зашифрованный текст и тег или `false`, если возникла ошибка.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Создаёт случайный ключ XChaCha20-Poly1305

### Описание

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Создаёт случайный ключ для использования в sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() и sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 256-битный случайный ключ.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Вычисляет тег для сообщения

### Описание

function sodium_crypto_auth(string `$message`, string `$key`): string

Симметричная проверка подлинности сообщения функцией sodium_crypto_auth() обеспечивает целостность, но не конфиденциальность.

В отличие от цифровых подписей (например, которые создаёт функция sodium_crypto_sign_detached()), любая сторона, которая способна проверить сообщение, также способна проверить подлинность своих собственных сообщений. (Следовательно, аутентификация — симметричная.)

### Список параметров

`message`
  Сообщение, которое требуется подтвердить.
`key`
  Ключ аутентификации.

### Возвращаемые значения

Функция возвращает тег аутентификации.

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Создаёт случайный ключ для sodium_crypto_auth

### Описание

function sodium_crypto_auth_keygen(): string

Создаёт ключ для использования в sodium_crypto_auth() и sodium_crypto_auth_verify().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 256-битный случайный ключ.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Проверяет, допустим ли тег для сообщения

### Описание

function sodium_crypto_auth_verify(string `$mac`, string `$message`, #[\SensitiveParameter]string `$key`): bool

Функция проверяет, что тег аутентификации действителен для сообщения и ключа.

В отличие от цифровых подписей (например, которые проверяет функция sodium_crypto_sign_verify_detached()), любая сторона, которая способна проверить сообщение, также способна проверить подлинность своих собственных сообщений. (Следовательно, проверка подлинности — симметричная.)

### Список параметров

`mac`
  Тег аутентификации, который создала функция sodium_crypto_auth().
`message`
  Сообщение.
`key`
  Ключ аутентификации.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Шифрует открытым ключом с проверкой подлинности

### Описание

function sodium_crypto_box(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string

Функция шифрует сообщение асимметричной криптографией (с открытым ключом).

Алгоритм, который используют функции с префиксом sodium_crypto_box(): Эллиптическая кривая Диффи-Хеллмана на кривой Монтгомери, Curve25519; обычно сокращённо X25519.

### Список параметров

`message`
  Сообщение, которое нужно зашифровать.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайно (например, функцией random_bytes()).
`key_pair`
  Смотрите описание функции sodium_crypto_box_keypair_from_secretkey_and_publickey(). Параметр должен включать секретный ключ X25519 отправителя и открытый ключ X25519 получателя.

### Возвращаемые значения

Функция возвращает зашифрованное сообщение (зашифрованный текст плюс тег аутентификации). Зашифрованный текст будет на 16 байтов длиннее, чем открытый текст, и необработанная двоичная строка. Смотрите описание функции sodium_bin2base64() для безопасного кодирования для хранения.

# sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Генерирует случайным образом секретный и открытый ключ, который соответствует закрытому

### Описание

function sodium_crypto_box_keypair(): string

Функция создаёт секретный и открытый ключи как одну строку.

Как получить секретный ключ из этой унифицированной строки ключевой пары, рассказывает описание функции sodium_crypto_box_secretkey(). Как получить открытый ключ из этой унифицированной строки ключевой пары, рассказывает описание функции sodium_crypto_box_publickey().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает одну строку, которая содержит секретный ключ X25519 и открытый ключ X25519, который соответствует секретному.

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Создаёт унифицированную строку ключевой пары из секретного и открытого ключей

### Описание

function sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Функция существует для удовлетворения требований API функций наподобие crypto_box(). При передаче секретного ключа одной стороны и открытого ключа другой получают пару для коммуникации.

### Список параметров

`secret_key`
  Секретный ключ.
`public_key`
  Открытый ключ.

### Возвращаемые значения

Функция возвращает ключевую пару X25519.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Расшифровывает открытый ключ с проверкой подлинности

### Описание

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string|false

Функция расшифровывает сообщение через асимметричную криптографию (с открытым ключом).

### Список параметров

`ciphertext`
  Зашифрованное сообщение, которое нужно попытаться расшифровать.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайным образом (например, функцией random_bytes()).
`key_pair`
  Смотрите описание функции sodium_crypto_box_keypair_from_secretkey_and_publickey(). Значение должно включать открытый ключ отправителя и секретный ключ получателя.

### Возвращаемые значения

Функция возвращает сообщение в случае успешного выполнения или `false`, если возникла ошибка.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Извлекает открытый ключ из ключевой пары crypto_box

### Описание

function sodium_crypto_box_publickey(#[\SensitiveParameter]string `$key_pair`): string

Функция получает только открытый ключ из ключевой пары.

### Список параметров

`key_pair`
  Ключевая пара, которую создали, например, функциями sodium_crypto_box_keypair() или sodium_crypto_box_seed_keypair().

### Возвращаемые значения

Функция возвращает открытый ключ X25519.

# sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Вычисляет открытый ключ из секретного ключа

### Описание

function sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Функция вычисляет открытый ключ с учётом секретного ключа.

Функция работает только с типом ключей, который предназначен для работы с функцией crypto_box(), которая шифрует данные на основе эллиптической кривой Диффи-Хеллмана на кривой Монтгомери, Curve25519; сокращённо X25519, а не функцией crypto_sign(), которая работает на основе алгоритма цифровой подписи Эдвардса на эллиптической кривой Эдвардса с соответствующими параметрами; сокращённо Ed25519.

### Список параметров

`secret_key`
  Секретный ключ X25519.

### Возвращаемые значения

Функция возвращает открытый ключ X25519.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Шифрует открытым ключом без проверки подлинности

### Описание

function sodium_crypto_box_seal(#[\SensitiveParameter]string `$message`, string `$public_key`): string

Функция шифрует сообщение так, что только получатель может его расшифровать.

В отличие от функции sodium_crypto_box(), требуется знать только открытый ключ получателя, чтобы использовать функцию sodium_crypto_box_seal(). Однако одно из следствий этого удобства - то, что зашифрованный текст не привязан к статическому открытому ключу и, следовательно, не аутентифицируется. Следовательно, выполняется шифрование открытым ключом без проверки подлинности.

Функция sodium_crypto_box_seal() по-прежнему обеспечивает целостность зашифрованного текста. Только не проверяет подлинность отправителя.

Если требуется также проверка подлинности отправителя, лучше всего начать с функций sodium_crypto_sign().

### Список параметров

`message`
  Сообщение, которое нужно зашифровать.
`public_key`
  Открытый ключ, который соответствует единственному ключу, который может расшифровать сообщение.

### Возвращаемые значения

Функция возвращает строку зашифрованного текста в формате (одноразовый открытый ключ, зашифрованное сообщение, тег аутентификации).

### Примеры

Пример #1 Пример использования функции sodium_crypto_box_seal()

    <?php

    $keypair = sodium_crypto_box_keypair();
    $public_key = sodium_crypto_box_publickey($keypair);

    // Обфусцированный текст, чтобы сделать пример более увлекательным
    $plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
    $decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
    var_dump(base64_encode($sealed));

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);

    ?>

Вывод приведённого примера будет похож на:

    string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Расшифровывает открытым ключом без проверки подлинности

### Описание

function sodium_crypto_box_seal_open(string `$ciphertext`, #[\SensitiveParameter]string `$key_pair`): string|false

Функция расшифровывает сообщение, которое зашифровали функцией sodium_crypto_box_seal().

### Список параметров

`ciphertext`
  Зашифрованное сообщение
`key_pair`
  Ключевая пара получателя. Должна включать секретный ключ.

### Возвращаемые значения

Функция возвращает текст в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции sodium_crypto_box_seal_open()

    <?php

    // Шифрованный текст нечувствителен; base64_decode в порядке
    $sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
    $sealed = base64_decode($sealed_b64);

    // Ключевая пара содержит криптографический секрет; использовать безопасный по времени декодер
    $keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
    $keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);

    ?>

Вывод приведённого примера будет похож на:

    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Извлекает секретный ключ из ключевой пары crypto_box

### Описание

function sodium_crypto_box_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Функция получает только секретный ключ для ключевой пары.

### Список параметров

`key_pair`
  Пара ключей, которую создали, например, функциями sodium_crypto_box_keypair() или sodium_crypto_box_seed_keypair()

### Возвращаемые значения

Функция возвращает секретный ключ X25519.

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Выводит ключевую пару из одного ключа детерминистическим способом

### Описание

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Функция скрепляет начальное значение для формирования секретного ключа, извлекает открытый ключ и возвращает их в виде пары ключей.

Функции `*_seed_keypair` идеально подходят, чтобы создавать пары ключей из пароля и соли. Используйте результат как `seed` для генерации желаемых ключей.

### Список параметров

`seed`
  Какие-то криптографические данные. Должно быть 32 байта.

### Возвращаемые значения

Функция возвращает ключевую пару X25519 (секретный и открытый ключи).

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — Добавляет элемент

### Описание

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Добавляет элемент `q` к `p`. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`p`
  Элемент.
`q`
  Элемент.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_random() - Генерирует случайный ключ
- sodium_crypto_core_ristretto255_sub() - Вычитает элемент

# sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — Сопоставляет вектор

### Описание

function sodium_crypto_core_ristretto255_from_hash(string `$s`): string

Сопоставляет вектор 64-байтовый вектор `s` с элементом группы. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  64-байтовый вектор.

### Возвращаемые значения

Возвращает 32-байтовую случайную строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_from_hash()

    <?php

    $hashes = sodium_hex2bin(
        '5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
        '4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
    );
    var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
    ?>

Результат выполнения приведённого примера:

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### Смотрите также

- sodium_hex2bin() - Декодирует строку в шестнадцатеричном представлении в двоичное
- sodium_bin2hex() - Кодирует в шестнадцатеричное представление
- sodium_crypto_core_ristretto255_from_hash()

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — Определяет, лежит ли точка на кривой ristretto255

### Описание

function sodium_crypto_core_ristretto255_is_valid_point(string `$s`): bool

Определяет, лежит ли точка на кривой ristretto255 в канонической форме на главной подгруппе и что точка не имеет малого порядка. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  Точка эллиптической кривой.

### Возвращаемые значения

Возвращает `true`, если точка `s` находится на кривой ristretto255, в противном случае возвращает`false`.

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_is_valid_point()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_scalarmult_ristretto255_base($foo);

    var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ
- sodium_crypto_scalarmult_ristretto255_base() - Вычисляет открытый ключ из закрытого ключа

# sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — Генерирует случайный ключ

### Описание

function sodium_crypto_core_ristretto255_random(): string

Генерирует случайный ключ. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_add() - Добавляет элемент
- sodium_crypto_core_ristretto255_sub() - Вычитает элемент

# sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — Добавляет скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_add(string `$x`, string `$y`): string

Добавляет элемент `y` к `x`. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`x`
  Скаляр, представляющий координату X.
`y`
  Скаляр, представляющий координату Y.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_scalar_add()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ
- sodium_crypto_core_ristretto255_scalar_sub() - Вычитает скалярное значение

# sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — Назначает основное скалярное дополнение в формате ristretto255

### Описание

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Функция доступна с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  Скалярное значение.

### Возвращаемые значения

Функция возвращает случайную 32-байтовую строку string.

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ

# sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — Инвертирует скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Инвертирует скалярное значение. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  Скалярное значение.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_scalar_invert()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
    $reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

    var_dump(hash_equals($foo, $reInverted));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ

# sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — Умножает скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Умножает скалярное значение. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`x`
  Скаляр, представляющий координату X.
`y`
  Скаляр, представляющий координату Y.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ

# sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — Отменяет скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Отменяет скалярное значение. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  Скалярное значение.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_scalar_negate()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
    $reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

    var_dump(hash_equals($foo, $reNegate));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ

# sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — Генерирует случайный ключ

### Описание

function sodium_crypto_core_ristretto255_scalar_random(): string

Генерирует случайный ключ. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_scalar_random()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_add() - Добавляет скалярное значение
- sodium_crypto_core_ristretto255_scalar_sub() - Вычитает скалярное значение

# sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — Уменьшает скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Уменьшает скалярное значение. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`s`
  Скалярное значение.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ

# sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — Вычитает скалярное значение

### Описание

function sodium_crypto_core_ristretto255_scalar_sub(string `$x`, string `$y`): string

Вычитает скалярное значение `y` из `x`. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`x`
  Скаляр, представляющий координату X.
`y`
  Скаляр, представляющий координату Y.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_scalar_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_scalar_random() - Генерирует случайный ключ
- sodium_crypto_core_ristretto255_scalar_add() - Добавляет скалярное значение

# sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — Вычитает элемент

### Описание

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Вычитает элемент `q` из `p`. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`p`
  Элемент.
`q`
  Элемент.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Примеры

Пример #1 Пример использования sodium_crypto_core_ristretto255_sub()

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_crypto_core_ristretto255_random() - Генерирует случайный ключ
- sodium_crypto_core_ristretto255_add() - Добавляет элемент

# sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Получает хеш сообщения

### Описание

function sodium_crypto_generichash(string `$message`, string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Функция хеширует сообщение алгоритмом BLAKE2b.

### Список параметров

`message`
  Хешируемое сообщение.
`key`
  (Необязательный) криптографический ключ. Ключ выполняет ту же функцию, что и ключ HMAC, но используется как зарезервированный раздел внутреннего состояния BLAKE2.
`length`
  Размер вывода.

### Возвращаемые значения

Функция возвращает криптографический хеш в виде необработанных байтов. Если требуется вывод в шестнадцатеричном коде, результат передают в функцию sodium_bin2hex().

# sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Заканчивает хеширование

### Описание

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Метод завершения для потокового API-интерфейса generichash.

### Список параметров

`state`
  Состояние хеша, которое вернула функция sodium_crypto_generichash_init().
`length`
  Длина вывода.

### Возвращаемые значения

Функция возвращает криптографический хеш.

### Примеры

Пример #1 Пример использования функции sodium_crypto_generichash_final()

    <?php

    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);

    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));

    ?>

Вывод приведённого примера будет похож на:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Инициализирует хеш для потоковой передачи

### Описание

function sodium_crypto_generichash_init(#[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Метод инициализации для потокового API-интерфейса generichash.

### Список параметров

`key`
  Ключ generichash.
`length`
  Ожидаемая длина вывода хеш-функции.

### Возвращаемые значения

Функция возвращает состояние хеша, который сериализовала как необработанную двоичную строку.

### Примеры

Пример #1 Пример использования sodium_crypto_generichash_init()

    <?php

    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);

    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));

    ?>

Вывод приведённого примера будет похож на:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Создаёт случайный общий хеш-ключ

### Описание

function sodium_crypto_generichash_keygen(): string

Создаёт случайный ключ для использования с API generichash.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Случайный 256-битный ключ.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Добавляет сообщение к хешу

### Описание

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Функция добавляет сообщение к внутреннему хеш-состоянию.

### Список параметров

`state`
  Значение, которое вернула функция sodium_crypto_generichash_init().
`message`
  Данные для добавления в состояние хеширования.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Пример использования функции sodium_crypto_generichash_update()

    <?php

    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init();

    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));

    ?>

Вывод приведённого примера будет похож на:

    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"

# sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Извлекает подраздел

### Описание

function sodium_crypto_kdf_derive_from_key(
int `$subkey_length`,
int `$subkey_id`,
string `$context`,
#[\SensitiveParameter]string `$key`
): string

Функция получает подраздел из корневого ключа и дополнительного контекста.

Функция работает аналогично функции hash_hkdf().

### Список параметров

`subkey_length`
  Длина возвращаемого ключа (в байтах).
`subkey_id`
  Вернуть n-й подключ из заданного корневого ключа. Полезно для поиска.
`context`
  Контекст, который зависит от приложения.
`key`
  Корневой ключ, из которого получили подключ.

### Возвращаемые значения

Функция возвращает строку псевдослучайных (необработанных двоичных) байтов.

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Создаёт случайный корневой ключ для интерфейса KDF

### Описание

function sodium_crypto_kdf_keygen(): string

Создаёт случайный ключ, подходящий для использования в качестве корневого ключа для sodium_crypto_kdf_derive_from_key().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Случайный 256-битный ключ.

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Вычисляет ключи сессии на стороне клиента

### Описание

function sodium_crypto_kx_client_session_keys(#[\SensitiveParameter]string `$client_key_pair`, string `$server_key`): array

Функция вычисляет ключи сеанса на стороне клиента методом обмена ключами X25519 + BLAKE2b.

### Список параметров

`client_key_pair`
  Пара ключей crypto_kx, которую, например, сгенерировала функция sodium_crypto_kx_keypair().
`server_key`
  Открытый ключ crypto_kx.

### Возвращаемые значения

Функция возвращает массив, который состоит из двух строк. Первая используется для приёма данных с сервера. Вторая — для отправки данных на сервер.

# sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Создаёт новую пару ключей sodium

### Описание

function sodium_crypto_kx_keypair(): string

Создать новую пару ключей sodium, состоящую из секретного ключа (32 байта) и следующего за ним открытого ключа (32 байта). Ключи можно получить, вызвав sodium_crypto_kx_secretkey() и sodium_crypto_kx_publickey() соответственно.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новую пару ключей в случае успешного выполнения; выбрасывает исключение в противном случае.

### Примеры

Пример #1 Пример использования sodium_crypto_kx_keypair()

Создать новую пару ключей и извлечь из неё секретный и открытый ключи.

    <?php
    $keypair = sodium_crypto_kx_keypair();
    $secret = sodium_crypto_kx_secretkey($keypair);
    $public = sodium_crypto_kx_publickey($keypair);
    printf("секретный ключ: %s\nоткрытый ключ: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
    ?>

Вывод приведённого примера будет похож на:

    секретный ключ: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
    открытый ключ: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Извлекает открытый ключ из пары ключей crypto_kx

### Описание

function sodium_crypto_kx_publickey(#[\SensitiveParameter]string `$key_pair`): string

Функция извлекает открытый ключ из пары ключей crypto_kx.

### Список параметров

`key_pair`
  Пара ключей X25519, которую сгенерировала, например, функция sodium_crypto_kx_keypair().

### Возвращаемые значения

Функция возвращает открытый ключ X25519.

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Извлекает секретный ключ из пары ключей crypto_kx

### Описание

function sodium_crypto_kx_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Функция извлекает секретный ключ из пары ключей crypto_kx.

### Список параметров

`key_pair`
  Пара ключей X25519, которую сгенерировала, например, функция sodium_crypto_kx_keypair().

### Возвращаемые значения

Функция возвращает секретный ключ X25519.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Возвращает описание

### Описание

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`seed`

### Возвращаемые значения

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Вычисляет ключи сессии на стороне сервера

### Описание

function sodium_crypto_kx_server_session_keys(#[\SensitiveParameter]string `$server_key_pair`, string `$client_key`): array

Функция вычисляет ключи сессии на стороне сервера методом обмена ключами X25519 + BLAKE2b.

### Список параметров

`server_key_pair`
  Пара ключей crypto_kx, которую сгенерировала, например, функция sodium_crypto_kx_keypair().
`client_key`
  Открытый ключ crypto_kx.

### Возвращаемые значения

Функция возвращает массив, который состоит из двух строк. Первая используется для получения данных от клиента. Вторая — для отправки данных клиенту.

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Получает ключ из пароля алгоритмом Argon2

### Описание

function sodium_crypto_pwhash(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`,
int `$algo` = `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT`
): string

Функция предоставляет низкоуровневый доступ к функции crypto_pwhash библиотеки libsodium. Если у отсутствует принципиальная необходимость в этой функции, лучше пользоваться функциями sodium_crypto_pwhash_str() или password_hash().

Распространённая причина, по которой вызывают эту функцию — получить начальные числа для криптографических ключей из пароля и соли, а затем использовать эти начальные числа для генерации фактических ключей, необходимых для некоторых целей (например, подписать сообщение, как делает функция sodium_crypto_sign_detached()).

### Список параметров

`length`
  Целое число (int); Длина хеша пароля в байтах.
`password`
  Строка (string); Пароль, для которого функция создаёт хеш.
`salt`
  Соль, которую добавляют к паролю перед хешированием. Соль должна быть непредсказуемой, в идеале генерироваться из хорошего источника случайных чисел наподобие функции random_bytes() и быть длиной, равной значению константы `SODIUM_CRYPTO_PWHASH_SALTBYTES`.
`opslimit`
  Представляет максимальное количество вычислений для выполнения Увеличение этого числа приведёт к тому, что функции потребуется больше циклов ЦП для вычисления ключа. Существуют константы, доступные для установки предела операций для соответствующих значений в зависимости от предполагаемого использования, в порядке убывания: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` и `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  Максимальный объем ОЗУ в байтах, который будет использовать функция. Выбрать подходящее значение помогают константы в порядке размера: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` и `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Как правило, константы должны сочетаться со значениями `opslimit`, которым они соответствуют.
`algo`
  Целое число (int), которое указывает алгоритм хеширования. По умолчанию задана константа `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (рекомендуемый алгоритм, который изменяется от версии к версии модуля libsodium), или явно задать константу `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13`, которая представляет версию алгоритма Argon2id 1.3.

### Возвращаемые значения

Функция возвращает захешированный пароль. Возвращаемое значение — двоичная строка хеша, а не ASCII-представление, и не содержит дополнительной информации о параметрах, с которыми генерировался хеш, поэтому разработчик сам сохраняет значения параметров для проверки корректности хеша в будущем. Чтобы избежать этого, пользуются функцией sodium_crypto_pwhash_str().

### Примеры

Пример #1 Пример использования функции sodium_crypto_pwhash()

    <?php

    // Для будущей проверки нужно сохранить соль
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);

    // Вызываем функцию bin2hex для удобочитаемости
    echo bin2hex(
        sodium_crypto_pwhash(
            16, // == 128 бит
            'password',
            $salt,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
        )
    );

    ?>

Вывод приведённого примера будет похож на:

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Получает ключ из пароля функцией scrypt

### Описание

function sodium_crypto_pwhash_scryptsalsa208sha256(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`
): string

Функция работает аналогично функции scrypt sodium_crypto_pwhash().

Распространённая причина, по которой вызывают эту функцию — получить начальные числа для криптографических ключей из пароля и соли, а затем использовать эти начальные числа для генерации фактических ключей, необходимых для отдельных целей (например, подписи сообщения, как это делает функция sodium_crypto_sign_detached()).

### Список параметров

`length`
  Длина генерируемого хеша пароля в байтах.
`password`
  Пароль, для которого создаётся хеш.
`salt`
  Соль, которую нужно добавить к паролю перед хешированием. Соль должна быть непредсказуемой, в идеале сгенерированной из хорошего источника случайных чисел наподобие функции random_bytes(), и иметь длину в байтах не меньше, чем значение константы `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES`.
`opslimit`
  Представляет максимальное количество вычислений для выполнения. Увеличение этого числа приведёт к тому, что функции потребуется больше циклов ЦП для вычисления ключа. Доступны некоторые константы для установки предела операций на соответствующие значения в зависимости от предполагаемого использования, в порядке размера: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` и `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE`.
`memlimit`
  Максимальный объем ОЗУ в байтах, который будет использовать функция. Выбрать требуемое значение в порядке размера помогают существующие константы: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` и `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE`. Обычно они должны сочетаться с значениями параметра `opslimit`, которые соответствуют константам.

### Возвращаемые значения

Функция возвращает строку байтов требуемой длины.

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Получает хеш в кодировке ASCII

### Описание

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`password`
`opslimit`
`memlimit`

### Возвращаемые значения

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Проверяет, что пароль — действительная строка проверки пароля

### Описание

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`hash`
`password`

### Возвращаемые значения

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Получает ASCII-кодированный хеш

### Описание

function sodium_crypto_pwhash_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Функция использует ресурсоёмкий по ЦПУ и памяти алгоритм хеширования, а также случайно сгенерированную соль и ограничения по памяти и процессору для генерации хэша в кодировке ASCII, который подходит для хранения паролей.

### Список параметров

`password`
  Строка (string); пароль, для которого функция сгенерирует хеш.
`opslimit`
  Задаёт ограничение на потребление процессорного времени. Увеличение этого числа приведет к тому, что функции потребуется больше циклов ЦП для вычисления ключа. Предел операций на соответствующие значения в зависимости от предполагаемого использования устанавливают константами в порядке силы: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` и `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  Максимальный объем оперативной памяти в байтах, которую будет использовать функция. В выборе подходящего значения помогают константы в порядке размера: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` и `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Обычно константы должны сочетаться со значениями opslimit, которые им соответствуют.

### Возвращаемые значения

Функция возвращает хеш пароля.

Чтобы для одного и того же пароля каждый раз генерировался один и тот же хеш, устанавливают одинаковые значения параметров `opslimit` и `memlimit`. Поскольку эти параметры функция включает в сгенерированный хеш, функция sodium_crypto_pwhash_str_verify() может проверять его корректность без необходимости хранить эти параметры отдельно.

### Примеры

Пример #1 Пример использования функции sodium_crypto_pwhash_str()

    <?php

    $password = 'password';

    echo sodium_crypto_pwhash_str(
        $password,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );

    ?>

Вывод приведённого примера будет похож на:

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### Примечания

> Замечание: Хеши вычисляются алгоритмом Argon2ID, который устойчив к атакам стороннего канала и GPU. В отличие от функции password_hash(), у этой функции нет параметра salt (он генерируется автоматически), а параметры `opslimit` и `memlimit` — обязательные.

### Смотрите также

- sodium_crypto_pwhash_str_verify() - Проверяет соответствие пароля хешу
- sodium_crypto_pwhash() - Получает ключ из пароля алгоритмом Argon2
- password_hash() - Создаёт хеш пароля
- password_verify() - Проверяет, соответствует ли пароль хешу
- » Документация на Libsodium Argon2

# sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Определяет, следует ли повторно использовать пароль

### Описание

function sodium_crypto_pwhash_str_needs_rehash(string `$password`, int `$opslimit`, int `$memlimit`): bool

Определяет, следует ли повторно использовать пароль, на основе текущего хеш-значения `opslimit` и `memlimit`.

### Список параметров

`password`
  Хеш пароля
`opslimit`
  Настроенный opslimit; смотрите sodium_crypto_pwhash_str()
`memlimit`
  Настроенный memlimit; смотрите sodium_crypto_pwhash_str()

### Возвращаемые значения

Возвращает `true`, если предоставленный memlimit/opslimit не соответствует тому, что хранится в хеше. Возвращает `false`, если они совпадают.

# sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Проверяет соответствие пароля хешу

### Описание

function sodium_crypto_pwhash_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Функция проверяет, соответствует ли хеш пароля, который создала функция sodium_crypto_pwhash_str(), паролю. Обратите внимание, что в этой функции порядок аргументов не соответствует порядку аргументов в похожей функции password_verify().

### Список параметров

`hash`
  Хеш, который создаёт функция password_hash().
`password`
  Пользовательский пароль.

### Возвращаемые значения

Функция возвращает `true`, если пароль соответствует хешу, и `false`, если нет.

### Примечания

> Замечание: Хеши вычисляются алгоритмом Argon2ID, который хорошо противостоит обоим видам атак: GPU и атакам по стороннему каналу.

### Смотрите также

- sodium_crypto_pwhash_str() - Получает ASCII-кодированный хеш
- password_hash() - Создаёт хеш пароля
- password_verify() - Проверяет, соответствует ли пароль хешу

# sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Вычисляет общий секрет на основании секретного ключа пользователя и открытого ключа другого пользователя

### Описание

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Эллиптическая кривая Диффи-Хеллмана. Функция вычисляет n-й скаляр, умноженный на точку p на эллиптической кривой.

### Список параметров

`n`
  Скаляр, который обычно является секретным ключом.
`p`
  Точка (координата x), которая обычно является открытым ключом.

### Возвращаемые значения

Функция возвращает 32-байтовую случайную строку.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — Псевдоним sodium_crypto_box_publickey_from_secretkey()

### Описание

Псевдоним функции sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Вычисляет общий секрет

### Описание

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Вычисляет скаляр `n`, умноженный на точку `p`. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`n`
  Скаляр, который обычно является закрытым ключом.
`p`
  Точка (x-координата), которая обычно является открытым ключом.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Смотрите также

- sodium_crypto_scalarmult_ristretto255_base() - Вычисляет открытый ключ из закрытого ключа

# sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — Вычисляет открытый ключ из закрытого ключа

### Описание

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

Учитывая закрытый ключ, вычисляет соответствующий открытый ключ. Доступно, начиная с libsodium 1.0.18.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`n`
  Закрытый ключ.

### Возвращаемые значения

Возвращает случайную 32-байтовую строку (string).

### Смотрите также

- sodium_crypto_scalarmult_ristretto255() - Вычисляет общий секрет

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Шифрует общим ключом с проверкой подлинности

### Описание

function sodium_crypto_secretbox(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Функция шифрует сообщения симметричным (общим) ключом.

### Список параметров

`message`
  Текстовое сообщение, которое нужно зашифровать.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайно (например, функцией random_bytes()).
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

Функция возвращает зашифрованную строку.

### Ошибки

- Функция выбрасывает исключение SodiumException, если длина байтов параметра `nonce` отличается от значения константы `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 байта).
- Функция выбрасывает исключение SodiumException, если длина байтов параметра `key` отличается от значения константы `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 байта).
- Функция выбрасывает исключение SodiumException, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции sodium_crypto_secretbox()

    <?php

    // Значение переменной $key должно храниться в секрете
    $key = sodium_crypto_secretbox_keygen();

    // Не используйте переменную $nonce повторно с тем же ключом
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $plaintext = "message to be encrypted";
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

    var_dump(bin2hex($ciphertext));

    // Для расшифровки переменной $ciphertext требуются те же nonce и ключ
    var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));

    ?>

Вывод приведённого примера будет похож на:

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "message to be encrypted"

### Смотрите также

- sodium_crypto_secretbox_open() - Расшифровывает общим ключом с проверкой подлинности
- sodium_crypto_secretbox_keygen() - Создаёт случайный ключ для sodium_crypto_secretbox
- random_bytes() - Генерирует криптографически безопасные случайные байты

# sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Создаёт случайный ключ для sodium_crypto_secretbox

### Описание

function sodium_crypto_secretbox_keygen(): string

Создаёт случайный ключ для sodium_crypto_secretbox() и sodium_crypto_secretbox_open().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сгенерированную строку криптографически безопасных случайных байтов.

### Примеры

Пример #1 Пример использования sodium_crypto_secretbox_keygen()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

Вывод приведённого примера будет похож на:

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

Пример #2 Сравнение sodium_crypto_secretbox_keygen() с random_bytes()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    $bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
    var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- sodium_bin2hex() - Кодирует в шестнадцатеричное представление
- random_bytes() - Генерирует криптографически безопасные случайные байты

# sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Расшифровывает общим ключом с проверкой подлинности

### Описание

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key`): string|false

Функция расшифровывает зашифрованное сообщение симметричным (общим) ключом.

### Список параметров

`ciphertext`
  Параметр должен быть в формате, который предоставляет функция sodium_crypto_secretbox() (зашифрованный текст и тег, объединённые).
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайно (например, функцией random_bytes()).
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

Функция возвращает расшифрованную строку в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

- Функция выбрасывает исключение SodiumException, если длина байтов параметра `nonce` отличается от значения константы `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 байта).
- Функция выбрасывает исключение SodiumException, если длина байтов параметра `key` отличается от значения константы `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 байта).

### Примеры

Пример #1 Пример использования функции sodium_crypto_secretbox_open()

    <?php

    // Значение переменной $key должно храниться в секрете
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);

    // Не используйте переменную $nonce повторно с тем же ключом
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('message to be encrypted', $nonce, $key);

    // Для расшифровки переменной $ciphertext требуются те же nonce и ключ
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);

    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }

    ?>

Результат выполнения приведённого примера:

    message to be encrypted

### Смотрите также

- sodium_crypto_secretbox() - Шифрует общим ключом с проверкой подлинности
- sodium_crypto_secretbox_keygen() - Создаёт случайный ключ для sodium_crypto_secretbox
- random_bytes() - Генерирует криптографически безопасные случайные байты

# sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Инициализирует контекст secretstream для дешифрования

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter]string `$key`): string

Функция инициализирует контекст secretstream для дешифрования.

### Список параметров

`header`
  Заголовок secretstream. Значение параметра должно быть одним из значений, которые создает функция sodium_crypto_secretstream_xchacha20poly1305_init_push().
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

Состояние secretstream.

### Примеры

Пример #1 Пример использования функции sodium_crypto_secretstream_xchacha20poly1305_init_pull()

    <?php

    function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        $header = fread($inputFile, 24);

        $state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
        $inputFileSize = fstat($inputFile)['size'];

        // Расшифровка файла и запись содержимого в выходной файл:
        for ($i = 24; $i < $inputFileSize; $i += 8192) {
            $ctxt_chunk = fread($inputFile, 8192);

            // Мы не используем переменную $tag, но в реальных протоколах его разрешается использовать для шифрования, например,
            // инициировать смену ключа или указать конец файла. Затем при расшифровке
            // можно подтвердить это поведение
            [$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
            fwrite($outputFile, $ptxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    $example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
    file_put_contents('hello.enc', $example);
    decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
    var_dump(file_get_contents('hello.txt.decrypted'));

    ?>

Вывод приведённого примера будет похож на:

    string(12) "Hello world!"

# sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Инициализирует контекст secretstream для шифрования

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter]string `$key`): array

Функция инициализирует контекст secretstream для шифрования

### Список параметров

`key`
  Ключ криптографии. Смотрите описание функции sodium_crypto_secretstream_xchacha20poly1305_keygen().

### Возвращаемые значения

Функция возвращает массив с двумя строковыми значениями:

- Состояние secretstream, необходимое для дальнейших действий
- Заголовок secretstream, который необходимо предоставить получателю, чтобы он мог извлекать данные.

### Примеры

Пример #1 Пример использования функции sodium_crypto_secretstream_xchacha20poly1305_init_push()

    <?php

    function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        [$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        // Запись заголовка:
        fwrite($outputFile, $header);
        $inputFileSize = fstat($inputFile)['size'];

        // Зашифровка файла и запись его содержимого в выходной файл:
        for ($i = 0; $i < $inputFileSize; $i += 8175) {
            $ptxt_chunk = fread($inputFile, 8175);
            $ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
            fwrite($outputFile, $ctxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    file_put_contents('hello.txt', 'Hello world!');
    encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
    var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));

    ?>

Вывод приведённого примера будет похож на:

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Создаёт случайный ключ secretstream

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Создаёт случайный ключ secretstream

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку случайных байтов.

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Расшифровывает часть данных из зашифрованного потока

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Расшифровывает часть данных из зашифрованного потока.

### Список параметров

`state`
  Смотрите sodium_crypto_secretstream_xchacha20poly1305_init_pull() и sodium_crypto_secretstream_xchacha20poly1305_init_push()
`ciphertext`
  Фрагмент зашифрованного текста, который нужно расшифровать.
`additional_data`
  Необязательные дополнительные данные для включения в тег аутентификации.

### Возвращаемые значения

Массив с двумя значениями:

- Строка (string); Расшифрованный фрагмент

- Целое число (int); Необязательный тег (если предоставляется во время отправки). Возможные значения:

  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: самый распространённый тег, который не добавляет никакой информации о характере сообщения.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: указывает, что сообщение отмечает конец потока, и стирает секретный ключ, использованный для шифрования предыдущей последовательности.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: указывает, что сообщение отмечает конец набора сообщений, но не конец потока. Например, огромная строка JSON, отправленная в виде нескольких фрагментов, может использовать этот тег, чтобы указать приложению, что строка завершена и что её можно декодировать. Но сам поток не закрывается и могут последовать дополнительные данные.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "забывает" ключ, использованный для шифрования этого и предыдущих сообщений и получает новый секретный ключ.

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Шифрует фрагмент данных для безопасной расшифровки через потоковый API

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_push(
string `&$state`,
#[\SensitiveParameter]string `$message`,
string `$additional_data` = "",
int `$tag` = `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`
): string

Функция шифрует фрагмент данных, чтобы его можно было безопасно расшифровать в потоковом API.

### Список параметров

`state`
  Смотрите описания функций sodium_crypto_secretstream_xchacha20poly1305_init_pull() и sodium_crypto_secretstream_xchacha20poly1305_init_push()
`message`
`additional_data`
`tag`
  Необязательно. Указывают для подтверждения поведения дешифрования (т. е. повторного ввода ключей или указания последнего фрагмента в потоке).
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: самый распространённый тег, который не добавляет никакой информации о характере сообщения.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: указывает, что сообщение отмечает конец потока, и стирает секретный ключ, использованный для шифрования предыдущей последовательности.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: указывает, что сообщение отмечает конец набора сообщений, но не конец потока. Например, огромная строка JSON, отправленная в виде нескольких фрагментов, может использовать этот тег, чтобы указать приложению, что строка завершена и что её можно декодировать. Но сам поток не закрывается и могут последовать дополнительные данные.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: «забывает» ключ, использованный для шифрования этого и предыдущих сообщений и получает новый секретный ключ.

### Возвращаемые значения

Функция возвращает зашифрованный текст.

# sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Явно поворачивает ключ в состояние secretstream

### Описание

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Явно поворачивает ключ в состояние secretstream. Заменяет переданное значение.

### Список параметров

`state`
  Состояние secretstream

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Вычисляет короткий хеш сообщения и ключ

### Описание

function sodium_crypto_shorthash(string `$message`, #[\SensitiveParameter]string `$key`): string

Функция sodium_crypto_shorthash() оборачивает хеш-функцию SipHash-2-4, которая идеально подходит для реализации хеш-таблиц, которые не подвержены атакам отказа в обслуживании из-за коллизии хешей (Hash-DoS).

SipHash-2-4 — не криптографическая хеш-функция общего назначения.

### Список параметров

`message`
  Сообщение, хеш которого требуется вычислить.
`key`
  Хеш-ключ.

### Возвращаемые значения

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Получает случайные байты для ключа

### Описание

function sodium_crypto_shorthash_keygen(): string

Функция создаёт ключ для функции sodium_crypto_shorthash().

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Подписывает сообщение

### Описание

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Функция подписывает сообщение секретным ключом, который можно проверить открытым ключом, который соответствует секретному ключу. Функция прикрепляет подпись к сообщению. Об откреплённых подписях рассказывает описание функции sodium_crypto_sign_detached().

### Список параметров

`message`
  Сообщение для подписи.
`secret_key`
  Секретный ключ. Смотрите описание функции sodium_crypto_sign_secretkey().

### Возвращаемые значения

Функция возвращает подписанное сообщение (не зашифрованное).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Подписывает сообщение

### Описание

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Функция подписывает сообщение секретным ключом, который проверяют открытым ключом, который соответствует сообщению. Функция возвращает отсоединённую подпись.

### Список параметров

`message`
  Сообщение, которое требуется подписать.
`secret_key`
  Секретный ключ. Смотрите описание функции sodium_crypto_sign_secretkey().

### Возвращаемые значения

Функция возвращает криптографическую подпись.

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Преобразовывает открытый ключ схемы Ed25519 в открытый ключ Curve25519

### Описание

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Функция вычисляет бирационально-эквивалентный открытый ключ X25519 для открытого ключа Ed25519.

### Список параметров

`public_key`
  Открытый ключ, который подходит для функций crypto_sign.

### Возвращаемые значения

Функция возвращает открытый ключ, который подходит для функций crypto_box.

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Преобразовывает секретный ключ из системы Ed25519 в секретный ключ Curve25519

### Описание

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter]string `$secret_key`): string

Функция вычисляет бирационально-эквивалентный секретный ключ X25519 для секретного ключа Ed25519.

### Список параметров

`secret_key`
  Секретный ключ, который подходит для функций crypto_sign.

### Возвращаемые значения

Функция возвращает секретный ключ, подходящий для функций crypto_box.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Генерирует произвольным способом секретный и открытый ключ, который соответствует секретному

### Описание

function sodium_crypto_sign_keypair(): string

Функция создаёт случайную пару ключей Ed25519 в виде одной строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает ключевую пару Ed25519.

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Объединяет секретный и открытый ключ

### Описание

function sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Функция объединяет секретный ключ с открытым.

### Список параметров

`secret_key`
  Секретный ключ Ed25519.
`public_key`
  Открытый ключ Ed25519.

### Возвращаемые значения

Ключевая пара

# sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Проверяет, корректна ли подпись подписанного сообщения

### Описание

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Функция проверяет подпись, которую прикрепили к сообщению, и возвращает сообщение.

### Список параметров

`signed_message`
  Сообщение, которое подписала функция sodium_crypto_sign().
`public_key`
  Открытый ключ Ed25519.

### Возвращаемые значения

В случае успешного выполнения функция возвращает исходное подписанное сообщение или `false`, если возникла ошибка.

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Извлекает открытый ключ Ed25519 из пары ключей

### Описание

function sodium_crypto_sign_publickey(#[\SensitiveParameter]string `$key_pair`): string

Функция извлекает открытый ключ Ed25519 из пары ключей.

### Список параметров

`key_pair`
  Ключевая пара Ed25519 (смотрите описание функции sodium_crypto_sign_keypair()).

### Возвращаемые значения

Открытый ключ Ed25519.

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Извлекает открытый ключ Ed25519 из секретного ключа

### Описание

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Функция извлекает открытый ключ Ed25519 из секретного ключа

### Список параметров

`secret_key`
  Секретный ключ Ed25519

### Возвращаемые значения

Открытый ключ Ed25519

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Извлекает секретный ключ Ed25519 из пары ключей

### Описание

function sodium_crypto_sign_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Функция извлекает секретный ключ Ed25519 из пары ключей.

### Список параметров

`key_pair`
  Ключевая пара Ed25519 (смотрите описание функции sodium_crypto_sign_keypair()).

### Возвращаемые значения

Секретный ключ Ed25519

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Выводит пару ключей из одного ключа детерминированным способом

### Описание

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Функция скрепляет начальное значение для формирования секретного ключа, извлекает открытый ключ и возвращает их в виде пары ключей.

Функции `*_seed_keypair` идеально подходят для создания пары ключей из пароля и соли. Используйте результат в качестве соли `seed` для генерации необходимых ключей.

### Список параметров

`seed`
  Криптографические входные данные. Должно быть 32 байта.

### Возвращаемые значения

Функция возвращает ключевую пару (секретный и открытый ключи).

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Проверяет подпись сообщения

### Описание

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Функция проверяет подпись сообщения.

### Список параметров

`signature`
  Криптографическая подпись, которую создала функция sodium_crypto_sign_detached().
`message`
  Проверяемое сообщение.
`public_key`
  Открытый ключ ed25519.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Создаёт детерминированную последовательность байтов из начального числа

### Описание

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Функция создаёт детерминированную последовательность байтов из начального числа через потоковый шифр XSalsa20.

### Список параметров

`length`
  Количество байтов, которые вернёт функция.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайно (например, функцией random_bytes()).
`key`
  Ключ шифрования (256 бит).

### Возвращаемые значения

Возвращает строку псевдослучайных байтов.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Генерирует случайный ключ sodium_crypto_stream

### Описание

function sodium_crypto_stream_keygen(): string

Создаёт ключ, который используется в sodium_crypto_stream() и sodium_crypto_stream_xor().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Ключ шифрования (256 бит).

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — Расширяет ключ и одноразовый номер в ключевой поток псевдослучайных байтов

### Описание

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Функция расширяет ключ `key` и одноразовый номер `nonce` в ключевой поток псевдослучайных байтов.

### Список параметров

`length`
  Требуемое количество байтов.
`nonce`
  24-байтовый одноразовый номер.
`key`
  Ключ, который, возможно, сгенерировала функция sodium_crypto_stream_xchacha20_keygen().

### Возвращаемые значения

Функция возвращает псевдослучайный поток, который можно использовать с функцией sodium_crypto_stream_xchacha20_xor().

# sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — Возвращает безопасный случайный ключ

### Описание

function sodium_crypto_stream_xchacha20_keygen(): string

Возвращает безопасный случайный ключ для использования функцией sodium_crypto_stream_xchacha20().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает 32-байтовый безопасный случайный ключ для использования функцией sodium_crypto_stream_xchacha20().

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — Шифрует сообщение одноразовым номером и секретным ключом (без аутентификации)

### Описание

function sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Функция шифрует сообщение `message`, используя одноразовый номер `nonce` и секретный ключ `key` (без аутентификации).

Предостережение

Это шифрование не аутентифицируется и не предотвращает атаки с выбранным зашифрованным текстом. Обязательно объедините зашифрованный текст с кодом аутентификации сообщения (Message Authentication Code), например, с функциями sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() или sodium_crypto_auth().

### Список параметров

`message`
  Сообщение для шифрования.
`nonce`
  24-байтовый одноразовый номер.
`key`
  Ключ, который, возможно, сгенерировала функция sodium_crypto_stream_xchacha20_keygen().

### Возвращаемые значения

Зашифрованное сообщение.

### Смотрите также

- sodium_crypto_stream_xchacha20_xor_ic() - Шифрует сообщение неясным кодом и секретным ключом (без аутентификации)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — Шифрует сообщение неясным кодом и секретным ключом (без аутентификации)

### Описание

function sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter]string `$message`,
string `$nonce`,
int `$counter`,
#[\SensitiveParameter]string `$key`
): string

Функция работает аналогично функции sodium_crypto_stream_xchacha20_xor(), но добавляет возможность установить начальное значение счётчика блоков в ненулевое значение. Это помогает получить прямой доступ к любому блоку без необходимости вычисления предыдущих.

Предостережение

Это шифрование неаутентифицировано и не предотвращает атаки с подобранным шифротекста. Обязательно объедините шифротекст с кодом аутентификации сообщения, например, с функциями sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() или sodium_crypto_auth().

### Список параметров

`message`
  Сообщение для шифрования.
`nonce`
  24-байтовый одноразовый номер.
`counter`
  Начальное значение счётчика блоков.
`key`
  Ключ, который, возможно, сгенерировала функция sodium_crypto_stream_xchacha20_keygen().

### Возвращаемые значения

Функция возвращает зашифрованное сообщение или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции sodium_crypto_stream_xchacha20_xor_ic()

    <?php

    $n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
    $left  = str_repeat("\x01", 64);
    $right = str_repeat("\xfe", 64);

    // Всё сразу:
    $stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

    // По частям, с начальным счётчиком:
    $stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
    $stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
    $stream7_concat = $stream7_left . $stream7_right;

    var_dump(strlen($stream7_concat));
    var_dump($stream7_unified === $stream7_concat);

    ?>

Вывод приведённого примера будет похож на:

    int(128)
    bool(true)

### Смотрите также

- sodium_crypto_stream_xchacha20_xor() - Шифрует сообщение одноразовым номером и секретным ключом (без аутентификации)

# sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Шифрует сообщение без аутентификации

### Описание

function sodium_crypto_stream_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Функция шифрует сообщение алгоритмом XSalsa20, но не предоставляет гарантий зашифрованного текста для открытого текста.

### Список параметров

`message`
  Сообщение для шифрования.
`nonce`
  Номер, который необходимо использовать только один раз для каждого сообщения. Длина 24 байта. Это достаточно большая граница, чтобы генерировать её случайно (например, функцией random_bytes()).
`key`
  Ключ шифрования (256 битов).

### Возвращаемые значения

Функция возвращает зашифрованное сообщение.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Декодирует строку в шестнадцатеричном представлении в двоичное

### Описание

function sodium_hex2bin(#[\SensitiveParameter]string `$string`, string `$ignore` = ""): string

Функция декодирует строку, которую закодировали в шестнадцатеричное представление, в бинарное.

Как и функция sodium_bin2hex(), функция sodium_hex2bin() устойчива к атакам по сторонним каналам (side-channel attacks), в отличие от функции hex2bin().

### Список параметров

`string`
  Шестнадцатеричное представление данных.
`ignore`
  Необязательный строковый аргумент с игнорируемыми символами.

### Возвращаемые значения

Функция возвращает двоичное представление переданных в аргументе `string` данных.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Увеличивает на единицу большое число

### Описание

function sodium_increment(string `&$string`): void

Функция обрабатывает строку как целое беззнаковое число с прямым порядком байтов, затем увеличивает число на 1. Функция работает за постоянное время.

### Список параметров

`string`
  Строка для увеличения.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Проверяет на равенство за постоянное время

### Описание

function sodium_memcmp(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Функция сравнивает две строки за постоянное время.

На практике чаще вместо этой функции вызывают функцию hash_equals(), поскольку она предоставляет ту же логику, но возвращает логическое значение (bool) вместо целого числа (int). Однако, если вы используете возвращаемое значение сравнения в вычислениях, которые чувствительны ко времени, и беспокоитесь об утечках времени при преобразованиях типа bool-to-int, функция sodium_memcmp() — идеальная замена.

### Список параметров

`string1`
  Строка для сравнения.
`string2`
  Другая строка для сравнения.

### Возвращаемые значения

Функция возвращает `0`, если обе строки равны; иначе `-1`.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Перезаписывает строку символами NULL

### Описание

function sodium_memzero(#[\SensitiveParameter]string `&$string`): void

Функция sodium_memzero() обнуляет строку, которую передали по ссылке.

### Список параметров

`string`
  Строка.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Дополняет строку данными

### Описание

function sodium_pad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Функция дополняет строку справа до требуемое длины. Функция безопасная по времени.

### Список параметров

`string`
  Входная строка.
`block_size`
  Функция будет дополнять строку, пока строка не станет чётным кратным размеру блока.

### Возвращаемые значения

Функция возвращает дополненную строку.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Удаляет дополняемые данные

### Описание

function sodium_unpad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Функция удаляет из строки данные дополненеия. Функция безопасная по времени.

### Список параметров

`string`
  Дополненная строка.
`block_size`
  Размер блока для заполнения.

### Возвращаемые значения

Функция возвращает строку с удалёнными дополненными данными.

## Содержание

- sodium_add — Добавляет большие числа
- sodium_base642bin — Преобразовывает строку в кодировке base64 в необработанный двоичный файл
- sodium_bin2base64 — Кодирует необработанную двоичную строку в формат base64
- sodium_bin2hex — Кодирует в шестнадцатеричное представление
- sodium_compare — Сравнивает большие числа
- sodium_crypto_aead_aegis128l_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen — Генерирует случайный ключ по алгоритму AEGIS-128L
- sodium_crypto_aead_aegis256_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256
- sodium_crypto_aead_aegis256_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-256
- sodium_crypto_aead_aegis256_keygen — Генерирует случайный ключ по алгоритму AEGIS-256
- sodium_crypto_aead_aes256gcm_decrypt — Проверяет и расшифровывает сообщение алгоритмом AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Шифрует, а затем проверяет подлинность алгоритмом AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Проверяет, поддерживает ли оборудование алгоритм AES256-GCM
- sodium_crypto_aead_aes256gcm_keygen — Создаёт случайный ключ AES-256-GCM
- sodium_crypto_aead_chacha20poly1305_decrypt — Проверяет, затем расшифровывает алгоритмом ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Шифрует, а затем проверяет подлинность алгоритмом ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Проверяет, содержит ли зашифрованный текст допустимый тег
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Шифрует сообщение
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Создаёт случайный ключ ChaCha20-Poly1305 (IETF)
- sodium_crypto_aead_chacha20poly1305_keygen — Создаёт случайный ключ ChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Предпочтительно) Проверяет, затем расшифровывает алгоритмом XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Предпочтительно) Шифрует, а затем проверяет подлинность алгоритмом XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Создаёт случайный ключ XChaCha20-Poly1305
- sodium_crypto_auth — Вычисляет тег для сообщения
- sodium_crypto_auth_keygen — Создаёт случайный ключ для sodium_crypto_auth
- sodium_crypto_auth_verify — Проверяет, допустим ли тег для сообщения
- sodium_crypto_box — Шифрует открытым ключом с проверкой подлинности
- sodium_crypto_box_keypair — Генерирует случайным образом секретный и открытый ключ, который соответствует закрытому
- sodium_crypto_box_keypair_from_secretkey_and_publickey — Создаёт унифицированную строку ключевой пары из секретного и открытого ключей
- sodium_crypto_box_open — Расшифровывает открытый ключ с проверкой подлинности
- sodium_crypto_box_publickey — Извлекает открытый ключ из ключевой пары crypto_box
- sodium_crypto_box_publickey_from_secretkey — Вычисляет открытый ключ из секретного ключа
- sodium_crypto_box_seal — Шифрует открытым ключом без проверки подлинности
- sodium_crypto_box_seal_open — Расшифровывает открытым ключом без проверки подлинности
- sodium_crypto_box_secretkey — Извлекает секретный ключ из ключевой пары crypto_box
- sodium_crypto_box_seed_keypair — Выводит ключевую пару из одного ключа детерминистическим способом
- sodium_crypto_core_ristretto255_add — Добавляет элемент
- sodium_crypto_core_ristretto255_from_hash — Сопоставляет вектор
- sodium_crypto_core_ristretto255_is_valid_point — Определяет, лежит ли точка на кривой ristretto255
- sodium_crypto_core_ristretto255_random — Генерирует случайный ключ
- sodium_crypto_core_ristretto255_scalar_add — Добавляет скалярное значение
- sodium_crypto_core_ristretto255_scalar_complement — Назначает основное скалярное дополнение в формате ristretto255
- sodium_crypto_core_ristretto255_scalar_invert — Инвертирует скалярное значение
- sodium_crypto_core_ristretto255_scalar_mul — Умножает скалярное значение
- sodium_crypto_core_ristretto255_scalar_negate — Отменяет скалярное значение
- sodium_crypto_core_ristretto255_scalar_random — Генерирует случайный ключ
- sodium_crypto_core_ristretto255_scalar_reduce — Уменьшает скалярное значение
- sodium_crypto_core_ristretto255_scalar_sub — Вычитает скалярное значение
- sodium_crypto_core_ristretto255_sub — Вычитает элемент
- sodium_crypto_generichash — Получает хеш сообщения
- sodium_crypto_generichash_final — Заканчивает хеширование
- sodium_crypto_generichash_init — Инициализирует хеш для потоковой передачи
- sodium_crypto_generichash_keygen — Создаёт случайный общий хеш-ключ
- sodium_crypto_generichash_update — Добавляет сообщение к хешу
- sodium_crypto_kdf_derive_from_key — Извлекает подраздел
- sodium_crypto_kdf_keygen — Создаёт случайный корневой ключ для интерфейса KDF
- sodium_crypto_kx_client_session_keys — Вычисляет ключи сессии на стороне клиента
- sodium_crypto_kx_keypair — Создаёт новую пару ключей sodium
- sodium_crypto_kx_publickey — Извлекает открытый ключ из пары ключей crypto_kx
- sodium_crypto_kx_secretkey — Извлекает секретный ключ из пары ключей crypto_kx
- sodium_crypto_kx_seed_keypair — Возвращает описание
- sodium_crypto_kx_server_session_keys — Вычисляет ключи сессии на стороне сервера
- sodium_crypto_pwhash — Получает ключ из пароля алгоритмом Argon2
- sodium_crypto_pwhash_scryptsalsa208sha256 — Получает ключ из пароля функцией scrypt
- sodium_crypto_pwhash_scryptsalsa208sha256_str — Получает хеш в кодировке ASCII
- sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Проверяет, что пароль — действительная строка проверки пароля
- sodium_crypto_pwhash_str — Получает ASCII-кодированный хеш
- sodium_crypto_pwhash_str_needs_rehash — Определяет, следует ли повторно использовать пароль
- sodium_crypto_pwhash_str_verify — Проверяет соответствие пароля хешу
- sodium_crypto_scalarmult — Вычисляет общий секрет на основании секретного ключа пользователя и открытого ключа другого пользователя
- sodium_crypto_scalarmult_base — Псевдоним sodium_crypto_box_publickey_from_secretkey
- sodium_crypto_scalarmult_ristretto255 — Вычисляет общий секрет
- sodium_crypto_scalarmult_ristretto255_base — Вычисляет открытый ключ из закрытого ключа
- sodium_crypto_secretbox — Шифрует общим ключом с проверкой подлинности
- sodium_crypto_secretbox_keygen — Создаёт случайный ключ для sodium_crypto_secretbox
- sodium_crypto_secretbox_open — Расшифровывает общим ключом с проверкой подлинности
- sodium_crypto_secretstream_xchacha20poly1305_init_pull — Инициализирует контекст secretstream для дешифрования
- sodium_crypto_secretstream_xchacha20poly1305_init_push — Инициализирует контекст secretstream для шифрования
- sodium_crypto_secretstream_xchacha20poly1305_keygen — Создаёт случайный ключ secretstream
- sodium_crypto_secretstream_xchacha20poly1305_pull — Расшифровывает часть данных из зашифрованного потока
- sodium_crypto_secretstream_xchacha20poly1305_push — Шифрует фрагмент данных для безопасной расшифровки через потоковый API
- sodium_crypto_secretstream_xchacha20poly1305_rekey — Явно поворачивает ключ в состояние secretstream
- sodium_crypto_shorthash — Вычисляет короткий хеш сообщения и ключ
- sodium_crypto_shorthash_keygen — Получает случайные байты для ключа
- sodium_crypto_sign — Подписывает сообщение
- sodium_crypto_sign_detached — Подписывает сообщение
- sodium_crypto_sign_ed25519_pk_to_curve25519 — Преобразовывает открытый ключ схемы Ed25519 в открытый ключ Curve25519
- sodium_crypto_sign_ed25519_sk_to_curve25519 — Преобразовывает секретный ключ из системы Ed25519 в секретный ключ Curve25519
- sodium_crypto_sign_keypair — Генерирует произвольным способом секретный и открытый ключ, который соответствует секретному
- sodium_crypto_sign_keypair_from_secretkey_and_publickey — Объединяет секретный и открытый ключ
- sodium_crypto_sign_open — Проверяет, корректна ли подпись подписанного сообщения
- sodium_crypto_sign_publickey — Извлекает открытый ключ Ed25519 из пары ключей
- sodium_crypto_sign_publickey_from_secretkey — Извлекает открытый ключ Ed25519 из секретного ключа
- sodium_crypto_sign_secretkey — Извлекает секретный ключ Ed25519 из пары ключей
- sodium_crypto_sign_seed_keypair — Выводит пару ключей из одного ключа детерминированным способом
- sodium_crypto_sign_verify_detached — Проверяет подпись сообщения
- sodium_crypto_stream — Создаёт детерминированную последовательность байтов из начального числа
- sodium_crypto_stream_keygen — Генерирует случайный ключ sodium_crypto_stream
- sodium_crypto_stream_xchacha20 — Расширяет ключ и одноразовый номер в ключевой поток псевдослучайных байтов
- sodium_crypto_stream_xchacha20_keygen — Возвращает безопасный случайный ключ
- sodium_crypto_stream_xchacha20_xor — Шифрует сообщение одноразовым номером и секретным ключом (без аутентификации)
- sodium_crypto_stream_xchacha20_xor_ic — Шифрует сообщение неясным кодом и секретным ключом (без аутентификации)
- sodium_crypto_stream_xor — Шифрует сообщение без аутентификации
- sodium_hex2bin — Декодирует строку в шестнадцатеричном представлении в двоичное
- sodium_increment — Увеличивает на единицу большое число
- sodium_memcmp — Проверяет на равенство за постоянное время
- sodium_memzero — Перезаписывает строку символами NULL
- sodium_pad — Дополняет строку данными
- sodium_unpad — Удаляет дополняемые данные

# Класс SodiumException

(PHP 7 >= 7.2.0, PHP 8)

## Введение

Исключения, выбрасываемые функциями sodium.

## Обзор класса

class SodiumException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Функции Sodium
  - sodium_add — Добавляет большие числа
  - sodium_base642bin — Преобразовывает строку в кодировке base64 в необработанный двоичный файл
  - sodium_bin2base64 — Кодирует необработанную двоичную строку в формат base64
  - sodium_bin2hex — Кодирует в шестнадцатеричное представление
  - sodium_compare — Сравнивает большие числа
  - sodium_crypto_aead_aegis128l_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-128L
  - sodium_crypto_aead_aegis128l_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-128L
  - sodium_crypto_aead_aegis128l_keygen — Генерирует случайный ключ по алгоритму AEGIS-128L
  - sodium_crypto_aead_aegis256_decrypt — Проверяет и расшифровывает сообщение, которое зашифровали по алгоритму AEGIS-256
  - sodium_crypto_aead_aegis256_encrypt — Шифрует и аутентифицирует сообщение по алгоритму AEGIS-256
  - sodium_crypto_aead_aegis256_keygen — Генерирует случайный ключ по алгоритму AEGIS-256
  - sodium_crypto_aead_aes256gcm_decrypt — Проверяет и расшифровывает сообщение алгоритмом AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Шифрует, а затем проверяет подлинность алгоритмом AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Проверяет, поддерживает ли оборудование алгоритм AES256-GCM
  - sodium_crypto_aead_aes256gcm_keygen — Создаёт случайный ключ AES-256-GCM
  - sodium_crypto_aead_chacha20poly1305_decrypt — Проверяет, затем расшифровывает алгоритмом ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Шифрует, а затем проверяет подлинность алгоритмом ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Проверяет, содержит ли зашифрованный текст допустимый тег
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Шифрует сообщение
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Создаёт случайный ключ ChaCha20-Poly1305 (IETF)
  - sodium_crypto_aead_chacha20poly1305_keygen — Создаёт случайный ключ ChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Предпочтительно) Проверяет, затем расшифровывает алгоритмом XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Предпочтительно) Шифрует, а затем проверяет подлинность алгоритмом XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Создаёт случайный ключ XChaCha20-Poly1305
  - sodium_crypto_auth — Вычисляет тег для сообщения
  - sodium_crypto_auth_keygen — Создаёт случайный ключ для sodium_crypto_auth
  - sodium_crypto_auth_verify — Проверяет, допустим ли тег для сообщения
  - sodium_crypto_box — Шифрует открытым ключом с проверкой подлинности
  - sodium_crypto_box_keypair — Генерирует случайным образом секретный и открытый ключ, который соответствует закрытому
  - sodium_crypto_box_keypair_from_secretkey_and_publickey — Создаёт унифицированную строку ключевой пары из секретного и открытого ключей
  - sodium_crypto_box_open — Расшифровывает открытый ключ с проверкой подлинности
  - sodium_crypto_box_publickey — Извлекает открытый ключ из ключевой пары crypto_box
  - sodium_crypto_box_publickey_from_secretkey — Вычисляет открытый ключ из секретного ключа
  - sodium_crypto_box_seal — Шифрует открытым ключом без проверки подлинности
  - sodium_crypto_box_seal_open — Расшифровывает открытым ключом без проверки подлинности
  - sodium_crypto_box_secretkey — Извлекает секретный ключ из ключевой пары crypto_box
  - sodium_crypto_box_seed_keypair — Выводит ключевую пару из одного ключа детерминистическим способом
  - sodium_crypto_core_ristretto255_add — Добавляет элемент
  - sodium_crypto_core_ristretto255_from_hash — Сопоставляет вектор
  - sodium_crypto_core_ristretto255_is_valid_point — Определяет, лежит ли точка на кривой ristretto255
  - sodium_crypto_core_ristretto255_random — Генерирует случайный ключ
  - sodium_crypto_core_ristretto255_scalar_add — Добавляет скалярное значение
  - sodium_crypto_core_ristretto255_scalar_complement — Назначает основное скалярное дополнение в формате ristretto255
  - sodium_crypto_core_ristretto255_scalar_invert — Инвертирует скалярное значение
  - sodium_crypto_core_ristretto255_scalar_mul — Умножает скалярное значение
  - sodium_crypto_core_ristretto255_scalar_negate — Отменяет скалярное значение
  - sodium_crypto_core_ristretto255_scalar_random — Генерирует случайный ключ
  - sodium_crypto_core_ristretto255_scalar_reduce — Уменьшает скалярное значение
  - sodium_crypto_core_ristretto255_scalar_sub — Вычитает скалярное значение
  - sodium_crypto_core_ristretto255_sub — Вычитает элемент
  - sodium_crypto_generichash — Получает хеш сообщения
  - sodium_crypto_generichash_final — Заканчивает хеширование
  - sodium_crypto_generichash_init — Инициализирует хеш для потоковой передачи
  - sodium_crypto_generichash_keygen — Создаёт случайный общий хеш-ключ
  - sodium_crypto_generichash_update — Добавляет сообщение к хешу
  - sodium_crypto_kdf_derive_from_key — Извлекает подраздел
  - sodium_crypto_kdf_keygen — Создаёт случайный корневой ключ для интерфейса KDF
  - sodium_crypto_kx_client_session_keys — Вычисляет ключи сессии на стороне клиента
  - sodium_crypto_kx_keypair — Создаёт новую пару ключей sodium
  - sodium_crypto_kx_publickey — Извлекает открытый ключ из пары ключей crypto_kx
  - sodium_crypto_kx_secretkey — Извлекает секретный ключ из пары ключей crypto_kx
  - sodium_crypto_kx_seed_keypair — Возвращает описание
  - sodium_crypto_kx_server_session_keys — Вычисляет ключи сессии на стороне сервера
  - sodium_crypto_pwhash — Получает ключ из пароля алгоритмом Argon2
  - sodium_crypto_pwhash_scryptsalsa208sha256 — Получает ключ из пароля функцией scrypt
  - sodium_crypto_pwhash_scryptsalsa208sha256_str — Получает хеш в кодировке ASCII
  - sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Проверяет, что пароль — действительная строка проверки пароля
  - sodium_crypto_pwhash_str — Получает ASCII-кодированный хеш
  - sodium_crypto_pwhash_str_needs_rehash — Определяет, следует ли повторно использовать пароль
  - sodium_crypto_pwhash_str_verify — Проверяет соответствие пароля хешу
  - sodium_crypto_scalarmult — Вычисляет общий секрет на основании секретного ключа пользователя и открытого ключа другого пользователя
  - sodium_crypto_scalarmult_base — Псевдоним sodium_crypto_box_publickey_from_secretkey
  - sodium_crypto_scalarmult_ristretto255 — Вычисляет общий секрет
  - sodium_crypto_scalarmult_ristretto255_base — Вычисляет открытый ключ из закрытого ключа
  - sodium_crypto_secretbox — Шифрует общим ключом с проверкой подлинности
  - sodium_crypto_secretbox_keygen — Создаёт случайный ключ для sodium_crypto_secretbox
  - sodium_crypto_secretbox_open — Расшифровывает общим ключом с проверкой подлинности
  - sodium_crypto_secretstream_xchacha20poly1305_init_pull — Инициализирует контекст secretstream для дешифрования
  - sodium_crypto_secretstream_xchacha20poly1305_init_push — Инициализирует контекст secretstream для шифрования
  - sodium_crypto_secretstream_xchacha20poly1305_keygen — Создаёт случайный ключ secretstream
  - sodium_crypto_secretstream_xchacha20poly1305_pull — Расшифровывает часть данных из зашифрованного потока
  - sodium_crypto_secretstream_xchacha20poly1305_push — Шифрует фрагмент данных для безопасной расшифровки через потоковый API
  - sodium_crypto_secretstream_xchacha20poly1305_rekey — Явно поворачивает ключ в состояние secretstream
  - sodium_crypto_shorthash — Вычисляет короткий хеш сообщения и ключ
  - sodium_crypto_shorthash_keygen — Получает случайные байты для ключа
  - sodium_crypto_sign — Подписывает сообщение
  - sodium_crypto_sign_detached — Подписывает сообщение
  - sodium_crypto_sign_ed25519_pk_to_curve25519 — Преобразовывает открытый ключ схемы Ed25519 в открытый ключ Curve25519
  - sodium_crypto_sign_ed25519_sk_to_curve25519 — Преобразовывает секретный ключ из системы Ed25519 в секретный ключ Curve25519
  - sodium_crypto_sign_keypair — Генерирует произвольным способом секретный и открытый ключ, который соответствует секретному
  - sodium_crypto_sign_keypair_from_secretkey_and_publickey — Объединяет секретный и открытый ключ
  - sodium_crypto_sign_open — Проверяет, корректна ли подпись подписанного сообщения
  - sodium_crypto_sign_publickey — Извлекает открытый ключ Ed25519 из пары ключей
  - sodium_crypto_sign_publickey_from_secretkey — Извлекает открытый ключ Ed25519 из секретного ключа
  - sodium_crypto_sign_secretkey — Извлекает секретный ключ Ed25519 из пары ключей
  - sodium_crypto_sign_seed_keypair — Выводит пару ключей из одного ключа детерминированным способом
  - sodium_crypto_sign_verify_detached — Проверяет подпись сообщения
  - sodium_crypto_stream — Создаёт детерминированную последовательность байтов из начального числа
  - sodium_crypto_stream_keygen — Генерирует случайный ключ sodium_crypto_stream
  - sodium_crypto_stream_xchacha20 — Расширяет ключ и одноразовый номер в ключевой поток псевдослучайных байтов
  - sodium_crypto_stream_xchacha20_keygen — Возвращает безопасный случайный ключ
  - sodium_crypto_stream_xchacha20_xor — Шифрует сообщение одноразовым номером и секретным ключом (без аутентификации)
  - sodium_crypto_stream_xchacha20_xor_ic — Шифрует сообщение неясным кодом и секретным ключом (без аутентификации)
  - sodium_crypto_stream_xor — Шифрует сообщение без аутентификации
  - sodium_hex2bin — Декодирует строку в шестнадцатеричном представлении в двоичное
  - sodium_increment — Увеличивает на единицу большое число
  - sodium_memcmp — Проверяет на равенство за постоянное время
  - sodium_memzero — Перезаписывает строку символами NULL
  - sodium_pad — Дополняет строку данными
  - sodium_unpad — Удаляет дополняемые данные
- SodiumException — Класс SodiumException

# Xpass

# Введение

Модуль работает на основе расширенной библиотеки crypt и предоставляет алгоритмы хеширования паролей, которые используются в дистрибутивах Linux.

Модуль также поддерживает дополнительные функции библиотеки libxcrypt, которых нет в ядре PHP.

# Установка и настройка

## Содержание

- Требования
- Установка с помощью PECL

## Требования

Для работы модуля требуется библиотека » libxcrypt версии 4.4 или выше.

## Установка с помощью PECL

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/xpass.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Модуль Xpass предоставляет набор констант: константы семейства `CRYPT_PREFIX_*`, которые обозначают методы хеширования для параметра prefix функции crypt_gensalt(), константы семейства `CRYPT_SALT_*` c кодами ошибок, которые возвращает функция crypt_checksalt(), и константы семейства `PASSWORD_*`, которые обозначают алгоритмы хеширования паролей для параметра algo функции password_hash().

Методы хеширования
`CRYPT_PREFIX_STD_DES` (string)
  Оригинальный метод хеширования из ОС Unix V7, который работает на основе блочного шифра DES. Парольную фразу, которую захешировали методом DES, возможно раскрыть, поскольку алгоритм нетребователен к ресурсам оборудования. Простота перебора DES-хешей объясняется тем, что метод выдаёт только `4096` возможных солей и 2**56 парольных фраз и обрезает до 8 символов. Из-за слабости DES-хешей шифром пользуются только при поддержке старых операционных систем, которые не поддерживают никаких других алгоритмов генерации хешей.
`CRYPT_PREFIX_EXT_DES` (string)
  Расширение традиционного шифра DES, которое устраняет ограничение длины, увеличивает размер соли и разрешает настраивать цену обработки хеша. Метод берёт начало в ОС BSD/OS компании BSDI и за счёт библиотеки FreeSec за авторством Дэвида Баррена (David Burren) также доступен по крайней мере в системах NetBSD, OpenBSD и FreeBSD. Качество этого метода превосходит традиционные алгоритмы DES и bigcrypt, но алгоритмом по-прежнему стараются не пользоваться для новых хешей.
`CRYPT_PREFIX_MD5` (string)
  Хеш работает на основе алгоритма MD5, который первоначально разработал Пол-Хеннинг Камп (Poul-Henning Kamp) для ОС FreeBSD. Алгоритм поддерживается большей частью свободных Unix-систем и более новыми версиями ОС Solaris. Этот хеш не такой слабый, как хеши на основе алгоритма DES, но MD5 настолько дёшев для перебора на современном оборудовании, что им лучше не пользоваться для генерации новых хешей. Цена обработки не настраивается.
`CRYPT_PREFIX_BLOWFISH` (string)
  Хеш работает на основе блочного шифра Blowfish, который модифицировали для генерации сверхдорогого расписания ключей. Алгоритм первоначально разработали Нильс Провос (Niels Provos) и Дэвид Мазьер (David Mazieres) для ОС OpenBSD. Алгоритм также поддерживается в последних версиях ОС FreeBSD и NetBSD, в Solaris 10 и новее и в ряде дистрибутивов GNU/*/Linux.
`CRYPT_PREFIX_SHA256` (string)
  Хеш работает на основе алгоритма SHA-2 с 256-битным выводом, который первоначально разработал Ульрих Дреппер (Ulrich Drepper) для GNU-библиотеки libc. Алгоритм поддерживается в ОС Linux, но не получил распространения в других местах. Алгоритм допустим для генерации новых хешей. Значение параметра цены обработки по умолчанию равняется `5000`, что чрезвычайно мало для современного оборудования.
`CRYPT_PREFIX_SHA512` (string)
  Хеш работает на основе алгоритма SHA-2 с 512-битным выводом, который первоначально разработал Ульрих Дреппер (Ulrich Drepper) для GNU-библиотеки libc. Алгоритм поддерживается в ОС Linux, но не получил распространения в других местах. Алгоритм допустим для генерации новых хешей. Значение параметра цены обработки по умолчанию равняется `5000`, что чрезвычайно мало для современного оборудования.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt — функция выведения ключа на основе пароля, которую создал Колин Персиваль (Colin Percival), первоначально для онлайн-сервиса резервного копирования Tarsnap. Алгоритм разработали, чтобы сделать дорогостоящим выполнение масштабных атак на пользовательское оборудование, требуя больших объёмов памяти. В 2016 году совет IETF опубликовал алгоритм scrypt как стандарт RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Алгоритм Gost-yescrypt использует данные вывода функции yescrypt как входное сообщение для HMAC-кода с хеш-функцией межгосударственного криптографического стандарта ГОСТ Р 34.11-2012 — Streebog с 256-битным дайджестом. Поэтому криптографические свойства функции yescrypt заменяются свойствами хеш-функции ГОСТа. Этот метод хеширования полезен в приложениях, которым требуется современное хеширование парольной фразы, но которые вынуждены полагаться на алгоритмы ГОСТа. Совет IETF опубликовал хеш-функцию «Стрибог», которую описывает ГОСТ Р 34.11-2012, как стандарт RFC 6986. Алгоритм допустим для генерации новых хешей, если требуется.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt — масштабируемая схема хеширования парольной фразы, разработка специалиста по безопасности из России Александра Песляка по прозвищу Solar Designer, которая основана на функции scrypt Колина Персиваля. Хотя стойкость функции yescrypt к атакам подбора пароля обусловлена её алгоритмом, криптографическую безопасность функции гарантирует алгоритм SHA-256 на внешнем уровне. Хеш-функцию SHA-256 опубликовал институт NIST в стандарте FIPS PUB 180-2 и его следующих редакциях наподобие FIPS PUB 180-4, и совет IETF как стандарт RFC 4634 и впоследствии стандарт RFC 6234. Алгоритм рекомендуют для генерации новых хешей.
`CRYPT_PREFIX_SM3CRYPT` (string)
  Хеш, основанный на хеш-функции ShangMi 3 с 256-битным выходом, который использует ту же конструкцию, что и sha256crypt и/или sha512crypt. Поддерживается в EulerOS, Kylin, openEuler и openKylin, но не распространен в других системах. Приемлем для новых хешей, где это необходимо. Параметр стоимости обработки по умолчанию равен 5000, что слишком мало для современного оборудования. Доступно с версии 1.2.0 с libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  Sm3-yescrypt использует вывод yescrypt в качестве входного сообщения для HMAC с хеш-функцией ShangMi 3 с 256-битным дайджестом. Таким образом, криптографические свойства yescrypt заменяются свойствами хеш-функции ShangMi 3. Метод хеширования полезен в приложениях, которые требуют современного хеширования паролей, но должны полагаться на алгоритмы, одобренные Государственным управлением коммерческой криптографии Китая (OSCCA). Хеш-функция ShangMi 3 была опубликована в части 3: «Специализированные хеш-функции» стандарта ISO/IEC 10118-3:2018. Приемлема для новых хешей, где это требуется. Доступно с версии 1.2.0 с libcxcrypt >= 4.5.0.

Error codes
`CRYPT_SALT_OK` (int)
  Ошибки не возникали.
`CRYPT_SALT_INVALID` (int)
  Неизвестный метод хеширования или недопустимые параметры.
`CRYPT_SALT_METHOD_DISABLED` (int)
  Метод хеширования запретили.
`CRYPT_SALT_METHOD_LEGACY` (int)
  Метод хеширования ненадёжен.
`CRYPT_SALT_TOO_CHEAP` (int)
  Чрезмерно низкая цена обработки.

Парольные алгоритмы
`PASSWORD_SHA512` (string)
  Константа `PASSWORD_SHA512` помогает создавать новые хеши паролей по алгоритму `CRYPT_PREFIX_SHA512`.
`PASSWORD_YESCRYPT` (string)
  Константа `PASSWORD_YESCRYPT` помогает создавать новые хеши паролей по алгоритму `CRYPT_PREFIX_YESCRYPT`.
`PASSWORD_SM3CRYPT` (string)
  Константа `PASSWORD_SM3CRYPT` помогает создавать новые хеши паролей по алгоритму `CRYPT_PREFIX_SM3CRYPT`. Доступно с версии 1.2.0 с libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  Константа `PASSWORD_SM3_YESCRYPT` помогает создавать новые хеши паролей по алгоритму `CRYPT_PREFIX_SM3_YESCRYPT`. Доступно с версии 1.2.0 с libcxcrypt >= 4.5.0.

# Функции Xpass

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Проверяет строку криптографических настроек

### Описание

function crypt_checksalt(string `$salt`): ?string

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

### Список параметров

`salt`
  Строка с солью, которую требуется проверить.

### Возвращаемые значения

Функция возвращает значение с типом int в виде константы семейства `CRYPT_SALT_*`.

### Примеры

Пример #1 Пример проверки соли функцией crypt_checksalt()

    <?php

    // Генерация соли для устаревшего метода
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);

    // Проверка соли
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Генерация соли для метода по умолчанию
    $salt = crypt_gensalt();

    // Проверка соли
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)

### Смотрите также

- crypt_gensalt() - Компилирует соль для функции crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Компилирует соль для функции crypt

### Описание

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Функция компилирует строку, которую передают в функцию crypt() как аргумент соли.

### Список параметров

`prefix`
  Метод хеширования в виде константы семейства `CRYPT_PREFIX_*`. При передаче значения `null` функция выберет наилучший из доступных метод хеширования.
`count`
  Управляет ценой обработки хеша; допустимый диапазон и точное значение цены зависят от метода хеширования, но большие числа соответствуют более дорогим хешам с точки зрения процессорного времени и, возможно, выделения памяти. При передаче в параметр count значения `0` функция выберет низкую цену по умолчанию.

### Возвращаемые значения

Функция возвращает строку с настройками или `null`, если возникла ошибка.

### Примеры

Пример #1 Пример компиляции соли функцией crypt_gensalt()

    <?php

    // Генерация соли
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);

    // Хеширование пароля
    $hash = crypt("secret", $salt);

    // Проверка хеша
    $test = hash_equals(crypt("secret", $hash), $hash);

    var_dump($salt, $hash, $test);

    ?>

Результат выполнения приведённого примера:

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### Смотрите также

- crypt_preferred_method() - Получает префикс предпочтительного метода хеширования
- crypt() - Хеширует строку необратимым способом
- hash_equals() - Сравнивает строки без риска атаки по времени

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Получает префикс предпочтительного метода хеширования

### Описание

function crypt_preferred_method(): ?string

Функция получает префикс предпочтительного метода хеширования.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает строку с префиксом или `null`, если возникла ошибка.

### Примеры

Пример #1 Пример получения префикса предпочтительного метода хеширования функцией crypt_preferred_method()

    <?php

    var_dump(crypt_preferred_method());

    ?>

Результат выполнения приведённого примера:

    string(3) "$y$"

### Смотрите также

- crypt_gensalt() - Компилирует соль для функции crypt

## Содержание

- crypt_checksalt — Проверяет строку криптографических настроек
- crypt_gensalt — Компилирует соль для функции crypt
- crypt_preferred_method — Получает префикс предпочтительного метода хеширования

- Установка и настройка
  - Требования
  - Установка с помощью PECL
- Предопределённые константы
- Функции Xpass
  - crypt_checksalt — Проверяет строку криптографических настроек
  - crypt_gensalt — Компилирует соль для функции crypt
  - crypt_preferred_method — Получает префикс предпочтительного метода хеширования

- Hash — Фреймворк HASH для дайджеста сообщений
  - Установка и настройка
  - Предопределённые константы
  - HashContext — Класс HashContext
  - Функции Hash
- Mcrypt
  - Установка и настройка
  - Предопределённые константы
  - Шифры Mcrypt
  - Mcrypt
- Mhash
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Mhash
- OpenSSL
  - Установка и настройка
  - Предопределённые константы
  - Параметры ключа и сертификата
  - Проверка сертификата
  - Функции OpenSSL
  - OpenSSLCertificate — Класс OpenSSLCertificate
  - OpenSSLCertificateSigningRequest — Класс OpenSSLCertificateSigningRequest
  - OpenSSLAsymmetricKey — Класс OpenSSLAsymmetricKey
- Хеширование паролей
  - Установка и настройка
  - Предопределённые константы
  - Функции хеширования паролей
- Rnp
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Rnp
  - RnpFFI — Класс RnpFFI
- Sodium
  - Установка и настройка
  - Предопределённые константы
  - Функции Sodium
  - SodiumException — Класс SodiumException
- Xpass
  - Установка и настройка
  - Предопределённые константы
  - Функции Xpass

# Модули для работы с базами данных

# Уровни абстракции

# Database (dbm-style) Abstraction Layer

# Введение

Эти функции — основа для доступа к базам данных наподобие Berkeley DB.

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

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Поведение в различных аспектах может отличаться в зависимости от реализации базы данных. такие функции как dba_optimize() и dba_sync() могут работать как обещано для одних баз данных и не работать вообще для других. Вам необходимо скачать и установить поддерживаемые обработчики dba.

Список обработчиков DBA
Обработчик | Замечания
--- | ---
`dbm` | Dbm - это старейший (оригинальный) тип баз данных Berkeley DB. Лучше, по возможности, избегать его использования. Мы не поддерживаем совместимость функций встроенных в DB2 и gdbm, потому что они совместимы только на уровне исходного кода, но не могут обрабатывать оригинальный формат dbm.
`ndbm` | Ndbm - это новейший, гораздо более гибкий чем dbm, тип базы. Он также имеет большинство ограничений dbm (следовательно является устаревшим).
`gdbm` | Gdbm - это » менеджер баз данных GNU.
`db2` | DB2 - используется для » Oracle Berkeley DB 2. Он описывается как "программный инструментарий, предоставляющий поддержку высокопроизводительной встроенной базы данных для отдельностоящих и клиент-серверных приложений".
`db3` | DB3 - используется для » Oracle Berkeley DB 3.
`db4` | DB4 - используется для » Oracle Berkeley DB 4 или 5. Может быть использована с BDB 5, начиная с PHP 5.3.3.
`cdb` | Cdb - это "быстрый, надёжный, лёгкий пакет для создания и чтения постоянных баз данных." от автора qmail. Может быть найден по ссылке » http://cr.yp.to/cdb.html. Так как база неизменяема, мы поддерживаем только операции чтения. С PHP 4.3.0 также поддерживается запись (не UPDATE!) через внутреннюю библиотеку cdb.
`cdb_make` | С PHP 4.3.0 мы поддерживаем создание (не изменение) файлов cdb при использовании встроенной библиотеки cdb.
`flatfile` | Доступно с PHP 4.3.0 только для поддержки совместимости с устаревшим модулем `dbm`. Использовать не рекомендуется. Тем не менее вы можете использовать этот обработчик для файлов, которые ранее были созданы в таком формате.
`inifile` | Доступно с PHP 4.3.3 для реализации возможности изменения файлов php.ini из скриптов PHP. При работе с ini-файлами вы должны передавать массивы формата array(0=>group,1=>value_name) или строки формата "[group]value_name", где group - опционально. Так как функции dba_firstkey() и dba_nextkey() возвращают строковое представление ключей, в PHP 5 была введена новая функция dba_key_split(), позволяющая конвертировать строковые ключи в ключи массива без потери `false`.
`qdbm` | Библиотека qdbm доступна по ссылке » http://fallabs.com/qdbm/index.html.
`tcadb` | Библиотека Tokyo Cabinet доступна по ссылке » http://fallabs.com/tokyocabinet/.
`lmdb` | Доступно с PHP 7.2.0. Библиотеку Lightning Memory-Mapped Database можно загрузить с сайта » https://symas.com/lmdb/.

При вызове функций dba_open() или dba_popen(), в качестве одно из аргументов необходимо передать имя обработчика. Актуальный список доступных обработчиков можно посмотреть с помощью функций phpinfo() или dba_handlers().

## Установка

Для включения базовой поддержки баз данных в стиле dbm, необходимо собрать PHP с поддержкой динамически загружаемого модуля, используя опцию --enable-dba=shared. Также вы можете добавить поддержку конкретных обработчиков, задав их скрипту конфигурации с помощью опций --with-XXXX или --enable-XXXX.

Внимание

После конфигурирования и сборки PHP, необходимо запустить следующий тест из командной строки: `php run-tests.php ext/dba`. Он покажет, работает ли ваша комбинация обработчиков. Самые проблематичные - это `dbm` и `ndbm`. Они конфликтуют с многими установками. Причина в том, что на некоторых системах, эти библиотеки являются частью более чем одной другой библиотеки. Тест конфигурации исключительно поможет вам избежать неработоспособной конфигурации с одним обработчиком, но не с их комбинацией.

Поддерживаемые обработчики DBA
Обработчик | Ключ конфигурации
--- | ---
`dbm` | Для включения поддержки dbm, добавьте --with-dbm[=DIR]. Замечание: dbm, как правило, представляет из себя обёртку подверженную частым сбоям. Следовательно использовать её можно только если вы абсолютно уверены в работоспособности и она вам действительно нужна.
`ndbm` | Для включения поддержки ndbm, добавьте --with-ndbm[=DIR]. Замечание: ndbm, как правило, представляет из себя обёртку подверженную частым сбоям. Следовательно использовать её можно только если вы абсолютно уверены в работоспособности и она вам действительно нужна.
`gdbm` | Для включения поддержки gdbm, добавьте --with-gdbm[=DIR].
`db2` | Для включения поддержки Oracle Berkeley DB 2, добавьте --with-db2[=DIR]. Замечание: db2 конфликтует с db3 и db4.
`db3` | Для включения поддержки Oracle Berkeley DB 3, добавьте --with-db3[=DIR]. Замечание: db3 конфликтует с db2 и db4.
`db4` | Для включения поддержки Oracle Berkeley DB 4 or 5, добавьте --with-db4[=DIR]. Замечание: db4 конфликтует с db2 и db3. Замечание: Библиотеки баз данных версий с 4.1 по 4.1.24 вообще не могут использоваться в PHP. Поддержка BDB 5 добавлена в PHP 5.3.3.
`cdb` | Для включения поддержки cdb, добавьте --with-cdb[=DIR]. Замечание: Вы можете не указывать DIR для использования встроенной библиотеки cdb, которая добавляет обработчик cdb_make, что позволяет создавать файлы базы cdb и предоставляет доступ к ним по сети, через потоки PHP.
`flatfile` | Для включения поддержки flatfile, добавьте --enable-flatfile. До PHP 5.2.1, необходимо использовать опцию --with-flatfile. Замечание: Добавлен для обеспечения совместимости с устаревшим модулем `dbm`. Используйте этот обработчик только если вы не можете установить одну из библиотек, требуемую другим обработчиком и если вам не достаточно встроенного обработчика cdb.
`inifile` | Для включения поддержки `inifile`, добавьте --enable-inifile. До PHP 5.2.1, необходимо использовать опцию --with-inifile. Замечание: Добавлено для получения доступ на чтение и запись к .ini файлам в стиле Microsoft (например php.ini).
`qdbm` | Для включения поддержки qdbm, добавьте --with-qdbm[=DIR]. Замечание: qdbm конфликтует с dbm и gdbm. Замечание: Библиотеку qdbm можно скачать по ссылке » http://fallabs.com/qdbm/index.html.
`tcadb` | Для включения поддержки Tokyo Cabinet, добавьте --with-tcadb[=DIR]. Замечание: Библиотеку можно скачать по ссылке » http://fallabs.com/tokyocabinet/.
`lmdb` | Для включения поддержки Lightning Memory-Mapped Database используйте --with-lmdb[=DIR]. Замечание: Добавлено в PHP 7.2.0. Библиотека Lightning Memory-Mapped Database доступна по ссылке » https://symas.com/lmdb/.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки DBA
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

Краткое разъяснение конфигурационных директив.

`dba.default_handler` string
  Имя обработчика по умолчанию

## Типы ресурсов

До PHP 8.4.0, большинство функций DBA работало с возвращаемыми ресурсами (например, dba_open() возвращает положительный идентификатор ссылки DBA, требуемый большинством функций DBA).

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`DBA_LMDB_USE_SUB_DIR` (int)
  Флаг LMDB Driver, разрешающий создание подкаталога для файлов базы данных. Доступно, начиная с PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  Флаг LMDB Driver, запрещающий создание подкаталога для файлов базы данных. Доступно, начиная с PHP 8.2.0.

# Примеры

## Содержание

- Базовое использование

## Базовое использование

Пример #1 DBA пример

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open failed\n";
        exit;
    }

    dba_replace("key", "This is an example!", $id);

    if (dba_exists("key", $id)) {
        echo dba_fetch("key", $id);
        dba_delete("key", $id);
    }

    dba_close($id);
    ?>

DBA является бинарно безопасным и не имеет каких-либо произвольных ограничений. Тем не менее, он наследует все ограничения, установленные базовой реализацией базы данных

Все файловые базы данных должны обеспечивать способ задания файлового режима только что созданной базы данных, если это вообще возможно. Файловый режим обычно передаётся как четвёртый аргумент в dba_open() или dba_popen().

Вы можете получить все записи базы данных в процедурном стиле используя функции dba_firstkey() и dba_nextkey(). Вы не можете изменить базу данных во время её обхода.

Пример #2 Обход базы данных

    <?php

    // ...open database...

    $key = dba_firstkey($id);

    while ($key !== false) {
        if (true) {          // запоминаем ключ для выполнения некоторых действий далее
            $handle_later[] = $key;
        }
        $key = dba_nextkey($id);
    }

    foreach ($handle_later as $val) {
        dba_delete($val, $id);
    }

    ?>

# Класс Dba\Connection

(PHP 8 >= 8.4.0)

## Введение

Полностью непрозрачный класс, который начиная с PHP 8.4.0 заменяет ресурс `dba`.

## Обзор класса

namespace Dba;
final class Connection {
}

# Функции DBA

# dba_close

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

dba_close — Закрывает базу данных DBA

### Описание

function dba_close(Dba\Connection `$dba`): void

dba_close() закрывает установленную базу данных и освобождает все связанные с ней ресурсы.

### Список параметров

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_open() - Открывает базу данных
- dba_popen() - Установить постоянный экземпляр базы данных

# dba_delete

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

dba_delete — Удаляет запись базы данных определённую ключом

### Описание

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() удаляет указанную запись в базе данных.

### Список параметров

`key`
  Ключ записи, которую надо удалить.
`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_exists() - Проверяет, существует ли ключ
- dba_fetch() - Извлекает данные по указанному ключу
- dba_insert() - Вставляет запись
- dba_replace() - Перезаписать или вставить запись

# dba_exists

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

dba_exists — Проверяет, существует ли ключ

### Описание

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() проверяет, если в базе данных заданный ключ `key`.

### Список параметров

`key`
  Проверяемый ключ.
`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Возвращает `true` если ключ существует и `false` в обратном случае.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_delete() - Удаляет запись базы данных определённую ключом
- dba_fetch() - Извлекает данные по указанному ключу
- dba_insert() - Вставляет запись
- dba_replace() - Перезаписать или вставить запись

# dba_fetch

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

dba_fetch — Извлекает данные по указанному ключу

### Описание

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

Перегруженная сигнатура устарела с PHP 8.3.0:

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() извлекает данные из базы данных, заданной `dba`, определённые ключом `key`.

### Список параметров

`key`
  Ключ, для которого надо извлечь данные.

  > Замечание: Когда работает с ini-файлом, эта функция принимает массив в качестве ключа, где по индексу 0 задана группа, а по индексу 1 - имя параметра. Дополнительно смотрите dba_key_split().

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().
`skip`
  Число пар ключ-значение, которые нужно проигнорировать при работе с базой данных cdb. Этот параметр игнорируется при работе со всеми остальными базами данных, в которых не поддерживаются множественные ключи с одинаковым именем.

### Возвращаемые значения

Возвращает строку, если пара ключ/данные найдена, иначе возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .
8.3.0 | Вызов функции dba_fetch() с параметром `dba` в качестве третьего аргумента устарел.
8.2.0 | Необязательный параметр skip функции dba_fetch() теперь находится в конце в соответствии с пользовательской семантикой PHP; перегруженная сигнатура по-прежнему принимается, но не рекомендуется.

### Смотрите также

- dba_exists() - Проверяет, существует ли ключ
- dba_delete() - Удаляет запись базы данных определённую ключом
- dba_insert() - Вставляет запись
- dba_replace() - Перезаписать или вставить запись
- dba_key_split() - Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей

# dba_firstkey

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

dba_firstkey — Извлекает первый ключ

### Описание

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() возвращает первый ключ из базы данных и сбрасывает внутренний указатель. Это позволяет производить прямой поиск по всей базе.

### Список параметров

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Возвращает ключ в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_nextkey() - Извлекает следующий ключ
- dba_key_split() - Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей
- Второй пример в примерах DBA

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — Список всех доступных обработчиков

### Описание

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() возвращает список всех доступных в этом модуле обработчиков.

### Список параметров

`full_info`
  Включает, либо выключает, вывод полной информации в результат.

### Возвращаемые значения

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

> Замечание: Если используется встроенная база данных, вы увидите и `cdb` и `cdb_make`.

### Примеры

Пример #1 Пример использования dba_handlers()

    <?php

    echo "Доступные обработчики DBA:\n";
    foreach (dba_handlers(true) as $handler_name => $handler_version) {
      // Очищаем строки с версиями
      $handler_version = str_replace('$', '', $handler_version);
      echo " - $handler_name: $handler_version\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    Доступные обработчики DBA:
     - cdb: 0.75, Revision: 1.3.2.3
     - cdb_make: 0.75, Revision: 1.2.2.4
     - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
     - inifile: 1.0, Revision: 1.6.2.3
     - flatfile: 1.0, Revision: 1.5.2.4

# dba_insert

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

dba_insert — Вставляет запись

### Описание

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() вставляет в базу данных запись заданную параметрами `key` и `value`.

### Список параметров

`key`
  Ключ записи для вставки. Если такой ключ уже существует в базе данных, функция завершится с ошибкой. Для замены записи используйте функцию dba_replace().
`value`
  Значение для вставки.
`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_exists() - Проверяет, существует ли ключ
- dba_delete() - Удаляет запись базы данных определённую ключом
- dba_fetch() - Извлекает данные по указанному ключу
- dba_replace() - Перезаписать или вставить запись

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей

### Описание

function dba_key_split(string|false|null `$key`): array|false

Функция dba_key_split() разделяет ключ, который указали в виде строки, и создаёт массив из полученных частей.

### Список параметров

`key`
  Ключ в виде строки.

### Возвращаемые значения

Функция возвращает массив следующего вида: `array(0 => group, 1 => value_name)`. Функция возвращает `false`, если ключ `key` равен `null` или `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Передача значений `null` или `false` в параметр `key` устарела.

### Смотрите также

- dba_firstkey() - Извлекает первый ключ
- dba_nextkey() - Извлекает следующий ключ
- dba_fetch() - Извлекает данные по указанному ключу

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — Список всех открытых файлов базы данных

### Описание

function dba_list(): array

dba_list() возвращает список всех открытых файлов базы данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Ассоциативный массив типа `resourceid => filename`.

# dba_nextkey

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

dba_nextkey — Извлекает следующий ключ

### Описание

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() возвращает следующий ключ из базы данных и перемещает внутренний указатель.

### Список параметров

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Возвращает ключ в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_firstkey() - Извлекает первый ключ
- dba_key_split() - Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей
- Второй пример в примерах DBA

# dba_open

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

dba_open — Открывает базу данных

### Описание

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() устанавливает экземпляр базы данных по пути `path` в режиме `mode` используя обработчик `handler`.

### Список параметров

`path`
  Путь до файлов базы данных.
`mode`
  `r` для режима чтения, `w` для режима чтения/записи с уже существующей базой данных. `c` для режима чтения/записи и создания базы данных, если она ещё не была создана, и `n` для создания, обрезания и доступа для чтения/записи. База данных создаётся с архитектурой BTree, другие архитектуры (вроде Hash или Queue) не поддерживаются. Дополнительно, с помощью следующего символа, вы можете задать режим блокировки базы данных. `l` для блокировки базы данных с помощью файла .lck, или `d` для самостоятельной блокировки средствами самой базы. Важно, чтобы все ваши приложения делали это согласованно. Если вы хотите просто проверить доступ и не хотите ждать освобождения блокировки, вы можете добавить третий символ `t`. Если вы абсолютно уверены, что вам не нужно использовать блокировку базы данных, вы можете использовать символ `-` вместо `l` или `d`. Если ни один из символов: `d`, `l` или `-` не задан, база данных будет использовать режим `d`.

  > Замечание:

  > В один момент времени может быть только один процесс, пишущий в базу данных. Когда вы используете dba на веб-сервере, и более чем один запрос требует записи в базу данных, они могут это делать только строго по очереди. Также, в момент чтения, запись не доступна. Модуль dba использует блокировки для предотвращения нежелательного поведения. Изучите следующую таблицу:

  > Блокировки DBA
  > уже открыта | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > не открыта | ok | ok | ok | ok | ok | ok | ok | ok
  > `mode` = "rl" | ok | ok | wait | false | illegal | illegal | illegal | illegal
  > `mode` = "wl" | wait | false | wait | false | illegal | illegal | illegal | illegal
  > `mode` = "rd" | illegal | illegal | illegal | illegal | ok | ok | wait | false
  > `mode` = "wd" | illegal | illegal | illegal | illegal | wait | false | wait | false

  > - ok: второй вызов будет успешным.
  > - wait: второй вызов будет ждать, пока первый не вызовет dba_close().
  > - false: второй вызов вернёт `false`.
  > - illegal: вы не можете смешивать модификаторы `"l"` и `"d"` в параметре `mode`.

`handler`
  Имя обработчика, который будет использоваться для доступа по пути `path`. Ему передаются все необязательные параметры, заданные в dba_open(). Если параметр `handler` равен `null`, то вызывается обработчик по умолчанию.
`permission`
  Необязательный параметр, заданный целым числом (int), который передаётся драйверу. У него то же значение, что и у параметра `permissions` функции chmod(), значение по умолчанию - `0644`. Драйверы `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` и `lmdb` поддерживают параметр `permission`.
`map_size`
  Необязательный параметр, заданный целым числом (int), который передаётся драйверу. Его значение должно быть кратно размеру страницы ОС или равно нулю, чтобы использовать размер карты по умолчанию. Только драйвер `lmdb` допускает параметр `map_size`.
`flags`
  Флаги для передачи драйверам базы данных. Если указано значение `null`, будут переданы флаги по умолчанию. В настоящее время только драйвер LMDB поддерживает следующие флаги: `DBA_LMDB_USE_SUB_DIR` и `DBA_LMDB_NO_SUB_DIR`.

### Возвращаемые значения

Функция возвращает экземпляр класса Dba\Connection в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

Функция возвращает значение `false` и выдаёт ошибку уровня `E_WARNING`, если параметр `handler` равен `null`, но нет обработчика по умолчанию.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает экземпляр класса Dba\Connection; ранее возвращался ресурс (resource).
8.2.0 | Добавлен параметр `flags`.
8.2.0 | Параметр `handler` теперь допускает значение `null`.
7.3.14, 7.4.2 | Драйвер `lmdb` теперь поддерживает дополнительный параметр `map_size`.

### Смотрите также

- dba_popen() - Установить постоянный экземпляр базы данных
- dba_close() - Закрывает базу данных DBA

# dba_optimize

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

dba_optimize — Оптимизирует базу данных

### Описание

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() оптимизирует основную базу данных.

### Список параметров

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_sync() - Синхронизирует базу данных

# dba_popen

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

dba_popen — Установить постоянный экземпляр базы данных

### Описание

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() устанавливает постоянный экземпляр базы данных по пути `path` в режиме `mode`, используя обработчик `handler`.

### Список параметров

`path`
  Путь до файлов базы данных.
`mode`
  `r` для режима чтения, `w` для режима чтения/записи с уже существующей базой данных. `c` для режима чтения/записи и создания базы данных, если она ещё не была создана, и `n` для создания, обрезания и доступа для чтения/записи. База данных создаётся с архитектурой BTree, другие архитектуры (вроде Hash или Queue) не поддерживаются.
`handler`
  Имя обработчика, который будет использоваться для доступа по пути `path`. Ему передаются все необязательные параметры, заданные в dba_open(). Если параметр `handler` равен `null`, то вызывается обработчик по умолчанию.
`permission`
  Необязательный параметр, заданный целым числом (int), который передаётся драйверу. У него то же значение, что и у параметра `permissions` функции chmod(), значение по умолчанию - `0644`. Драйверы `db1`, `db2`, `db3`, `db4`, `dbm`, `gdbm`, `ndbm` и `lmdb` поддерживают параметр `permission`.
`map_size`
  Необязательный параметр, заданный целым числом (int), который передаётся драйверу. Его значение должно быть кратно размеру страницы ОС или равно нулю, чтобы использовать размер карты по умолчанию. Только драйвер `lmdb` допускает параметр `map_size`.
`flags`
  Флаги для передачи драйверам базы данных. Если указано значение `null`, будут переданы флаги по умолчанию. В настоящее время только драйвер LMDB поддерживает следующие флаги: `DBA_LMDB_USE_SUB_DIR` и `DBA_LMDB_NO_SUB_DIR`.

### Возвращаемые значения

Функция возвращает экземпляр класса Dba\Connection в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

Функция возвращает значение `false` и выдаёт ошибку уровня `E_WARNING`, если параметр `handler` равен `null`, но нет обработчика по умолчанию.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает экземпляр класса Dba\Connection; ранее возвращался ресурс (resource).
8.2.0 | Добавлен параметр `flags`.
8.1.0 | Параметр `handler` теперь допускает значение `null`.
7.3.14, 7.4.2 | Драйвер `lmdb` теперь поддерживает дополнительный параметр `map_size`.

### Смотрите также

- dba_open() - Открывает базу данных
- dba_close() - Закрывает базу данных DBA

# dba_replace

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

dba_replace — Перезаписать или вставить запись

### Описание

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() перезаписывает или вставляет запись, заданную ключом `key` и значением `value` в базу данных определённую обработчиком `dba`.

### Список параметров

`key`
  Ключ записи, которую надо заменить.
`value`
  Новое значение.
`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_exists() - Проверяет, существует ли ключ
- dba_delete() - Удаляет запись базы данных определённую ключом
- dba_fetch() - Извлекает данные по указанному ключу
- dba_insert() - Вставляет запись

# dba_sync

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

dba_sync — Синхронизирует базу данных

### Описание

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() синхронизирует базу данных. Скорее всего эта функция, если поддерживается, вызовет запись на диск.

### Список параметров

`dba`
  Экземпляр класса Dba\Connection, который возвращают функции dba_open() и dba_popen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `dba` теперь принимает объект Dba\Connection; раньше параметр ждал ресурс (resource) `dba` .

### Смотрите также

- dba_optimize() - Оптимизирует базу данных

## Содержание

- dba_close — Закрывает базу данных DBA
- dba_delete — Удаляет запись базы данных определённую ключом
- dba_exists — Проверяет, существует ли ключ
- dba_fetch — Извлекает данные по указанному ключу
- dba_firstkey — Извлекает первый ключ
- dba_handlers — Список всех доступных обработчиков
- dba_insert — Вставляет запись
- dba_key_split — Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей
- dba_list — Список всех открытых файлов базы данных
- dba_nextkey — Извлекает следующий ключ
- dba_open — Открывает базу данных
- dba_optimize — Оптимизирует базу данных
- dba_popen — Установить постоянный экземпляр базы данных
- dba_replace — Перезаписать или вставить запись
- dba_sync — Синхронизирует базу данных

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Примеры
  - Базовое использование
- Dba\Connection — Класс Dba\Connection
- Функции DBA
  - dba_close — Закрывает базу данных DBA
  - dba_delete — Удаляет запись базы данных определённую ключом
  - dba_exists — Проверяет, существует ли ключ
  - dba_fetch — Извлекает данные по указанному ключу
  - dba_firstkey — Извлекает первый ключ
  - dba_handlers — Список всех доступных обработчиков
  - dba_insert — Вставляет запись
  - dba_key_split — Разделяет ключ, заданный в виде строки, и создаёт массив из полученных частей
  - dba_list — Список всех открытых файлов базы данных
  - dba_nextkey — Извлекает следующий ключ
  - dba_open — Открывает базу данных
  - dba_optimize — Оптимизирует базу данных
  - dba_popen — Установить постоянный экземпляр базы данных
  - dba_replace — Перезаписать или вставить запись
  - dba_sync — Синхронизирует базу данных

# Модуль Unified ODBC

# Введение

В дополнение к стандартной поддержке интерфейса ODBC, функции модуля Unified ODBC в PHP умеют взаимодействовать с базами данных, которые позаимствовали семантику API-интерфейса ODBC для реализации собственного API. Вместо поддержки множества практически идентичных драйверов баз данных в PHP драйверы объединили в единый набор функций ODBC.

Функции модуля Unified ODBC поддерживают работу со следующими базами данных: » Adabas D, » IBM DB2, » Solid, » Sybase SQL Anywhere и менеджером драйверов » iODBC.

> Замечание: При взаимодействии с перечисленными базами данных вызовы ODBC-функций непосредственно перенаправляются в клиентские библиотеки самих баз данных; менеджер драйверов iODBC задействуется только при подключении к базам данным вне списка. ODBC-функции в PHP спроектировали с теми же названиями и синтаксисом вызова, что и функции спецификации ODBC. При этом сборка PHP с поддержкой менеджера iODBC разрешает PHP-приложениями взаимодействовать со всеми ODBC-совместимыми драйверами. Дополнительная информация о менеджере iODBC доступна по адресу » www.iodbc.org, а об альтернативном менеджере unixODBC — по адресу » www.unixodbc.org.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для доступа к базам данных, которые поддерживает модуль, потребуется установить библиотеки, через которые модуль будет взаимодействовать с конкретной СУБД.

## Установка

--with-adabas[=DIR]

  Включить поддержку Adabas D. DIR - это каталог установки Adabas, по умолчанию /usr/local.

--with-sapdb[=DIR]

  Включить поддержку SAP DB. DIR - каталог установки SAP DB, по умолчанию /usr/local.

--with-solid[=DIR]

  Включить поддержку Solid. DIR - каталог установки Solid base, по умолчанию /usr/local/solid.

--with-ibm-db2[=DIR]

  Включить поддержку IBM DB2. DIR - это каталог установки DB2, по умолчанию /home/db2inst1/sqllib.

--with-empress[=DIR]

  Включить поддержку Empress. DIR - это каталог установки Empress, по умолчанию $EMPRESSPATH. Опция поддерживается только Empress версии 8.60 и выше.

--with-empress-bcs[=DIR]

  Включить поддержку `"Empress Local Access"`. DIR - это каталог установки Empress, по умолчанию $EMPRESSPATH. Опция поддерживается только Empress версии 8.60 и выше.

--with-birdstep[=DIR]

  Включить поддержку Birdstep. DIR - это каталог установки Birdstep, по умолчанию /usr/local/birdstep.

--with-custom-odbc[=DIR]

  Включить определённую пользователем поддержку ODBC. DIR - это каталог установки ODBC, по умолчанию /usr/local. Убедитесь, что вы определили CUSTOM_ODBC_LIBS и у вас есть несколько odbc.h в ваших включаемых каталогах. Например, вы должны определить следующее для Sybase SQL Anywhere 5.5.00 в QNX перед запуском скрипта настройки:

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Включить поддержку iODBC. DIR - это каталог установки iODBC, по умолчанию /usr/local.

--with-esoob[=DIR]

  Включить поддержку Easysoft OOB. DIR - это каталог установки Easysoft OOB, по умолчанию /usr/local/easysoft/oob/client.

--with-unixODBC[=DIR]

  Включить поддержку unixODBC. DIR - это каталог установки unixODBC, по умолчанию /usr/local.

--with-openlink[=DIR]

  Включить поддержку OpenLink ODBC. DIR - это каталог установки OpenLink, по умолчанию /usr/local. Это то же самое, что и iODBC.

--with-dbmaker[=DIR]

  Включить поддержку DBMaker. DIR - это каталог установки DBMaker, по умолчанию это место, где установлена последняя версия DBMaker (например, /home/dbmaker/3.6).

Пользователи Windows должны включить php_odbc.dll, чтобы использовать этот модуль.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации модуля Unified ODBC
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
odbc.allow_persistent | "1" | `INI_SYSTEM` |
odbc.check_persistent | "1" | `INI_SYSTEM` |
odbc.max_persistent | "-1" | `INI_SYSTEM` |
odbc.max_links | "-1" | `INI_SYSTEM` |
odbc.defaultlrl | "4096" | `INI_ALL` |
odbc.defaultbinmode | "1" | `INI_ALL` |
odbc.default_cursortype | "3" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`odbc.default_db` string

  Источник данных ODBC для использования, если ни один не указали в функции odbc_connect() или odbc_pconnect().

`odbc.default_user` string

  Имя пользователя для использования, если ни один не указали в функции odbc_connect() или odbc_pconnect().

`odbc.default_pw` string

  Пароль для использования, если ни один не указали в функции odbc_connect() или odbc_pconnect().

`odbc.allow_persistent` bool

  Разрешать ли постоянные соединения ODBC.

`odbc.check_persistent` bool

  Перед повторным использованием убедитесь, что соединение всё ещё доступно.

`odbc.max_persistent` int

  Максимальное количество постоянных соединений ODBC на процесс.

`odbc.max_links` int

  Максимальное количество соединений ODBC на процесс, включая постоянные соединения.

`odbc.defaultlrl` int

  Обработка LONG-полей. Определяет количество байтов, которые возвращают переменные. Подробннее рассказывает описание функции odbc_longreadlen().

  Объём измеряется в байтах, если значение параметра указали как целое число (int). Параметр также принимает значения в сокращённой нотации, которую описывает раздел FAQ.
`odbc.defaultbinmode` int

  Обработка двоичных данных. Подробннее рассказывает описание функции odbc_binmode().

`odbc.default_cursortype` int

  Управляет моделью курсора ODBC. Возможные значения `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` и `SQL_CURSOR_STATIC` (по умолчанию).

## Типы ресурсов

До PHP 8.4.0 модуль определял два типа ресурсов: идентификатор ODBC-соединения и идентификатор объекта ODBC с результатом запроса.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`ODBC_TYPE` (string)
`ODBC_BINMODE_PASSTHRU` (int)
`ODBC_BINMODE_RETURN` (int)
`ODBC_BINMODE_CONVERT` (int)
`SQL_ODBC_CURSORS` (int)
`SQL_CUR_USE_DRIVER` (int)
`SQL_CUR_USE_IF_NEEDED` (int)
`SQL_CUR_USE_ODBC` (int)
`SQL_CONCURRENCY` (int)
`SQL_CONCUR_READ_ONLY` (int)
`SQL_CONCUR_LOCK` (int)
`SQL_CONCUR_ROWVER` (int)
`SQL_CONCUR_VALUES` (int)
`SQL_CURSOR_TYPE` (int)
`SQL_CURSOR_FORWARD_ONLY` (int)
`SQL_CURSOR_KEYSET_DRIVEN` (int)
`SQL_CURSOR_DYNAMIC` (int)
`SQL_CURSOR_STATIC` (int)
`SQL_KEYSET_SIZE` (int)
`SQL_CHAR` (int)
`SQL_VARCHAR` (int)
`SQL_LONGVARCHAR` (int)
`SQL_WCHAR` (int)
  Строка символов Юникода фиксированной длины.
`SQL_WVARCHAR` (int)
  Строка символов переменной длины Юникода.
`SQL_WLONGVARCHAR` (int)
  Символьные данные Юникода переменной длины. Максимальная длина зависит от источника данных.
`SQL_DECIMAL` (int)
`SQL_NUMERIC` (int)
`SQL_BIT` (int)
`SQL_TINYINT` (int)
`SQL_SMALLINT` (int)
`SQL_INTEGER` (int)
`SQL_BIGINT` (int)
`SQL_REAL` (int)
`SQL_FLOAT` (int)
`SQL_DOUBLE` (int)
`SQL_BINARY` (int)
`SQL_VARBINARY` (int)
`SQL_LONGVARBINARY` (int)
`SQL_DATE` (int)
`SQL_TIME` (int)
`SQL_TIMESTAMP` (int)
`SQL_TYPE_DATE` (int)
`SQL_TYPE_TIME` (int)
`SQL_TYPE_TIMESTAMP` (int)
`SQL_BEST_ROWID` (int)
`SQL_ROWVER` (int)
`SQL_SCOPE_CURROW` (int)
`SQL_SCOPE_TRANSACTION` (int)
`SQL_SCOPE_SESSION` (int)
`SQL_NO_NULLS` (int)
`SQL_NULLABLE` (int)
`SQL_INDEX_UNIQUE` (int)
`SQL_INDEX_ALL` (int)
`SQL_ENSURE` (int)
`SQL_QUICK` (int)
`SQL_FETCH_FIRST` (int)
  Вернуть первый набор строк.
`SQL_FETCH_NEXT` (int)
  Вернуть следующий набор строк.

# Функции ODBC

# odbc_autocommit

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

odbc_autocommit — Переключает поведение автоматической фиксации

### Описание

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Функция переключает поведение автоматической фиксации.

По умолчанию для подключения включена автоматическая фиксация. Отключение автоматической фиксации эквивалентно запуску транзакции.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`enable`

  Со значением `true` параметр `enable` включает автоматическую фиксацию, со значением `false` — отключает. Функция возвращает статус автофиксации в соединении `odbc`, если в этот параметр передали значение `null`.

### Возвращаемые значения

Функция возвращает статус автоматической фиксации для подключения, которое передали в параметр `odbc`, если в параметр `enable` передали значение `null`. Функция возвращает ненулевое значение, если автоматическая фиксация включена, 0, если выключена, и `false`, если возникла ошибка.

Функция возвращает `true`, если выполнилась успешно, и `false`, если возникла ошибка, если значение аргумента `enable` отличается от значения `null`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.3.0 | Параметр `enable` теперь принимает значение `null`.

### Смотрите также

- odbc_commit() - Фиксирует ODBC-транзакцию
- odbc_rollback() - Откатывает транзакцию

# odbc_binmode

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

odbc_binmode — Обрабатывает данные двоичного столбца

### Описание

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

Функция управляет обработкой данных двоичного столбца. На ODBC-серверах функция затрагивает следующие типы SQL-данных: `BINARY`, `VARBINARY` и `LONGVARBINARY`. Режим по умолчанию устанавливают через директиву uodbc.defaultbinmode, которая содержится в файле php.ini.

Когда двоичные SQL-данные преобразовываются в символьные C-данные (`ODBC_BINMODE_CONVERT`), каждый байт (8 битов) исходных данных представляется парой символов в кодировке ASCII. Эти символы формируют символьное представление числа в формате ASCII в шестнадцатеричной форме. Например, двоичное число `00000001` преобразовывается в символьное представление `"01"`, а число `11111111` — в `"FF"`.

Хотя обработка столбцов с типами `BINARY` и `VARBINARY` зависит только от директивы binmode, обработка столбцов с типом `LONGVARBINARY` также зависит от атрибута longreadlen:

Обработка данных с типом LONGVARBINARY
Режим директивы binmode | Значение атрибута longreadlen | Результат
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | Сквозной сеанс
`ODBC_BINMODE_RETURN` | 0 | Сквозной сеанс
`ODBC_BINMODE_CONVERT` | 0 | Сквозной сеанс
`ODBC_BINMODE_PASSTHRU` | >0 | Сквозной сеанс
`ODBC_BINMODE_RETURN` | >0 | Данные возвращаются как есть
`ODBC_BINMODE_CONVERT` | >0 | Данные возвращаются как char

В сквозном режиме функция odbc_fetch_into() возвращает из столбцов с двоичными данными пустую строку. При установке сквозного режима и вызове функции odbc_result() данные отправляются непосредственно клиенту, выводятся.

### Список параметров

`statement`

  Объект ODBC с результатом.

`mode`

  Возможные значения параметра `mode`:

  - `ODBC_BINMODE_PASSTHRU`: Устанавливает сквозной режим для данных с типом BINARY
  - `ODBC_BINMODE_RETURN`: Данные возвращаются как есть
  - `ODBC_BINMODE_CONVERT`: Перед возвратом данные преобразовываются в тип char

  > Замечание: На обработку столбцов с типом двоичных данных LONG также влияет функция odbc_longreadlen().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_close

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

odbc_close — Закрывает ODBC-соединение

### Описание

function odbc_close(Odbc\Connection `$odbc`): void

Функция закрывает соединение с сервером базы данных.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.

### Примечания

> Замечание:

> Функция не сработает, если в соединении остались открытые транзакции, а соединение останется открытым.

# odbc_close_all

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

odbc_close_all — Закрывает все соединения ODBC

### Описание

function odbc_close_all(): void

odbc_close_all() закроет все соединения с сервером (серверами) базы данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примечания

> Замечание:

> Эта функция не сработает, если в соединении есть открытые транзакции. В этом случае соединение останется открытым.

# odbc_columnprivileges

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

odbc_columnprivileges — Перечисляет столбцы таблицы и привилегии, которые связаны со столбцами

### Описание

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Функция перечисляет столбцы таблицы и привилегии, которые связаны со столбцами.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`table`

  Название таблицы. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`column`

  Название столбца. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка. Из этого объекта получают список столбцов и связанные привилегии.

В результирующем наборе содержатся следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Драйвер иногда сообщает о дополнительных столбцах.

Результирующий набор упорядочивается по столбцам `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` и `PRIVILEGE`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.

### Примеры

Пример #1 Пример перечисления привилегий столбца

    <?php

    $conn = odbc_connect($dsn, $user, $pass);

    $privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');

    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => test
        [COLUMN_NAME] => id
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => INSERT
        [IS_GRANTABLE] => YES
    )

# odbc_columns

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

odbc_columns — Перечисляет названия столбцов в таблицах

### Описание

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Функция перечисляет столбцы в запрошенном диапазоне.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`table`

  Название таблицы. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`column`

  Название столбца. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

В результирующем наборе содержатся следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Драйвер иногда сообщает о дополнительных столбцах.

Результирующий набор упорядочивается по столбцам `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` и `ORDINAL_POSITION`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.0.0 | Параметры `schema`, `table` и `column` теперь принимают значение `null`.

### Примеры

Пример #1 Пример перечисления столбцов таблицы

    <?php

    $conn = odbc_connect($dsn, $user, $pass);

    $columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');

    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [DATA_TYPE] => 4
        [TYPE_NAME] => int
        [COLUMN_SIZE] => 10
        [BUFFER_LENGTH] => 4
        [DECIMAL_DIGITS] => 0
        [NUM_PREC_RADIX] => 10
        [NULLABLE] => 0
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => 4
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] =>
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => NO
    )

### Смотрите также

- odbc_columnprivileges() - Перечисляет столбцы таблицы и привилегии, которые связаны со столбцами
- odbc_procedurecolumns() - Получает информацию о параметрах процедур

# odbc_commit

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

odbc_commit — Фиксирует ODBC-транзакцию

### Описание

function odbc_commit(Odbc\Connection `$odbc`): bool

Функция фиксирует незавершённые транзакции соединения.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.

# odbc_connect

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

odbc_connect — Соединяется с источником данных

### Описание

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Идентификатор соединения, который возвращает функция, потребуется другим ODBC-функциям. Разрешается открывать несколько соединений одновременно, если коннектор установил соединение с разными базами данных или разными учётными данными.

Отдельные ODBC-драйверы, которые выполняют сложные хранимые процедуры, иногда завершаются ошибкой наподобие: "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it" («Невозможно открыть курсор в хранимой процедуре, которая содержит другие команды, кроме одной команды SELECT»). Тип курсора SQL_CUR_USE_ODBC помогает избегать появления этой ошибки. Отдельные драйверы также не поддерживают необязательный параметр row_number в функции odbc_fetch_row(). Курсор SQL_CUR_USE_ODBC также иногда помогает в похожих случаях.

### Список параметров

`dsn`

  Имя источника базы данных (англ. Database Source Name, DSN) для соединения. Альтернативно функция работает и со строкой соединения без DSN-имени.

`user`

  Имя. Параметр игнорируется, если `dsn` содержит `uid`. Для подключения без указания `user` используйте `null`.

`password`

  Пароль. Параметр игнорируется, если `dsn` содержит `pwd`. Для подключения без указания `password` используйте `null`.

`cursor_option`

  Устанавливает тип курсора для соединения. Обычно этот параметр не требуется, но иногда становится полезным для обхода проблем с отдельными ODBC-драйверами.

  Для типа курсора определили следующие константы:

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### Возвращаемые значения

Функция возвращает ODBC-соединение или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает экземпляр соединения Odbc\Connection; раньше возвращалось значение с типом resource.
8.4.0 | Параметры `user` и `password` теперь допускают значение `null`; они теперь являются необязательными и по умолчанию имеют значение `null`.
8.4.0 | Ранее использование пустой строки для параметра `password` не включало `pwd` в генерируемую строку подключения параметра `dsn`. Теперь он генерируется для включения `pwd`, который имеет пустую строку в качестве своего значения. Чтобы восстановить прежнее поведение, в параметр `password` теперь можно передать значение `null`.
8.4.0 | Ранее, если `dsn` содержал `uid` или `pwd`, параметры `user` и `password` игнорировались. Теперь параметр `user` игнорируется, только если значение параметра `dsn` содержит `uid`, а параметр `password` игнорируется, только если значение параметра `dsn` содержит `pwd`.

### Примеры

Пример #1 Пример соединения без DSN-строки подключения

    <?php

    // Microsoft SQL Server, который работает через драйвер SQL Native Client 10.0 ODBC Driver, разрешает соединяться
    // с серверами SQL 7, 2000, 2005 и 2008
    $connection = odbc_connect(
        "Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;",
        $user,
        $password
    );

    // Соединение с источником данных Microsoft Access
    $connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

    // Соединение с источником данных Microsoft Excel
    $excelFile = realpath('C:/ExcelData.xls');
    $excelDir = dirname($excelFile);
    $connection = odbc_connect(
        "Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir",
        '',
        ''
    );

    ?>

### Смотрите также

- Для постоянных соединений: odbc_pconnect() - Открывает постоянное соединение с базой данных

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Определяет, заключено ли значение строки соединения ODBC в кавычки

### Описание

function odbc_connection_string_is_quoted(string `$str`): bool

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

### Список параметров

`str`

  Строка, которую необходимо проверить на наличие кавычек.

### Возвращаемые значения

Возвращает `true`, если кавычки приведены правильно, в противном случае возвращает `false`.

### Смотрите также

- odbc_connection_string_quote() - Заключает в кавычки значение строки подключения
- odbc_connection_string_should_quote() - Определяет, следует ли заключать значение строки соединения ODBC в кавычки

# odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — Заключает в кавычки значение строки подключения

### Описание

function odbc_connection_string_quote(string `$str`): string

Заключает в кавычки значение строки подключения в соответствии с правилами ODBC. То есть оно будет окружено кавычками, а все завершающие фигурные скобки будут экранированы. Это необходимо делать для всех значений строки подключения, которые поступают от пользователя. Невыполнение этого требования может привести к проблемам с разбором строки подключения или к инъекции значений в строку подключения.

Обратите внимание, что данная функция не проверяет, не заключена ли уже строка в кавычки и не нуждается ли она в кавычках. Для этого следует использовать функцию odbc_connection_string_is_quoted() и odbc_connection_string_should_quote().

### Список параметров

`str`

  Строка, не заключённая в кавычки.

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования odbc_connection_string_quote()

В этом примере строка заключается в кавычки, а затем помещается в строку соединения. Обратите внимание, что строка заключена в кавычки, а символ окончания кавычек в середине строки был экранирован.

    <?php
    $value = odbc_connection_string_quote("foo}bar");
    $connection_string = "DSN=PHP;UserValue=$value";
    echo $connection_string;
    ?>

Вывод приведённого примера будет похож на:

    DSN=PHP;UserValue={foo}}bar}

### Смотрите также

- odbc_connection_string_is_quoted() - Определяет, заключено ли значение строки соединения ODBC в кавычки
- odbc_connection_string_should_quote() - Определяет, следует ли заключать значение строки соединения ODBC в кавычки

# odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — Определяет, следует ли заключать значение строки соединения ODBC в кавычки

### Описание

function odbc_connection_string_should_quote(string `$str`): bool

Определяет, нужно ли заключать строку в кавычки для строкового значения соединения ODBC, т.е. содержит ли она специальные символы.

Обратите внимание, что при этом не проверяется, заключена ли строка в кавычки; уже заключённая в кавычки строка будет содержать символы, которые заставят эту функцию вернуть значение true. Для проверки следует использовать функцию odbc_connection_string_is_quoted().

### Список параметров

`str`

  Строка, которую необходимо проверить.

### Возвращаемые значения

Возвращает `true`, если строка должна быть заключена в кавычки, в противном случае возвращает `false`.

### Смотрите также

- odbc_connection_string_quote() - Заключает в кавычки значение строки подключения
- odbc_connection_string_is_quoted() - Определяет, заключено ли значение строки соединения ODBC в кавычки

# odbc_cursor

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

odbc_cursor — Возвращает имя курсора

### Описание

function odbc_cursor(Odbc\Result `$statement`): string|false

Функция возвращает имя курсора для ODBC-объекта с результатом запроса.

### Список параметров

`statement`

  Объект ODBC с результатом.

### Возвращаемые значения

Функция возвращает имя курсора в виде строки или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Возвращает информацию о доступных именах DSN

### Описание

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

Функция вернёт список доступных имён источников данных DSN (после нескольких вызовов).

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`fetch_type`

  Параметр `fetch_type` указывают как один из двух типов констант: `SQL_FETCH_FIRST`, `SQL_FETCH_NEXT`. При первом вызове функции указывают константу `SQL_FETCH_FIRST`, а затем передают константу `SQL_FETCH_NEXT`.

### Возвращаемые значения

Функция возвращает `false`, если возникла ошибка, массив (array), если выполнилась успешно, и `null` после выборки последнего доступного DSN-имени.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.

### Примеры

Пример #1 Пример перечисления доступных DSN-строк для подключения

    <?php

    $conn = odbc_connect('dsn', 'user', 'pass');
    $dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);

    while ($dsn_info) {
        print_r($dsn_info);
        $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [server] => dsn
        [description] => ODBC Driver 17 for SQL Server
    )
    Array
    (
        [server] => other_dsn
        [description] => Microsoft Access Driver (*.mdb, *.accdb)
    )

# odbc_do

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

odbc_do — Псевдоним odbc_exec()

### Описание

Псевдоним функции odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Возвращает последний код ошибки

### Описание

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Функция возвращает шестизначное состояние ODBC-соединения или пустую строку, если ошибки не возникали.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция возвращает последнее состояние соединения `odbc`, если аргумент передали, иначе возвращает последнее состояние любого соединения.

Функция возвращает осмысленное значение, только если последний ODBC-запрос завершился ошибкой, — если функция odbc_exec() вернула значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.0.0 | Параметр `odbc` теперь принимает значение `null`.

### Смотрите также

- odbc_errormsg() - Возвращает последнее сообщение об ошибке
- odbc_exec() - Выполняет прямой SQL-запрос

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Возвращает последнее сообщение об ошибке

### Описание

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

Функция возвращает строку с последним сообщение об ошибке ODBC-соединения, или пустую строку, если ошибки не возникали.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция возвращает последенее состояние соединения `odbc`, если аргумент передали, иначе возвращает последнее состояние любого соединения.

Функция возвращает осмысленное значение, только если последний ODBC-запрос завершился неудачно, — если функция odbc_exec() вернула значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.0.0 | Параметр `odbc` теперь принимает значение `null`.

### Смотрите также

- odbc_error() - Возвращает последний код ошибки
- odbc_exec() - Выполняет прямой SQL-запрос

# odbc_exec

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

odbc_exec — Выполняет прямой SQL-запрос

### Описание

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Функция отправляет SQL-запрос на сервер базы данных.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`query`

  SQL-запрос.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом, если SQL-команда выполнилась успешно, или `false`, если возникла ошибки.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.
8.0.0 | Параметр `flags` удалили.

### Смотрите также

- odbc_prepare() - Подготавливает запрос к выполнению
- odbc_execute() - Выполняет запрос

# odbc_execute

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

odbc_execute — Выполняет запрос

### Описание

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Функция выполняет запрос, который подготовили функцией odbc_prepare().

### Список параметров

`statement`

  Объект ODBC с результатом из функции odbc_prepare().

`params`

  Заполнители в подготовленном запросе по порядку заменятся параметрами, которые передали в аргументе `params`. Элементы этого массива преобразуются в строки при вызове функции.

  Параметры в одинарных кавычках в аргументе `params` функция воспринимает как название файла для считывания и отправки на сервер базы данных в качестве данных для заполнителя.

  Для сохранения строки, которая начинается и заканчивается самими одинарными кавычками, потребуется обернуть параметр пробелами или другими символами, которые отличаются от одинарных кавычек, что предотвратит восприятие параметра как название файла. Строку сохраняют через другой механизм, например отправляют прямой запрос функцией odbc_exec(), если невозможно обернуть параметр другими символами.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.
8.0.0 | Параметр `flags` удалили.

### Примеры

Пример #1 Пример выполнения запроса функциями odbc_execute() и odbc_prepare()

В следующем примере переменной $success присвоится значение `true`, только если каждый из трёх параметров в списке параметров для выполнения хранимой процедуры myproc относится ко входному in-параметру, — передаётся в процедуру по значению:

    <?php

    $a = 1;
    $b = 2;
    $c = 3;

    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));

    ?>

Для вызова хранимой процедуры с inout-параметром, который передаётся по ссылке, или с out-параметром, который возвращается из процедуры по значению, лучше отправить запрос через родной модуль базы данных наподобие модуля oci8 для СУБД Oracle.

### Смотрите также

- odbc_prepare() - Подготавливает запрос к выполнению

# odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — Возвращает строку результата в виде ассоциативного массива

### Описание

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

Функция возвращает ассоциативный массив (array) из ODBC-запроса.

### Список параметров

`statement`

  Объект ODBC с результатом из функции odbc_exec().

`row`

  Необязательный параметр, который указывает номер строки для возврата.

### Возвращаемые значения

Функция возвращает массив, который соответствует возвращаемой строке, или `false`, если строк не осталось.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.
8.4.0 | Параметр `row` теперь принимает значение `null`.

### Примечания

> Замечание: Функция доступна при компиляции двоичного файла PHP с поддержкой драйвера DBMaker, IBM DB2 или UnixODBC.

### Смотрите также

- odbc_fetch_row() - Возвращает строку
- odbc_fetch_object() - Возвращает строку данных из результата запроса как объект
- odbc_num_rows() - Возвращает количество строк в результате

# odbc_fetch_into

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

odbc_fetch_into — Заполняет выходной параметр строкой из результата запроса

### Описание

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Функция извлекает из ODBC-объекта с результатом запроса одну строку и вставляет данные строки в параметр array, ссылкой на значение которого становится переменная в списке аргументов.

### Список параметров

`statement`

  Объект ODBC с результатом.

`array`

  Параметр array принимает значение произвольного типа, поскольку аргумент преобразуется в массив. Массив будет содержать значения столбцов, начиная с элемента с индексом 0.

`row`

  Номер строки.

### Возвращаемые значения

Функция возвращает количество столбцов, которое содержит строка в объекте с результатом запроса, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.
8.4.0 | Параметр `row` теперь принимает значение `null`.

### Примеры

Пример #1 Примеры извлечения строки из объекта с результатом запроса функцией odbc_fetch_into()

    <?php

    $rc = odbc_fetch_into($res_id, $my_array);

    ?>

или

    <?php

    $rc = odbc_fetch_into($res_id, $my_array, 2);

    ?>

# odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — Возвращает строку данных из результата запроса как объект

### Описание

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

Функция возвращает объект (object) из объекта ODBC с результатом запроса.

### Список параметров

`statement`

  Объект ODBC с результатом из функции odbc_exec().

`row`

  Необязательный параметр, который указывает номер строки для возврата.

### Возвращаемые значения

Функция возвращает объект, который соответствует извлечённой строке, или `false`, если строк не осталось.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.
8.4.0 | Параметр `row` теперь принимает значение `null`.

### Примечания

> Замечание: Функция доступна при только при компиляции двоичного файла PHP с поддержкой драйвера DBMaker, IBM DB2 или UnixODBC.

### Смотрите также

- odbc_fetch_row() - Возвращает строку
- odbc_fetch_array() - Возвращает строку результата в виде ассоциативного массива
- odbc_num_rows() - Возвращает количество строк в результате

# odbc_fetch_row

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

odbc_fetch_row — Возвращает строку

### Описание

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Функция выбирает строку из данных, которые вернула функция odbc_do() или odbc_exec(). После вызова функции odbc_fetch_row() доступ к полям этой строки получают функцией odbc_result().

### Список параметров

`statement`

  Объект ODBC с результатом.

`row`

  Функция odbc_fetch_row() попытается выбрать следующую строку в наборе результата, если параметр `row` не указали. Вызовы функции odbc_fetch_row() с параметром `row` и без него разрешается смешивать.

  Следующий способ разрешает обойти результат больше одного раза: функцию odbc_fetch_row() вызывают с аргументом `row`, равным 1, а затем продолжают вызывать функцию odbc_fetch_row() без аргумента `row`, чтобы просмотреть результат. Параметр `row` игнорируется, если драйвер не поддерживает выборку строк по номеру.

### Возвращаемые значения

Функция возвращает `true`, если строка существует, иначе возвращает значение `false`.

### Ошибки

Выбрасывается ошибка уровня `E_WARNING`, если значение параметра `row` меньше либо равно нулю.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.
8.4.0 | Теперь выбрасывается ошибка уровня `E_WARNING`, если значение параметра `row` меньше либо равно нулю.
8.0.0 | Параметр `row` теперь принимает значение `null`.

# odbc_field_len

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

odbc_field_len — Возвращает длину, или точность, поля

### Описание

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Функция получает длину поля по номеру поля в результате. Длина поля определяется количеством значащих десятичных цифр в числе.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Номер поля. Нумерация полей начинается с 1.

### Возвращаемые значения

Функция возвращает длину поля или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Смотрите также

- odbc_field_scale() - Получает масштаб поля Получает масштаб поля, чтобы узнать масштаб числа плавающей точкой

# odbc_field_name

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

odbc_field_name — Возвращает название столбца

### Описание

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Функция получает название поля по номеру столбца в объекте с результатом.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Номер поля. Нумерация полей начинается с 1.

### Возвращаемые значения

Функция возвращает имя поля в виде строки или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_field_num

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

odbc_field_num — Возвращает номер столбца

### Описание

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Функция получает номер слота столбца, который соответствует именованному полю в объекте с результатом.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Имя поля.

### Возвращаемые значения

Функция возвращает номер поля в виде целого числа или `false`, если возникла ошибка. Нумерация полей начинается с 1.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_field_precision

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

odbc_field_precision — Псевдоним odbc_field_len()

### Описание

Псевдоним функции odbc_field_len().

### Смотрите также

- odbc_field_scale() - Получает масштаб поля для получения масштаба числа с плавающей точкой

# odbc_field_scale

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

odbc_field_scale — Получает масштаб поля

### Описание

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

Функция получает масштаб поля по номеру поля в объекте с результатом. Масштаб поля определяется количеством цифр справа или слева от десятичной точки до наименее значащей цифры.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Номер поля. Нумерация полей начинается с 1.

### Возвращаемые значения

Функция возвращает масштаб поля в виде целого числа или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_field_type

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

odbc_field_type — Возвращает тип данных поля

### Описание

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Функция находит в объекте с результатом поле с заданным номером и возвращает тип SQL-данных этого поля.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Номер поля. Нумерация полей начинается с 1.

### Возвращаемые значения

Функция возвращает тип поля в виде строки или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_foreignkeys

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

odbc_foreignkeys — Извлекает список внешних ключей

### Описание

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

Функция извлекает список внешних ключей в заданной таблице или список внешних ключей в других таблицах, которые ссылаются на первичный ключ заданной таблицы.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`fk_catalog`

  Каталог ('квалификатор' на языке ODBC 2) таблицы с первичным ключом.

`pk_schema`

  Схема ('владелец' на языке ODBC 2) таблицы с первичным ключом.

`pk_table`

  Таблица с первичным ключом.

`pk_catalog`

  Каталог ('квалификатор' на языке ODBC 2) таблицы c внешним ключом.

`fk_schema`

  Схема ('владелец' на языке ODBC 2) таблицы с внешним ключом.

`fk_table`

  Таблица с внешним ключом.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

В результирующем наборе содержатся следующие столбцы:

- `PKTABLE_CAT`
- `PKTABLE_SCHEM`
- `PKTABLE_NAME`
- `PKCOLUMN_NAME`
- `FKTABLE_CAT`
- `FKTABLE_SCHEM`
- `FKTABLE_NAME`
- `FKCOLUMN_NAME`
- `KEY_SEQ`
- `UPDATE_RULE`
- `DELETE_RULE`
- `FK_NAME`
- `PK_NAME`
- `DEFERRABILITY`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `FKTABLE_CAT`, `FKTABLE_SCHEM`, `FKTABLE_NAME` и `KEY_SEQ`, если запрашиваются внешние ключи, которые связаны с первичным ключом. Набор результатов упорядочивается по столбцам `PKTABLE_CAT`, `PKTABLE_SCHEM`, `PKTABLE_NAME` и `KEY_SEQ`, если запрашиваются первичные ключи, которые связаны с внешним ключом.

Функция odbc_foreignkeys() возвращает набор результатов, в котором содержится первичный ключ заданной таблицы и все внешние ключи, которые на него ссылаются, если аргумент `pk_table` содержит название таблицы.

Функция odbc_foreignkeys() возвращает набор результатов, в котором содержатся все внешние ключи заданной таблицы и первичные ключи других таблиц, на которые ссылаются внешние ключи заданной таблицы, если аргумент `fk_table` содержит название таблицы.

Функция odbc_foreignkeys() возвращает внешние ключи таблицы `fk_table`, которые ссылаются на первичный ключ таблицы `pk_table`, если оба аргумента — `pk_table` и `fk_table` — содержат названия таблиц. Это должен быть максимум один ключ.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Смотрите также

- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных
- odbc_primarykeys() - Получает первичные ключи таблицы

# odbc_free_result

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

odbc_free_result — Освобождает объекты, которые связаны с результатом

### Описание

function odbc_free_result(Odbc\Result `$statement`): true

Функция освобождает объекты, которые связаны с результатом.

Функцию odbc_free_result() вызывают, только если во время работы скрипта потребляется чрезмерно много памяти. Память, которая хранит результат, автоматически освобождается после завершения скрипта.

### Список параметров

`statement`

  Объект ODBC с результатом.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Примечания

> Замечание:

> Транзакции, которые остались в режиме ожидания, отказываются, если автоматическую фиксацию отключили и функция odbc_free_result() вызывается перед фиксацией. Подробнее о включении и выключении автофиксации рассказывает описание функции odbc_autocommit().

# odbc_gettypeinfo

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

odbc_gettypeinfo — Возвращает информацию о типах данных, которые поддерживаются источником данных

### Описание

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Функция возвращает информацию о типах данных, которые поддерживаются источником данных.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`data_type`

  Тип данных, который умеет ограничивать информацию одним типом данных.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE

Набор результатов упорядочивается по столбцам DATA_TYPE и TYPE_NAME.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

# odbc_longreadlen

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

odbc_longreadlen — Обрабатывает столбцы с типом данных LONG

### Описание

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Функция управляет обработкой столбцов, в которых хранятся данные с типом `LONG`, `LONGVARCHAR` и `LONGVARBINARY`. Длина по умолчанию устанавливают через директиву uodbc.defaultlrl в файле php.ini.

### Список параметров

`statement`

  Объект ODBC с результатом.

`length`

  Количество байтов, которые возвращает PHP, контролируется длиной параметра. Данные столбца с типом LONG передаются клиенту, выводятся, при получении функцией odbc_result(), если установить значение `0`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Примечания

> Замечание:

> На обработку столбцов `LONGVARBINARY` также влияет функция odbc_binmode().

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Проверяет, доступно ли несколько результатов

### Описание

function odbc_next_result(Odbc\Result `$statement`): bool

Функция проверяет, доступны ли другие наборы результатов, и разрешает доступ к следующему набору результатов функциями odbc_fetch_array(), odbc_fetch_row(), odbc_result() и похожими.

### Список параметров

`statement`

  Объект ODBC с результатом.

### Возвращаемые значения

Функция возвращает `true`, если доступны другие наборы результатов, иначе возвращает значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Примеры

Пример #1 Пример проверки доступности нескольких результатов функцией odbc_next_result()

    <?php

    $r_Connection = odbc_connect($dsn, $username, $password);

    $s_SQL = <<<END_SQL
    SELECT 'A'
    SELECT 'B'
    SELECT 'C'
    END_SQL;

    $r_Results = odbc_exec($r_Connection, $s_SQL);

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Вывод первого набора результатов ";
    var_dump($a_Row1, $a_Row2);

    echo "Получаем второй набор результатов ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Вывод второго набора результатов ";
    var_dump($a_Row1, $a_Row2);

    echo "Получаем третий набор результатов ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Вывод третьего набора результатов ";
    var_dump($a_Row1, $a_Row2);

    echo "Попытка получить четвёртый набор результатов ";
    var_dump(odbc_next_result($r_Results));

    ?>

Результат выполнения приведённого примера:

    Вывод первого набора результатов array(1) {
      ["A"]=>
      string(1) "A"
    }
    bool(false)
    Получаем второй набор результатов bool(true)
    Вывод второго набора результатов array(1) {
      ["B"]=>
      string(1) "B"
    }
    bool(false)
    Получаем третий набор результатов bool(true)
    Вывод третьего набора результатов array(1) {
      ["C"]=>
      string(1) "C"
    }
    bool(false)
    Попытка получить четвёртый набор результатов bool(false)

# odbc_num_fields

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

odbc_num_fields — Возвращает количество столбцов в результате

### Описание

function odbc_num_fields(Odbc\Result `$statement`): int

Функция возвращает количество полей, или столбцов, в объекте ODBC с результатом запроса.

### Список параметров

`statement`

  Объект ODBC с результатом, который возвращает функция odbc_exec().

### Возвращаемые значения

Функция возвращает количество полей или -1, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

# odbc_num_rows

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

odbc_num_rows — Возвращает количество строк в результате

### Описание

function odbc_num_rows(Odbc\Result `$statement`): int

Функция получает количество строк в результате. Для инструкций INSERT, UPDATE и DELETE функция odbc_num_rows() возвращает количество строк, которое затронул — вставил, обновил или удалил — запрос. Для инструкции SELECT функция иногда возвращает количество доступных строк.

### Список параметров

`statement`

  Объект ODBC с результатом, который возвращает функция odbc_exec().

### Возвращаемые значения

Функция возвращает количество строк в объекте ODBC с результатом запроса. Функция вернёт -1, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Примечания

> Замечание:

> Попытка определить функцией odbc_num_rows() количество строк, доступных после выполнения инструкции SELECT, для большей части драйверов вернёт значение -1.

# odbc_pconnect

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

odbc_pconnect — Открывает постоянное соединение с базой данных

### Описание

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Функция открывает постоянное соединение с базой данных.

Функция похожа на функцию odbc_connect(), за исключением того, что соединение на самом деле не закрывается после завершения работы скрипта. Очередные запросы на соединение с той же комбинацией аргументов `dsn`, `user` и `password`, которые выполняют функциями odbc_connect() и odbc_pconnect(), могут повторно использовать постоянное соединение.

### Список параметров

Подробне о соединении с источником данных рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция возвращает ODBC-соединение или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь возвращает экземпляр соединения Odbc\Connection; раньше возвращалось значение с типом resource.
8.4.0 | Параметры `user` и `password` теперь допускают значение `null`; они теперь являются необязательными и по умолчанию имеют значение `null`.
8.4.0 | Ранее использование пустой строки для параметра `password` не включало `pwd` в генерируемую строку подключения параметра `dsn`. Теперь он генерируется для включения `pwd`, который имеет пустую строку в качестве своего значения. Чтобы восстановить прежнее поведение, в параметр `password` теперь можно передать значение `null`.
8.4.0 | Ранее, если `dsn` содержал `uid` или `pwd`, параметры `user` и `password` игнорировались. Теперь параметр `user` игнорируется, только если значение параметра `dsn` содержит `uid`, а параметр `password` игнорируется, только если значение параметра `dsn` содержит `pwd`.

### Примечания

> Замечание: Постоянные соединения не действуют, если PHP работает в режиме CGI.

### Смотрите также

- odbc_connect() - Соединяется с источником данных
- Постоянные соединения с базами данных

# odbc_prepare

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

odbc_prepare — Подготавливает запрос к выполнению

### Описание

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Функция подготавливает запрос к выполнению. Объект ODBC с результатом затем передают в функцию odbc_execute() для выполнения запроса.

Отдельные базы данных наподобие IBM DB2, MS SQL Server и Oracle поддерживают хранимые процедуры, которые принимают in-, inout- и out-параметры, как определяет спецификация протокола ODBC. Однако драйвер Unified ODBC пока поддерживает для хранимых процедур только in-параметры.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`query`

  Подготавливаемый запрос в виде строки.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом, если подготовка SQL-команды выполнилась успешно. Функция возвращает значение `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Примеры

Пример #1 Пример подготовки запроса к выполнению функциями odbc_execute() и odbc_prepare()

В следующем примере переменной $success присвоится значение `true`, только если каждый из трёх параметров в списке параметров для выполнения хранимой процедуры myproc относится ко входному in-параметру, — передаётся в процедуру по значению:

    <?php

    $a = 1;
    $b = 2;
    $c = 3;

    $stmt    = odbc_prepare($conn, 'CALL myproc(?, ?, ?)');
    $success = odbc_execute($stmt, array($a, $b, $c));

    ?>

Для вызова хранимой процедуры с inout-параметром, который передаётся по ссылке, или с out-параметром, который возвращается из процедуры по значению, лучше отправить запрос через родной модуль базы данных наподобие модуля oci8 для СУБД Oracle.

### Смотрите также

- odbc_execute() - Выполняет запрос

# odbc_primarykeys

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

odbc_primarykeys — Получает первичные ключи таблицы

### Описание

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Функция возвращает объект с результатами, из которых извлекают названия столбцов, из которых составили первичный ключ таблицы.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2).

`table`

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` и `KEY_SEQ`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Примеры

Пример #1 Пример получения списка первичных ключей столбца

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');

    while (($row = odbc_fetch_array($primarykeys))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### Смотрите также

- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных
- odbc_foreignkeys() - Извлекает список внешних ключей

# odbc_procedurecolumns

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

odbc_procedurecolumns — Получает информацию о параметрах процедур

### Описание

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Функция получает информацию о параметрах процедур.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`procedure`

  Процедура. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`column`

  Столбец. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

### Возвращаемые значения

Функция возвращает список входных и выходных параметров, и столбцы, из которых состоит набор результатов для заданных процедур. Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `COLUMN_NAME`
- `COLUMN_TYPE`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` и `COLUMN_TYPE`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.
8.0.0 | До этой версии функцию разрешалось вызывать только с одним или пятью аргументами.

### Примеры

Пример #1 Пример получения списка столбцов хранимой процедуры

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');

    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [COLUMN_NAME] => @SalesPerson
        [COLUMN_TYPE] => 1
        [DATA_TYPE] => -9
        [TYPE_NAME] => nvarchar
        [COLUMN_SIZE] => 50
        [BUFFER_LENGTH] => 100
        [DECIMAL_DIGITS] =>
        [NUM_PREC_RADIX] =>
        [NULLABLE] => 1
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => -9
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] => 100
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => YES
    )

### Смотрите также

- odbc_columns() - Перечисляет названия столбцов в таблицах

# odbc_procedures

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

odbc_procedures — Получает список процедур, которые хранятся в источнике данных

### Описание

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

Функция перечисляет процедуры в запрошенном диапазоне.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`procedure`

  Имя процедуры. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом, который содержит информацию, или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `NUM_INPUT_PARAMS`
- `NUM_OUTPUT_PARAMS`
- `NUM_RESULT_SETS`
- `REMARKS`
- `PROCEDURE_TYPE`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` и `PROCEDURE_NAME`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.
8.0.0 | До этой версии функцию разрешалось вызывать только с одним или четырьмя аргументами.

### Примеры

Пример #1 Пример получения списка хранимых процедур базы данных

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $procedures = odbc_procedures($conn, $catalog, $schema, '%');

    while (($row = odbc_fetch_array($procedures))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [NUM_INPUT_PARAMS] => -1
        [NUM_OUTPUT_PARAMS] => -1
        [NUM_RESULT_SETS] => -1
        [REMARKS] =>
        [PROCEDURE_TYPE] => 2
    )

### Смотрите также

- odbc_procedurecolumns() - Получает информацию о параметрах процедур
- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных

# odbc_result

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

odbc_result — Получает данные результата

### Описание

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Получает данные результата.

### Список параметров

`statement`

  Объект ODBC с результатом.

`field`

  Название поля, которое требуется извлечь: целое число с номером столбца поля или строка с названием поля.

### Возвращаемые значения

Функция возвращает строковое содержимое поля, `false`, если возникла ошибка, `null` для данных с типом NULL или `true` для двоичных данных.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.

### Примеры

Первый вызов функции odbc_result() возвращает значение третьего поля в текущей записи результата запроса. Второй вызов функции odbc_result() возвращает значение поля с именем "val" в текущей записи результата запроса. Ошибка возникает, если параметр номера столбца для поля меньше единицы или превышает количество столбцов (или полей) в текущей записи. Ошибка также возникает при попытке получить столбец с названием, которое не встречается ни в одном названии поля запрашиваемой таблицы, или нескольких таблиц.

Пример #1 Примеры получения данных результата функцией odbc_result()

    <?php

    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "val");

    ?>

### Примечания

Индексы полей начинаются с 1. Подробнее о способе возврата двоичных данных или данных столбцов с типом LONG рассказывают описания функций odbc_binmode() и odbc_longreadlen().

# odbc_result_all

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

odbc_result_all — Выводит результат в виде HTML-таблицы

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Функция выводит все строки из ODBC-объекта с результатом, который вернула функция odbc_exec(). Результат выводится в формате HTML-таблицы, данные не экранируются.

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

### Список параметров

`statement`

  Объект ODBC с результатом.

`format`

  Дополнительный параметр, который определяет общее форматирование таблицы.

### Возвращаемые значения

Функция возвращает количество строк в результате или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `statement` теперь принимает экземпляр с результом OBDC-запроса Odbc\Result; раньше принимался тип resource.
8.1.0 | Функция устарела.

# odbc_rollback

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

odbc_rollback — Откатывает транзакцию

### Описание

function odbc_rollback(Odbc\Connection `$odbc`): bool

Функция откатывает все запросы соединения, которые ожидают выполнения.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.

# odbc_setoption

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

odbc_setoption — Настраивает параметры ODBC-соединения или объекта ODBC с результатом запроса

### Описание

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

Функция настраивает параметры объекта ODBC для конкретного соединения или результата запроса. Функция помогает найти решение проблем в конкретных ODBC-драйверах. Функцией рекомендуют пользоваться только ODBC-программистам, которые понимают, как параметры влияют на объекты соединения и результата. Влияние параметров объясняют развёрнутые справочные руководства по протоколу ODBC. Список параметров, которые поддерживаются конкретным драйвером, зависит от версии драйвера.

Поскольку влияние параметров зависит от ODBC-драйвера, настоятельно не рекомендуют пользоваться функцией в общедоступных скриптах. Кроме прочего, функции недоступны отдельные параметры протокола ODBC, поскольку их требуется настроить до установки соединения или подготовки запроса. Функцией лучше пользоваться, только если она выполняет задачи, для решения которых приходится покупать коммерческий продукт.

### Список параметров

`odbc`

  Идентификатор соединения или идентификатор результата, для которого требуется изменить настройки. Для функции SQLSetConnectOption() это идентификатор соединения. Для функции SQLSetStmtOption() это идентификатор результата.

`which`

  ODBC-функция, которую требуется вызывать. Для функции SQLSetConnectOption() указывают значение 1, а для функции SQLSetStmtOption() значение 2.

`option`

  Параметр, который требуется установить.

`value`

  Значение для параметра `option`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь ожидает экземпляр класса Odbc\Connection или Odbc\Result; раньше ожидалось значение с типом resource.

### Примеры

Пример #1 Примеры установки параметров функцией odbc_setoption()

    <?php

    // 1. Опция 102 SQLSetConnectOption() — SQL_AUTOCOMMIT.
    //    Значение 1 SQL_AUTOCOMMIT — SQL_AUTOCOMMIT_ON.
    //    Этот пример сработает аналогично
    //    вызову odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Опция 0 SQLSetStmtOption() — SQL_QUERY_TIMEOUT.
    //    Пример устанавливает для времени ожидания запроса 30 секунд

    $result = odbc_prepare($conn, $sql);
    odbc_setoption($result, 2, 0, 30);
    odbc_execute($result);

    ?>

# odbc_specialcolumns

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

odbc_specialcolumns — Извлекает особые столбцы

### Описание

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

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

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`type`
  С аргументом `SQL_BEST_ROWID` функция odbc_specialcolumns() возвращает столбец или столбцы, которые однозначно идентифицируют каждую строку в таблице. С аргументом `SQL_ROWVER` функция odbc_specialcolumns() возвращает столбец или столбцы в заданной таблице, если таблица содержит эти столбцы, которые автоматически обновляются источником данных, когда любое значение в строке обновляется любой транзакцией.
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2).

`table`

  Таблица.

`scope`

  Область, которая упорядочивает результирующий набор. Константа из следующего списка: `SQL_SCOPE_CURROW`, `SQL_SCOPE_TRANSACTION` или `SQL_SCOPE_SESSION`.

`nullable`

  Определяет, возвращать ли специальные столбцы, в которых разрешается хранить значение NULL. Константа `SQL_NO_NULLS` или `SQL_NULLABLE`.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка. ошибки.

Набор результатов содержит следующие столбцы:

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцу `SCOPE`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Смотрите также

- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных

# odbc_statistics

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

odbc_statistics — Получает статистику о таблице

### Описание

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

Функция получает статистику о таблице и её индексах.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2).

`table`

  Имя таблицы.

`unique`

  Тип индекса. Константа `SQL_INDEX_UNIQUE` или `SQL_INDEX_ALL`.

`accuracy`

  Константа `SQL_ENSURE` или `SQL_QUICK`. Последняя запрашивает у драйвера получение `CARDINALITY` и `PAGES`, только если они легко доступны с сервера.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `NON_UNIQUE`
- `INDEX_QUALIFIER`
- `INDEX_NAME`
- `TYPE`
- `ORDINAL_POSITION`
- `COLUMN_NAME`
- `ASC_OR_DESC`
- `CARDINALITY`
- `PAGES`
- `FILTER_CONDITION`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` и `ORDINAL_POSITION`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Примеры

Пример #1 Пример вывода статистики о таблице

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);

    while (($row = odbc_fetch_array($statistics))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [NON_UNIQUE] =>
        [INDEX_QUALIFIER] =>
        [INDEX_NAME] =>
        [TYPE] => 0
        [ORDINAL_POSITION] =>
        [COLUMN_NAME] =>
        [ASC_OR_DESC] =>
        [CARDINALITY] => 15
        [PAGES] => 3
        [FILTER_CONDITION] =>
    )

### Смотрите также

- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных

# odbc_tableprivileges

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

odbc_tableprivileges — Перечисляет таблицы и привилегии, которые связаны с каждой таблицей

### Описание

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Функция перечисляет таблицы в запрошенном диапазоне и привилегии, которые связаны с каждой таблицей.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`table`

  Имя таблицы. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` и `GRANTEE`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.

### Примеры

Пример #1 Пример вывода списка привилегий таблицы

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');

    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### Смотрите также

- odbc_tables() - Получает список имён таблиц, которые хранятся в источнике данных

# odbc_tables

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

odbc_tables — Получает список имён таблиц, которые хранятся в источнике данных

### Описание

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|false

Функция перечисляет таблицы в запрошенном диапазоне.

Для поддержки перечисления квалификаторов, владельцев и типов таблиц доступна следующая специальная семантика для параметром `catalog`, `schema`, `table` и `table_type`:

- Набор результатов будет содержать список допустимых квалификаторов для источника данных (все столбцы, кроме столбца TABLE_QUALIFIER, содержат NULL), если значение аргумента `catalog` равно символу процента (%), а в аргументах `schema` и `table` передали пустые строки.
- Набор результатов будет содержать список допустимых владельцев для источника данных (все столбцы, кроме столбца TABLE_OWNER, содержат NULL), если значение аргумента `schema` равно символу процента (%), а в аргументы `catalog` и `table` передали пустые строки.
- Набор результатов будет содержать список допустимых типов таблиц для источника данных (все столбцы, кроме столбца TABLE_TYPE, содержат NULL), если значение аргумента `table_type` равно символу процента (%), а в аргументах `catalog`, `schema` и `table` передали пустые строки.

### Список параметров

`odbc`
  Объект ODBC-соединения. Подробнее о коннекторе рассказывает описание функции odbc_connect().
`catalog`

  Каталог ('qualifier' на языке ODBC 2).

`schema`

  Схема ('owner' на языке ODBC 2). Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`table`

  Имя таблицы. Параметр принимает следующие шаблоны поиска: `%`, который соответствует нулю или более символам, и `_`, который соответствует ровно одному символу.

`types`

  В параметр передают список значений типов через запятую, если в параметр `table_type` передаётся не пустая строка; каждое значение разрешается заключать в одинарные кавычки `'` или передавать значения без кавычек. Например, `'TABLE','VIEW'` или `TABLE, VIEW`. Функция odbc_tables() не вернёт никаких результатов для типа, если источник данных не поддерживает заданный тип таблицы.

### Возвращаемые значения

Функция возвращает объект ODBC с результатом, который содержит информацию, или `false`, если возникла ошибка.

Набор результатов содержит следующие столбцы:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Драйвер иногда сообщает о дополнительных столбцах.

Набор результатов упорядочивается по столбцам `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` и `TABLE_NAME`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `odbc` теперь принимает объект соединения Odbc\Connection; раньше принимался тип resource.
8.4.0 | Функция теперь возвращает объект с результатом ODBC-запроса Odbc\Result; раньше возвращалось значение с типом resource.
8.0.0 | Параметры `schema`, `table` и `types` теперь принимают значение `null`.

### Примеры

Пример #1 Пример вывода списка таблиц в каталоге

    <?php

    $conn = odbc_connect($dsn, $user, $pass);
    $tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');

    while (($row = odbc_fetch_array($tables))) {
        print_r($row);
        break; // Следующие строки опустили для краткости
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### Смотрите также

- odbc_tableprivileges() - Перечисляет таблицы и привилегии, которые связаны с каждой таблицей
- odbc_columns() - Перечисляет названия столбцов в таблицах
- odbc_specialcolumns() - Извлекает особые столбцы
- odbc_statistics() - Получает статистику о таблице
- odbc_procedures() - Получает список процедур, которые хранятся в источнике данных

## Содержание

- odbc_autocommit — Переключает поведение автоматической фиксации
- odbc_binmode — Обрабатывает данные двоичного столбца
- odbc_close — Закрывает ODBC-соединение
- odbc_close_all — Закрывает все соединения ODBC
- odbc_columnprivileges — Перечисляет столбцы таблицы и привилегии, которые связаны со столбцами
- odbc_columns — Перечисляет названия столбцов в таблицах
- odbc_commit — Фиксирует ODBC-транзакцию
- odbc_connect — Соединяется с источником данных
- odbc_connection_string_is_quoted — Определяет, заключено ли значение строки соединения ODBC в кавычки
- odbc_connection_string_quote — Заключает в кавычки значение строки подключения
- odbc_connection_string_should_quote — Определяет, следует ли заключать значение строки соединения ODBC в кавычки
- odbc_cursor — Возвращает имя курсора
- odbc_data_source — Возвращает информацию о доступных именах DSN
- odbc_do — Псевдоним odbc_exec
- odbc_error — Возвращает последний код ошибки
- odbc_errormsg — Возвращает последнее сообщение об ошибке
- odbc_exec — Выполняет прямой SQL-запрос
- odbc_execute — Выполняет запрос
- odbc_fetch_array — Возвращает строку результата в виде ассоциативного массива
- odbc_fetch_into — Заполняет выходной параметр строкой из результата запроса
- odbc_fetch_object — Возвращает строку данных из результата запроса как объект
- odbc_fetch_row — Возвращает строку
- odbc_field_len — Возвращает длину, или точность, поля
- odbc_field_name — Возвращает название столбца
- odbc_field_num — Возвращает номер столбца
- odbc_field_precision — Псевдоним odbc_field_len
- odbc_field_scale — Получает масштаб поля
- odbc_field_type — Возвращает тип данных поля
- odbc_foreignkeys — Извлекает список внешних ключей
- odbc_free_result — Освобождает объекты, которые связаны с результатом
- odbc_gettypeinfo — Возвращает информацию о типах данных, которые поддерживаются источником данных
- odbc_longreadlen — Обрабатывает столбцы с типом данных LONG
- odbc_next_result — Проверяет, доступно ли несколько результатов
- odbc_num_fields — Возвращает количество столбцов в результате
- odbc_num_rows — Возвращает количество строк в результате
- odbc_pconnect — Открывает постоянное соединение с базой данных
- odbc_prepare — Подготавливает запрос к выполнению
- odbc_primarykeys — Получает первичные ключи таблицы
- odbc_procedurecolumns — Получает информацию о параметрах процедур
- odbc_procedures — Получает список процедур, которые хранятся в источнике данных
- odbc_result — Получает данные результата
- odbc_result_all — Выводит результат в виде HTML-таблицы
- odbc_rollback — Откатывает транзакцию
- odbc_setoption — Настраивает параметры ODBC-соединения или объекта ODBC с результатом запроса
- odbc_specialcolumns — Извлекает особые столбцы
- odbc_statistics — Получает статистику о таблице
- odbc_tableprivileges — Перечисляет таблицы и привилегии, которые связаны с каждой таблицей
- odbc_tables — Получает список имён таблиц, которые хранятся в источнике данных

# Класс Odbc\Connection

(PHP 8 >= 8.4.0)

## Введение

Полностью непрозрачный класс, которым с PHP 8.4.0 заменили ресурс (resource) `odbc_connection`.

## Обзор класса

namespace Odbc;
class Connection {
}

# Класс Odbc\Result

(PHP 8 >= 8.4.0)

## Введение

Полностью непрозрачный класс, которым с PHP 8.4.0 заменили ресурс (resource) `odbc_result`

## Обзор класса

namespace Odbc;
class Result {
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Функции ODBC
  - odbc_autocommit — Переключает поведение автоматической фиксации
  - odbc_binmode — Обрабатывает данные двоичного столбца
  - odbc_close — Закрывает ODBC-соединение
  - odbc_close_all — Закрывает все соединения ODBC
  - odbc_columnprivileges — Перечисляет столбцы таблицы и привилегии, которые связаны со столбцами
  - odbc_columns — Перечисляет названия столбцов в таблицах
  - odbc_commit — Фиксирует ODBC-транзакцию
  - odbc_connect — Соединяется с источником данных
  - odbc_connection_string_is_quoted — Определяет, заключено ли значение строки соединения ODBC в кавычки
  - odbc_connection_string_quote — Заключает в кавычки значение строки подключения
  - odbc_connection_string_should_quote — Определяет, следует ли заключать значение строки соединения ODBC в кавычки
  - odbc_cursor — Возвращает имя курсора
  - odbc_data_source — Возвращает информацию о доступных именах DSN
  - odbc_do — Псевдоним odbc_exec
  - odbc_error — Возвращает последний код ошибки
  - odbc_errormsg — Возвращает последнее сообщение об ошибке
  - odbc_exec — Выполняет прямой SQL-запрос
  - odbc_execute — Выполняет запрос
  - odbc_fetch_array — Возвращает строку результата в виде ассоциативного массива
  - odbc_fetch_into — Заполняет выходной параметр строкой из результата запроса
  - odbc_fetch_object — Возвращает строку данных из результата запроса как объект
  - odbc_fetch_row — Возвращает строку
  - odbc_field_len — Возвращает длину, или точность, поля
  - odbc_field_name — Возвращает название столбца
  - odbc_field_num — Возвращает номер столбца
  - odbc_field_precision — Псевдоним odbc_field_len
  - odbc_field_scale — Получает масштаб поля
  - odbc_field_type — Возвращает тип данных поля
  - odbc_foreignkeys — Извлекает список внешних ключей
  - odbc_free_result — Освобождает объекты, которые связаны с результатом
  - odbc_gettypeinfo — Возвращает информацию о типах данных, которые поддерживаются источником данных
  - odbc_longreadlen — Обрабатывает столбцы с типом данных LONG
  - odbc_next_result — Проверяет, доступно ли несколько результатов
  - odbc_num_fields — Возвращает количество столбцов в результате
  - odbc_num_rows — Возвращает количество строк в результате
  - odbc_pconnect — Открывает постоянное соединение с базой данных
  - odbc_prepare — Подготавливает запрос к выполнению
  - odbc_primarykeys — Получает первичные ключи таблицы
  - odbc_procedurecolumns — Получает информацию о параметрах процедур
  - odbc_procedures — Получает список процедур, которые хранятся в источнике данных
  - odbc_result — Получает данные результата
  - odbc_result_all — Выводит результат в виде HTML-таблицы
  - odbc_rollback — Откатывает транзакцию
  - odbc_setoption — Настраивает параметры ODBC-соединения или объекта ODBC с результатом запроса
  - odbc_specialcolumns — Извлекает особые столбцы
  - odbc_statistics — Получает статистику о таблице
  - odbc_tableprivileges — Перечисляет таблицы и привилегии, которые связаны с каждой таблицей
  - odbc_tables — Получает список имён таблиц, которые хранятся в источнике данных
- Odbc\Connection — Класс Odbc\Connection
- Odbc\Result — Класс Odbc\Result

# Модуль доступа к базам данных PHP Data Objects

# Введение

Модуль PDO (англ. сокр.: `PHP Data Objects` — «Объекты баз данных в языке PHP») определяет легковесный и непротиворечивый интерфейс доступа к базам данных в PHP. Каждый драйвер базы данных, в котором реализовали интерфейс модуля, умеет представлять характерную для базы данных функциональность в виде стандартных функций модуля. Для доступа к серверу базы данных потребуется указать PDO-драйвер, который соответствует конкретной базе данных; взаимодействовать с базой данных только через сам модуль PDO невозможно.

PDO поддерживает доступ к данным на уровне абстракции, поэтому независимо от конкретной базы данных доступны одни и те же функции выполнения запросов и извлечения данных. Модуль PDO не абстрагирует саму базу данных; модуль не переписывает SQL-запросы и не эмулирует функции, которые не поддерживает СУБД. Доступ к таким функциям даёт только полноценная абстракция базы данных.

PHP поставляется вместе с модулем PDO.

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

Модуль включён по умолчанию. Модуль отключается во время выполнения опцией: --disable-pdo

Установка PDO на Unix-системах

1. PDO и драйвер PDO_SQLITE включены по умолчанию в PHP. Чтобы включить PDO драйвер для произвольной базы данных, обратитесь к документации драйверы PDO баз данных.

   > Замечание:

   > Если PDO собирается, как подгружаемый модуль (не рекомендуется), то все PDO-драйверы должны быть загружены после загрузки самого PDO.

2. При установке PDO в качестве подгружаемого модуля в файл php.ini необходимо внести изменения, чтобы модуль PDO загружался автоматически при запуске PHP. Также туда придётся включить загрузку некоторых драйверов баз данных; при этом убедитесь, что они перечислены после строки extension=pdo, так как PDO должен загрузиться первым. Если вы устанавливаете PDO и драйверы баз данных как статичные модули, этот шаг можно пропустить.

       extension=pdo

Пользователи Windows

1. Модуль PDO включён по умолчанию. Выберите DLL конкретных баз данных и либо загружать их во время выполнения функцией dl(), либо включить их в php.ini. Например, следующий код загружает драйвер PDO_SQLITE, но оставляет закомментированным драйвер PDO_ODBC:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   Эти DLL должны находиться в директории extension_dir.

> Замечание:

> Не забывайте, что после внесения изменений в php.ini необходим перезапуск PHP, чтобы новые опции конфигурации вступили в силу.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Настройки конфигурации PDO
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
pdo.dsn.* |  | только php.ini |

Краткое разъяснение конфигурационных директив.

`pdo.dsn.*` string

  Определяет псевдоним DSN. Дополнительно смотрите PDO::__construct().

# Предопределённые константы

## Содержание

- Режимы выборки

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

## Режимы выборки

Информацию о семействе констант курсора — `PDO::FETCH_ORI_*` — содержит раздел «Константы курсора».

## Базовые режимы выборки

Режим выборки | Краткое описание
--- | ---
`PDO::FETCH_DEFAULT` | Служебный режим, в котором данные извлекаются в текущем режиме выборки по умолчанию.
`PDO::FETCH_ASSOC` | Ассоциативный массив с индексацией только по названию столбца.
`PDO::FETCH_BOTH` (режим по умолчанию) | Индексно-ассоциативный массив с индексацией как по номеру, так и по названию столбца.
`PDO::FETCH_NAMED` | Вариант режима `PDO::FETCH_ASSOC`, в котором при дублировании названий столбцов значения не перезаписываются, а возвращаются в массиве.
`PDO::FETCH_NUM` | Индексный массив с индексацией только по номеру столбца.
`PDO::FETCH_COLUMN` | Значение или массив значений одного столбца.
`PDO::FETCH_KEY_PAIR` | Массив пар «ключ — значение» с индексацией по первому столбцу.
`PDO::FETCH_FUNC` | Результат вызова callback-функции. Режим совместим только с методом PDOStatement::fetchAll().
`PDO::FETCH_OBJ` | Объект стандартного класса — stdClass.
`PDO::FETCH_CLASS` | Объект конкретного класса.

## Опции режима PDO::FETCH_CLASS

Опции изменяют поведение режима `PDO::FETCH_CLASS`.

Опция | Краткое описание
--- | ---
`PDO::FETCH_CLASSTYPE` | Опция указывает вернуть данные в объекте класса, название которого совпадает с названием первого столбца в запросе.
`PDO::FETCH_PROPS_LATE` | Опция указывает вызвать конструктор перед установкой свойств объекта.
`PDO::FETCH_SERIALIZE` | Опция указывает вернуть PHP-объект из сериализованных данных. Начиная с PHP 8.1.0 опция устарела.

## Режимы с одним результатом

Следующие режимы несовместимы с методом PDOStatement::fetchAll().

Режим выборки | Краткое описание
--- | ---
`PDO::FETCH_BOUND` | Привязывает значения к переменным.
`PDO::FETCH_INTO` | Обновляет свойства объекта.
`PDO::FETCH_LAZY` | Ленивая выборка через объект PDORow, который поддерживает доступ к свойствам как через синтаксис доступа к элементам массива, так и через стандартный синтаксис доступа к свойствам объекта.

## Флаги специфичного поведения метода PDOStatement::fetchAll()

Следующие режимы работают только для многострочной выборки методом PDOStatement::fetchAll() и несовместимы с режимами выборки по другой логике. Подробности даёт полная документация.

Режим выборки | Краткое описание
--- | ---
`PDO::FETCH_GROUP` | Группирует результаты по первому столбцу.
`PDO::FETCH_UNIQUE` | Уникально индексирует результаты по первому столбцу.

## Обработка дублирующихся названий столбцов

Результаты выборки иногда содержат столбцы с одинаковым названием, как при объединении двух таблиц с одноимёнными столбцами.

Массив или объект возвращается с единственным значением из одноимённых столбцов, поскольку PHP-структуры — массивы и объекты — не поддерживают одинаковых названий ключей или свойств.

Какое значение из дубликатов названий вернётся — не определено.

Столбцам указывают псевдонимы, чтобы проблема дублирования названий столбцов не возникала. Например:

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

Дополнительную информацию даёт описание режимов `PDO::FETCH_NAMED`, `PDO::ATTR_FETCH_TABLE_NAMES` и `PDO::ATTR_FETCH_CATALOG_NAMES`.

## Установка режима выборки по умолчанию

Передача константы `PDO::ATTR_DEFAULT_FETCH_MODE` в параметрах метода PDO::__construct() или в аргументе атрибута метода PDO::setAttribute() устанавливает режим выборки по умолчанию для всех запросов.

Режим выборки по умолчанию для конкретной SQL-инструкции устанавливают методом PDOStatement::setFetchMode(). Индивидуальный режим влияет на повторное выполнение подготовленных SQL-инструкций и перебор результатов конструкцией `foreach`.

Предостережение

Методом PDOStatement::setAttribute() нельзя установить режим выборки по умолчанию для конкретного запроса. Метод принимает только атрибуты, совместимые с текущим драйвером, и молча игнорирует атрибуты, которые не распознал.

## PDO::FETCH_DEFAULT (int)

Режим доступен с PHP 8.0.7.

Служебное значение, которое ссылается на текущий режим выборки по умолчанию для объекта PDOStatement. Константу часто указывают как значение по умолчанию для параметров методов пользовательских классов, которые расширяют класс PDOStatement и которые указывают через атрибут `PDO::ATTR_STATEMENT_CLASS` как тип для возврата результатов запроса.

Значение нельзя указывать с атрибутом `PDO::ATTR_DEFAULT_FETCH_MODE`.

## PDO::FETCH_ASSOC (int)

В режиме `PDO::FETCH_ASSOC` возвращается ассоциативный массив, в котором ключи соответствуют названиям столбцов.

    <?php

    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

Режим выборки по умолчанию.

В режиме `PDO::FETCH_BOTH` возвращается индексно-ассоциативный массив, в котором значение каждой строки дублируется: одно возвращается со строковым ключом по названию столбца, другое — с числовым ключом по номеру столбца.

Нумерация столбцов начинаются с 0 и определяется порядком столбцов в результатах запроса, а не, например, порядком определения столбцов в таблице.

> Замечание:

> Лучше не опираться на числовой индекс столбца, поскольку нумерация изменится при изменении порядка столбцов в запросе или при изменении схемы таблицы и запросе наподобие `SELECT *`.

> Замечание: Количество записей с индексацией по названию столбца не совпадёт с количеством записей с индексацией по номеру столбца, если в результате возвращаются столбцы с одинаковым названием.

    <?php

    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

В режиме `PDO::FETCH_NAMED` результаты возвращаются в формате, аналогичном режиму `PDO::FETCH_ASSOC`, за исключением возврата всех значений повторных столбцов в виде списка.

Подробнее об обработке повторных названий столбцов и альтернативах рассказывает раздел «Обработка дублирующихся названий столбцов».

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

    <?php

    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );

    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

В режиме `PDO::FETCH_NUM` возвращается индексный массив, в котором ключи соответствуют номеру столбца. Нумерация столбцов начинается с 0 и определяется порядком столбцов в результатах запроса, а не, например, порядком определения столбцов в таблице.

> Замечание: Лучше не опираться на числовой индекс столбца, поскольку нумерация изменится при изменении порядка столбцов в запросе или при изменении схемы таблицы и запросе наподобие `SELECT *`.

    <?php

    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

В режиме `PDO::FETCH_COLUMN` возвращаются значения из одного столбца. При вызове метода PDOStatement::setFetchMode() или PDOStatement::fetchAll() конкретный столбец указывают во втором аргументе.

Метод выбросит ошибку ValueError, если таблица не содержит заданный столбец.

    <?php

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

В режиме `PDO::FETCH_KEY_PAIR` возвращается массив пар «ключ — значение», в котором ключи соответствуют первому столбцу. В этом режиме в запросе указывают только 2 столбца. Режим выборки вернёт осмысленные результаты только при вызове метода PDOStatement::fetchAll().

> Замечание: Значения потеряются, если первый столбец содержит неуникальные значения. Невозможно определить, какое значение или какие значения теряются.

    <?php

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

В этом режиме возвращается значение, которое вернёт функция обратного вызова. Режим работает только с методом PDOStatement::fetchAll().

Значения столбцов становятся аргументами функции. По значениям аргументов невозможно получить названия столбцов. При определении пользовательской функции проверяют соответствие порядка столбцов в запросе порядку параметров функции.

> Замечание: Режим `PDO::FETCH_GROUP` группирует, а режим `PDO::FETCH_UNIQUE` уникализирует результаты выборки до вызова пользовательской функции обратного вызова.

    <?php

    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

В режиме `PDO::FETCH_OBJ` возвращается объект stdClass.

См. также описания метода PDOStatement::fetchObject() и режима `PDO::FETCH_CLASS`.

    <?php

    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

Результат выполнения приведённого примера:

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

В этом режиме возвращается объект заданного класса. Дополнительную информацию о поведении даёт описание флагов опций.

Свойство объявится динамически, если класс не содержит свойства с названием возвращаемого столбца. Объявление динамических свойств устарело и начиная с PHP 9.0 вызовет ошибку.

См. также описание метода PDOStatement::fetchObject().

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
            print "Свойства устанавливаются до вызова конструктора? "
                . (isset($this->name) ? 'Да' : 'Нет') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );

    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);

    $result = $stmt->fetch();

    var_dump($result);

Вывод приведённого примера будет похож на:

    Конструктор вызвали со следующим количеством аргументов: 0
    Свойства устанавливаются до вызова конструктора? Да
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

Опция работает только в сочетании с режимом `PDO::FETCH_CLASS` и другими опциями режима.

С этой опцией модуль PDO возвращает данные в объекте класса, название которого совпадает с названием первого столбца в запросе.

Модуль вернет объект stdClass, без выдачи предупреждения или ошибки, если заданный класс недоступен.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
            print "Свойства устанавливаются до вызова конструктора? "
                . (isset($this->name) ? 'Да' : 'Нет') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );

    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);

    $result = $stmt->fetch();

    var_dump($result);

Вывод приведённого примера будет похож на:

    Конструктор вызвали со следующим количеством аргументов: 0
    Свойства устанавливаются до вызова конструктора? Да
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

Опция работает только в сочетании с режимом `PDO::FETCH_CLASS` и другими опциями режима.

С этой опцией конструктор вызывается до установки свойств.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
            print "Свойства устанавливаются до вызова конструктора? "
                . (isset($this->name) ? 'Да' : 'Нет') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );

    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);

    $result = $stmt->fetch();
    var_dump($result);

Вывод приведённого примера будет похож на:

    Конструктор вызвали со следующим количеством аргументов: 0
    Свойства устанавливаются до вызова конструктора? Нет
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

Внимание

Начиная с PHP 8.1.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

Режим выборки работает только в сочетании с режимом `PDO::FETCH_CLASS` и опциями режима.

Режим устанавливают только с классами, которые реализуют интерфейс Serializable.

Предостережение

Режим не поддерживает сами строки с результатом сериализации объекта, как это делает функция serialize().

Предостережение

Режим выборки не вызывает конструктор.

    <?php

    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
            print "Свойства устанавливаются до вызова конструктора? "
                . (isset($this->name) ? 'Да' : 'Нет') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Настройка записи (конструктор вызывается вручную):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nПолучаем результат:\n";

    $query = "SELECT sdata FROM serialize";

    $stmt = $db->query($query);

    // ПРИМЕЧАНИЕ: Конструктор не вызывается!
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);

    $result = $stmt->fetch();

    var_dump($result);

Вывод приведённого примера будет похож на:

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Настройка записи (конструктор вызывается вручную):
    Конструктор вызвали со следующим количеством аргументов: 0
    Свойства устанавливаются до вызова конструктора? Нет

    Получаем результат:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

Опция несовместима с методом PDOStatement::fetchAll().

С этой опцией модуль не возвращает результат напрямую, а привязывает значения к переменным, которые указали методом PDOStatement::bindColumn(). Вызов метода выборки возвращает значение `true`.

> Замечание:

> Для корректной работы подготовленных SQL-инструкций переменные привязывают после выполнения запроса.

    <?php

    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // Связываем переменную по позиции столбца, чтобы разрешить дублирование названия столбца.
    // А лучше вместо названия столбца указать в SQL-запросе псевдоним,
    // чтобы не сломать привязку при изменении запроса,
    // например: referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

Результат выполнения приведённого примера:

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

Режим выборки несовместим с методом PDOStatement::fetchAll().

Режим выборки обновляет свойства заданного объекта. Метод выборки возвращает объект, если выполнился успешно.

Свойство объявится динамически, если класс не содержит свойства с названием возвращаемого столбца. Объявление динамических свойств устарело и начиная с PHP 9.0 вызовет ошибку.

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

Предостережение

Невозможно изменить обновляемый объект без вызова метода PDOStatement::setFetchMode() между извлечением каждой записи.

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

Вывод приведённого примера будет похож на:

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

Режим выборки несовместим с методом PDOStatement::fetchAll().

Режим возвращает объект PDORow, который поддерживает доступ к свойствам как через синтаксис доступа к элементам массива, так и через синтаксис доступа к свойствам объекта, сочетая поведение режимов `PDO::FETCH_BOTH` и `PDO::FETCH_OBJ`. В этом режиме при извлечении очередной строки метод подготавливает объект с результатами «ленивым» способом — не создаёт новый экземпляр, а обновляет значения свойств в том же объекте.

Ленивое извлечение повышает эффективность доступа к небуферизованным результатам на сервере баз данных, с точки зрения работы с памятью на стороне PHP. Буферизует ли модуль PDO результаты на клиентской стороне, зависит от специфичного для базы данных драйвера и его конфигурации.

Предостережение

При доступе к неопределённым свойствам или ключам объект PDORow вернет значение `NULL`, без ошибки или предупреждения. Это затруднит обнаружение и отладку ошибок, которые возникают из-за опечаток, или запросов, которые не возвращают ожидаемые данные.

Предостережение

Возвращаемый объект PDORow обновляется каждый раз при извлечении результата.

    <?php

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: " . $result[0] . "\n";
    print "Name: {$result->name}\n";
    print "Country: " . $result['country'] . "\n";
    // Возвращается NULL. Без выдачи предупреждения или ошибки.
    print "Неопределённое свойство: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // Предыдущий объект PDORow теперь указывает на вновь извлечённый результат
    print "ID: " . $result[0] . "\n";

Результат выполнения приведённого примера:

    ID: 104
    Name: Chris
    Country: Ukraine
    Неопределённое свойство: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

В режиме `PDO::FETCH_GROUP` возвращаются списки ассоциативных массивов, ключами которых становятся значения первого столбца. Для уникальных столбцов возвращаются списки из одной записи, поэтому установка режима становится оправданной только при группировке результатов по неуникальному столбцу. Режим выборки работает только с методом PDOStatement::fetchAll().

При объединении с режимом `PDO::FETCH_UNIQUE` оба проиндексируют результаты выборки по одному и тому же столбцу, поэтому сочетание режимов бесполезно.

Режим выборки с группировкой по первому столбцу комбинируют со следующими режимами: `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` или `PDO::FETCH_FUNC`.

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

    <?php

    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

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

    <?php

    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

В режиме `PDO::FETCH_UNIQUE` возвращается массив, в котором записи индексируются по первому столбцу, и возвращается только одна запись для значения индекса. Режим выборки работает только с методом PDOStatement::fetchAll().

При объединении с режимом `PDO::FETCH_GROUP` оба проиндексируют результаты выборки по одному и тому же столбцу, поэтому сочетание режимов бесполезно.

Режим выборки с уникализацией по первому столбцу комбинируют со следующими режимами: `PDO::FETCH_ASSOC`, `PDO::FETCH_BOTH`, `PDO::FETCH_NAMED`, `PDO::FETCH_NUM`, `PDO::FETCH_COLUMN` или `PDO::FETCH_FUNC`.

Объект PDOStatement обработает результаты в режиме выборки по умолчанию, если для режима уникализации не задали режим из приведённого списка.

При работе с уникальным столбцом наподобие ID режим быстро возвращает результаты, поскольку БД содержит индекс для такого значения.

> Замечание: При выборке из неуникальных столбцов значения потеряются. Невозможно определить, какое значение или какие значения теряются.

Предостережение

Фильтрацию записей лучше выполнять в SQL-запросе, когда возможно. База данных построит план запроса с учётом индексов, чтобы оптимизировать фильтрацию и вернуть только искомые записи. Выборка из базы данных избыточного количества записей значительно увеличивает потребление памяти и время выполнения запроса для более крупных наборов данных с результатами запроса.

    <?php

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

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

    <?php

    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

Результат выполнения приведённого примера:

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## Курсоры

См. также описание константы `PDO::ATTR_CURSOR_NAME`.

`PDO::FETCH_ORI_NEXT` (int)
  Предписывает выбрать следующую строку из набора результатов. Константа действительна только для прокручиваемых курсоров.
`PDO::FETCH_ORI_PRIOR` (int)
  Предписывает выбирать предыдущую строку из набора результатов. Константа действительна только для прокручиваемых курсоров.
`PDO::FETCH_ORI_FIRST` (int)
  Предписывает выбирать первую строку из набора результатов. Константа действительна только для прокручиваемых курсоров.
`PDO::FETCH_ORI_LAST` (int)
  Предписывает выбирать последнюю строку из набора результатов. Константа действительна только для прокручиваемых курсоров.
`PDO::FETCH_ORI_ABS` (int)
  Предписывает выбирать строку с заданным номером из набора результатов. Константа действительна только для прокручиваемых курсоров.
`PDO::FETCH_ORI_REL` (int)
  Предписывает выбирать строку из набора результатов относительно текущего положения курсора. Константа действительна только для прокручиваемых курсоров.
`PDO::CURSOR_FWDONLY` (int)
  Предписывает создавать объект PDOStatement с последовательным курсором. Последовательные курсоры выбираются по умолчанию, поскольку это наиболее общий и быстрый в PHP шаблон доступа к данным.
`PDO::CURSOR_SCROLL` (int)
  Предписывает создавать объект PDOStatement с прокручиваемым курсором. Передача констант семейства `PDO::FETCH_ORI_*` управляет поведением курсора при выборке строк из набора результатов.

## Другие константы

`PDO::PARAM_BOOL` (int)
  Представляет логический тип данных.
`PDO::PARAM_NULL` (int)
  Представляет тип данных NULL в SQL.
`PDO::PARAM_INT` (int)
  Представляет тип данных INTEGER в SQL.
`PDO::PARAM_STR` (int)
  Представляет CHAR, VARCHAR и другие строковые типы данных в SQL.
`PDO::PARAM_STR_NATL` (int)
  Флаг для обозначения строк в национальных кодировках. Константа доступна с PHP 7.2.0.
`PDO::PARAM_STR_CHAR` (int)
  Флаг для обозначения строк в кодировках по умолчанию для БД. Константа доступна с PHP 7.2.0.
`PDO::PARAM_LOB` (int)
  Представляет в БД тип данных для больших объектов (англ. Large Objects, LOB) в SQL.
`PDO::PARAM_STMT` (int)
  Представляет тип recordset. Не поддерживается текущими драйверами.
`PDO::PARAM_INPUT_OUTPUT` (int)
  Указывает, что параметр хранимой процедуры работает в режиме INOUT. Константу указывают через побитовое ИЛИ с константой семейства `PDO::PARAM_*`.
`PDO::ATTR_AUTOCOMMIT` (bool)
  Со значением `false` модуль PDO попытается отключить автоматическую фиксацию изменений в базе данных, чтобы подключение начало транзакцию. Начиная с PHP 8.4.0 у константы логический тип (bool); ранее использовался целочисленный тип (int).
`PDO::ATTR_PREFETCH` (int)
  Баланс между расходом памяти и скоростью работы с базой данных регулируют путём изменения размера буфера предвыборки. Не каждая комбинация «база — драйвер» поддерживает изменение размера этого буфера. Чем больше этот размер, тем выше быстродействие, но и выше расход памяти.
`PDO::ATTR_TIMEOUT` (int)
  Устанавливает время в секундах, в течение которого требуется завершить обмен с базой данных.
`PDO::ATTR_ERRMODE` (int)
  Подробно об этом атрибуте рассказывает раздел «Ошибки и обработка ошибок».
`PDO::ATTR_SERVER_VERSION` (int)
  Атрибут доступен только для чтения; константа возвращает информацию о версии сервера баз данных, к которому подключён модуль PDO.
`PDO::ATTR_CLIENT_VERSION` (int)
  Атрибут доступен только для чтения; константа хранит информацию о версии клиентских библиотек, с которыми взаимодействует драйвер модуля PDO.
`PDO::ATTR_SERVER_INFO` (int)
  Атрибут доступен только для чтения; константа возвращает метаинформацию о сервере баз данных, к которому подключён модуль PDO.
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  Приводит названия столбцов к регистру, который определяют константами семейства `PDO::CASE_*`.
`PDO::ATTR_CURSOR_NAME` (int)
  Получает или устанавливает название курсора. Константа полезна при работе с прокручиваемыми курсорами и позиционными обновлениями.
`PDO::ATTR_CURSOR` (int)
  Выбирает типа курсора. Драйвер модуля PDO поддерживает два типа курсоров: `PDO::CURSOR_FWDONLY` и `PDO::CURSOR_SCROLL`. Тип `PDO::CURSOR_SCROLL` указывают, только если требуется прокручиваемый курсор, иначе выбирают режим последовательного курсора — `PDO::CURSOR_FWDONLY`.
`PDO::ATTR_DRIVER_NAME` (int)
  Возвращает название драйвера.

  Пример #1 Извлечение названия драйвера через атрибут `PDO::ATTR_DRIVER_NAME`

      <?php

      if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
          echo "Работаем с драйвером mysql; выполняем операцию, специфичную для драйвера mysql\n";
      }

`PDO::ATTR_ORACLE_NULLS` (int)
  При выборке данных преобразует пустые строки в значения с SQL-типом NULL.
`PDO::ATTR_PERSISTENT` (int)
  Запрашивать постоянное соединение вместо установки нового подключения. Подробнее об атрибуте рассказывает раздел «Подключения и управление подключениями».
`PDO::ATTR_STATEMENT_CLASS` (int)
  Устанавливает название класса, в виде экземпляров которого возвращаются результаты SQL-запросов.
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  Предписывает предварять названия столбцов названиями каталогов в наборе результатов. Название столбца и название каталога разделяют символом точки. Поддержка атрибута выполняется на уровне драйвера; атрибут поддерживается не каждым драйвером.
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  Предписывает предварять названия столбцов названиями исходных таблиц в наборе результатов. Название столбца и название таблицы разделяют символом точки. Поддержка атрибута выполняется на уровне драйвера; атрибут поддерживается не каждым драйвером.
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  Заставляет значения выборки, кроме `null`, обрабатываться как строки. Значения `null` не изменяются, если только для атрибута `PDO::ATTR_ORACLE_NULLS` не установили значение `PDO::NULL_TO_STRING`.
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  Устанавливает максимум длины названия столбца.
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (bool)
  Включает или отключает эмуляцию подготовленных запросов. Некоторые драйверы либо не поддерживают встроенные подготовленные запросы, либо поддерживают их ограниченно. Со значением `true` модуль PDO всегда эмулирует подготовленные запросы; со значением `false` используются встроенные подготовленные запросы драйвера. Начиная с PHP 8.4.0 у константы логический тип (bool); ранее использовался целочисленный тип (int).
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  Устанавливает тип строкового параметра по умолчанию. Атрибут принимает значение в виде константы `PDO::PARAM_STR_NATL` или `PDO::PARAM_STR_CHAR`. Константа доступна с PHP 7.2.0.
`PDO::ERRMODE_SILENT` (int)
  Подавляет генерацию ошибок и исключений при сбое. Разработчик сам проверяет, не возникла ли ошибка. До PHP 8.0.0 этот режим обработки ошибок применялся по умолчанию. Подробнее об атрибуте рассказывает раздел «Ошибки и обработка ошибок».
`PDO::ERRMODE_WARNING` (int)
  Предписывает выдавать сообщение о PHP-ошибке уровня `E_WARNING`. Подробнее об атрибуте рассказывает раздел «Ошибки и обработка ошибок».
`PDO::ERRMODE_EXCEPTION` (int)
  Предписывает выбрасывать исключение PDOException при ошибках. Подробнее об атрибуте рассказывает раздел «Ошибки и обработка ошибок».
`PDO::CASE_NATURAL` (int)
  Сохраняет регистр названий столбцов в результатах драйвера базы данных.
`PDO::CASE_LOWER` (int)
  Приводит названия столбцов к нижнему регистру.
`PDO::CASE_UPPER` (int)
  Приводит названия столбцов к верхнему регистру.
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::ERR_NONE` (string)
  Значение константы соответствует SQLSTATE-коду '00000', который указывает на успешное выполнение SQL-запроса, без ошибок и предупреждений. Константа помогает убедиться в отсутствии ошибок через сравнение значения константы с SQLSTATE-кодами из методов PDO::errorCode() и PDOStatement::errorCode(), хотя о появлении ошибки и так станет известно, когда сам результат выполнения PDO-метода укажет на состояние ошибки.
`PDO::PARAM_EVT_ALLOC` (int)
  Сигнализирует о событии выделения памяти для параметра запроса.
`PDO::PARAM_EVT_FREE` (int)
  Сигнализирует о событии освобождения памяти, выделенной для параметра запроса.
`PDO::PARAM_EVT_EXEC_PRE` (int)
  Идентифицирует событие, которое срабатывает перед выполнением подготовленного SQL-запроса.
`PDO::PARAM_EVT_EXEC_POST` (int)
  Идентифицирует событие, которое срабатывает после выполнения подготовленного SQL-запроса.
`PDO::PARAM_EVT_FETCH_PRE` (int)
  Идентифицирует событие, которое срабатывает перед извлечением данных из результата запроса.
`PDO::PARAM_EVT_FETCH_POST` (int)
  Идентифицирует событие, которое срабатывает после извлечения данных из результата запроса.
`PDO::PARAM_EVT_NORMALIZE` (int)
  Идентифицирует событие, которое срабатывает при регистрации драйвером привязанного параметра перед нормализацией названия параметра.
`PDO::SQLITE_DETERMINISTIC` (int)
  Указывает на детерминированность функции, которую создали методом PDO::sqliteCreateFunction(). Детерминированная функция всегда возвращает один и тот же результат при одинаковых входных данных в пределах одной SQL-инструкции. Константа доступна с PHP 7.1.4.

# Подключения и управление подключениями

Для установки соединений создают экземпляры базового класса — PDO. Неважно, через какой драйвер разработчик взаимодействует с базой данных; объекты подключения создают по имени класса PDO, независимо от драйвера. Конструктор класса принимает аргументы, которые определят источник базы данных (англ. Data Source Name, DSN) и необязательные имя пользователя и пароль, если передали.

Пример #1 Подключение к БД MySQL

    <?php

    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);

    ?>

Модуль выбросит исключение `PDOException`, если при подключении возникнут ошибки. Исключение перехватывают и обрабатывают, или оставляют глобальному обработчику исключений приложения, который установили функцией set_exception_handler().

Пример #2 Пример обработки ошибок подключения

    <?php

    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // Например, через какое-то время повторить попытку соединения
    }

    ?>

Внимание

Как и остальные исключения, исключение PDOException перехватывают явно — через блок `catch` или неявно — функцией set_exception_handler(). По умолчанию непойманное исключение преобразуется в фатальную ошибку уровня `E_FATAL_ERROR`. Фатальная ошибка будет содержать стек вызовов, из-за которой появляется риск утечки информации о соединении. Поэтому на сервере, который работает в производственной среде, в файле php.ini для опции `display_errors` устанавливают значение `0`.

После успешного подключения к базе данных экземпляр класса PDO возвращается в скрипт. Соединение остаётся активным в течение жизни объекта PDO. Потребуется уничтожить объект, чтобы закрыть соединение. Объект уничтожают путём удаления ссылок на объект через присваивание значения `null` переменным, которые содержат объект. PHP автоматически закроет соединение по окончании работы скрипта, если не сделать этого явно.

> Замечание: Другие ссылки, которые по-прежнему указывают на экземпляр PDO, также потребуется удалить. Такие ссылки остаются в экземпляре PDOStatement или в других переменных, которые ссылаются на тот же экземпляр PDO. Ссылки удаляют путём присваивания значения `null` переменной, которая ссылается на объект PDOStatement.

Пример #3 Пример закрытия соединения

    <?php

    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);

    // С этого места пользуемся соединением...
    $sth = $dbh->query('SELECT * FROM foo');

    // ...а здесь соединение больше не требуется; закрываем его
    $sth = null;
    $dbh = null;

    ?>

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

Пример #4 Постоянные соединения

    <?php

    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
        PDO::ATTR_PERSISTENT => true
    ));

    ?>

Значение параметра `PDO::ATTR_PERSISTENT` преобразовывается в логическое значение (bool): включить или выключить постоянные подключения, если только это не числовая строка (string), которая разрешает использовать несколько пулов постоянных подключений. Это приносит пользу, когда разные соединения используют несовместимые настройки, например, разные значения режима буферизации `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`.

> Замечание:

> Постоянные соединения включают путём добавления константы `PDO::ATTR_PERSISTENT` в массив параметров драйвера, которые передают конструктору класса PDO. Драйвер не будет использовать постоянные соединения, если установить этот атрибут методом PDO::setAttribute() после создания объекта.

Внимание

Модуль PDO не выполняет очистку постоянных подключений. Временные таблицы, блокировки, транзакции и другие изменения состояния могут оставаться от предыдущего использования подключения, вызывая непредвиденные проблемы. Дополнительные сведения смотрите в разделе Постоянные соединения с базами данных.

> Замечание:

> При взаимодействии с ODBC-драйвером модуля PDO и если ODBC-библиотеки поддерживают объединение подключений в пул по протоколу ODBC, как это делают unixODBC и Windows, и, возможно, другие системы, то вместо постоянных PDO-соединений рекомендуют оставлять кеширование соединений на уровне ODBC-пула. Пул соединений драйвера ODBC разделяет соединения с другими модулями в процессе; если PDO-объект попросят кешировать соединение, то такое соединение не вернётся в пул соединений драйвера ODBC, из-за чего драйвер создаст дополнительные подключения для обслуживания других модулей.

# Транзакции и автоматическая фиксация изменений

После подключения к базе данных средствами модуля PDO потребуется понять, как PDO управляет транзакциями, прежде чем отправлять запросы. Тем, кто прежде не сталкивались с транзакциями, полезно знать 4 главных характеристики транзакций: атомарность, согласованность, изолированность и долговечность (англ. Atomicity, Consistency, Isolation and Durability, или ACID). Говоря простым языком, транзакция гарантирует, что каждая операция с базой данных выполнится безопасно и без помех со стороны других подключений, даже если операция выполняется поэтапно. Транзакционные операции автоматически отменяются по запросу, если транзакцию ещё не зафиксировали, что упрощает обработку ошибок в скриптах.

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

Не каждая база данных поддерживает транзакции, поэтому при первом подключении модуль PDO вынужден работать в так называемом режиме «автоматической фиксации». В режиме автофиксации модуль оборачивает каждый запрос к базе данных в неявную транзакцию, если СУБД поддерживает транзакции, или выполняет отдельные запросы, если база данных не поддерживает механизм транзакций. Явное начало транзакции обозначают вызовом метода PDO::beginTransaction(). Независимо от настроек обработки ошибок модуль выбросит исключение PDOException, если нижележащий драйвер не поддерживает механизм транзакций, поскольку попытка начать транзакцию без поддержки драйвера — серьёзная ошибка. Внутри транзакции изменения фиксируют методом PDO::commit(), если код выполнился успешно, или откатывают транзакцию методом PDO::rollBack(), если при запуске кода в течение транзакции возникла ошибка.

Внимание

Модуль PDO проверяет доступность транзакций только на уровне драйвера. Метод PDO::beginTransaction() вернёт `true` без ошибок, если сервер базы данных примет запрос на запуск транзакции, даже если в конкретных условиях при выполнении запроса выяснится, что транзакции недоступны.

К таким примерам относится попытка запуска транзакций в таблицах MyISAM базы данных MySQL.

Внимание

Неявные фиксации при выполнении DDL-запросов: Отдельные базы данных неявно выполняют команду `COMMIT` и фиксируют изменения в одной транзакции при выполнении серии DDL-запросов (англ. Database Definition Language) наподобие `DROP TABLE` или `CREATE TABLE`. Поэтому изменения, которые оказались в транзакции, автоматически фиксируются, и откатить такие изменения невозможно.

К примерам баз данных с таким поведением относятся СУБД `MySQL` и `Oracle`.

Пример #1 Пример неявной фиксации

    <?php

    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // Неявная фиксация командой COMMIT выполняется в этом месте
    $pdo->rollBack(); // Невозможно отменить серию команд INSERT/CREATE в БД MySQL или Oracle

    ?>

Лучшая практика: При работе с базами данных с таким поведением рекомендуют избегать выполнения DDL-запросов внутри транзакций. DDL-операции исключают из транзакционной логики, когда требуется.

Модуль PDO автоматически откатит невыполненные транзакции при завершении работы скрипта или при закрытии соединения. Откат транзакций — мера безопасности, которая помогает избегать нарушения целостности данных, когда скрипт неожиданно прерывает работу. Модуль предполагает, что взаимодействие с базой данных нарушилось, раз изменения не зафиксировали явным образом, и откатывает изменения для безопасности данных.

Внимание

Изменения откатятся автоматически, только если транзакцию открыли методом PDO::beginTransaction(). При ручной отправке запроса, который начинает транзакцию, PDO не узнает об этом, поэтому не откатит транзакцию при сбое.

Пример #2 Выполнение пакета изменений в рамках транзакции

В следующем примере предположим, что требуется создать набор записей для нового сотрудника с идентификатором 23. Кроме ввода базовой информации о сотруднике потребуется записать его зарплату. Вместо двух отдельных изменений обернём обновление таблиц методами PDO::beginTransaction() и PDO::commit(), чтобы гарантировать, что никто другой не увидит этих изменений, пока вставка данных не завершится. При сбое блок catch откатит изменения, которые внесли с момента начала транзакции, и выведет сообщение об ошибке.

    <?php

    try {
        $dbh = new PDO(
            'odbc:SAMPLE',
            'db2inst1',
            'ibmdb2',
            array(PDO::ATTR_PERSISTENT => true)
        );

        echo "Подключились\n";
    } catch (Exception $e) {
        die("Возникла ошибка подключения: " . $e->getMessage());
    }

    try {
        $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

        $dbh->beginTransaction();
        $dbh->exec("INSERT INTO staff (id, first, last) VALUES (23, 'Joe', 'Bloggs')");
        $dbh->exec("INSERT INTO salarychange (id, amount, changedate) VALUES (23, 50000, NOW())");
        $dbh->commit();
    } catch (Exception $e) {
        $dbh->rollBack();
        echo "Ошибка: " . $e->getMessage();
    }

    ?>

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

# Подготовленные запросы и хранимые процедуры

Большинство баз данных поддерживают концепцию подготовленных запросов. Что это такое? Это можно описать, как некий вид скомпилированного шаблона SQL запроса, который будет запускаться приложением и настраиваться с помощью входных параметров. У подготовленных запросов есть два главных преимущества:

- Запрос необходимо однажды подготовить и затем его можно запускать столько раз, сколько нужно, причём как с теми же, так и с отличающимися параметрами. Когда запрос подготовлен, СУБД анализирует его, компилирует и оптимизирует план его выполнения. В случае сложных запросов этот процесс может занимать ощутимое время и заметно замедлить работу приложения, если потребуется много раз выполнять запрос с разными параметрами. При использовании подготовленного запроса СУБД анализирует/компилирует/оптимизирует запрос любой сложности только один раз, а приложение запускает на выполнение уже подготовленный шаблон. Таким образом подготовленные запросы потребляют меньше ресурсов и работают быстрее.
- Параметры подготовленного запроса не требуется экранировать кавычками; драйвер это делает автоматически. Если в приложении используются исключительно подготовленные запросы, разработчик может быть уверен, что никаких SQL-инъекций случиться не может (однако, если другие части текста запроса создаются с неэкранированным вводом, то SQL инъекция по-прежнему возможна).

Подготовленные запросы также полезны тем, что PDO может эмулировать их, если драйвер базы данных не имеет подобной функциональности. Это значит, что приложение может пользоваться одной и той же методикой доступа к данным независимо от возможностей СУБД.

Пример #1 Повторяющиеся вставки в базу с использованием подготовленных запросов

В этом примере 2 раза выполняется INSERT запрос с разными значениями `name` и `value`, которые подставляются вместо соответствующих псевдопеременных:

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // вставим одну строку
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // теперь другую строку с другими значениями
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Пример #2 Повторяющиеся вставки в базу с использованием подготовленных запросов

В этом примере 2 раза выполняется INSERT запрос с разными значениями `name` и `value`, которые подставляются вместо псевдопеременных `?`.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // вставим одну строку
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // теперь другую строку с другими значениями
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Пример #3 Выборка данных с использованием подготовленных запросов

В этом примере производится выборка из базы по ключу, который вводит пользователь через форму. Пользовательский ввод автоматически заключается в кавычки, поэтому нет риска SQL инъекции.

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

Пример #4 Вызов хранимой процедуры с выходными параметрами

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

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // вызов хранимой процедуры
    $stmt->execute();

    print "процедура вернула $return_value\n";
    ?>

Пример #5 Вызов хранимой процедуры с входным/выходным параметром

Можно задать параметр одновременно входным и выходным; синтаксис при этом тот же, что и для выходных параметров. В следующем примере строка 'привет' передаётся в хранимую процедуру, а затем эта строка будет заменена возвращаемым значением.

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'привет';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // вызов хранимой процедуры
    $stmt->execute();

    print "процедура вернула $value\n";
    ?>

Пример #6 Неправильное использование псевдопеременной

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // псевдопеременная может использоваться только в виде отдельного значения
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# Ошибки и их обработка

PDO предлагает на выбор 3 стратегии обработки ошибок в зависимости от вашего стиля разработки приложений.

- `PDO::ERRMODE_SILENT`

  До PHP 8.0.0, это был режим по умолчанию. PDO просто предоставит вам код ошибки, который можно получить методами PDO::errorCode() и PDO::errorInfo(). Эти методы реализованы как в объектах запросов, так и в объектах баз данных. Если ошибка вызвана во время выполнения кода объекта запроса, нужно вызвать метод PDOStatement::errorCode() или PDOStatement::errorInfo() этого объекта. Если ошибка вызова объекта базы данных, нужно вызвать аналогичные методы у этого объекта.

- `PDO::ERRMODE_WARNING`

  Помимо установки кода ошибки PDO выдаст обычное E_WARNING сообщение. Это может быть полезно при отладке или тестировании, когда нужно видеть, что произошло, но не нужно прерывать работу приложения.

- `PDO::ERRMODE_EXCEPTION`

  Начиная с PHP 8.0.0 является режимом по умолчанию. Помимо задания кода ошибки PDO будет выбрасывать исключение PDOException, свойства которого будут отражать код ошибки и её описание. Этот режим также полезен при отладке, так как сразу известно, где в программе произошла ошибка. Это позволяет быстро локализовать и решить проблему. (Не забывайте, что если исключение является причиной завершения работы скрипта, все активные транзакции будут откачены.)

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

  Подробнее об исключениях в PHP смотрите в разделе Исключения.

PDO стандартизирован для работы со строковыми кодами ошибок SQL-92 SQLSTATE. Отдельные драйверы PDO могут задавать соответствия своих собственных кодов кодам SQLSTATE. Метод PDO::errorCode() возвращает одиночный код SQLSTATE. Если необходима специфичная информация об ошибке, PDO предлагает метод PDO::errorInfo(), который возвращает массив, содержащий код SQLSTATE, код ошибки драйвера, а также строку ошибки драйвера.

Пример #1 Создание PDO объекта и установка режима обработки ошибок

    <?php
    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // PDO выбросит исключение PDOException (если таблица не существует)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

Результат выполнения приведённого примера:

    Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
    Stack trace:
    #0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
    #1 {main}
      thrown in /tmp/pdo_test.php on line 10

> Замечание:

> Метод PDO::__construct() будет всегда бросать исключение PDOException, если соединение оборвалось, независимо от установленного значения `PDO::ATTR_ERRMODE`.

Пример #2 Создание экземпляра класса PDO и установка режима обработки ошибок в конструкторе

    <?php
    $dsn = 'mysql:dbname=test;host=127.0.0.1';
    $user = 'googleguy';
    $password = 'googleguy';

    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

    // Следующий запрос приводит к ошибке уровня E_WARNING вместо исключения (когда таблица не существует)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");
    ?>

Результат выполнения приведённого примера:

    Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
    /tmp/pdo_test.php on line 9

# Большие объекты

Иногда для работы приложения требуется хранить «большие» порции данных в базе. Часто под большим понимают объем данных «около 4 килобайтов или больше», хотя отдельные базы данных спокойно обрабатывают до 32 килобайтов, прежде чем размер данных становится «большим». Большие объекты (англ. Large Objects, LOB) бывают текстовыми или двоичными. Модуль PDO разрешает работать с такими объектами путём установки типа данных `PDO::PARAM_LOB` в методах PDOStatement::bindParam() или PDOStatement::bindColumn(). Флаг `PDO::PARAM_LOB` сообщает объекту PDO, что данные требуется отобразить в виде потока, чтобы управлять данными через API-интерфейс PHP-потоков.

Пример #1 Вывод изображения, которое хранится в базе данных

В примере LOB-объект связывают с переменной $lob, а затем отправляют в браузер функцией fpassthru(). Поскольку PDO-объект представил LOB-объект как поток, с большим объектом получится работать функциями наподобие fgets(), fread() и stream_get_contents().

    <?php

    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');

    $stmt = $db->prepare("select contenttype, imagedata from images where id=?");
    $stmt->execute(array($_GET['id']));
    $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
    $stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
    $stmt->fetch(PDO::FETCH_BOUND);

    header("Content-Type: $type");

    fpassthru($lob);

    ?>

Пример #2 Вставка изображения в базу данных

Следующий пример открывает файл и передаёт дескриптор файла в объект PDO для вставки файла в базу данных в виде LOB-объекта. Объект PDO извлечёт содержимое файла и вставит его в базу данных самым эффективным способом.

    <?php

    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');

    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // Некоторая функция, которая выделит новый ID

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

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();

    ?>

Пример #3 Вставка изображения в базу данных: Oracle

БД Oracle требует другой синтаксис для извлечения содержимого файла в виде LOB-объекта и вставки большого объекта в базу данных. Вставку больших объектов в БД выполняют в рамках транзакции, иначе БД зафиксирует LOB-объект, который только что вставила, с нулевой длиной — как часть неявной фиксации, которая возникает при выполнении каждого запроса.

    <?php

    $db = new PDO('oci:', 'scott', 'tiger');

    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
    "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?")
    ;

    $id = get_new_id(); // Некоторая функция, которая выделит новый ID

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

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();

    ?>

# Класс PDO

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## Введение

Представляет соединение между PHP и сервером базы данных.

## Обзор класса

class PDO {
/* Константы */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* Методы */
public function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — Инициализация транзакции

### Описание

public function PDO::beginTransaction(): bool

Выключает режим автоматической фиксации транзакции. В то время как режим автоматической фиксации выключен, изменения, внесённые в базу данных через объект экземпляра PDO, не применяются, пока вы не завершите транзакцию, вызвав PDO::commit(). Вызов PDO::rollBack() откатит все изменения в базе данных и вернёт соединение к режиму автоматической фиксации.

Некоторые базы данных, включая MySQL, автоматически выполняют неявную фиксацию, когда выражения языка описания данных (DDL), такие как DROP TABLE или CREATE TABLE, находятся внутри транзакции. Неявная фиксация предотвратит вам откат любых изменений, сделанных в этой транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Выбрасывает PDOException, если транзакция уже стартовала, либо если драйвер не поддерживает транзакции.

> Замечание: Исключение выбрасывается, даже если для атрибута `PDO::ATTR_ERRMODE` не установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Откат транзакции

Следующий пример начинает транзакцию и выполняет два выражения, что изменяет базу данных до отката изменений. В MySQL, тем не менее, выражение DROP TABLE автоматически фиксирует транзакцию так, что ни одно из изменений транзакции не откатывается.

    <?php
    /* Начало транзакции, отключение автоматической фиксации */
    $dbh->beginTransaction();

    /* Изменение схемы базы данных и данных */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Распознаем ошибку и откатываем изменения */
    $dbh->rollBack();

    /* Соединение с базой данных снова в режиме автоматической фиксации */
    ?>

### Смотрите также

- PDO::commit() - Фиксирует транзакцию
- PDO::rollBack() - Откат транзакции
- Транзакции и автоматическая фиксация

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — Фиксирует транзакцию

### Описание

public function PDO::commit(): bool

Фиксирует транзакцию, возвращая соединение с базой данных в режим автоматической фиксации до тех пор, пока следующий вызов PDO::beginTransaction() не начнёт новую транзакцию.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Вызывает исключение PDOException, если нет активной транзакции.

> Замечание: Исключение выбрасывается, даже если для атрибута `PDO::ATTR_ERRMODE` не установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Фиксация обычной транзакции

    <?php
    /* Начало транзакции, отключение автоматической фиксации */
    $dbh->beginTransaction();

    /* Вставка множества записей по принципу "все или ничего" */
    $sql = 'INSERT INTO fruit
        (name, colour, calories)
        VALUES (?, ?, ?)';

    $sth = $dbh->prepare($sql);

    foreach ($fruits as $fruit) {
        $sth->execute(array(
            $fruit->name,
            $fruit->colour,
            $fruit->calories,
        ));
    }

    /* Фиксация изменений */
    $dbh->commit();

    /* Соединение с базой данных снова в режиме автоматической фиксации */
    ?>

Пример #2 Фиксация DDL-транзакции

    <?php
    /* Начало транзакции, отключение автоматической фиксации */
    $dbh->beginTransaction();

    /* Изменение схемы базы данных */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* Фиксация изменений */
    $dbh->commit();

    /* Соединение с базой данных снова в режиме автоматической фиксации */
    ?>

> Замечание: Не все базы данных позволяют транзакциям работать с DDL-выражениями: в некоторых генерируются ошибки, тогда как в других (включая MySQL) транзакция автоматически фиксируется после первого встретившегося DDL-выражения.

### Смотрите также

- PDO::beginTransaction() - Инициализация транзакции
- PDO::rollBack() - Откат транзакции
- Транзакции и автоматическая фиксация

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Подключается к базе данных и возвращает объект подкласса PDO для драйвера, который поддерживает заданную БД

### Описание

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static

Метод создаёт объект подкласса PDO для базы данных, с которой устанавливают соединение, если PDO-подкласс для такой БД определили, иначе возвращает универсальный экземпляр класса PDO.

### Список параметров

`dsn`

  Имя источника данных (англ. Data Source Name, DSN) с информацией, которая требуется для подключения к базе данных.

  Часто DSN-строка подключения состоит из названия PDO-драйвера, за которым следует двоеточие и синтаксис соединения, характерный для PDO-драйвера. Дополнительную информацию даёт раздел «Документация к PDO-драйверам, характерным для баз данных».

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

  Вызов драйвера

    Аргумент `dsn` с полной DSN-строкой подключения.

  Вызов URI-идентификатора

    Аргумент `dsn`, который состоит из префикса `uri:`, за которым идёт URI-идентификатор, который определяет расположение файла с DSN-строкой. Идентификатор URI указывает на локальный файл или удалённый URL-адрес.

    `uri:file:///path/to/dsnfile`

  Совмещение имён

    Аргумент `dsn` состоит из имени `name`, которое соответствует параметру `pdo.dsn.`name`` в файле php.ini, который определяет DSN-строку подключения.

    > Замечание:

    > Псевдоним требуется определять в файле php.ini, но не в файлах .htaccess или httpd.conf

`username`

  Имя пользователя для DSN-строки. Этот параметр необязателен для ряда PDO-драйверов.

`password`

  Пароль для строки DSN. Этот параметр необязателен для ряда PDO-драйверов.

`options`

  Массив параметров подключения, характерных для драйвера, в виде пар ключ=>значение.

### Возвращаемые значения

Метод возвращает объект PDO-подкласса для PDO-драйвера конкретной БД, если такой PDO-подкласс определили, или стандартный экземпляр класса PDO.

### Ошибки

Метод выбрасывает исключение PDOException, если попытка подключения к базе данных не удалась, независимо от текущей стратегии обработки ошибок, установленной в атрибуте `PDO::ATTR_ERRMODE`.

### Смотрите также

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - Создаёт объект PDO, который предоставляет соединение с базой данных

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — Создаёт объект PDO, который предоставляет соединение с базой данных

### Описание

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)

Метод создаёт экземпляр класса PDO, который предоставляет подключение к необходимой базе данных.

### Список параметров

`dsn`

  Имя источника данных (англ. Data Source Name, DSN) с информацией, которая требуется для подключения к базе данных.

  Часто DSN-строка подключения состоит из названия PDO-драйвера, за которым следует двоеточие и синтаксис соединения, характерный для PDO-драйвера. Дополнительную информацию даёт раздел «Документация к PDO-драйверам, характерным для баз данных».

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

  Вызов драйвера

    Аргумент `dsn` с полной DSN-строкой подключения.

  Вызов URI-идентификатора

    Аргумент `dsn`, который состоит из префикса `uri:`, за которым идёт URI-идентификатор, который определяет расположение файла с DSN-строкой. Идентификатор URI указывает на локальный файл или удалённый URL-адрес.

    `uri:file:///path/to/dsnfile`

  Совмещение имён

    Аргумент `dsn` состоит из имени `name`, которое соответствует параметру `pdo.dsn.`name`` в файле php.ini, который определяет DSN-строку подключения.

    > Замечание:

    > Псевдоним требуется определять в файле php.ini, но не в файлах .htaccess или httpd.conf

`username`

  Имя пользователя для DSN-строки. Этот параметр необязателен для ряда PDO-драйверов.

`password`

  Пароль для строки DSN. Этот параметр необязателен для ряда PDO-драйверов.

`options`

  Массив параметров подключения, характерных для драйвера, в виде пар ключ=>значение.

### Ошибки

Метод выбрасывает исключение PDOException, если попытка подключения к базе данных не удалась, независимо от текущей стратегии обработки ошибок, установленной в атрибуте `PDO::ATTR_ERRMODE`.

### Примеры

Пример #1 Пример создания экземпляра класса PDO через вызов драйвера

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Пример #2 Пример создания экземпляра класса PDO через вызов URI-идентификатора

В следующем примере предполагается, что файл /usr/local/dbconnect существует с правами доступа, которые разрешают PHP прочитать файл. Файл содержит PDO DSN для подключения к базе данных DB2 через драйвер PDO_ODBC:

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

PHP-скрипт создаёт подключение к базе данных путём простой передачи параметра `uri:`, который указывает на файл идентификатора URI:

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Пример #3 Пример создания экземпляра класса PDO через псевдоним

В следующем примере предполагается, что файл php.ini содержит следующую запись, которая разрешает подключиться к базе данных MySQL только через псевдоним `mydb`:

    [PDO]
         pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"

    <?php

    $dsn = 'mydb';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — Возвращает код SQLSTATE результата последней операции с базой данных

### Описание

public function PDO::errorCode(): ?string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает SQLSTATE - пятисимвольный идентификатор, определённый в стандарте ANSI SQL-92. Первые два символа SQLSTATE отвечают за класс ошибки, а следующие три определяют её подкласс. Класс ошибок 01 означает предупреждение, которому сопутствует возвращаемый код SQL_SUCCESS_WITH_INFO. Классы отличные от 01, за исключением 'IM', означают ошибки выполнения запросов к базе данных. Класс 'IM' свидетельствует об ошибках и предупреждениях, которые вызваны самой реализацией PDO (или, возможно, ODBC, если используется драйвер ODBC). Значение подкласса '000' в любом классе означает, что подкласс для этого SQLSTATE отсутствует.

PDO::errorCode() выдаёт код ошибки только для операций, совершаемых с базой данных напрямую из PDO. Если создать объект PDOStatement методами PDO::prepare() или PDO::query(), и вызвать ошибку его методами, PDO::errorCode() эту ошибку не отобразит. Вам нужно вызвать PDOStatement::errorCode(), чтобы получить код ошибки для операции, выполняемой на определённом объекте PDOStatement.

Возвращает `null`, если никаких операций над базой данных средствами PDO-объекта не производилось.

### Примеры

Пример #1 Получение кода SQLSTATE

    <?php
    /* Спровоцируем ошибку -- таблицы BONES не существует */
    $dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

Результат выполнения приведённого примера:

    PDO::errorCode(): 42S02

### Смотрите также

- PDO::errorInfo() - Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных
- PDOStatement::errorCode() - Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement
- PDOStatement::errorInfo() - Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных

### Описание

public function PDO::errorInfo(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

PDO::errorInfo() возвращает массив с информацией об ошибке, произошедшей в ходе выполнения последней операции с базой данных. Массив содержит как минимум следующие поля:

Элемент | Информация
--- | ---
0 | Код ошибки SQLSTATE (пятисимвольный идентификатор, определённый в стандарте ANSI SQL).
1 | Код ошибки, заданный драйвером.
2 | Сообщение об ошибке, заданное драйвером

> Замечание:

> Если не задан SQLSTATE код или драйвер не сообщил об ошибке, то элементы следующие за нулевым будут иметь значение `null`.

PDO::errorInfo() выдаёт информацию об ошибке только для операций, совершаемых с базой данных напрямую из PDO. Если создать объект PDOStatement методами PDO::prepare() или PDO::query(), и вызвать ошибку его методами, PDO::errorInfo() эту ошибку не отобразит. Вам нужно вызвать PDOStatement::errorInfo(), чтобы получить информации об ошибках для операции, выполняемой на определённом объекте PDOStatement.

### Примеры

Пример #1 Вывод полей массива errorInfo() для PDO_ODBC подключения к базе данных DB2

    <?php
    /* Спровоцируем синтаксическую ошибку SQL */
    $stmt = $dbh->prepare('bogus sql');
    if (!$stmt) {
        echo "\nPDO::errorInfo():\n";
        print_r($dbh->errorInfo());
    }
    ?>

Результат выполнения приведённого примера:

    PDO::errorInfo():
    Array
    (
        [0] => HY000
        [1] => 1
        [2] => near "bogus": syntax error
    )

### Смотрите также

- PDO::errorCode() - Возвращает код SQLSTATE результата последней операции с базой данных
- PDOStatement::errorCode() - Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement
- PDOStatement::errorInfo() - Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — Выполняет SQL-запрос и возвращает количество затронутых строк

### Описание

public function PDO::exec(string `$statement`): int|false

Метод PDO::exec() запускает SQL-запрос на выполнение и возвращает количество строк, задействованных в ходе его выполнения.

Метод PDO::exec() не возвращает результат выборки оператором SELECT. Если нужно выбрать данные этим оператором единожды в ходе выполнения программы, используют метод PDO::query(). Если требуется запускать один и тот же запрос на выборку множество раз, лучше создать подготовленный запрос PDOStatement методом PDO::prepare(), а затем запускать его методом PDOStatement::execute() столько раз, сколько потребуется.

### Список параметров

`statement`

  SQL-выражение, которое необходимо подготовить и запустить.

  Данные внутри запроса должны быть правильно экранированы.

### Возвращаемые значения

Метод PDO::exec() возвращает количество строк, которые были модифицированы или удалены в ходе его выполнения. Если таких строк нет, метод PDO::exec() вернёт значение `0`.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

В этом примере разработчик допустил ошибку, полагаясь на возвращаемый методом PDO::exec() результат. В результате, если запрос отработал без ошибок, но не модифицировал ни одной строки, работа скрипта будет завершена функцией die():

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // неправильно
    ?>

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Выполнение запроса DELETE

Получение количества удалённых записей запросом DELETE без условий WHERE.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /* Удаляем все записи из таблицы FRUIT */
    $count = $dbh->exec("DELETE FROM fruit");

    /* Получим количество удалённых записей */
    print "Удалено $count строк.\n";
    ?>

Результат выполнения приведённого примера:

    Удалено 1 строк.

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей
- PDOStatement::execute() - Выполняет подготовленный запрос

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — Получает атрибут соединения с базой данных

### Описание

public function PDO::getAttribute(int `$attribute`): mixed

Эта функция возвращает значение атрибута соединения с базой данных. Чтобы получить атрибуты объекта PDOStatement, обращаются к методу PDOStatement::getAttribute().

Обратите внимание, что не все комбинации «база данных/драйвер» поддерживают все атрибуты соединения с базой данных.

### Список параметров

`attribute`

  Одна из констант `PDO::ATTR_*`. Список общих атрибутов, применяемых к подключениям к базе данных:

  - `PDO::ATTR_AUTOCOMMIT`
  - `PDO::ATTR_CASE`
  - `PDO::ATTR_CLIENT_VERSION`
  - `PDO::ATTR_CONNECTION_STATUS`
  - `PDO::ATTR_DRIVER_NAME`
  - `PDO::ATTR_ERRMODE`
  - `PDO::ATTR_ORACLE_NULLS`
  - `PDO::ATTR_PERSISTENT`
  - `PDO::ATTR_PREFETCH`
  - `PDO::ATTR_SERVER_INFO`
  - `PDO::ATTR_SERVER_VERSION`
  - `PDO::ATTR_TIMEOUT`
  Некоторые драйверы могут использовать дополнительные, характерные для этого драйвера, атрибуты. Обратите внимание, что атрибуты драйвера не должны быть использованы с другими драйверами.

### Возвращаемые значения

Возвращает значение атрибута запрошенного PDO (при успешном вызове). Неудачный вызов возвращает `null`.

### Ошибки

Метод PDO::getAttribute() может выбросить исключение PDOException, когда базовый драйвер не поддерживает запрошенный в параметре `attribute` атрибут.

### Примеры

Пример #1 Получение атрибутов соединения с базой данных

    <?php
    $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
    $attributes = array(
        "AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
        "ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
        "TIMEOUT"
    );

    foreach ($attributes as $val) {
        echo "PDO::ATTR_$val: ";
        echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
    }
    ?>

### Смотрите также

- PDO::setAttribute() - Устанавливает атрибут
- PDOStatement::getAttribute() - Получение значения атрибута запроса PDOStatement
- PDOStatement::setAttribute() - Устанавливает атрибут объекту PDOStatement

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — Возвращает массив доступных драйверов PDO

### Описание

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

Эта функция возвращает все имеющиеся в настоящее время драйверы PDO, которые можно использовать в `DSN`-параметре PDO::__construct().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция PDO::getAvailableDrivers() возвращает массив имён драйверов PDO. Если нет драйверов, то возвращается пустой массив.

### Примеры

Пример #1 Пример выполнения PDO::getAvailableDrivers()

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — Проверяет, начата ли транзакция

### Описание

public function PDO::inTransaction(): bool

Проверяет, активна ли в данный момент транзакция в драйвере. Этот метод работает только для драйверов баз данных, которые поддерживают транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если транзакция в данный момент активна и `false`, если нет.

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — Возвращает ID последней вставленной строки или значение последовательности

### Описание

public function PDO::lastInsertId(?string `$name` = `null`): string|false

Возвращает ID последней вставленной строки или последнее значение от объекта последовательности, в зависимости от базового драйвера. Например, драйвер PDO_PGSQL разрешает задать имя объекта последовательности для параметра `name`.

> Замечание:

> В зависимости от драйвера PDO этот метод может вообще не выдать осмысленного результата, так как база данных может не поддерживать автоматического инкремента полей или последовательностей.

### Список параметров

`name`

  Имя объекта последовательности, который должен выдать ID.

### Возвращаемые значения

Если объект последовательности для параметра `name` не задан, метод PDO::lastInsertId() вернёт строку, представляющую ID последней добавленной в базу записи.

Если же объект последовательности для параметра `name` задан, метод PDO::lastInsertId() вернёт строку, представляющую последнее значение, полученное от этого объекта.

Если PDO-драйвер не поддерживает эту возможность, метод PDO::lastInsertId() запишет значение `IM001` в SQLSTATE.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект

### Описание

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

Подготавливает SQL-запрос к базе данных к запуску посредством метода PDOStatement::execute(). Запрос может содержать именованные (:name) или неименованные (?) псевдопеременные, которые будут заменены реальными значениями во время запуска запроса на выполнение. Использовать одновременно и именованные, и неименованные псевдопеременные в одном запросе нельзя, необходимо выбрать что-то одно. Используйте псевдопеременные, чтобы привязать к запросу пользовательский ввод, не включайте данные, введённые пользователем, напрямую в запрос.

Вы должны подбирать уникальные имена псевдопеременных для каждого значения, которое необходимо передавать в запрос при вызове PDOStatement::execute(). Нельзя использовать одну псевдопеременную в запросе более одного раза, кроме варианта, когда включён режим эмуляции.

> Замечание:

> Псевдопеременные должны представлять только единичный объем данных. Ни часть значения, ни служебное слово, ни имя поля, ни какую-либо произвольную часть запроса. К примеру, вы не можете связать псевдопеременную с несколькими значениями для вставки в конструкцию IN().

Вызов PDO::prepare() и PDOStatement::execute() для запросов, которые будут запускаться многократно с различными параметрами, повышает производительность приложения, позволяя драйверу кешировать на клиенте и/или сервере план выполнения запроса и метаданные, а также помогает избежать SQL-инъекций, так как нет необходимости экранировать передаваемые параметры.

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

> Замечание: Синтаксический анализатор, используемый для эмулируемых подготовленных операторов и для перезаписи именованных параметров или параметров стиля вопросительного знака, поддерживает нестандартные обратные слеши для одинарных и двойных кавычек. Это означает, что завершающие кавычки, непосредственно предшествующие обратной косой черте, не распознаются как таковые, что может привести к неправильному обнаружению параметров, что приведёт к сбою подготовленного оператора при его выполнении. Обходной путь — не использовать эмулированную подготовку к таким SQL-запросам и избегать перезаписи параметров, используя стиль параметров, который изначально поддерживается драйвером.

Начиная с PHP 7.4.0, можно избежать экранирования вопросительных знаков, удвоив их. Это означает, что строка `??` будет преобразована в `?` при отправке запроса в базу данных.

### Список параметров

`query`

  Это должен быть корректный SQL-запрос с точки зрения целевой СУБД.

`options`

  Этот массив содержит одну или более пар ключ=>значение для установки значений атрибутов объекта PDOStatement, который будет возвращён из этого метода. В основном, вы будете использовать этот массив для присвоения значения `PDO::ATTR_CURSOR` атрибуту `PDO::CURSOR_SCROLL`, чтобы получить прокручиваемый курсор. У некоторых драйверов могут быть свои специфические настройки, которые можно задать во время подготовки запроса.

### Возвращаемые значения

Если СУБД успешно подготовила запрос, PDO::prepare() возвращает объект PDOStatement. Если подготовить запрос не удалось, PDO::prepare() возвращает `false` или выбрасывает исключение PDOException (зависит от текущего режима обработки ошибок).

> Замечание:

> Эмулируемые подготовленные запросы не создаются на сервере баз данных, поэтому PDO::prepare() не может проверить правильность построенного запроса.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Подготовка SQL-запроса с именованными параметрами

    <?php
    /* Выполнение запроса с передачей ему массива параметров */
    $sql = 'SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour';
    $sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
    $sth->execute(['calories' => 150, 'colour' => 'red']);
    $red = $sth->fetchAll();
    /* Ключи массива также могут начинаться с двоеточия ":" (необязательно) */
    $sth->execute([':calories' => 175, ':colour' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Пример #2 Подготовка SQL-запроса с неименованными параметрами (символ '?')

    <?php
    /* Выполнение запроса с передачей ему массива параметров */
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->execute([150, 'red']);
    $red = $sth->fetchAll();
    $sth->execute([175, 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Пример #3 Подготовка SQL-запроса с экранированным вопросительным знаком

    <?php
    /* замечание: работает только с базами данных PostgreSQL */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### Смотрите также

- PDO::exec() - Выполняет SQL-запрос и возвращает количество затронутых строк
- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей
- PDOStatement::execute() - Выполняет подготовленный запрос

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — Подготавливает и выполняет выражение SQL без заполнителей

### Описание

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false

PDO::query() подготавливает и выполняет выражение SQL за один вызов функции, возвращая выражение как объект PDOStatement.

Если запрос будет запускаться многократно, для улучшения производительности приложения имеет смысл этот запрос один раз подготовить PDOStatement методом PDO::prepare(), а затем запускать на выполнение методом PDOStatement::execute() столько раз, сколько потребуется.

Если после выполнения предыдущего запроса вы не выбрали все данные из результирующего набора, следующий вызов PDO::query() может потерпеть неудачу. В таких случаях следует вызывать метод PDOStatement::closeCursor(), который освободит ресурсы базы данных, занятые предыдущим объектом PDOStatement. После этого можно безопасно вызывать PDO::query().

> Замечание:

> Если `query` содержит заполнители, выражение должно быть подготовлено и выполнено отдельно с использованием методов PDO::prepare() и PDOStatement::execute().

### Список параметров

`query`

  SQL-запрос для подготовки и выполнения.

  Если SQL содержит заполнители, вместо этого метода следует использовать PDO::prepare() и PDOStatement::execute(). В качестве альтернативы, SQL можно подготовить вручную перед вызовом PDO::query(), при этом данные должны быть правильно отформатированы с использованием PDO::quote(), если драйвер поддерживает это.

`fetchMode`

  Режим выборки по умолчанию для возвращённого PDOStatement. Должен быть одной из констант `PDO::FETCH_*`.

  Если этот аргумент передаётся функции, остальные аргументы будут обрабатываться так, как если бы PDOStatement::setFetchMode() был вызван для полученного объекта выражения. Последующие аргументы зависят от выбранного режима выборки.

### Возвращаемые значения

Возвращает объект PDOStatement или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 SQL без заполнителей может быть выполнен с использованием PDO::query()

    <?php
    $sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
    foreach ($conn->query($sql) as $row) {
        print $row['name'] . "\t";
        print $row['color'] . "\t";
        print $row['calories'] . "\n";
    }
    ?>

Результат выполнения приведённого примера:

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### Смотрите также

- PDO::exec() - Выполняет SQL-запрос и возвращает количество затронутых строк
- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — Форматирует строку в SQL-литерал

### Описание

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

С параметрами по умолчанию метод PDO::quote() оборачивает входные строковые данные кавычками и попутно экранирует спецсимволы в стиле конкретного PDO-драйвера.

Разработчики языка настоятельно рекомендуют подготавливать запросы методом PDO::prepare() и привязывать параметры, а не интерполировать пользовательский ввод в SQL-инструкцию методом PDO::quote(). Подготовленные запросы с привязкой параметров проще в построении, универсальнее при переносе между БД, надёжнее в части устойчивости к SQL-инъекциям и часто выполняются быстрее запросов с интерполяцией за счёт кеширования скомпилированной формы запроса клиентом и сервером.

Метод поддерживается не каждым PDO-драйвером, например, в драйвере PDO_ODBC метод не реализовали. Лучше предпочесть подготовленные запросы вместо форматирования строк этим методом.

Предостережение

# Безопасность: набор символов по умолчанию

Метод PDO::quote() работает корректно только при установке правильной кодировки символов — либо на уровне сервера БД, либо в настройках соединения, в зависимости от конкретного PDO-драйвера. Дополнительную информацию содержит документация к конкретному драйверу.

### Список параметров

`string`

  Строка, которую требуется отформатировать для безопасного встраивания в текст SQL-запроса.

`type`

  Подсказка типа данных. В драйверах, которые учитывают параметр, подсказка определяет стиль обрамления кавычками и синтаксис экранирования. Флаг `PDO::PARAM_LOB`, например, укажет драйверу экранировать значение как двоичные данные.

### Возвращаемые значения

Метод возвращает отформатированную строку, которую, теоретически, безопасно встраивать в тело SQL-запроса. Метод возвращает значение `false`, если драйвер не поддерживает форматирование таким способом.

### Примеры

Пример #1 Форматирование стандартной строки

    <?php

    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Обыкновенная строка */
    $string = 'Nice';
    print "Исходная строка: $string\n";
    print "Отформатированная строка: " . $conn->quote($string) . "\n";

Результат выполнения приведённого примера:

    Исходная строка: Nice
    Отформатированная строка: 'Nice'

Пример #2 Форматирование строки с одинарной кавычкой

    <?php

    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Опасная строка */
    $string = 'Naughty \' string';
    print "Исходная строка: $string\n";
    print "Отформатированная строка: " . $conn->quote($string) . "\n";

Результат выполнения приведённого примера:

    Исходная строка: Naughty ' string
    Отформатированная строка: 'Naughty '' string'

Пример #3 Форматирование строки со смешанными кавычками

    <?php

    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Сложная строка */
    $string = "Co'mpl''ex \"st'\"ring";
    print "Исходная строка: $string\n";
    print "Отформатированная строка: " . $conn->quote($string) . "\n";

Результат выполнения приведённого примера:

    Исходная строка: Co'mpl''ex "st'"ring
    Отформатированная строка: 'Co''mpl''''ex "st''"ring'

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — Откат транзакции

### Описание

public function PDO::rollBack(): bool

Откатывает изменения в базе данных сделанные в рамках текущей транзакции, которая была создана методом PDO::beginTransaction().

Если в СУБД включён режим автофиксации изменений, эта функция восстановит этот режим после отката.

Некоторые СУБД, включая MySQL, автоматически неявно фиксируют изменения, когда встречаются выражения языка определения базы данных (DDL), выполняемые в рамках транзакции. Эта неявная фиксация делает невозможным откат других изменений, сделанных в рамках этой транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если активной транзакции нет, будет выброшено исключение PDOException.

> Замечание: Исключение выбрасывается, даже если для атрибута `PDO::ATTR_ERRMODE` не установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Откат транзакции

В следующем примере создаётся транзакция и выполняются два запроса, которые модифицируют данные в базе, а затем база возвращается к исходному состоянию. В MySQL, тем не менее, выражение DROP TABLE автоматически фиксирует изменения, поэтому их откат не произойдёт.

    <?php
    /* Начинаем транзакцию, отключение автоматической фиксации */
    $dbh->beginTransaction();

    /* Изменяем схему базы данных и данные в таблицах */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Осознаем свою ошибку и откатываем транзакцию */
    $dbh->rollBack();

    /* База данных возвращается в режим автофиксации */
    ?>

### Смотрите также

- PDO::beginTransaction() - Инициализация транзакции
- PDO::commit() - Фиксирует транзакцию
- Транзакции и автофиксация изменений

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — Устанавливает атрибут

### Описание

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

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

`PDO::ATTR_CASE`

  Принудительное приведение названия столбцов к конкретному регистру. Принимает значение из следующего списка:

  `PDO::CASE_LOWER`
    Принудительное приведение названий столбцов к нижнему регистру.
  `PDO::CASE_NATURAL`
    Оставить названия столбцов в том виде, в котором их возвращает драйвер базы данных.
  `PDO::CASE_UPPER`
    Принудительное приведение названий столбцов к верхнему регистру.
`PDO::ATTR_ERRMODE`

  Режим сообщения об ошибках модуля PDO. Принимает значение из следующего списка:

  `PDO::ERRMODE_SILENT`
    Устанавливает только коды ошибок.
  `PDO::ERRMODE_WARNING`
    Вызывает диагностику ошибок уровня `E_WARNING`.
  `PDO::ERRMODE_EXCEPTION`
    Выбрасывает PDOException.
`PDO::ATTR_ORACLE_NULLS`

  > Замечание: Атрибут доступен для всех драйверов, а не только для Oracle.

  Определяет, требуется ли и как преобразовывать значения `null` и пустые строки. Принимает значение из следующего списка:

  `PDO::NULL_NATURAL`
    Никакого преобразования не происходит.
  `PDO::NULL_EMPTY_STRING`
    Пустые строки преобразуются в `null`.
  `PDO::NULL_TO_STRING`
    Значение `null` преобразуется в пустую строку.
`PDO::ATTR_STRINGIFY_FETCHES`

  Управляет преобразованием извлечённых значений (кроме `null`) в строки. Атрибут принимает логическое значение (bool): `true` для включения и `false` для отключения. Значение по умолчанию равняется `true`. Значения `null` остаются неизменными, если только для атрибута `PDO::ATTR_ORACLE_NULLS` не установили значение `PDO::NULL_TO_STRING`.

`PDO::ATTR_STATEMENT_CLASS`

  Установка пользовательского класса оператора, производного от PDOStatement. Требуется `array(string classname, array(mixed constructor_args))`.

  Предостережение

  Не может использоваться с постоянными экземплярами PDO.

`PDO::ATTR_TIMEOUT`

  Указывает продолжительность времени ожидания в секундах. Принимает значение в виде целого числа (int).

  > Замечание:

  > Не каждый драйвер поддерживает этот параметр и его значение иногда отличается от драйвера к драйверу. Например, SQLite будет ждать до этого значения времени, прежде чем отказаться от получения блокировки на запись, но другие драйверы могут интерпретировать это как интервал ожидания соединения или чтения.

`PDO::ATTR_AUTOCOMMIT`

  > Замечание: Доступно только для драйверов OCI, Firebird и MySQL.

  Требуется ли автоматически фиксировать каждый отдельный оператор. Атрибут принимает логическое значение (bool): `true` для включения и `false` для отключения. Значение по умолчанию равняется `true`.

`PDO::ATTR_EMULATE_PREPARES`

  > Замечание: Атрибут доступен только для драйверов СУБД OCI, Firebird и MySQL.

  Включает или отключает эмуляцию подготовленных запросов. Отдельные драйверы не поддерживают подготовленные запросы из коробки или поддерживают ограниченно. Со значением `true` объект PDO будет эмулировать подготовленные запросы, иначе PDO будет пытаться использовать встроенные подготовленные запросы. PDO будет возвращаться к эмуляции подготовленного запроса, если драйвер не сумеет подготовить текущий запрос.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > Замечание: Доступно только для драйвера СУБД MySQL.

  Определяет, использовать ли буферизованные запросы. Атрибут принимает логическое значение (bool): `true` для включения и `false` для отключения. Значение по умолчанию равняется `true`.

`PDO::ATTR_DEFAULT_FETCH_MODE`

  Устанавливает режим выборки по умолчанию. Описание режимов даёт документация к методу PDOStatement::fetch().

### Список параметров

`attribute`

  Атрибут для изменения.

`value`

  Значение для установки параметра `attribute`, иногда требует конкретный тип в зависимости от атрибута.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- PDO::getAttribute() - Получает атрибут соединения с базой данных
- PDOStatement::getAttribute() - Получение значения атрибута запроса PDOStatement
- PDOStatement::setAttribute() - Устанавливает атрибут объекту PDOStatement

## Содержание

- PDO::beginTransaction — Инициализация транзакции
- PDO::commit — Фиксирует транзакцию
- PDO::connect — Подключается к базе данных и возвращает объект подкласса PDO для драйвера, который поддерживает заданную БД
- PDO::__construct — Создаёт объект PDO, который предоставляет соединение с базой данных
- PDO::errorCode — Возвращает код SQLSTATE результата последней операции с базой данных
- PDO::errorInfo — Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных
- PDO::exec — Выполняет SQL-запрос и возвращает количество затронутых строк
- PDO::getAttribute — Получает атрибут соединения с базой данных
- PDO::getAvailableDrivers — Возвращает массив доступных драйверов PDO
- PDO::inTransaction — Проверяет, начата ли транзакция
- PDO::lastInsertId — Возвращает ID последней вставленной строки или значение последовательности
- PDO::prepare — Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDO::query — Подготавливает и выполняет выражение SQL без заполнителей
- PDO::quote — Форматирует строку в SQL-литерал
- PDO::rollBack — Откат транзакции
- PDO::setAttribute — Устанавливает атрибут

# Класс PDOStatement

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Введение

Класс представляет подготовленный запрос к базе данных, а после выполнения запроса набор результатов, который соответствует запросу.

## Обзор класса

class PDOStatement implements IteratorAggregate {
/* Свойства */
public string $queryString;
/* Методы */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## Свойства

queryString

  Используемая строка запроса.

## Список изменений

Версия | Описание
--- | ---
8.0.0 | Класс PDOStatement вместо интерфейса Traversable теперь реализует интерфейс IteratorAggregate.

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — Связывает столбец с переменной PHP

### Описание

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() привязывает переменную к заданному столбцу в результирующем наборе запроса. Каждый вызов PDOStatement::fetch() или PDOStatement::fetchAll() будет обновлять все переменные, задавать им значения столбцов, с которыми они связаны.

> Замечание:

> В связи с тем, что информация о столбцах результирующего набора запроса не всегда доступна объекту PDO, пока запрос не будет запущен, приложениям следует вызывать этот метод после вызова PDOStatement::execute().

> Однако, при работе с драйвером PgSQL, когда привязывается столбец с LOB-данными, приложению необходимо вызывать этот метод до вызова PDOStatement::execute(). В противном случае идентификатор большого объекта OID будет иметь тип integer.

### Список параметров

`column`

  Номер столбца (начиная с 1) или его имя в результирующем наборе запроса. Используя имя столбца, имейте в виду, что имя должно быть в том же регистре, в каком оно возвращено драйвером.

`var`

  Имя переменной PHP, к которой требуется привязать столбец.

`type`

  Тип данных параметра, заданный одной из констант `PDO::PARAM_*`.

`maxLength`

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

`driverOptions`

  Дополнительные параметры для драйвера.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Связывание результирующего набора с переменными PHP

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

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* Bind by column number */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* Bind by column name */
    $stmt->bindColumn('calories', $cals);

    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }

Результат выполнения приведённого примера:

    apple   red     150
    banana  yellow  175
    kiwi    green   75
    orange  orange  150
    mango   red     200
    strawberry      red     25

### Смотрите также

- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора
- PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов
- PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — Привязывает параметр запроса к переменной

### Описание

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

Связывает переменную PHP с именованным или неименованным параметром подготавливаемого SQL-запроса. В отличие от PDOStatement::bindValue(), переменная привязывается по ссылке и её значение будет вычисляться во время вызова PDOStatement::execute().

В большинстве случаев в подготавливаемых запросах используются только входные параметры, то есть при построении запроса доступ к ним осуществляется только в режиме чтения (возможно приведение в соответствии с `type`). Тем не менее, некоторые драйверы позволяют запускать хранимые процедуры, которые, в свою очередь, могут возвращать данные посредством выходных параметров. Зачастую, такие параметры используются одновременно как входные и как выходные.

### Список параметров

`param`

  Идентификатор параметра. Для подготавливаемых запросов с именованными параметрами это будет имя в виде :name. Если используются неименованные параметры (знаки вопроса ?) это будет позиция псевдопеременной в запросе (начиная с 1).

`var`

  Имя переменной PHP, которую требуется привязать к параметру SQL-запроса.

`type`

  Явно заданный тип данных параметра. Тип задаётся одной из констант `PDO::PARAM_*`. Если параметр используется, в том числе для вывода информации из хранимой процедуры, к значению аргумента `type` необходимо добавить `PDO::PARAM_INPUT_OUTPUT`, используя оператор побитовое ИЛИ.

`maxLength`

  Размер типа данных. Чтобы указать, что параметр используется для вывода данных из хранимой процедуры, необходимо явно задать его размер. Имеет значение, только если у параметра `type` установлено значение `PDO::PARAM_INPUT_OUTPUT`.

`driverOptions`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Выполнение подготовленного запроса с именованными псевдопеременными

    <?php
    /* Выполнение запроса с привязкой PHP-переменных */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Имена также могут начинаться с двоеточия ":" (необязательно) */
    $sth->bindParam(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Пример #2 Выполнение подготовленного запроса с неименованными псевдопеременными (?)

    <?php
    /* Выполнение запроса с привязкой PHP-переменных */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Пример #3 Вызов хранимой процедуры с INOUT-параметром

    <?php
    /* Вызов хранимой процедуры с INOUT-параметром */
    $colour = 'red';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "После приготовления фруктового пюра, цвет - $colour";
    ?>

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::bindValue() - Связывает параметр с заданным значением

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — Связывает параметр с заданным значением

### Описание

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

Задаёт значение именованной или неименованной псевдопеременной в подготовленном SQL-запросе.

### Список параметров

`param`

  Идентификатор параметра запроса. Для подготавливаемых запросов с именованными параметрами это будет имя в виде :name. Если используются неименованные параметры (знаки вопроса ?) это будет позиция псевдопеременной в запросе (начиная с 1).

`value`

  Значение, которое требуется привязать к параметру.

`type`

  Явно заданный тип данных параметра. Тип задаётся одной из констант `PDO::PARAM_*`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Выполнение подготовленного запроса с именованными псевдопеременными

    <?php
    /* Выполнение запроса с привязкой PHP-переменных */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');

    /* Устанавливает значение параметра, используя его имя */
    $sth->bindValue('calories', $calories, PDO::PARAM_INT);
    /* По желанию, в именах параметров можно также ставить двоеточие ":" */
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Пример #2 Выполнение подготовленного запроса с неименованными псевдопеременными (?)

    <?php
    /* Выполнение запроса с привязкой PHP-переменных */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindValue(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::bindParam() - Привязывает параметр запроса к переменной

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — Закрывает курсор, переводя запрос в состояние готовности к повторному запуску

### Описание

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() освобождает соединение с сервером, давая возможность запускать другие SQL-запросы. Метод оставляет запрос в состоянии готовности к повторному запуску.

Этот метод полезен при использовании драйверов баз данных, которые не позволяют запустить PDOStatement, пока предыдущий объект PDOStatement не выберет все данные из результирующего набора. Если это ограничение распространяется на ваш драйвер, будет вызвана ошибка нарушения последовательности запросов (out-of-sequence error).

PDOStatement::closeCursor() может быть реализован как дополнительный метод конкретного драйвера (позволяющий добиться максимальной эффективности работы), либо как внутренний метод PDO, если такой функции в драйвере нет. Реализация внутреннего метода PDO семантически схожа с приведённой ниже:

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Пример использования PDOStatement::closeCursor()

В приведённом примере, объект PDOStatement $stmt возвращает несколько строк, однако приложение считывает только первую из них, оставляя объект PDOStatement в состоянии, когда есть ещё невыбранные строки. Чтобы быть уверенным в том, что приложение будет работать со всеми драйверами баз данных, автор добавил вызов метода PDOStatement::closeCursor() объекта $stmt перед тем как запустить другой запрос PDOStatement $otherStmt.

    <?php
    /* Создание объекта PDOStatement */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* Создание другого объекта PDOStatement */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* Выполнение первого запроса */
    $stmt->execute();

    /* Выборка только первой строки результирующего набора первого запроса */
    $stmt->fetch();

    /* Следующий вызов closeCursor() может быть обязательным для некоторых драйверов */
    $stmt->closeCursor();

    /* теперь можно запускать второй запрос */
    $otherStmt->execute();
    ?>

### Смотрите также

- PDOStatement::execute() - Выполняет подготовленный запрос

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — Возвращает количество столбцов в результирующем наборе

### Описание

public function PDOStatement::columnCount(): int

Используйте PDOStatement::columnCount(), чтобы узнать количество столбцов в результирующем наборе, который представляет объект PDOStatement.

Если объект PDOStatement был возвращён из метода PDO::query(), число столбцов можно узнать сразу же.

Если объект PDOStatement был возвращён из метода PDO::prepare(), точное количество столбцов можно будет узнать только после запуска метода PDOStatement::execute().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество столбцов в результирующем наборе запроса PDOStatement, даже если он пуст. Если результирующего набора нет, PDOStatement::columnCount() возвращает `0`.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Подсчёт столбцов

В этом примере показано, как PDOStatement::columnCount() работает в случае наличия и отсутствия результирующего набора.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");

    /* Подсчёт количества столбцов в (несуществующем) результирующем наборе */
    $colcount = $sth->columnCount();
    print "Перед вызовом execute(), в результирующем наборе $colcount столбцов (должно быть 0)\n";

    $sth->execute();

    /* Подсчёт количества столбцов в результирующем наборе */
    $colcount = $sth->columnCount();
    print "После вызова execute(), в результирующем наборе $colcount столбцов (должно быть 2)\n";

    ?>

Результат выполнения приведённого примера:

    Перед вызовом execute(), в результирующем наборе 0 столбцов (должно быть 0)
    После вызова execute(), в результирующем наборе 2 столбцов (должно быть 2)

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::rowCount() - Возвращает количество строк, которое затронул последний SQL-запрос

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — Вывод информации о подготовленной SQL-команде в целях отладки

### Описание

public function PDOStatement::debugDumpParams(): ?bool

Выводит информацию о подготовленном запросе в выходной поток. Будет выводиться текст используемого `SQL` запроса, количество задействованных параметров (`Params`), список параметров с их именами ключей или индексами, их именами, индексами в запросе (если поддерживается в драйвере PDO, иначе -1), типом (`param_type`) в виде целого числа и логическое значение `is_param`.

Это отладочная функция, которая направляет данные на стандартный вывод.

Подсказка

Как и с остальными функциями или конструкциями языка, которые выводят результат в браузер, для захвата и сохранения вывода конструкции, например, в значении с типом string пользуются функциями управления выводом.

Эта функция выведет информацию о параметрах запроса, существующих на момент вызова. Дополнительные параметры не хранятся в запросе, поэтому отображены не будут.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `null` или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | PDOStatement::debugDumpParams() теперь возвращает SQL, отправленный в базу данных, в том числе полный необработанный запрос (включая заменённые параметры с их связанными значениями). Обратите внимание, что это будет работать только при включённой эмуляции подготавливаемых запросов.

### Примеры

Пример #1 Пример использования PDOStatement::debugDumpParams() с именованными параметрами

    <?php
    /* Выполнение запроса с привязкой PHP переменных */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam(':calories', $calories, PDO::PARAM_INT);
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

Результат выполнения приведённого примера:

    SQL: [96] SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour
    Params:  2
    Key: Name: [9] :calories
    paramno=-1
    name=[9] ":calories"
    is_param=1
    param_type=1
    Key: Name: [7] :colour
    paramno=-1
    name=[7] ":colour"
    is_param=1
    param_type=2

Пример #2 Пример использования PDOStatement::debugDumpParams() с неименованными (?) параметрами

    <?php

    /* Выполнение запроса с привязкой PHP переменных */
    $calories = 150;
    $colour = 'red';
    $name = 'apple';

    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

Результат выполнения приведённого примера:

    SQL: [82] SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?
    Params:  2
    Key: Position #0:
    paramno=0
    name=[0] ""
    is_param=1
    param_type=1
    Key: Position #1:
    paramno=1
    name=[0] ""
    is_param=1
    param_type=2

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::bindParam() - Привязывает параметр запроса к переменной
- PDOStatement::bindValue() - Связывает параметр с заданным значением

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement

### Описание

public function PDOStatement::errorCode(): ?string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод идентичен PDO::errorCode() за исключением того, что PDOStatement::errorCode() возвращает коды ошибок, произошедших в результате работы объекта PDOStatement.

### Примеры

Пример #1 Получение кода SQLSTATE

    <?php
    /* Спровоцируем ошибку -- таблицы BONES не существует */
    $err = $dbh->prepare('SELECT skull FROM bones');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

Результат выполнения приведённого примера:

    PDOStatement::errorCode(): 42S02

### Смотрите также

- PDO::errorCode() - Возвращает код SQLSTATE результата последней операции с базой данных
- PDO::errorInfo() - Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных
- PDOStatement::errorInfo() - Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement

### Описание

public function PDOStatement::errorInfo(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

PDOStatement::errorInfo() возвращает массив с информацией об ошибке, соответствующей последней операции объекта PDOStatement. Массив состоит как минимум из следующих полей:

Элемент | Информация
--- | ---
0 | Код ошибки SQLSTATE (пятисимвольный код состоящий из букв и цифр, определённый в стандарте ANSI SQL).
1 | Код ошибки, возвращаемый драйвером.
2 | Сообщение об ошибке, возвращаемое драйвером.

### Примеры

Пример #1 Вывод полей errorInfo() при PDO_ODBC подключении к DB2

    <?php
    /* Спровоцируем ошибку -- таблицы BONES не существует */
    $sth = $dbh->prepare('SELECT skull FROM bones');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

Результат выполнения приведённого примера:

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Смотрите также

- PDO::errorCode() - Возвращает код SQLSTATE результата последней операции с базой данных
- PDO::errorInfo() - Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных
- PDOStatement::errorCode() - Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — Выполняет подготовленный запрос

### Описание

public function PDOStatement::execute(?array `$params` = `null`): bool

Метод запускает подготовленный запрос. Если подготовленный запрос включает маркеры параметров, или заполнители, требуется:

- Вызвать метод PDOStatement::bindParam(), чтобы связать маркеры с переменными, или метод PDOStatement::bindValue(), чтобы связать маркеры со значениями. Переменные, которые связали с маркерами, передают свои значения как входные данные метода и получают значения вывода, если метод заполняет переменные аргументов значениями вывода. При возврате значений вывода метод присваивает переменным, которые передали по ссылке, значения параметров, с которым связали маркеры.

- или передать массив значений параметров, которые метод только примет как входные значения и не будет заполнять значениями вывода.

### Список параметров

`params`

  Массив значений, в котором количество элементов совпадает с количеством связанных параметров в SQL-запросе, который выполняет метод. Метод обрабатывает каждое значение массива как значение с типом `PDO::PARAM_STR`.

  Нельзя привязать несколько значений к одному параметру; например, нельзя привязать два значения к именованному параметру в условии IN().

  Невозможно привязать больше значений, чем указали в запросе; метод не выполнит запрос и вызовет ошибку, если массив `params` содержит больше ключей, чем указали при подготовке SQL-запроса методом PDO::prepare().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Пример выполнения подготовленного запроса с привязкой переменных и значений

    <?php

    /* Выполнение подготовленного запроса с привязкой переменных и значений */
    $calories = 150;
    $colour = 'gre';

    $sth = $dbh->prepare(
        'SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour LIKE :colour'
    );

    $sth->bindParam('calories', $calories, PDO::PARAM_INT);

    /* Именам разрешают начинаться с двоеточия ":" */
    $sth->bindValue(':colour', "%$colour%");

    $sth->execute();

    ?>

Пример #2 Пример выполнения подготовленного запроса с массивом именованных значений

    <?php

    /* Выполнение подготовленного запроса с передачей массива входных значений */
    $calories = 150;
    $colour = 'red';

    $sth = $dbh->prepare(
        'SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour'
    );

    $sth->execute(array('calories' => $calories, 'colour' => $colour));

    /* Ключи массива также разрешают начинать с двоеточия ":" */
    $sth->execute(array(':calories' => $calories, ':colour' => $colour));

    ?>

Пример #3 Пример выполнения подготовленного запроса с массивом позиционных значений

    <?php

    /* Выполнение подготовленного запроса с передачей массива входных значений */
    $calories = 150;
    $colour = 'red';

    $sth = $dbh->prepare(
        'SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?'
    );

    $sth->execute(array($calories, $colour));

    ?>

Пример #4 Пример выполнения подготовленного запроса с переменными, которые привязали к позиционным заполнителям

    <?php

    /* Выполнение подготовленного запроса с привязкой PHP переменных */
    $calories = 150;
    $colour = 'red';

    $sth = $dbh->prepare(
        'SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?'
    );

    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $colour, PDO::PARAM_STR, 12);

    $sth->execute();

    ?>

Пример #5 Пример выполнения подготовленного запроса с массивом для условия IN

    <?php

    /* Выполнение подготовленного запроса с массивом для условия IN */
    $params = array(1, 21, 63, 171);

    /* Создаём строку из знаков вопроса (?) в количестве, равном количеству параметров */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /**
     * Пример подготавливает запрос с неименованными заполнителями (?),
     * количество которых совпадает с количеством значений в массиве $params. При выполнении
     * запроса метод заменит знаки вопроса элементами массива. Это не то же
     * самое, что вызывать метод PDOStatement::bindParam(), в котором значения привязываются
     * по ссылке на переменную. Метод PDOStatement::execute() связывает параметры по значению
     */
    $sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
    $sth->execute($params);

    ?>

### Примечания

> Замечание:

> Отдельные драйверы требуют закрытия курсора перед запуском следующего запроса.

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::bindParam() - Привязывает параметр запроса к переменной
- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора
- PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов
- PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Извлекает следующую строку из результирующего набора

### Описание

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Метод извлекает следующую строку из результирующего набора объекта PDOStatement. Параметр `mode` определяет, в каком виде модуль PDO вернёт эту строку.

### Список параметров

`mode`

  Параметр определяет, в каком виде следующая строка вернётся в вызывающий метод. Параметр принимает значение в виде константы семейства `PDO::FETCH_*`. Значение по умолчанию равняется `PDO::ATTR_DEFAULT_FETCH_MODE`, что равносильно значению `PDO::FETCH_BOTH`.

  - `PDO::FETCH_ASSOC`: возвращает массив, индексированный именами столбцов результирующего набора

  - `PDO::FETCH_BOTH` (по умолчанию): возвращает массив, индексированный названиями столбцов результирующего набора, и их номерами начиная с 0

  - `PDO::FETCH_BOUND`: возвращает `true` и присваивает значения столбцов результирующего набора PHP-переменным, которые привязали к этим столбцам методом PDOStatement::bindColumn()

  - `PDO::FETCH_CLASS`: возвращает новый экземпляр запрошенного класса. Объект инициализируется путём сопоставления столбцов из набора с результатами запроса со свойствами класса. Столбцы сопоставляются до вызова конструктора, что разрешает заполнять свойства независимо от видимости или установки модификатора `readonly`. PHP вызовет магический метод __set(), если класс не содержит свойства с таким названием и если метод определили в классе; иначе в объекте создаётся динамическое открытое свойство. Однако при установке флага `PDO::FETCH_PROPS_LATE` конструктор вызывается до заполнения свойств. При передаче в параметр `mode` флага `PDO::FETCH_CLASSTYPE` в аргументе наподобие `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE` название класса определяется из значения первого столбца.

  - `PDO::FETCH_INTO`: обновляет существующий объект запрошенного класса, присваивая значения столбцов результирующего набора именованным свойствам объекта.

  - `PDO::FETCH_LAZY`: комбинирует `PDO::FETCH_BOTH` и `PDO::FETCH_OBJ` и возвращает объект PDORow, который создаёт имена свойств объекта по мере доступа к ним.

  - `PDO::FETCH_NAMED`: возвращает массив в той же форме, в какой его возвращает флаг `PDO::FETCH_ASSOC`, но если в наборе с результатами запроса содержатся столбцы с одинаковым названием, значением, на который ссылается ключ, станет массив значений строки, которые содержатся в столбцах с этим названием.

  - `PDO::FETCH_NUM`: возвращает массив, индексированный номерами столбцов (начиная с 0)

  - `PDO::FETCH_OBJ`: создаёт анонимный объект со свойствами, соответствующими именам столбцов результирующего набора

  - `PDO::FETCH_PROPS_LATE`: если используется с `PDO::FETCH_CLASS`, конструктор класса будет вызван перед назначением свойств из значений столбцов.

`cursorOrientation`

  Для объектов PDOStatement представляющих прокручиваемый курсор, этот параметр определяет, какая строка будет возвращаться в вызывающий метод. Значением параметра должна быть одна из констант `PDO::FETCH_ORI_*`, по умолчанию `PDO::FETCH_ORI_NEXT`. Чтобы запросить прокручиваемый курсор для запроса PDOStatement, необходимо задать атрибут `PDO::ATTR_CURSOR` со значением `PDO::CURSOR_SCROLL` во время подготовки запроса методом PDO::prepare().

`cursorOffset`

  Для объектов PDOStatement, представляющих прокручиваемый курсор, параметр `cursorOrientation` которых принимает значение `PDO::FETCH_ORI_ABS`, эта величина означает абсолютный номер строки, которую необходимо извлечь из результирующего набора.

  Для объектов PDOStatement, представляющих прокручиваемый курсор, параметр `cursorOrientation` которых принимает значение `PDO::FETCH_ORI_REL`, эта величина указывает, какая строка относительно текущего положения курсора будет извлечена функцией PDOStatement::fetch().

### Возвращаемые значения

Значение возврата зависит от режима выборки, когда функция выполнилась успешно. Функция возвращает `false`, если возникла ошибка или не осталось строк.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Извлечение строк в разных режимах выборки

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Примеры различных режимов работы PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Возвращаем следующую строку в виде массива, индексированного именами столбцов\n";
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Возвращаем следующую строку в виде массива, индексированного как именами столбцов, так и их номерами\n";
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Возвращаем следующую строку в виде объекта класса PDORow с именами столбцов в качестве свойств\n";
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

Результат выполнения приведённого примера:

    PDO::FETCH_ASSOC: Возвращаем следующую строку в виде массива, индексированного именами столбцов
    Array
    (
        [name] => apple
        [colour] => red
    )

    PDO::FETCH_BOTH: Возвращаем следующую строку в виде массива, индексированного как именами столбцов, так и их номерами
    Array
    (
        [name] => banana
        [0] => banana
        [colour] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам
    PDO::FETCH_LAZY: Возвращаем следующую строку в виде объекта класса PDORow с именами столбцов в качестве свойств
    PDORow Object
    (
        [name] => orange
        [colour] => orange
    )

    PDO::FETCH_OBJ: Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам
    kiwi

Пример #2 Выборка строк средствами прокручиваемого курсора

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Читаем в прямой последовательности:\n";
    readDataForwards($conn);

    print "Читаем в обратной последовательности:\n";
    readDataBackwards($conn);
    ?>

Результат выполнения приведённого примера:

    Читаем в прямой последовательности:
    21    10    5
    16    0     5
    19    20    10

    Читаем в обратной последовательности:
    19    20    10
    16    0     5
    21    10    5

Пример #3 Порядок конструкторов

При извлечении объектов через флаг `PDO::FETCH_CLASS` сначала присваиваются свойства объекта, а затем вызывается конструктор класса. Однако при одновременной передаче флага `PDO::FETCH_PROPS_LATE` порядок действий изменяется на противоположный: вначале вызывается конструктор, а затем присваиваются свойства.

    <?php

    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Меня зовут {$this->name}.\n";
            } else {
                echo "Мне ещё не дали имя.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");

    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();

    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();

    ?>

Вывод приведённого примера будет похож на:

    Меня зовут Alice.
    Меня зовут Alice.
    Мне ещё не дали имя.
    Меня зовут Bob.

### Смотрите также

- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов
- PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора
- PDOStatement::fetchObject() - Извлекает следующую строку и возвращает её в виде объекта
- PDOStatement::setFetchMode() - Устанавливает режим выборки по умолчанию для объекта запроса

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — Выбирает строки, которые остались в наборе результатов

### Описание

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array

### Список параметров

`mode`

  Режим управляет содержанием массива, который вернёт метод, как задокументировали в описании метода PDOStatement::fetch(). Параметр принимает значение по умолчанию, которое определяет константа `PDO::ATTR_DEFAULT_FETCH_MODE`, значение по умолчанию которой определяет константа `PDO::FETCH_BOTH`.

  В параметр передают константу `PDO::FETCH_COLUMN`, чтобы извлечь значения только одного столбца. Параметром `column` задают столбец, данные которого требуется извлечь.

  Название столбца помещают первым в списке столбцов SQL-запроса и указывают флаг `PDO::FETCH_UNIQUE`, чтобы проиндексировать массив с результатами по значению конкретного столбца, а не по последовательным числам. Часть данных из столбцов с неуникальными значениями потеряется.

  Название столбца помещают первым в списке столбцов SQL-запроса и указывают флаг `PDO::FETCH_GROUP`, чтобы сгруппировать результаты в виде 3-мерного массива, который БД проиндексирует по значениям заданного столбца.

  Для группировки результатов в виде 2-мерного массива флаги `PDO::FETCH_GROUP` и `PDO::FETCH_COLUMN` указывают через побитовое ИЛИ. Результаты сгруппируются по первому столбцу, при этом значениями элементов массива будут массивы со списком записей из второго столбца, которые соответствуют записям первого.

Дальше идут динамические параметры, которые зависят от режима выборки. Эти параметры нельзя использовать с именованными параметрами.

`column`

  Аргумент для этого параметра передают при выборке в режиме `PDO::FETCH_COLUMN`. Параметр возвращает столбец по индексу, которые начинаются с 0.

`class`

  Аргумент для этого параметра передают при выборке в режиме `PDO::FETCH_CLASS`. Параметр сопоставляет столбцы строк с названиями свойств класса и возвращает экземпляры класса.

`constructorArgs`

  Параметр принимает аргументы для конструктора пользовательского класса, когда через параметр `mode` установили режим выборки `PDO::FETCH_CLASS`.

`callback`

  Аргумент для этого параметра передают при выборке в режиме `PDO::FETCH_FUNC`. Параметр передаёт столбцы строк как аргументы функции обратного вызова и возвращает результаты вызова функции.

### Возвращаемые значения

Метод PDOStatement::fetchAll() возвращает массив со строками, которые остались в наборе результатов. Массив представляет каждую строку либо как массив значений столбцов, либо как объект, названия свойств которого соответствуют названиям столбцов.

При извлечении наборов результатов с большим количеством строк метод серьёзно нагружает систему и, возможно, ресурсы сети. Наборы результатов лучше обрабатывать средствами СУБД, чем извлекать все данные и обрабатывать набор результатов в PHP. В языке запросов SQL, например, пользуются условиями WHERE и ORDER BY, чтобы ограничить выборку результатов перед извлечением и обработкой в PHP.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь метод каждый раз возвращает массив (array), раньше иногда возвращалось `false`, если возникала ошибка.

### Примеры

Пример #1 Пример извлечения строк, которые остались в наборе результатов

    <?php

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Извлекаем строки, которые остались в наборе результатов */
    print "Извлечение строк, которые остались в наборе результатов:\n";
    $result = $sth->fetchAll();
    print_r($result);

    ?>

Вывод приведённого примера будет похож на:

    Извлечение строк, которые остались в наборе результатов:
    Array
    (
        [0] => Array
            (
                [name] => apple
                [0] => apple
                [colour] => red
                [1] => red
            )

        [1] => Array
            (
                [name] => pear
                [0] => pear
                [colour] => green
                [1] => green
            )

        [2] => Array
            (
                [name] => watermelon
                [0] => watermelon
                [colour] => pink
                [1] => pink
            )
    )

Пример #2 Пример извлечения значений одного столбца из набора результатов

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

    <?php

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Извлекаем значения первого столбца */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

Вывод приведённого примера будет похож на:

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

Пример #3 Пример группировки строк по значениям одного столбца

Следующий пример показывает, как получить ассоциативный массив строк набора результатов, которые метод сгруппировал по значениям столбца. Массив содержит три ключа: значения `apple` и `pear` — массивы, каждое из которых содержит два разных цвета; а ключ `watermelon` будет массивом только с одним цветом.

    <?php

    $insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
    $insert->execute(array('apple', 'green'));
    $insert->execute(array('pear', 'yellow'));

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Группируем записи по значениям первого столбца */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));

    ?>

Вывод приведённого примера будет похож на:

    array(3) {
      ["apple"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(3) "red"
      }
      ["pear"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(6) "yellow"
      }
      ["watermelon"]=>
      array(1) {
        [0]=>
        string(5) "pink"
      }
    }

Пример #4 Создание объекта для каждой строки

Следующий пример показывает поведение метода в режиме выборки `PDO::FETCH_CLASS`.

    <?php

    class fruit
    {
        public $name;
        public $colour;
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
    var_dump($result);

    ?>

Вывод приведённого примера будет похож на:

    array(3) {
      [0]=>
      object(fruit)#1 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(5) "green"
      }
      [1]=>
      object(fruit)#2 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(6) "yellow"
      }
      [2]=>
      object(fruit)#3 (2) {
        ["name"]=>
        string(10) "watermelon"
        ["colour"]=>
        string(4) "pink"
      }
      [3]=>
      object(fruit)#4 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(3) "red"
      }
      [4]=>
      object(fruit)#5 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(5) "green"
      }
    }

Пример #5 Пример вызова функции для каждой строки

Следующий пример показывает поведение метода в режиме выборки `PDO::FETCH_FUNC`.

    <?php

    function fruit($name, $colour)
    {
        return "{$name}: {$colour}";
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
    var_dump($result);

    ?>

Вывод приведённого примера будет похож на:

    array(3) {
      [0]=>
      string(12) "apple: green"
      [1]=>
      string(12) "pear: yellow"
      [2]=>
      string(16) "watermelon: pink"
      [3]=>
      string(10) "apple: red"
      [4]=>
      string(11) "pear: green"
    }

### Смотрите также

- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей
- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора
- PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора
- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::setFetchMode() - Устанавливает режим выборки по умолчанию для объекта запроса

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — Возвращает данные одного столбца следующей строки результирующего набора

### Описание

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

Возвращает данные одного столбца следующей строки результирующей таблицы. Если в результате запроса строк больше нет, функция вернёт `false`.

> Замечание:

> Не следует использовать PDOStatement::fetchColumn() для получения логических полей, так как невозможно отличить значение `false` от отсутствия оставшихся строк результата. Вместо этого используйте метод PDOStatement::fetch().

### Список параметров

`column`

  Номер столбца, данные которого необходимо извлечь. Нумерация начинается с 0. Если параметр не задан, PDOStatement::fetchColumn() выберет данные первого столбца.

### Возвращаемые значения

Метод PDOStatement::fetchColumn() возвращает значение одного столбца следующей строки результирующего набора или `false`, если больше нет строк.

Внимание

При вызове метода PDOStatement::fetchColumn() для извлечения данных из результирующего набора невозможно получить значение другого столбца той же строки.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Получение значения первого столбца следующей строки

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    print "Получение значения первого столбца первой строки:\n";
    $result = $sth->fetchColumn();
    print "name = $result\n";

    print "Получение значения второго столбца второй строки:\n";
    $result = $sth->fetchColumn(1);
    print "colour = $result\n";
    ?>

Результат выполнения приведённого примера:

    Получение значения первого столбца первой строки:
    name = lemon
    Получение значения второго столбца второй строки:
    colour = red

### Смотрите также

- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей
- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора
- PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов
- PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
- PDOStatement::setFetchMode() - Устанавливает режим выборки по умолчанию для объекта запроса

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — Извлекает следующую строку и возвращает её в виде объекта

### Описание

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

Извлекает следующую строку и возвращает её в виде объекта. Этот метод является альтернативой вызову PDOStatement::fetch() с параметром `PDO::FETCH_CLASS` или `PDO::FETCH_OBJ`.

Когда объект извлечён, его свойства наполняются значениями соответствующих столбцов, и, после этого, вызывается его конструктор.

### Список параметров

`class`

  Имя класса создаваемого объекта.

`constructorArgs`

  Элементы этого массива будут переданы в конструктор класса.

### Возвращаемые значения

Возвращает новый объект указанного класса, имена свойств которого соответствуют именам столбцов результирующего набора или `false`, если возникла ошибка.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Смотрите также

- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — Получение значения атрибута запроса PDOStatement

### Описание

public function PDOStatement::getAttribute(int `$name`): mixed

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

- `PDO::ATTR_CURSOR_NAME` (для Firebird и ODBC): Получение имени курсора для запроса `UPDATE ... WHERE CURRENT OF`.

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

### Список параметров

`name`

  Атрибут для запроса.

### Возвращаемые значения

Возвращает значение атрибута.

### Смотрите также

- PDO::getAttribute() - Получает атрибут соединения с базой данных
- PDO::setAttribute() - Устанавливает атрибут
- PDOStatement::setAttribute() - Устанавливает атрибут объекту PDOStatement

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — Возвращает метаданные столбца в результирующей таблице

### Описание

public function PDOStatement::getColumnMeta(int `$column`): array|false

Возвращает метаданные столбца результирующей таблицы в виде ассоциативного массива. Индексация столбцов начинается с 0.

Внимание

Некоторые драйверы PDO могут не реализуют функцию PDOStatement::getColumnMeta(), поскольку она является необязательной. Однако все драйверы PDO, указанные в руководстве, реализуют эту функцию.

### Список параметров

`column`

  Индекс (начиная с 0) столбца результирующего набора.

### Возвращаемые значения

Возвращает ассоциативный массив, содержащий следующие значения метаданных:

Метаданные столбца
Имя | Значение
--- | ---
`native_type` | Внутренний тип PHP, используемый для представления значения столбца.
`driver:decl_type` | Тип SQL, используемый для представления значения столбца в базе данных. Если значение столбца результирующей таблицы было возвращено из функции, PDOStatement::getColumnMeta() не будет определять этот тип.
`flags` | Какие-либо флаги, установленные для столбца.
`name` | Имя этого столбца, возвращаемое базой данных.
`table` | Имя таблицы этого столбца, возвращаемое базой данных.
`len` | Размер поля столбца. Как правило, для типов, отличных от чисел с плавающей точкой, это значение равно `-1`.
`precision` | Числовая точность этого столбца. Как правило, для типов, отличных от чисел с плавающей точкой, это значение равно `0`.
`pdo_type` | Тип PDO значения столбца в виде одной из констант `PDO::PARAM_*`.

Возвращает `false` в случаях, когда указанного столбца нет в результирующей таблице, а также если не существует самого результирующего набора.

### Примеры

Пример #1 Извлечение метаданных столбца

В следующем примере показаны результаты извлечения метаданных одного столбца, сгенерированного функцией COUNT драйвера PDO_SQLITE.

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

Результат выполнения приведённого примера:

    array(6) {
      ["native_type"]=>
      string(7) "integer"
      ["flags"]=>
      array(0) {
      }
      ["name"]=>
      string(8) "COUNT(*)"
      ["len"]=>
      int(-1)
      ["precision"]=>
      int(0)
      ["pdo_type"]=>
      int(2)
    }

### Смотрите также

- PDOStatement::columnCount() - Возвращает количество столбцов в результирующем наборе
- PDOStatement::rowCount() - Возвращает количество строк, которое затронул последний SQL-запрос

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Получает итератор набора результатов

### Описание

public function PDOStatement::getIterator(): Iterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — Переход к следующему набору строк в результате запроса

### Описание

public function PDOStatement::nextRowset(): bool

Некоторые СУБД поддерживают хранимые процедуры, которые возвращают более одного набора строк (его ещё называют результирующим набором). PDOStatement::nextRowset() позволяет получить доступ ко второму и дальнейшим наборам, соответствующим объекту PDOStatement. Разные наборы строк могут иметь разное количество столбцов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Извлечение данных из нескольких наборов строк, возвращённых хранимой процедурой

В следующем примере показано, как вызывать хранимую процедуру `MULTIPLE_ROWSETS`, которая возвращает три набора строк. Мы вызываем PDOStatement::nextRowset() в цикле do-while, пока он не вернёт `false` и завершит цикл, когда больше не будет доступных результирующих наборов.

    <?php
    $sql = 'CALL multiple_rowsets()';
    $stmt = $conn->query($sql);
    $i = 1;
    do {
        $rowset = $stmt->fetchAll(PDO::FETCH_NUM);
        if ($rowset) {
            printResultSet($rowset, $i);
        }
        $i++;
    } while ($stmt->nextRowset());

    function printResultSet(&$rowset, $i) {
        print "Результирующий набор $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

Результат выполнения приведённого примера:

    Результирующий набор 1:
    apple    red
    banana   yellow

    Результирующий набор 2:
    orange   orange    150
    banana   yellow    175

    Результирующий набор 3:
    lime     green
    apple    red
    banana   yellow

### Смотрите также

- PDOStatement::columnCount() - Возвращает количество столбцов в результирующем наборе
- PDOStatement::execute() - Выполняет подготовленный запрос
- PDOStatement::getColumnMeta() - Возвращает метаданные столбца в результирующей таблице
- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — Возвращает количество строк, которое затронул последний SQL-запрос

### Описание

public function PDOStatement::rowCount(): int

Метод PDOStatement::rowCount() возвращает количество строк, которое затронул последний запрос DELETE, INSERT или UPDATE объекта `PDOStatement`.

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

> Замечание:

> При взаимодействии с БД через драйвер PostgreSQL метод возвращает числовую строку "0", если в запросе для атрибута `PDO::ATTR_CURSOR` установили значение `PDO::CURSOR_SCROLL`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество строк.

### Ошибки

Метод выдаёт ошибку уровня `E_WARNING`, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_WARNING`.

Метод выбрасывает исключение PDOException, если для атрибута `PDO::ATTR_ERRMODE` установили режим `PDO::ERRMODE_EXCEPTION`.

### Примеры

Пример #1 Пример получения количества удалённых строк

Метод PDOStatement::rowCount() возвращает количество строк, изменённых выражениями DELETE, INSERT или UPDATE.

    <?php

    /* Удалим все строки из таблицы FRUIT */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /* Выведем число удалённых строк */
    print "Количество удалённых строк:\n";
    $count = $del->rowCount();
    print "Удалено $count строк.\n";

    ?>

Вывод приведённого примера будет похож на:

    Количество удалённых строк:
    Удалено 9 строк.

Пример #2 Пример подсчёта строк в результатах запроса SELECT

Для большей части СУБД метод PDOStatement::rowCount() не возвращает количество строк в результатах SELECT-запроса. Вместо этого метода вызывают метод PDO::query() со строкой запроса SELECT COUNT(*) и теми же предикатами, которые планировали указать в главном SELECT-запросе, а затем вызывают метод PDOStatement::fetchColumn(), чтобы получить количество строк, которое соответствует запросу.

    <?php

    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "Количество записей, которые соответствуют запросу: " .  $count;

    ?>

Вывод приведённого примера будет похож на:

    Количество записей, которые соответствуют запросу: 2

### Смотрите также

- PDOStatement::columnCount() - Возвращает количество столбцов в результирующем наборе
- PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора
- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — Устанавливает атрибут объекту PDOStatement

### Описание

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

Задаёт атрибут объекта PDOStatement. На данный момент никаких общих атрибутов устанавливать нельзя, только характерные для конкретного драйвера:

- `PDO::ATTR_CURSOR_NAME` (для Firebird и ODBC): Задаёт имя курсора для запросов вида `UPDATE ... WHERE CURRENT OF`.

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

### Список параметров

`attribute`

  Атрибут для изменения.

`value`

  Значение для установки параметра `attribute` может потребовать определённого типа в зависимости от атрибута.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- PDO::getAttribute() - Получает атрибут соединения с базой данных
- PDO::setAttribute() - Устанавливает атрибут
- PDOStatement::getAttribute() - Получение значения атрибута запроса PDOStatement

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — Устанавливает режим выборки по умолчанию для объекта запроса

### Описание

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### Список параметров

`mode`

  Режим выборки: константа семейства `PDO::FETCH_*`.

`colno`

  Номер столбца.

`class`

  Название класса.

`constructorArgs`

  Аргументы конструктора класса.

`object`

  Объект.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Пример #1 Изменение режима выборки

Следующий пример показывает изменение режима выборки по умолчанию для объекта PDOStatement методом PDOStatement::setFetchMode().

    <?php

    $stmt = $dbh->query('SELECT name, colour, calories FROM fruit');

    $stmt->setFetchMode(PDO::FETCH_NUM);

    foreach ($stmt as $row) {
        print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
    }

Результат выполнения приведённого примера:

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## Содержание

- PDOStatement::bindColumn — Связывает столбец с переменной PHP
- PDOStatement::bindParam — Привязывает параметр запроса к переменной
- PDOStatement::bindValue — Связывает параметр с заданным значением
- PDOStatement::closeCursor — Закрывает курсор, переводя запрос в состояние готовности к повторному запуску
- PDOStatement::columnCount — Возвращает количество столбцов в результирующем наборе
- PDOStatement::debugDumpParams — Вывод информации о подготовленной SQL-команде в целях отладки
- PDOStatement::errorCode — Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement
- PDOStatement::errorInfo — Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement
- PDOStatement::execute — Выполняет подготовленный запрос
- PDOStatement::fetch — Извлекает следующую строку из результирующего набора
- PDOStatement::fetchAll — Выбирает строки, которые остались в наборе результатов
- PDOStatement::fetchColumn — Возвращает данные одного столбца следующей строки результирующего набора
- PDOStatement::fetchObject — Извлекает следующую строку и возвращает её в виде объекта
- PDOStatement::getAttribute — Получение значения атрибута запроса PDOStatement
- PDOStatement::getColumnMeta — Возвращает метаданные столбца в результирующей таблице
- PDOStatement::getIterator — Получает итератор набора результатов
- PDOStatement::nextRowset — Переход к следующему набору строк в результате запроса
- PDOStatement::rowCount — Возвращает количество строк, которое затронул последний SQL-запрос
- PDOStatement::setAttribute — Устанавливает атрибут объекту PDOStatement
- PDOStatement::setFetchMode — Устанавливает режим выборки по умолчанию для объекта запроса

# Класс PDORow

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Введение

Объект представляет строку из набора результатов, которую возвращает метод PDOStatement::fetch() при вызове в режиме ленивой выборки — `PDO::FETCH_LAZY`.

Объекты класса невозможно создать или сериализовать.

Объект PDORow поддерживает доступ к строке результата выборки и как к свойствам объекта, и как к элементам массива, причём как по строковому ключу с названием столбца, так и по целочисленному, который соответствует смещению столбца. Объект сочетает способы доступа к данным в режимах выборки `PDO::FETCH_OBJ` и `PDO::FETCH_BOTH`.

Предостережение

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

## Обзор класса

final class PDORow {
/* Свойства */
public string $queryString;
}

## Свойства

queryString

  Строка запроса из объекта PDOStatement, метод которого вернул объект PDORow.

## Ошибки

При попытке записать значение в свойство объекта или удалить свойство языковой конструкцией unset() объект выбрасывает ошибку Error.

# Исключение PDOException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Введение

Исключение представляет ошибку, которая возникла в модуле PDO. Программистам не требуется выбрасывать исключения PDOException в пользовательском коде. Дополнительную информацию об исключениях в PHP даёт раздел «Исключения».

## Обзор класса

class PDOException extends RuntimeException {
/* Свойства */
protected int|string $code;
public ?array $errorInfo = null;
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

errorInfo

  Значение свойства соответствует информации, которую возвращает метод PDO::errorInfo() или PDOStatement::errorInfo()

code

  Код ошибки `SQLSTATE`. Доступ к коду возврата получают методом Exception::getCode().

# Драйверы модуля PDO

## Содержание

- PDO-драйвер СУБД CUBRID
- PDO-драйвер СУБД MS SQL Server
- Pdo\Dblib
- PDO-драйвер СУБД Firebird
- Pdo\Firebird
- PDO-драйвер СУБД IBM
- PDO-драйвер СУБД Informix
- PDO-драйвер СУБД MySQL
- Pdo\Mysql
- PDO-драйвер СУБД MS SQL Server
- PDO-драйвер СУБД Oracle
- PDO-драйвер СУБД ODBC и DB2
- Pdo\Odbc
- PDO-драйвер СУБД PostgreSQL
- Pdo\Pgsql
- PDO-драйвер СУБД SQLite
- Pdo\Sqlite

PDO-интерфейс реализуют следующие драйверы:

Название драйвера | Поддерживаемые базы данных
--- | ---
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS, Microsoft SQL Server и Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x, 4.x, 5.x и 8.x
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3: IBM DB2, unixODBC и win32 ODBC
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 и SQLite 2
PDO_SQLSRV | Microsoft SQL Server, SQL Azure

# PDO_CUBRID: драйвер модуля PDO для СУБД CUBRID

## Введение

PDO_CUBRID — драйвер, через который PHP получает доступ к базам данных CUBRID. Для этого драйвер реализует интерфейс модуля PDO.

> Замечание: Текущая версия драйвера PDO_CUBRID не поддерживает постоянные соединения.

## Установка

Для сборки модуля PDO_CUBRID потребуется установить СУБД CUBRID на том же хосте, на котором установили PHP. PDO_CUBRID — модуль » PECL, поэтому для его установки следуйте инструкциям Установка PECL-модулей. Для указания команде configure директории с установленной базой CUBRID, используйте следующий синтаксис:

       $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]

По умолчанию configure будет искать соответствующие библиотеки, руководствуясь значением переменной окружения CUBRID.

DLL для этого модуля PECL пока недоступна. Смотрите также раздел сборка на Windows. Для более подробной информации о ручной установке модуля под Linux и Windows, читайте build-guide.html, содержащийся в пакете PECL.

## Функции драйвера PDO_CUBRID

## Прокручиваемые курсоры

Драйвер PDO_CUBRID поддерживает прокручиваемые курсоры. Тип курсора по умолчанию — "forward only" (только вперёд), и чтобы изменить тип курсора в методе PDO::prepare() указывают параметр driver_options.

## Время ожидания

Драйвер PDO_CUBRID поддерживает настройку времени ожидания выполнения SQL-запроса; значение времени ожидания устанавливают методом PDO::setAttribute().

## Режим автоподтверждения и транзакции

Драйвер PDO_CUBRID поддерживает как режим автоподтверждения autocommit_mode, так и работу с транзакциями, а по умолчанию включён режим автоподтверждения. Состояние режима изменяют методом PDO::setAttribute().

Автоподтверждение будет автоматически запрещено и снова разрешено после вызова метода PDO::commit() или PDO::rollBack(), если для старта транзакции вызвали метод PDO::beginTransaction().

> Замечание: Перед отключением автоподтверждения ожидающие запросы автоматически фиксируются.

## Множественные SQL-запросы

Драйвер PDO_CUBRID поддерживает множественные SQL-запросы. Множественные SQL-запросы разделяются точкой с запятой (`;`).

## Информация о схеме

Драйвер PDO_CUBRID реализует метод PDO::cubrid_schema(), чтобы получать информацию о схеме.

## Большие объекты

Драйвер PDO_CUBRID поддерживает типы данных BLOB и CLOB. Тип данных LOB (англ. сокр.: Large Objects) в модуле PDO представили как поток. Поэтому разрешается вставлять LOB-объект в базу данных путём связывания подготовленного запроса с потоком и получения LOB-объекта считыванием из потока, который возвращает PDO-объект, который настроили на работу с драйвером БД CUBRID. Например:

Пример #1 Пример вставки LOB-объекта в БД CUBRID

    <?php

    $fp = fopen('lob_test.png', 'rb');

    $sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

    $stmt = $dbh->prepare($sql_stmt);
    $ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
    $ret = $stmt->execute();

Пример #2 Пример получения LOB-объекта из БД CUBRID

    <?php

    $sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

    $stmt = $dbh->prepare($sql_stmt);
    $stmt->execute();
    $result = $stmt->fetch(PDO::FETCH_NUM);

    header("Content-Type: image/png");
    fpassthru($result[0]);

## Метаинформация о столбцах

Метод PDOStatement::getColumnMeta() в PDO-объекте, который настроили на работу с БД CUBRID, вернёт ассоциативный массив, который содержит следующие значения:

- type
- name
- table
- def
- precision
- scale
- not_null
- auto_increment
- unique_key
- multiple_key
- primary_key
- foreign_key
- reverse_index
- reverse_unique

## Тип данных Коллекция

Драйвер PDO_CUBRID поддерживает типы данных SET, MULTISET и SEQUENCE. Тип данных по умолчанию — char, если тип данных не указали вручную. Например:

Пример #3 Пример вставки коллекции в БД CUBRID с типом данных по умолчанию

    <?php

    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);

    $data = array("abc","def","ghi");

    $ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);

    $ret = $stmt->execute();

    var_Dump($ret);

Пример #4 Пример указания типа данных при вставке коллекции в БД CUBRID

    <?php

    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);

    $data = array(1,2,3,4);

    $ret = $stmt->bindParam(1, $data, 0,0,"int");

    $ret = $stmt->execute();

    var_Dump($ret);

База данных CUBRID связывает типы данных для пятого параметра метода PDOStatement::bindParam():

- CHAR
- STRING
- NCHAR
- VARNCHAR
- BIT
- VARBIT
- NUMERIC
- NUMBER
- INT
- SHORT
- BIGINT
- MONETARY
- FLOAT
- DOUBLE
- DATE
- TIME
- DATETIME
- TIMESTAMP

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

Следующими константами устанавливают атрибуты базы данных. Эти константы передают в методы PDO::getAttribute() и PDO::setAttribute().

Флаги атрибутов драйвера PDO::CUBRID
Константы | Описание
--- | ---
`PDO::CUBRID_ATTR_ISOLATION_LEVEL` | Уровень изоляции для соединения.
`PDO::CUBRID_ATTR_LOCK_TIMEOUT` | Время ожидания транзакции в секундах.
`PDO::CUBRID_ATTR_MAX_STRING_LENGTH` | Только для чтения. Максимальная длина строки для типов данных bit, varbit, char, varchar, nchar, nchar при работе с API драйвера CUBRID модуля PDO.

Следующие константы устанавливают уровень изоляции транзакции. Эти константы передают в методы PDO::getAttribute() и PDO::setAttribute().

Флаги уровней изоляции драйвера PDO::CUBRID
Константы | Описание
--- | ---
`PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | Самый низкий уровень изоляции (1). Для кортежа может произойти грязное, неповторяемое или фантомное считывание, а также для таблицы может произойти неповторяемое считывание.
`PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Относительно низкий уровень изоляции (2). Грязного чтения не будет, но неповторяющееся или фантомное возможно.
`PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | Уровень изоляции драйвера CUBRID по умолчанию (3). Для кортежа может произойти «грязное», неповторяемое или фантомное чтение, но для таблицы гарантировано повторяющееся чтение.
`PDO::TRAN_REP_CLASS_COMMIT_INSTANCE` | Относительно низкий уровень изоляции (4). Грязного чтения не будет, но неповторяющееся или фантомное возможно.
`PDO::TRAN_REP_CLASS_REP_INSTANCE` | Относительно высокий уровень изоляции (5). Грязного и неповторяющегося чтения не будет, но фантомное может возникнуть.
`PDO::TRAN_SERIALIZABLE` | Самый высокий уровень изоляции (6). Грязное, неповторяющееся и фантомное чтение невозможны.

Следующие константы передают, когда получают информацию о схеме. Эти константы передают в метод PDO::cubrid_schema().

Флаги схемы драйвера PDO::CUBRID
Константы | Описание
--- | ---
`PDO::CUBRID_SCH_TABLE` | Получить имя и тип таблицы CUBRID.
`PDO::CUBRID_SCH_VIEW` | Получить имя и тип представления в CUBRID.
`PDO::CUBRID_SCH_QUERY_SPEC` | Получить определение запроса представления.
`PDO::CUBRID_SCH_ATTRIBUTE` | Получить атрибуты столбца таблицы.
`PDO::CUBRID_SCH_TABLE_ATTRIBUTE` | Получить атрибуты таблицы.
`PDO::CUBRID_SCH_METHOD` | Получить метод экземпляра. Метод экземпляра — метод, который вызвал экземпляр класса. Методом экземпляра пользуются чаще, чем методом класса, поскольку большинство операций выполняют в экземпляре.
`PDO::CUBRID_SCH_TABLE_METHOD` | Получить метод класса. Метод класса — метод, который вызвал объект класса. Методом класса обычно создают новый экземпляр класса или инициализируют его. Метод также вызывают, чтобы получить доступ или обновить атрибуты класса.
`PDO::CUBRID_SCH_METHOD_FILE` | Получить информацию о файле, в котором определили метод таблицы.
`PDO::CUBRID_SCH_SUPER_TABLE` | Получить имя и тип таблицы, из которой таблица наследует атрибуты.
`PDO::CUBRID_SCH_SUB_TABLE` | Получить имя и тип таблицы, которая наследует атрибуты из этой таблицы.
`PDO::CUBRID_SCH_CONSTRAINT` | Получить ограничения таблицы.
`PDO::CUBRID_SCH_TRIGGER` | Получить триггеры таблицы.
`PDO::CUBRID_SCH_TABLE_PRIVILEGE` | Получить информацию о правах на таблицу.
`PDO::CUBRID_SCH_COL_PRIVILEGE` | Получить информацию о правах на столбец.
`PDO::CUBRID_SCH_DIRECT_SUPER_TABLE` | Получить прямую супертаблицу для заданной таблицы.
`PDO::CUBRID_SCH_PRIMARY_KEY` | Получить первичный ключ таблицы.
`PDO::CUBRID_SCH_IMPORTED_KEYS` | Получить импортированные ключи таблицы.
`PDO::CUBRID_SCH_EXPORTED_KEYS` | Получить экспортированные ключи таблицы.
`PDO::CUBRID_SCH_CROSS_REFERENCE` | Получить связи двух таблиц.

# DSN-строка подключения через драйвер PDO_CUBRID

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_CUBRID — Соединение с базой данных CUBRID

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_CUBRID состоит из следующих элементов, разделённых точкой с запятой:

DSN-префикс

  DSN-префикс — строка `cubrid:`.

`host`
  Имя хоста, на котором развернули базу данных.
`port`
  Порт, на котором база данных слушает подключения.
`dbname`
  Название базы данных.

### Примечания

> Замечание: При соединении с БД CUBRID требуется указать имя пользователя и пароль.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_CUBRID

Следующий пример показывает DSN-строку подключения через драйвер PDO_CUBRID для соединения с базой CUBRID:

    cubrid:host=localhost;port=33000;dbname=demodb

# PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — Получает информацию о схеме

### Описание

public function PDO::cubrid_schema(int `$schema_type`, string `$table_name` = ?, string `$col_name` = ?): array

Метод получает информацию о схеме из базы данных. Потребуется указать название таблицы `table_name`, чтобы получить информацию о конкретной таблице, название столбца `col_name`, чтобы получить информацию о конкретном столбце; параметр с названием столбца работает только с флагом PDO::CUBRID_SCH_COL_PRIVILEGE.

Метод возвращает результат в виде двумерного массива (столбец (ассоциативный массив) * строка (числовой массив)). Следующие таблицы показывают типы схем и структуру столбцов массива с результатами, который вернёт метод на основе типа схемы.

Структура результата каждого типа
Схема | Номер столбца | Название столбца | Значение
--- | --- | --- | ---
PDO::CUBRID_SCH_TABLE | 1 | NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_VIEW | 1 | NAME |
| 2 | TYPE | 1:view
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Список параметров

`schema_type`
  Тип схемы, информацию о котором требуется узнать.
`table_name`
  Название таблицы, информацию о схеме которой требуется узнать.
`col_name`
  Название столбца, схему которого требуется узнать.

### Возвращаемые значения

Метод возвращает ассоциативный массив с информацией о схеме, если процесс выполнился успешно.

При ошибке метод возвращает значение `false`.

### Примеры

Пример #1 Пример получения информации о схеме методом PDO::cubrid_schema()

Пример показывает, как получить информацию о первичных и внешних ключах таблицы "game".

    <?php

    $pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
    print_r($pk_list);

    $fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
    print_r($fk_list);

    ?>

Результат выполнения приведённого примера:

    Результат:
    Array
    (
        [0] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => athlete_code
                [KEY_SEQ] => 3
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [1] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => event_code
                [KEY_SEQ] => 2
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [2] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => host_year
                [KEY_SEQ] => 1
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

    )
    Array
    (
        [0] => Array
            (
                [PKTABLE_NAME] => athlete
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => athlete_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_athlete_code
                [PK_NAME] => pk_athlete_code
            )

        [1] => Array
            (
                [PKTABLE_NAME] => event
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => event_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_event_code
                [PK_NAME] => pk_event_code
            )

    )

## Содержание

- DSN-строка подключения через драйвер PDO_CUBRID — Соединение с базой данных CUBRID
- PDO::cubrid_schema — Получает информацию о схеме

# PDO_DBLIB: драйвер модуля PDO для СУБД Microsoft SQL Server и Sybase

## Введение

PDO_DBLIB — драйвер, через который PHP получает доступ к базам данных Microsoft SQL Server и Sybase, совместимым с библиотекой FreeTDS. Для этого драйвер реализует интерфейс модуля PDO.

Модуль больше недоступен для ОС Windows.

В Windows пользуются драйвером SqlSrv — альтернативным драйвером БД MS SQL, который доступен для скачивания на сайте Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .

Когда использовать драйвер SqlSrv невозможно, с СУБД Microsoft SQL Server и Sybase соединяются через драйвер PDO_ODBC, поскольку собственный драйвер Windows DB-LIB устарел, непотокобезопасен и не поддерживается корпорацией Microsoft.

# DSN-строка подключения через драйвер PDO_DBLIB

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_DBLIB — Соединение с базами данных Microsoft SQL Server и Sybase

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_DBLIB состоит из следующих элементов::

DSN-префикс

  DSN-префикс — строка `sybase:` указывают, только если драйвер PDO_DBLIB собрали с библиотеками Sybase ct-lib, строка `mssql:`, если драйвер PDO_DBLIB собрали с библиотеками сервера Microsoft SQL Server, и строка `dblib:`, если драйвер PDO_DBLIB собрали с библиотеками FreeTDS.

`host`

  Имя сервера, на котором лежит база данных. Значение по умолчанию — 127.0.0.1.

`dbname`

  Название базы данных.

`charset`

  Клиентский набор символов.

`appname`

  Название приложения, которое указывают в системном представлении совместимости sysprocesses. Значение по умолчанию — "PHP Generic DB-lib" или "PHP freetds".

`secure`

  Пока не используется.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_DBLIB

Следующий пример показывает DSN-строку подключения через драйвер PDO_DBLIB для соединения с базами данных Microsoft SQL Server и Sybase:

    mssql:host=localhost;dbname=testdb
    sybase:host=localhost;dbname=testdb
    dblib:host=localhost;dbname=testdb

## Содержание

- DSN-строка подключения через драйвер PDO_DBLIB — Соединение с базами данных Microsoft SQL Server и Sybase

# Класс Pdo\Dblib

(PHP 8 >= 8.4.0)

## Введение

Этот PDO-подкласс представляет соединение с БД, которое устанавливает и обслуживает DBLib-драйвер модуля PDO.

## Обзор класса

class Pdo\Dblib extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  Начиная с PHP 8.4.0 у константы логический тип (bool); ранее использовался целочисленный тип (int).
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  Атрибут подключения управляет форматом строк для типов datetime. Если значение равно `false`, PDO_DBLIB возвращает тип datetime в виде строки в формате, в котором его возвращает SQL Server (то есть `"2017-10-27 10:22:44"`). Если значение равно `true`, PDO_DBLIB преобразует тип datetime в строку, используя пользовательский или региональный формат, указанный в файле FreeTDS locales.conf. По умолчанию атрибут установлен в `false`. Начиная с PHP 8.4.0 у константы логический тип (bool); ранее использовался целочисленный тип (int).

# PDO_FIREBIRD: драйвер модуля PDO для СУБД Firebird

## Введение

PDO_FIREBIRD — драйвер, через который PHP получает доступ к базам данных Firebird. Для этого драйвер реализует интерфейс модуля PDO.

## Установка

Для установки модуля PDO Firebird используйте опцию --with-pdo-firebird[=DIR], где `[=DIR]` указывает на директорию установки Firebird.

    $ ./configure --with-pdo-firebird

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO::FB_ATTR_DATE_FORMAT` (int)

  Псевдоним `Pdo\Firebird::ATTR_DATE_FORMAT`.

`PDO::FB_ATTR_TIME_FORMAT` (int)

  Псевдоним `Pdo\Firebird::ATTR_TIME_FORMAT`.

`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)

  Псевдоним `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# DSN-строка подключения через драйвер PDO_FIREBIRD

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_FIREBIRD — Соединение с базой Firebird

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_FIREBIRD состоит из следующих элементов:

DSN-префикс

  DSN-префикс — строка `firebird:`.

`dbname`

  Название базы данных.

`charset`

  Кодировка.

`role`

  Имя SQL-роли.

`dialect`

  Диалект базы данных; `1` или `3`. Значение по умолчанию для диалекта равно `3`. Параметр доступен с PHP 7.4.0.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_FIREBIRD с путём

Следующий пример показывает DSN-строку подключения через драйвер PDO_FIREBIRD для соединения с базой данных Firebird:

    firebird:dbname=/path/to/DATABASE.FDB

Пример #2 Пример DSN-строки подключения через драйвер PDO_FIREBIRD с путём и портом

Следующий пример показывает DSN-строку подключения через драйвер PDO_FIREBIRD с указанием пути и порта для соединения с базой данных Firebird:

    firebird:dbname=hostname/port:/path/to/DATABASE.FDB

Пример #3 Пример DSN-строки подключения через драйвер PDO_FIREBIRD для хоста localhost и пути до employee.fdb в системе Debian

Следующий пример показывает DSN-строку подключения через драйвер PDO_FIREBIRD для соединения с базой данных Firebird на локальном хосте и базой данных employee.fdb:

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

Пример #4 Пример DSN-строки подключения через драйвер PDO_FIREBIRD для соединения с БД-диалектом со значением 1

Следующий пример показывает DSN-строку подключения через драйвер PDO_FIREBIRD для соединения с базой данных Firebird test.fdb, которую создали через диалект со значением 1. Поддерживается с PHP 7.4.0.

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;charset=utf-8;dialect=1

## Содержание

- DSN-строка подключения через драйвер PDO_FIREBIRD — Соединение с базой Firebird

# Класс Pdo\Firebird

(PHP 8 >= 8.4.0)

## Введение

Этот PDO-подкласс представляет соединение с БД, которое устанавливает и обслуживает Firebird-драйвер модуля PDO.

## Обзор класса

namespace Pdo;
class Firebird extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* Методы */
public static function getApiVersion(): int
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Firebird::ATTR_DATE_FORMAT`
  Устанавливает формат даты.
`Pdo\Firebird::ATTR_TIME_FORMAT`
  Устанавливает формат времени.
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  Устанавливает формат метки времени.
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  Атрибут устанавливает уровень изоляции транзакции: `Pdo\Firebird::READ_COMMITTED`, `Pdo\Firebird::REPEATABLE_READ` или `Pdo\Firebird::SERIALIZABLE`.
`Pdo\Firebird::READ_COMMITTED`
  Флаг обозначает изоляцию транзакции по стандарту ANSI на уровне «чтение фиксированных данных» (англ. read committed). Это поведение по умолчанию.
`Pdo\Firebird::REPEATABLE_READ`
  Флаг обозначает изоляцию транзакции по стандарту ANSI на уровне «повторяющееся чтение» (англ. repeatable read). Уровень соответствует изоляции на уровне "snapshot" в СУБД Firebird.
`Pdo\Firebird::SERIALIZABLE`
  Флаг обозначает изоляцию транзакции по стандарту ANSI на уровне «упорядочиваемость» (англ. serializable). Уровень соответствует изоляции на уровне "snapshot table stability" в СУБД Firebird.
`Pdo\Firebird::WRITABLE_TRANSACTION`
  Логический атрибут, который переключает режимы доступа к транзакции `READ ONLY` и `READ WRITE`. Значение по умолчанию `true` указывает на режим `READ WRITE`.

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — Получает версию API

### Описание

public static function Pdo\Firebird::getApiVersion(): int

Возвращает версию API Firebird, определённую константой C `FB_API_VER` в ibase.h.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает API FireBird в виде целого числа (int).

## Содержание

- Pdo\Firebird::getApiVersion — Получает версию API

# PDO_IBM: драйвер модуля PDO для СУБД IBM

## Введение

PDO_IBM — драйвер, через который PHP получает доступ к базам данных IBM. Для этого драйвер реализует интерфейс модуля PDO.

## Установка

Для сборки модуля PDO_IBM на вашей системе должен быть установлен DB2 Client версии v9.1 или выше. DB2 Client можно загрузить с сайта » сайта разработки приложений IBM.

> Замечание: Обратите внимание

> DB2 Client версии v9.1 и выше поддерживает прямой доступ к DB2 для Linux, UNIX и Windows Server v8 и v9.1.

> Также DB2 Client v9.1 поддерживает доступ к серверам DB2 UDB для i5 и DB2 UDB для z/OS, используя отдельно купленный » продукт DB2 Connect.

PDO_IBM - это модуль » PECL, так что следуйте инструкции Установка PECL-модулей для установки данного модуля. Не забудьте указать команде configure местоположение заголовочных файлов DB2 Client и библиотек:

    bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]

Команда configure по умолчанию будет использовать переменную окружения DB2DIR.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки PDO_IBM
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
pdo_ibm.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Добавлена в PDO_IBM 1.5.0
pdo_ibm.i5_override_ccsid | "0" | `INI_SYSTEM` | Добавлена в PDO_IBM 1.5.0

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`pdo_ibm.i5_dbcs_alloc` int

  Опция влияет на стратегию выделения внутреннего буфера в IBM i. По умолчанию опция равна 0. Когда опция установлена, буферы выделяются с гораздо большим размером, на случай, если база данных вводит в заблуждение относительно размера символов при преобразовании между кодировками. Этот параметр потребляет в шесть раз больше памяти для буферов (для учёта максимально возможных последовательностей UTF-8), но может быть нужна, если возвращаются усечённые данные.

  - 0 — Выделяются буферы минимального размера.

  - 1 — Выделяются буферы максимального размера.

`pdo_ibm.i5_override_ccsid` int

  Идентификатор CCSID в кодировке ASCII для преобразования из восьмибитного кода EBCDIC в операционной системе IBM i. Если установить значение 1208, будет выбрана кодировка UTF-8. По умолчанию это значение равно 0, который выберет CCSID задания ASCII по умолчанию.

  Узнать больше об идентификаторах CCSIDs в операционной системе IBM i можно в «» документации IBM».

# DSN-строка подключения через драйвер PDO_IBM

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_IBM — Соединение с базой данных IBM

### Описание

В основе DSN-строки подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_IBM лежит DSN-строка CLI-интерфейса IBM. Главные компоненты DSN-строки подключения через драйвер PDO_IBM:

DSN-префикс

  DSN-префикс — строка `ibm:`.

DSN

  DSN-строку указывают тремя способами:

  - a) Настройка источника данных в файле db2cli.ini или odbc.ini

  - b) Каталогизированное имя базы данных — псевдоним базы данных в каталоге клиента БД DB2

  - c) Полная строка подключения в следующем формате: `DRIVER={IBM DB2 ODBC DRIVER};DATABASE=`database`;HOSTNAME=`hostname`;PORT=`port`;PROTOCOL=TCPIP;UID=`username`;PWD=`password`;`, где параметры представляют следующие значения:

    `database`

      Название базы данных.

    `hostname`

      Имя хоста или IP-адрес сервера баз данных.

    `port`

      Порт TCP/IP, на котором база данных слушает запросы.

    `username`

      Имя пользователя.

    `password`

      Пароль пользователя.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_IBM с файлом db2cli.ini

Следующий пример показывает DSN-строку подключения через драйвер PDO_IBM для соединения с базой DB2, которую каталогизировали как DB2_9 в файле db2cli.ini:

    $db = new PDO("ibm:DSN=DB2_9", "", "");

    [DB2_9]
    Database=testdb
    Protocol=tcpip
    Hostname=11.22.33.444
    Servicename=56789

Пример #2 Пример DSN-строки подключения через драйвер PDO_IBM со строкой соединения

Следующий пример показывает DSN-строку подключения через драйвер PDO_IBM для соединения с базой DB2 с названием `testdb`, которую записали синтаксисом соединения с CLI-интерфейса БД DB2.

    $db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
      "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

## Содержание

- DSN-строка подключения через драйвер PDO_IBM — Соединение с базой данных IBM

# PDO_INFORMIX: драйвер модуля PDO для СУБД Informix

## Введение

PDO_INFORMIX — драйвер, через который PHP получает доступ к базам данных Informix. Для этого драйвер реализует интерфейс модуля PDO.

## Установка

Для сборки модуля PDO_INFORMIX вам потребуется установленный на том же хосте Informix Client SDK 2.81 UC1 или выше. Informix Client SDK можно загрузить с » сайта поддержки IBM Informix.

PDO_INFORMIX является модулем » PECL, так что для его установки следуйте следующим инструкциям Установка PECL-модулей. Выполните команду configure указав местоположение заголовочных файлов и библиотек Informix Client SDK:

       bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]

По умолчанию команда configure будет использовать значение переменной окружения INFORMIXDIR.

## Прокручиваемые курсоры

Драйвер PDO_INFORMIX поддерживает прокручиваемые курсоры; однако такие курсоры выключены по умолчанию. Потребуется либо установить `ENABLESCROLLABLECURSORS=1` в настройках ODBC-соединения в файле odbc.ini, либо задать параметр `EnableScrollableCursors=1` в DSN-строке соединения, чтобы включить поддержку прокручиваемого курсора.

# DSN-строка подключения для драйвера PDO_INFORMIX

(No version information available, might only be in Git)

DSN-строка подключения для драйвера PDO_INFORMIX — Соединение с базой данных Informix

### Описание

В основе DSN-строки подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_INFORMIX лежит DSN-строка ODBC-драйвера Informix. Подробности конфигурирования DSN-строки подключения через ODBC-драйвер Informix приводит сайта » Informix Dynamic Server Information Center. Главные компоненты DSN-строки подключения через драйвер PDO_INFORMIX:

DSN-префикс

  DSN-префикс — строка `informix:`.

DSN-строка

  DSN-строку задают либо как источник данных, который указали в файле odbc.ini, либо в виде полной » строкой соединения.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_INFORMIX в виде источника данных файле odbc.ini

Следующий пример показывает DSN-строку подключения через драйвер для соединения с БД Informix, которую каталогизировали как Infdrv33 в файле odbc.ini:

    $db = new PDO("informix:DSN=Infdrv33", "", "");

    [ODBC Data Sources]
    Infdrv33=INFORMIX 3.3 32-BIT

    [Infdrv33]
    Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
    Description=INFORMIX 3.3 32-BIT
    Database=common_db
    LogonID=testuser
    pwd=testpass
    Servername=ids_server
    DB_LOCALE=en_US.819
    OPTIMIZEAUTOCOMMIT=1
    ENABLESCROLLABLECURSORS=1

Пример #2 Соединение с использованием полноценной строки соединения

Следующий пример показывает DSN-строку подключения через драйвер PDO_INFORMIX для соединения с БД Informix с названием `common_db`, которую записали синтаксисом строки подключения к БД Informix.

    $db = new PDO("informix:host=host.domain.com; service=9800;
        database=common_db; server=ids_server; protocol=onsoctcp;
        EnableScrollableCursors=1", "testuser", "tespass");

## Содержание

- DSN-строка подключения для драйвера PDO_INFORMIX — Соединение с базой данных Informix

# PDO_MYSQL: драйвер модуля PDO для СУБД MySQL

## Введение

PDO_MYSQL — драйвер, через который PHP получает доступ к базам данных MySQL. Для этого драйвер реализует интерфейс модуля PDO.

Драйвер PDO_MYSQL по умолчанию использует эмулированную подготовку.

MySQL 8

При запуске PHP до версии 7.1.16 или PHP с версии 7.2 до версии 7.2.4 в качестве плагина шифрования паролей по умолчанию для сервера MySQL 8 устанавливают mysql_native_password, иначе выдаётся ошибка наподобие The server requested authentication method unknown to the client [caching_sha2_password], даже когда плагин caching_sha2_password не задали.

Причина этого состоит в том, что на сервере MySQL 8 в качестве плагина по умолчанию указан caching_sha2_password, который не распознаётся старыми выпусками PHP (драйвером mysqlnd). Вместо него в файле конфигурации сервера my.cnf указывают — `default_authentication_plugin=mysql_native_password`. Плагин caching_sha2_password получил полную поддержку начиная с PHP 7.4.4. В предыдущих версиях PHP его поддерживает модуль mysql_xdevapi.

Внимание

Осторожно: MySQL-таблицы подсистемы хранения данных не поддерживают транзакции. БД MySQL сделает вид, что транзакция успешно началась, если в коде, который работает с транзакционной базой данных, указали таблицу, которая не поддерживает транзакции. Кроме того, каждый выполненный DDL-запрос будет неявно фиксировать незавершённые транзакции — то есть завершать открытые транзакции и выполнять стек незавершённых запросов.

> Замечание:

> Драйвер MySQL неправильно обрабатывает бит `PDO::PARAM_INPUT_OUTPUT` в методе PDOStatement::bindParam(); хотя такие параметры и разрешается указывать, они не обновляются (т. е. фактический вывод игнорируется).

## Установка

Обычно установочные пакеты Unix имеют в своём составе бинарные пакеты PHP. Несмотря на то, что эти бинарные пакеты обычно собраны с поддержкой модуля MySQL, может понадобиться установка библиотек модулей отдельно. Проверьте свой дистрибутив на наличие нужных библиотек через пакетный менеджер.

К примеру, на Ubuntu установка пакета `php5-mysql` устанавливает модули ext/mysql, ext/mysqli, и PDO_MYSQL. На CentOS пакет `php-mysql` также устанавливает эти три модуля.

Также вы всегда можете скомпилировать необходимые модули самостоятельно. Сборка PHP из исходных кодов позволит вам собрать именно те модули MySQL, которые вам нужны, а также выбрать нужную клиентскую библиотеку для каждого модуля.

Используйте --with-pdo-mysql[=DIR] для установки модуля PDO MySQL, где необязательный параметр `[=DIR]` указывает директорию, где установлена MySQL. По умолчанию используется библиотека mysqlnd. Более детальный разбор по выбору библиотеки можно почитать в разделе "Выбор библиотеки MySQL".

Дополнительный параметр --with-mysql-sock[=DIR] указывает расположение unix-сокета MySQL для всех MySQL модулей, включая PDO_MYSQL. Если параметр не указан, поиск производится в директориях по умолчанию.

Дополнительный параметр --with-zlib-dir[=DIR] используется как префикс пути к libz.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

Поддержка SSL включается, используя соответствующую константу `Pdo\Mysql::ATTR_SSL_*`, которая эквивалентна вызову » API MySQL-функции mysql_ssl_set() в C. К тому же SSL не может быть включён с помощью PDO::setAttribute, потому что соединение уже существует. Смотрите документацию MySQL о » подключении к MySQL с SSL.

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  Псевдоним `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  Псевдоним `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  Псевдоним `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Константа доступна с PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  Псевдоним `Pdo\Mysql::ATTR_INIT_COMMAND`
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  Псевдоним `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  Псевдоним `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  Псевдоним `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  Псевдоним `PDO::ATTR_EMULATE_PREPARES` Начиная с PHP 8.4.0 у константы логический тип (bool); ранее использовался целочисленный тип (int).
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  Псевдоним `Pdo\Mysql::ATTR_FOUND_ROWS`
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  Псевдоним `Pdo\Mysql::ATTR_IGNORE_SPACE`
`PDO::MYSQL_ATTR_COMPRESS` (int)
  Псевдоним `Pdo\Mysql::ATTR_COMPRESS`
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  Псевдоним `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
`PDO::MYSQL_ATTR_SSL_CA` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_CA`
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_CAPATH`
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_CERT`
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_CIPHER`
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_KEY`
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  Псевдоним `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` Константа доступна с PHP 7.0.18 и PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  Псевдоним `Pdo\Mysql::ATTR_MULTI_STATEMENTS`

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции конфигурации PDO_MYSQL
Имя | По умолчанию | Место изменения
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`pdo_mysql.default_socket` string

  Устанавливает сокет домена UNIX. Эту опцию необходимо указать во время компиляции, если сокет домена найден во время конфигурирования. Эта настройка только для Unix.

`pdo_mysql.debug` bool

  Разрешает отладку для PDO_MYSQL. Эта настройка доступна только, если PDO_MYSQL скомпилирован с "mysqlnd" и в режиме отладки PDO.

# DSN-строка подключения через драйвер PDO_MYSQL

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_MYSQL — Соединение с базой данных MySQL

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) для драйвера PDO_MYSQL состоит из следующих элементов:

DSN-префикс

  DSN-префикс — строка `mysql:`.

`host`

  Имя хоста сервера баз данных.

`port`

  Номер порта, который слушает сервер баз данных.

`dbname`

  Имя базы данных.

`unix_socket`

  Unix-сокет БД MySQL. Сокет нельзя указывать вместе с аргументом `host` или `port`.

`charset`

  Кодировка. Дополнительную информацию даёт раздел «Кодировки».

### Примеры

Пример #1 Примеры DSN-строк подключения через драйвер PDO_MYSQL

Следующий пример показывает DSN-строку подключения через драйвер PDO_MYSQL для соединения с базой данных MySQL:

    mysql:host=localhost;dbname=testdb

Более полные примеры:

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### Примечания

> Замечание: Только Unix:

> Соединение с сервером выполняется через сокет домена, если имя хоста установили как `"localhost"`. Файла сокета будет лежать в каталоге, в котором скомпилировали клиент libmysqlclient, если драйвер PDO_MYSQL скомпилировали с библиотекой libmysqlclient. Установка сокета по умолчанию будет доступна через директиву pdo_mysql.default_socket, если драйвер PDO_MYSQL скомпилировали с драйвером mysqlnd.

## Содержание

- DSN-строка подключения через драйвер PDO_MYSQL — Соединение с базой данных MySQL

# Класс Pdo\Mysql

(PHP 8 >= 8.4.0)

## Введение

Этот PDO-подкласс представляет соединение с БД, которое устанавливает и обслуживает MySQL-драйвер модуля PDO.

Драйвер поддерживает выделенный для диалекта СУБД MySQL парсер SQL-запросов. Парсер умеет обрабатывать следующее:

- Литералы в одинарных и двойных кавычках с механизмом экранирования как путём удвоения кавычки, так и путём добавления перед кавычкой обратного слеша
- Литералы обратных кавычек, машинописных апострофов, с механизмом экранирования путём удвоения
- Комментарии с двумя дефисами, символом решётки и комментарии в стиле языка C

## Обзор класса

class Pdo\Mysql extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* Методы */
public function getWarningCount(): int
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  По умолчанию SQL-запросы выполняются в режиме буферизации. MySQL-драйвер будет работать в режиме без буферизации, если в объекте Pdo\Mysql для атрибута установили значение `false`.

  Пример #1 Пример установки для MySQL-запросов небуферизованного режима

      <?php

      $pdo = new Pdo\Mysql("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
      $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

      $unbufferedResult = $pdo->query("SELECT Name FROM City");
      foreach ($unbufferedResult as $row) {
          echo $row['Name'] . PHP_EOL;
      }

      ?>

`Pdo\Mysql::ATTR_LOCAL_INFILE`
  Включает правило `LOAD LOCAL INFILE`.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  Разрешает ограничить для правила LOCAL DATA загрузку только из файлов в заданном каталоге.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_INIT_COMMAND`
  Команда, которая автоматически выполняется при каждом подключении к MySQL-серверу.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  Считывает параметры из файла с заданным названием, а не из файла my.cnf.

  > Замечание: Атрибут недоступен при работе через драйвер mysqlnd, потому что драйвер mysqlnd не считывает MySQL-файлы конфигурации.

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  Считывает параметры из группы параметров в файле my.cnf или в файле, который указали в атрибуте `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.

  > Замечание: Атрибут недоступен при работе через драйвер mysqlnd, потому что драйвер mysqlnd не считывает MySQL-файлы конфигурации.

`Pdo\Mysql::ATTR_COMPRESS`
  Включает сжатие данных при сетевом взаимодействии.
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  Псевдоним атрибута `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Возвращает количество строк, которые БД нашла, которые совпали, а не которые изменились.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  Разрешает использовать пробелы после названий SQL-функций. Делает названия SQL-функций зарезервированными словами.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  Устанавливает максимальный размер буфера. Значение по умолчанию равно 1 МиБ — 1024 байтам.

  > Замечание: Константа не поддерживается при компиляции с драйвером mysqlnd.

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  Со значением `false` атрибут отключает выполнение множественных запросов в методах PDO::prepare() и PDO::query().

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  Указывает файл открытого RSA-ключа для аутентификации на основе хеширования по алгоритму SHA-256.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_KEY`
  Указывает путь к файлу с SSL-ключом.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_CERT`
  Указывает путь к файлу с SSL-сертификатом.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_CA`
  Указывает путь к файлу с SSL-сертификатом удостоверяющего центра.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_CAPATH`
  Указывает путь к каталогу, который содержит доверенные CA-сертификаты в формате PEM для передачи данных по протоколу SSL.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_CIPHER`
  Список из одного или нескольких названий допустимых алгоритмов SSL-шифрования в формате, который понимает библиотека OpenSSL. Например: `DHE-RSA-AES256-SHA:AES128-SHA`

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  Разрешает отключать проверку SSL-сертификата сервера.

  > Замечание: Атрибут доступен только при работе через драйвер mysqlnd.

  > Замечание: Атрибут работает только в массиве параметров драйвера — `driver_options`, когда создают новый дескриптор базы данных.

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — Возвращает количество предупреждений из последнего выполненного запроса

### Описание

public function Pdo\Mysql::getWarningCount(): int

Метод возвращает количество предупреждений из последнего выполненного запроса

> Замечание: Сообщения с предупреждениями также возвращает следующая SQL-команда: `SHOW WARNINGS [limit row_count]`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает значение с типом int, которое представляет количество предупреждений, сгенерированных последним запросом.

### Примеры

Пример #1 Пример получения предупреждений в последнем запросе методом Pdo\Mysql::getWarningCount()

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

Результат выполнения приведённого примера:

    Warning (1365): Division by 0

## Содержание

- Pdo\Mysql::getWarningCount — Возвращает количество предупреждений из последнего выполненного запроса

# PDO_SQLSRV: драйвер модуля PDO для СУБД Microsoft SQL Server

## Введение

PDO_SQLSRV — драйвер, через который PHP получает доступ к базам данных MS SQL Server (начиная с версии SQL Server 2005) и SQL Azure. Для этого драйвер реализует интерфейс модуля PDO.

## Установка

Последняя версия драйвера доступна для скачивания по ссылке: » Загрузка SQLSRV. Исходный код драйвера размещён в » публичном репозитории.

За подробностями о системных требованиях обратитесь к разделу » Системные требования SQLSRV.

В Windows модуль PDO_SQLSRV включается путём загрузки и добавления необходимых DLL-файлов в каталог модулей PHP и добавления в файл php.ini записи, которая загрузит модуль.

В Linux и macOS модуль PDO_SQLSRV можно установить из библиотеки » PECL. Подробности смотрите в » руководстве по установке.

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO::SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Данная константа - допустимое значение для ключа TransactionIsolation SQLSRV DSN. Устанавливает уровень изоляции транзакций для соединения в значение Read Uncommitted.
`PDO::SQLSRV_TXN_READ_COMMITTED` (int)
  Данная константа - допустимое значение для ключа TransactionIsolation SQLSRV DSN. Устанавливает уровень изоляции транзакций для соединения в значение Read Committed.
`PDO::SQLSRV_TXN_REPEATABLE_READ` (int)
  Данная константа - допустимое значение для ключа TransactionIsolation SQLSRV DSN. Устанавливает уровень изоляции транзакций для соединения в значение Repeateable Read.
`PDO::SQLSRV_TXN_SNAPSHOT` (int)
  Данная константа - допустимое значение для ключа TransactionIsolation SQLSRV DSN. Устанавливает уровень изоляции транзакций для соединения в значение Snapshot.
`PDO::SQLSRV_TXN_SERIALIZABLE` (int)
  Данная константа - допустимое значение для ключа TransactionIsolation SQLSRV DSN. Устанавливает уровень изоляции транзакций для соединения в значение Serializable.
`PDO::SQLSRV_ENCODING_BINARY` (int)
  Определяет, что данные отправляются/получаются в виде потока байтов к/от сервера без выполнения преобразования кодировки или другого преобразования. Константа может быть передана в функции PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn и PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_SYSTEM` (int)
  Определяет, что данные отправляются/получаются к/от сервера в 8ми-битной кодировке локали Windows, установленной в системе. Все мультибайтовые символы и символы, не преобразуемые в данную кодировку, заменяются символом вопроса (?). Константа может быть передана в функции PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn и PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_UTF8` (int)
  Определяет, что данные отправляются/получаются к/от сервера в кодировке UTF-8. Константа может быть передана в функции PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn и PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_DEFAULT` (int)
  Определяет, что данные отправляются/получаются к/от сервера согласно значению PDO::SQLSRV_ENCODING_SYSTEM, указанному при подключении. Для подключения может использоваться кодировка, указанная при подготовке выражения. Константа может быть передана в функции PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn и PDOStatement::bindParam.
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT` (int)
  Неотрицательное целое число, отражающее время ожидания в секундах. Ноль (0) - это значение по умолчанию, означающее, что время ожидания не учитывается. Константа может быть передана в функции PDOStatement::setAttribute, PDO::setAttribute и PDO::prepare.
`PDO::SQLSRV_ATTR_DIRECT_QUERY` (int)
  Показывает, что запрос должен быть немедленно выполнен, без подготовки выражения. Константа может быть передана в функции PDO::setAttribute и PDO::prepare. За подробностями обратитесь к разделу документации » Немедленное выполнение выражений и выполнение подготовленных выражений.

# DSN-строка подключения через драйвер PDO_SQLSRV

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_SQLSRV — Подключение к базам данных MS SQL Server и SQL Azure

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) для драйвера PDO_SQLSRV состоит из следующих элементов:

DSN-префикс

  DSN-префикс — строка `sqlsrv:`.

`APP`
  Имя приложения для трассировки.
`ConnectionPooling`
  Определяет, назначается ли соединение из пула соединений: 1 или `true`, если да, 0 или `false`, если нет.
`Database`
  Название базы данных.
`Encrypt`
  Определяет, шифруются ли соединение с SQL Server: 1 или `true`, если да, 0 или `false`, если нет.
`Failover_Partner`
  Определяет сервер и экземпляр зеркала базы данных (если включили и настроили) при недоступности первичного сервера.
`LoginTimeout`
  Время ожидания подключения в секундах.
`MultipleActiveResultSets`
  Отключает или явно включает режим MARS (англ. сокр.: Multiple Active Result Sets), который поддерживает множественные активные результирующие наборы.
`QuotedId`
  Определяет, применять ли к идентификаторам в кавычках правила стандарта SQL-92: 1 или `true`, или применять устаревшие правила стандарта Transact-SQL: 0 или `false`.
`Server`
  Имя сервера базы данных.
`TraceFile`
  Путь до файла для данных трассировки.
`TraceOn`
  Определяет, включается ли для соединения, которое устанавливает драйвер, функция ODBC-трассировки: 1 или `true`, если да, 0 или `false`, если нет.
`TransactionIsolation`
  Уровень изоляции транзакций. Опция принимает следующие значения: PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT и PDO::SQLSRV_TXN_SERIALIZABLE.
`TrustServerCertificate`
  Определяет, примет ли клиент самоподписанный сертификат сервера или отклонит: 1 или `true` — доверять, 0 или `false` — отклонять.
`WSID`
  Имя компьютера для трассировки.

### Примеры

Пример #1 Примеры DSN-строки подключения через драйвер PDO_SQLSRV

Следующий пример показывает, как подключаться к конкретной базе данных MS SQL Server:

    $c = new PDO("sqlsrv:Server=localhost;Database=testdb", "UserName", "Password");

Следующий пример показывает, как подключаться к базе данных MS SQL Server на конкретном порте:

    $c = new PDO("sqlsrv:Server=localhost,1521;Database=testdb", "UserName", "Password");

Следующий пример показывает, как подключиться к базе данных SQL Azure с идентификатором сервера 12345abcde. Примечание: при соединении к БД SQL Azure через модуль PDO имя пользователя передают в формате UserName@ServerId: UserName@12345abcde.

    $c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=testdb", "UserName@12345abcde", "Password");

## Содержание

- DSN-строка подключения через драйвер PDO_SQLSRV — Подключение к базам данных MS SQL Server и SQL Azure

# PDO_OCI: драйвер модуля PDO для СУБД Oracle

## Установка

Если база данных Oracle находится на том же компьютере, что и PHP, программное обеспечение базы данных уже содержит необходимые библиотеки. Если PHP находится на другом компьютере, используйте бесплатные библиотеки » Oracle Instant Client. Подробнее смотрите в требованиях OCI8.

## PHP 8.4

Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 8.4.0

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

Для установки модуля PDO Oracle OCI используйте опцию --with-pdo-oci[=DIR], где `[=DIR]` – необязательное значение, указывающее на домашнюю директорию Oracle. По умолчанию `[=DIR]` принимает значение переменной окружения $ORACLE_HOME.

Используйте опцию --with-pdo-oci=instantclient,prefix,version Для Oracle Instant Client SDK, с указанными префиксом и версией.

    // Использование $ORACLE_HOME
    $ ./configure --with-pdo-oci

    // Использование OIC для Linux с версией 10.2.0.3 и префиксом /usr
    $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO::OCI_ATTR_ACTION` (int)

  Позволяет задать действие для сессии.

  Доступно с PHP 7.2.16 и 7.3.3

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  Позволяет задать информацию по клиенту для сессии.

  Доступно с PHP 7.2.16 и 7.3.3

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  Позволяет задать идентификатор клиента для сессии.

  Доступно с PHP 7.2.16 и 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Позволяет задать модуль для сессии.

  Доступно с PHP 7.2.16 и 7.3.3

# DSN-строка подключения через драйвер PDO_OCI

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_OCI — Соединение с базой данных Oracle

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_OCI состоит из следующих элементов:

Префикс DSN-имени

  `oci:`.

`dbname` (Oracle Instant Client)

  URI-идентификатор для клиента Oracle Instant Client записывают в формате `dbname=//hostname:port-number/database`. При соединении с базой данных, которую указали в файле tnsnames.ora, разрешается использовать только название базы данных: `dbname=database`.

`charset`

  Кодировка на стороне клиента для заданного окружения.

### Примеры

Пример #1 Примеры DSN-строк подключения через драйвер PDO_OCI

Следующие примеры показывают DSN-строки подключения через драйвер PDO_OCI для соединения с базой данных Oracle:

    // Соединение с базой данных в файле tnsnames.ora
    oci:dbname=mydb

    // Соединение через Oracle Instant Client
    oci:dbname=//localhost:1521/mydb

## Содержание

- DSN-строка подключения через драйвер PDO_OCI — Соединение с базой данных Oracle

# PDO_ODBC: драйвер модуля PDO для СУБД ODBC и DB2

## Введение

PDO_ODBC — драйвер, через который PHP получает доступ к базам данных, совместимым с драйверами ODBC (англ. сокр.: Open Database Connectivity) или библиотекой IBM DB2 Call Level Interface (DB2 CLI). Для этого драйвер реализует интерфейс модуля PDO. Драйвер PDO_ODBC поддерживает три вида драйверов баз данных:

ibm-db2

  Драйвер поддерживает доступ к серверам IBM DB2 Universal Database, Cloudscape и Apache Derby через свободный клиент DB2 express-C.

unixODBC

  Драйвер поддерживает доступ к базам данных через менеджер драйверов unixODBC и собственные ODBC-драйверы баз данных.

generic

  Драйвер предлагает опцию компиляции для менеджеров ODBC-драйверов, которые драйвер PDO_ODBC не поддерживает явно.

В операционной системе Windows библиотеку php_pdo_odbc.dll включают как модуль в файле php.ini. Библиотека связана с диспетчером драйверов Windows ODBC Driver Manager, поэтому PHP доступны подключения к любой базе данных, которую занесли в каталог как системное имя источника данных System DSN.

## Установка

PDO_ODBC на UNIX системах

1. Модуль PDO_ODBC включён в исходный код PHP. Вы можете скомпилировать модуль как статический или разделяемый, используя следующий синтаксис configure.

   ibm_db2

         ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/

     Для сборки PDO_ODBC для ibm-db2 вам потребуется предварительно установить заголовочные файлы пакета разработчика приложений DB2. Заголовочные файлы пакета разработчика приложений DB2 можно установить как с помощью установочного пакета сервера DB2, так и в составе отдельного клиента "DB2 Application Development Client", доступного для загрузки с » сайта поддержки IBM developerWorks.

     Если вы не укажете директорию установки библиотек и заголовочных файлов DB2, configure будет искать их в /home/db2inst1/sqllib.

   unixODBC

         ./configure --with-pdo-odbc=unixODBC,/usr/local

     Если вы не укажете директорию установки библиотек и заголовочных файлов unixODBC, configure будет искать их в /usr/local.
   generic

         ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO_ODBC_TYPE` (string)

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  Псевдоним `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  Псевдоним `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  Псевдоним `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  Псевдоним `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  Псевдоним `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Конфигурационные опции PDO_ODBC
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | NULL | `INI_SYSTEM` | Функция устарела и ее удалят в будущем.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`pdo_odbc.connection_pooling` string

  Нужно ли объединять соединения ODBC. Может быть `"strict"`, `"relaxed"` или `"off"` (аналогично `""`). Параметр определяет как строго менеджер соединений должен сравнивать параметры соединений для выбора, создавать новое соединение или возвращать уже существующее. По умолчанию рекомендуется использовать `strict`, что означает, что сохранённое соединение будет возвращаться только, если все параметры точно совпадают. `relaxed` приведёт к тому, что закешированное соединение будет возвращено, если параметры схожи. Это приведёт к более активному использованию кеша, но может привести к утечке информации о соединении (к примеру) между виртуальными хостами.

  Эту настройку можно изменить только в php.ini и воздействует на все процессы; все модули, загруженные в процесс и использующие те же библиотеки ODBC будут зависеть от этой настройки, включая Унифицированный модуль ODBC.

  Внимание

  Значение `relaxed` не должно использоваться на общем хостинге в целях безопасности.

  Подсказка

  Если у вас нет очень серьёзного повода использовать значение, отличное от `strict` - не меняйте его.

`pdo_odbc.db2_instance_name` string

  Если вы скомпилировали PDO_ODBC с использованием `db2`, эта опция установит значение переменной окружения DB2INSTANCE в системах Linux и UNIX, равным выбранному имени экземпляра DB2. Это позволяет PDO_ODBC определить местоположение библиотек DB2 и произвести соединение с каталогом базы данных DB2.

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

  Эта опция не работает в Windows.

# DSN-строка подключения через драйвер PDO_ODBC

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_ODBC — Соединение с базами данных ODBC или DB2

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_ODBC состоит из следующих элементов:

DSN-префикс

  DSN-префикс — строка `odbc:`. При подключении к базе данных, которую указали в каталоге менеджера ODBC-драйверов или в каталоге БД DB2, разрешается добавить к DSN-строке подключения имя из этого каталога.

DSN

  Имя базы данных, как каталогизировали в диспетчере ODBC-драйверов или каталоге DB2. Как альтернативу указывают полную строку подключения к БД ODBC, как описывает сайт » http://www.connectionstrings.com/.

`UID`

  Имя пользователя для соединения. Модуль PDO проигнорирует значение, которое передали как аргумент конструктора, если указать имя пользователя в DSN-имени.

`PWD`

  Пароль пользователя для соединения. Модуль PDO проигнорирует значение, которое передали как аргумент конструктора, если задать пароль в DSN-имени.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | При передаче пустой строки (string) в качестве аргумента password в конструкторе PDO, `pwd` не передавался в создаваемую строку подключения, такое поведение было изменено и теперь значение передается в качестве пустой строки. Передача `null` в качестве аргумента password в конструкторе PDO приводит к тому же поведению, что и раньше.
8.4.0 | Изменено поведение, чтобы игнорировать аргумент имени пользователя и аргумент пароля в конструкторе PDO отдельно, когда DSN содержит `uid` или `pwd`. Ранее, если в DSN был передан только `uid` или `pwd`, аргумент имени пользователя и аргумент пароля в конструкторе PDO игнорировались.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_ODBC для диспетчера ODBC-драйверов

Следующий пример показывает DSN-строку подключения через драйвер PDO_ODBC, чтобы установить соединение с базой данных, которую определили в диспетчере ODBC-драйверов как testdb:

    odbc:testdb

Пример #2 Пример DSN-строки подключения через драйвер PDO_ODBC для некаталогизированного соединения с БД IBM DB2

Следующий пример показывает синтаксис полной DSN-строки подключения через драйвер PDO_ODBC для соединения с базой данных IBM DB2 с именем `SAMPLE`:

    odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Пример #3 Пример DSN-строки подключения через драйвер PDO_ODBC для некаталогизированного соединения с БД Microsoft Access

Следующий пример показывает синтаксис полной DSN-строки подключения через драйвер PDO_ODBC для соединения с базой данных Microsoft Access, которая хранится в файле `C:\db.mdb`:

    odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

## Содержание

- DSN-строка подключения через драйвер PDO_ODBC — Соединение с базами данных ODBC или DB2

# Класс Pdo\Odbc

(PHP 8 >= 8.4.0)

## Введение

Этот PDO-подкласс представляет соединение с БД, которое устанавливает и обслуживает ODBC-драйвер модуля PDO.

## Обзор класса

namespace Pdo;
class Odbc extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  Параметр определяет, будет ли драйвер использовать ODBC-библиотеку курсоров. ODBC-библиотека курсоров поддерживает расширенные функции СУБД ODBC наподобие блока прокручиваемых курсоров, которые иногда остаются без реализации в драйвере. Параметр поддерживает следующие значения:

  `Pdo\Odbc::SQL_USE_IF_NEEDED`
    Использовать библиотеку курсоров ODBC, если требуется. Это значение по умолчанию.
  `Pdo\Odbc::SQL_USE_DRIVER`
    Не использовать библиотеку курсоров ODBC.
  `Pdo\Odbc::SQL_USE_ODBC`
    Использовать библиотеку курсоров ODBC.
`Pdo\Odbc::ATTR_ASSUME_UTF8`
  Только для систем Windows. Со значением `true` символьные данные в кодировке UTF-16 — `CHAR`, `VARCHAR` и `LONGVARCHAR` — преобразовываются в кодировку UTF-8, когда данные считываются из базы данных или записываются в базу. Со значением `false`, значение по умолчанию, кодировку символов преобразовывает драйвер.

# PDO_PGSQL: драйвер модуля PDO для СУБД PostgreSQL

## Введение

PDO_PGSQL — драйвер, через который PHP получает доступ к базам данных PostgreSQL. Для этого драйвер реализует интерфейс модуля PDO.

## Типы ресурсов

Модуль определяет потоковый ресурс, который возвращает метод PDO::pgsqlLOBOpen().

## Установка

Для установки модуля PDO PostgreSQL используйте опцию --with-pdo-pgsql[=DIR], где `[=DIR]` - необязательное значение, которое указывает на директорию установки базы PostgreSQL или путь до команды pg_config.

    $ ./configure --with-pdo-pgsql

## Предопределённые константы

Драйвер определяет следующие константы и открывает доступ к ним только тогда, когда PHP собрали с поддержкой этого модуля, или модуль динамически загрузили при выполнении кода. Константы, которые зависят от драйвера, разрешается использовать только совместно с драйвером. Атрибуты одного драйвера с другим драйвером ведут себя неожиданно. Чтобы проверить название драйвера, которое содержит атрибут `PDO::ATTR_DRIVER_NAME`, вызывают метод PDO::getAttribute(), если код запускается с несколькими драйверами.

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  Псевдоним `Pdo\Pgsql::ATTR_DISABLE_PREPARES`.

## Общие замечания

> Замечание:

> Поля `bytea` возвращаются как потоки.

# DSN-строка подключения через драйвер PDO_PGSQL

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_PGSQL — Соединение с базой данных PostgreSQL

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_PGSQL состоит из следующих элементов, разделённых пробелом или точкой с запятой:

Префикс DSN-имени

  `pgsql:`.

`host`

  Имя хоста, на котором лежит база данных.

`port`

  Порт, на котором эта база данных ждёт подключения.

`dbname`

  Имя базы данных.

`user`

  Имя пользователя для соединения. Модуль PDO проигнорирует значение, которое передали как аргумент конструктора, если указать имя пользователя в DSN-имени.

`password`

  Пароль пользователя для соединения. Модуль PDO проигнорирует значение, которое передали как аргумент конструктора, если задать пароль в DSN-имени.

`sslmode`

  SSL-режим. Значения, которые поддерживает параметр и описание режимов перечисляет » документация к БД PostgreSQL.

> Замечание: Каждая точка с запятой в строке DSN-строки подключения заменяется пробелами, потому что БД PostgreSQL ожидает такой формат. Поэтому точки с запятой в компонентах наподобие `password` или `dbname`) не поддерживаются.

### Примеры

Пример #1 Примеры DSN-строки подключения через драйвер PDO_PGSQL

Следующий пример показывает DSN-строку для подключения к базе PostgreSQL:

    pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

Следующий пример показывает DSN-строку подключения через драйвер PDO_PGSQL для соединения с базой данных PostgreSQL через Unix-сокет /tmp/.s.PGSQL.5432:

    pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Псевдоним Pdo\Pgsql::copyFromArray()

### Описание

public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Псевдоним метода Pdo\Pgsql::copyFromArray().

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Псевдоним Pdo\Pgsql::copyFromFile()

### Описание

public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Псевдоним метода Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Псевдоним Pdo\Pgsql::copyToArray()

### Описание

public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Псевдоним метода Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Псевдоним Pdo\Pgsql::copyToFile()

### Описание

public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Псевдоним метода Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Псевдоним Pdo\Pgsql::getNotify()

### Описание

public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

Псевдоним метода Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Псевдоним Pdo\Pgsql::getPid()

### Описание

public function PDO::pgsqlGetPid(): int

Псевдоним метода Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Псевдоним Pdo\Pgsql::lobCreate()

### Описание

public function PDO::pgsqlLOBCreate(): string

Псевдоним метода Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Псевдоним Pdo\Pgsql::lobOpen()

### Описание

public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

Псевдоним метода Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Псевдоним Pdo\Pgsql::lobUnlink()

### Описание

public function PDO::pgsqlLOBUnlink(string `$oid`): bool

Псевдоним метода Pdo\Pgsql::lobUnlink().

## Содержание

- DSN-строка подключения через драйвер PDO_PGSQL — Соединение с базой данных PostgreSQL
- PDO::pgsqlCopyFromArray — Псевдоним Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — Псевдоним Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — Псевдоним Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — Псевдоним Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — Псевдоним Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — Псевдоним Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — Псевдоним Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — Псевдоним Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — Псевдоним Pdo\Pgsql::lobUnlink

# Класс Pdo\Pgsql

(PHP 8 >= 8.4.0)

## Введение

Этот PDO-подкласс представляет соединение с БД, которое устанавливает и обслуживает PostgreSQL-драйвер модуля PDO.

Драйвер поддерживает выделенный для диалекта СУБД PostgreSQL парсер SQL-запросов. Парсер умеет обрабатывать следующее:

- Литералы в одинарных и двойных кавычках с механизмом экранирования путём удвоения кавычки
- «Управляющие последовательности» в строковых литералах в стиле языка C
- Строковые литералы, которые обернули символами доллара
- Комментарии с двумя дефисами и комментарии в стиле языка C, без вложения
- Поддержка символов `??` как экранирующей последовательности для оператора `?`

## Обзор класса

namespace Pdo;
class Pgsql extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* Методы */
public function copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  Отправлять запрос и параметры на сервер вместе в одном вызове, чтобы не создавать именованный подготовленный запрос отдельно. Это сокращает время ожидания при отправке однократного запроса, поскольку не требуется отправлять лишний запрос и ждать ответ сервера.
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  Возвращать объём памяти в байтах, которая выделилась для конкретного экземпляра класса PDOStatement с результатом запроса, или `null`, если результатов пока нет, поскольку запрос ещё не выполнялся.
`Pdo\Pgsql::TRANSACTION_IDLE`
`Pdo\Pgsql::TRANSACTION_ACTIVE`
`Pdo\Pgsql::TRANSACTION_INTRANS`
`Pdo\Pgsql::TRANSACTION_INERROR`
`Pdo\Pgsql::TRANSACTION_UNKNOWN`

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — Копирует данные из массива PHP в таблицу

### Описание

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Копирует данные из массива `rows` в таблицу `tableName`, используя `separator` в качестве разделителя полей и список `fields`.

### Список параметров

`tableName`
  Строка, содержащая имя таблицы.
`rows`
  Индексированный массив (array) строк (string) с полями, разделёнными `separator`.
`separator`
  Разделитель, используемый для разделения полей в записи массива `rows`.
`nullAs`
  Как интерпретировать SQL-значения `NULL`.
`fields`
  Список полей для добавления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- Pdo\Pgsql::copyToArray() - Копирует данные из таблицы базы данных в массив PHP
- Pdo\Pgsql::copyFromFile() - Копирует данные из файла в таблицу
- Pdo\Pgsql::copyToFile() - Копирует данные из таблицы в файл

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — Копирует данные из файла в таблицу

### Описание

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Копирует данные из файла, указанного в параметре `filename`, в таблицу `tableName`, используя разделитель полей `separator` и список `fields`.

### Список параметров

`tableName`
  Строка, содержащая имя таблицы.
`filename`
  Имя файла, содержащего данные для импорта.
`separator`
  Разделитель, используемый для разделения полей в записи массива `rows`.
`nullAs`
  Как интерпретировать SQL-значения `NULL`.
`fields`
  Список полей для добавления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- Pdo\Pgsql::copyToFile() - Копирует данные из таблицы в файл
- Pdo\Pgsql::copyFromArray() - Копирует данные из массива PHP в таблицу
- Pdo\Pgsql::copyToArray() - Копирует данные из таблицы базы данных в массив PHP

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — Копирует данные из таблицы базы данных в массив PHP

### Описание

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Копирует данные из таблицы `tableName` в массив, используя разделитель полей `separator` и список `fields`.

### Список параметров

`tableName`
  Строка, содержащая имя таблицы.
`separator`
  Разделитель, используемый для разделения полей в записи массива `rows`.
`nullAs`
  Как интерпретировать SQL-значения `NULL`.
`fields`
  Список полей для экспорта.

### Возвращаемые значения

Возвращает массив строк или `false`, если возникла ошибка.

### Смотрите также

- Pdo\Pgsql::copyFromArray() - Копирует данные из массива PHP в таблицу
- Pdo\Pgsql::copyFromFile() - Копирует данные из файла в таблицу
- Pdo\Pgsql::copyToFile() - Копирует данные из таблицы в файл

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — Копирует данные из таблицы в файл

### Описание

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Копирует данные из таблицы в файл, указанный в параметре `filename`, используя разделитель полей `separator` и список `fields`.

### Список параметров

`tableName`
  Строка, содержащая имя таблицы.
`filename`
  Имя файла для экспорта данных.
`separator`
  Разделитель, используемый для разделения полей в записи массива `rows`.
`nullAs`
  Как интерпретировать SQL-значения `NULL`.
`fields`
  Список полей для добавления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- Pdo\Pgsql::copyFromFile() - Копирует данные из файла в таблицу
- Pdo\Pgsql::copyFromArray() - Копирует данные из массива PHP в таблицу
- Pdo\Pgsql::copyToArray() - Копирует данные из таблицы базы данных в массив PHP

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — Экранирует строку для использования в качестве SQL-идентификатора

### Описание

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

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

### Список параметров

`input`
  Строка (string), содержащая текст, который должен быть экранирован.

### Возвращаемые значения

Строка (string), содержащая экранированные данные.

### Примеры

Пример #1 Пример использования метода Pdo\Pgsql::escapeIdentifier()

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
      "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

Вывод приведённого примера будет похож на:

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### Смотрите также

- PDO::quote() - Форматирует строку в SQL-литерал

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Получает асинхронное уведомление

### Описание

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Возвращает набор результатов, представляющий ожидающее асинхронное уведомление.

### Список параметров

`fetchMode`

  Формат, в котором должен быть возвращён набор результатов, одна из следующих констант:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  Длительность ожидания ответа, в миллисекундах.

### Возвращаемые значения

Если одно или несколько уведомлений находятся на рассмотрении, возвращает одну строку с полями `message` и `pid`, в противном случае возвращает значение `false`.

### Ошибки

Если значение параметра `fetchMode` не является одной из допустимых констант `PDO::FETCH_*`, выбрасывается ошибка ValueError.

Если значение параметра `timeoutMilliseconds` меньше `0`, выбрасывается ошибка ValueError.

Если значение параметра `timeoutMilliseconds` больше значения, которое может содержаться в 32-битном целом числе со знаком, выбрасывается ошибка уровня `E_WARNING`, а значением параметра будет максимальное значение 32-битного целого числа со знаком.

### Смотрите также

- PDO::query() - Подготавливает и выполняет выражение SQL без заполнителей
- PDOStatement::fetch() - Извлекает следующую строку из результирующего набора
- PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Получает PID процесса, обрабатывающего соединение

### Описание

public function Pdo\Pgsql::getPid(): int

Возвращает PID процесса, обрабатывающего данное соединение. Обратите внимание, что PID принадлежит процессу, выполняющемуся на хосте сервера базы данных, а не на локальном хосте.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает PID в виде целого числа (int).

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Создает новый большой объект (LOB)

### Описание

public function Pdo\Pgsql::lobCreate(): string|false

Метод Pdo\Pgsql::lobCreate() создаёт большой объект и возвращает OID, который на него ссылается. Его можно открыть для чтения или записи данных с помощью метода Pdo\Pgsql::lobOpen().

OID может храниться в столбцах типа OID и использоваться для ссылок на большой объект, не вызывая произвольного роста строки. Большой объект будет храниться в базе данных до тех пор, пока его не удалят вызовом метода Pdo\Pgsql::lobUnlink().

Большие объекты громоздки в использовании. Действительно, необходимо, чтобы метод Pdo\Pgsql::lobUnlink() вызывался до удаления последней строки, ссылающейся на OID во всей базе данных; в противном случае большой объект без ссылок будут оставаться на сервере неопределенное время. Кроме того, большие объекты не имеют контроля доступа. Альтернативой является тип столбца bytea, размер которого может достигать 1 ГБ, и этот тип столбца прозрачно управляет хранением для оптимального размера строки.

> Замечание: Функция и все манипуляции с большим объектом должны вызываться и выполняться в рамках транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает OID только что созданного большого объекта в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования метода Pdo\Pgsql::lobCreate()

В примере создаётся новый большой объект и в него копируется содержимое файла. Затем OID сохраняется в таблице.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($oid, 'w');
    $local = fopen($filename, 'rb');
    stream_copy_to_stream($local, $stream);
    $local = null;
    $stream = null;
    $stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
    $stmt->execute([$some_id, $oid]);
    $db->commit();
    ?>

### Смотрите также

- Pdo\Pgsql::lobOpen() - Открывает поток для существующего большого объекта
- Pdo\Pgsql::lobUnlink() - Удаляет большой объект
- pg_lo_create() - Создаёт большой объект
- pg_lo_open() - Открывает большой объект базы данных

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Открывает поток для существующего большого объекта

### Описание

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Метод Pdo\Pgsql::lobOpen() открывает поток для доступа к данным, на которые ссылается `oid`. Для работы с содержимым потока можно использовать все обычные функции файловой системы, такие как функция fread(), fwrite() или fgets().

> Замечание: Функция и все манипуляции с большим объектом должны вызываться и выполняться в рамках транзакции.

### Список параметров

`oid`
  Идентификатор большого объекта.
`mode`
  Если указано значение `r`, поток открывается для чтения. Если указано значение `w`, поток открывается для записи.

### Возвращаемые значения

Метод возвращает ресурс потока в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования метода Pdo\Pgsql::lobOpen()

Продолжая пример метода Pdo\Pgsql::lobCreate(), этот фрагмент кода извлекает большой объект из базы данных и выводит его в браузер.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $stmt = $db->prepare("SELECT oid FROM BLOBS WHERE ident = ?");
    $stmt->execute(array($some_id));
    $stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
    $stmt->fetch(PDO::FETCH_BOUND);
    $stream = $db->pgsqlLOBOpen($oid, 'r');
    header("Content-type: application/octet-stream");
    fpassthru($stream);
    ?>

### Смотрите также

- Pdo\Pgsql::lobCreate() - Создает новый большой объект (LOB)
- Pdo\Pgsql::lobUnlink() - Удаляет большой объект
- pg_lo_create() - Создаёт большой объект
- pg_lo_open() - Открывает большой объект базы данных

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Удаляет большой объект

### Описание

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Метод удаляет большой объект из базы данных по идентификатору OID.

> Замечание: Функция и все манипуляции с большим объектом должны вызываться и выполняться в рамках транзакции.

### Список параметров

`oid`
  Идентификатор большого объекта.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример удаления большого объекта методом Pdo\Pgsql::lobUnlink()

Пример удаления связи большого объекта с базой данных перед удалением строки, которая ссылается на объект из таблицы "blobs" — это та же таблица, с которой взаимодействуют соединения в примерах кода с методами Pdo\Pgsql::lobCreate() и Pdo\Pgsql::lobOpen().

    <?php

    $db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $db->pgsqlLOBUnlink($oid);
    $stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
    $stmt->execute(array($some_id));
    $db->commit();

    ?>

### Смотрите также

- Pdo\Pgsql::lobCreate() - Создает новый большой объект (LOB)
- Pdo\Pgsql::lobOpen() - Открывает поток для существующего большого объекта
- pg_lo_create() - Создаёт большой объект
- pg_lo_open() - Открывает большой объект базы данных

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Устанавливает callback-функцию для обработки уведомлений и предупреждений бэкенда

### Описание

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

Метод устанавливает callback-функцию для обработки сообщений с уведомлениями и предупреждениями, которые генерирует бэкенд. К этим сообщениям относятся уведомления и предупреждения, которые выдаёт сама СУБД PostgreSQL, и сообщения, которые выдают пользовательские SQL-функции через команду `RAISE`. Обратите внимание, что фактическое получение сообщений зависит от параметра `client_min_messages` в настройках бэкенда.

### Список параметров

`callback`
  При передаче значения `null` обработчик сбрасывается в состояние по умолчанию.

  В остальных случаях обработчиком будет callback-функция со следующей сигнатурой:

  function handler(string `$message`): void
  `message`
    Сообщение, которое сгенерировал бэкенд.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример установки функции обратного вызова для обработки уведомлений и предупреждений бэкенда методом Pdo\Pgsql::setNoticeCallback()

    <?php

    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');

    ?>

Вывод приведённого примера будет похож на:

    NOTICE:  truncate cascades to table "child"

## Содержание

- Pdo\Pgsql::copyFromArray — Копирует данные из массива PHP в таблицу
- Pdo\Pgsql::copyFromFile — Копирует данные из файла в таблицу
- Pdo\Pgsql::copyToArray — Копирует данные из таблицы базы данных в массив PHP
- Pdo\Pgsql::copyToFile — Копирует данные из таблицы в файл
- Pdo\Pgsql::escapeIdentifier — Экранирует строку для использования в качестве SQL-идентификатора
- Pdo\Pgsql::getNotify — Получает асинхронное уведомление
- Pdo\Pgsql::getPid — Получает PID процесса, обрабатывающего соединение
- Pdo\Pgsql::lobCreate — Создает новый большой объект (LOB)
- Pdo\Pgsql::lobOpen — Открывает поток для существующего большого объекта
- Pdo\Pgsql::lobUnlink — Удаляет большой объект
- Pdo\Pgsql::setNoticeCallback — Устанавливает callback-функцию для обработки уведомлений и предупреждений бэкенда

# PDO_SQLITE: драйвер модуля PDO для СУБД SQLite

## Введение

PDO_SQLITE — драйвер, через который PHP получает доступ к базам данных SQLite 3. Для этого драйвер реализует интерфейс модуля PDO.

> Замечание:

> Кроме потоков с флагом `PDO::PARAM_LOB` драйвер PDO_SQLITE разрешает использовать строки.

## Установка

Драйвер PDO_SQLITE PDO доступен по умолчанию. Для отключения используйте --without-pdo-sqlite[=DIR], где `[=DIR]` - директория, куда установлен sqlite. Начиная с PHP 7.4.0 требуется библиотека » libsqlite версии 3.5.0 или новее. Ранее встроенный из коробки libsqlite мог использовался вместо этого, и был значением по умолчанию, если опция `[=DIR]` не задана.

> Замечание: Дополнительная настройка на Windows с PHP 7.4.0

> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libsqlite3.dll.

# DSN-строка подключения через драйвер PDO_SQLITE

(No version information available, might only be in Git)

DSN-строка подключения через драйвер PDO_SQLITE — Соединение с базой данных SQLite

### Описание

DSN-строка подключения (англ. сокр.: Data Source Name — имя источника данных) через драйвер PDO_SQLITE состоит из следующих элементов:

DSN-префикс (SQLite 3)

  DSN-префикс — строка `sqlite:`.

  - Для доступа к базе данных на диске потребуется добавить после DSN-префикса абсолютный путь.

  - Для создания базы данных в памяти потребуется добавить после DSN-префикса `:memory:`.

  - Драйвер создаст временную базу данных, которую удалит при закрытии соединения, если DSN-строка подключения состоит только из DSN-префикса.

### Примеры

Пример #1 Пример DSN-строки подключения через драйвер PDO_SQLITE

Следующий пример показывает DSN-строку подключения через драйвер PDO_SQLITE для соединения с БД SQLite:

    sqlite:/opt/databases/mydb.sq3
    sqlite::memory:
    sqlite:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Псевдоним Pdo\Sqlite::createAggregate()

### Описание

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Псевдоним метода Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Псевдоним Pdo\Sqlite::createCollation()

### Описание

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

Псевдоним метода Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Псевдоним Pdo\Sqlite::createFunction()

### Описание

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Псевдоним метода Pdo\Sqlite::createFunction().

### Список изменений

Версия | Описание
--- | ---
7.1.4 | Добавлен параметр `flags`.

## Содержание

- DSN-строка подключения через драйвер PDO_SQLITE — Соединение с базой данных SQLite
- PDO::sqliteCreateAggregate — Псевдоним Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — Псевдоним Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — Псевдоним Pdo\Sqlite::createFunction

# Класс Pdo\Sqlite

(PHP 8 >= 8.4.0)

## Введение

Подкласс PDO, представляющий соединение с использованием драйвера SQLite PDO.

Драйвер поддерживает специальный парсер SQL-запросов для диалекта SQLite. Он может обрабатывать следующие запросы:

- Литералы с одинарными, двойными и обратными кавычками, с удвоением в качестве механизма экранирования.
- Квадратные скобки в кавычках для идентификаторов.
- Два тире и комментарии в стиле Си (не вложенные).

## Обзор класса

class Pdo\Sqlite extends PDO {
/* Наследуемые константы */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Константы */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* Методы */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* Наследуемые методы */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Предопределённые константы

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — Регистрирует агрегирующую пользовательскую функцию для использования в SQL-выражениях

### Описание

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Метод похож на Pdo\Sqlite::createFunction(), за исключением того, что он регистрирует функции, которые могут быть использованы для вычисления результата, агрегированного по всем строкам запроса.

Ключевое отличие метода от Pdo\Sqlite::createFunction() заключается в том, что для управления агрегатом требуется две функции.

Подсказка

С помощью метода можно переопределить собственные SQL-функции.

### Список параметров

`name`
  Имя функции, используемой в SQL-выражениях.
`step`
  Callback-функция, вызываемая для каждой строки набора результатов. Callback-функция должна накапливать результат и сохранять его в контексте агрегации.

  Сигнатура функции должна быть определена как:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    `null` для первой строки; в последующих строках это будет значение, которое ранее было возвращено функцией step; это необходимо использовать для поддержания агрегатного состояния.
  `rownumber`
    Номер текущей строки.
  `value`
    Первый аргумент, передаваемый агрегату.
  `values`
    Дополнительные аргументы, передаваемые агрегату.
  Возвращаемое значение функции будет использовано в качестве аргумента `context` при следующем вызове функций step или finalize.
`finalize`
  Callback-функция для агрегации «пошаговых» данных из каждой строки. После обработки всех строк будет вызвана функция, которая должна получить данные из контекста агрегации и вернуть результат. Callback-функция должна возвращать тип, понятный SQLite (например, скалярный тип).

  Сигнатура функции должна быть определена как:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Хранит значение, возвращённое при последнем вызове функции step.

  `rowcount`

    Указывает количество строк, по которым было выполнено агрегирование.

  Возвращаемое значение функции будет использоваться в качестве возвращаемого значения для агрегата.
`numArgs`
  Подсказка парсеру SQLite, если callback-функция принимает заданное количество аргументов.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования метода Pdo\Sqlite::createAggregate()

В этом примере создаётся пользовательская агрегатная функция с именем `max_length`, которую можно использовать в SQL-запросах.

В этом примере создаётся агрегирующая функция с именем `max_length`, которая будет вычислять длину самой длинной строки в одном из столбцов таблицы. Для каждой строки вызывается функция `max_len_step`, которой передаётся параметр `$context`. Параметр context, как и любая другая переменная PHP, может содержать массив (array) или даже объект (object). В этом примере он используется для хранения максимальной длины, которую уже была обработана; если $string длиннее, чем текущий максимум, контекст обновляется, чтобы содержать новую максимальную длину.

После обработки всех строк, SQLite вызывает функцию `max_len_finalize` для определения агрегированного результата. Можно выполнить какое-либо вычисление на основе данных в `$context`. В данном примере результат вычислялся по мере выполнения запроса, поэтому значение контекста может быть возвращено напрямую.

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->execute(array($str));
    }
    $insert = null;

    function max_len_step($context, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

Подсказка

НЕ рекомендуется хранить копию значений в контексте и затем обрабатывать их в конце, так как SQLite будет использовать много памяти для обработки запроса – просто подумайте, сколько памяти вам понадобится, если в памяти будет храниться миллион строк, каждая из которых будет содержать строку длиной 32 байта.

### Смотрите также

- Pdo\Sqlite::createFunction() - Регистрирует пользовательскую функцию для вызова в SQL-инструкциях
- Pdo\Sqlite::createCollation() - Регистрирует определяемую пользователем функцию для использования в качестве функции сопоставления в SQL-выражениях
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — Регистрирует определяемую пользователем функцию для использования в качестве функции сопоставления в SQL-выражениях

### Описание

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

Метод похож на Pdo\Sqlite::createFunction(), за исключением того, что он регистрирует функции, которые используются для сортировки строк.

### Список параметров

`name`
  Имя создаваемой или переопределяемой SQL-функции сортировки.
`callback`
  Callback-функция, определяющая поведение сортировки. Должна принимать две строки (string) и возвращать значение `-1`, `0` или `1`, если первая строка сортируется до, сортируется идентично или сортируется после второй строки соответственно. Встроенной функцией, которая ведёт себя подобным образом, является strcmp().

  Сигнатура функции должна быть определена как:

  function collation(string `$string1`, string `$string2`): int

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования метода Pdo\Sqlite::createCollation()

    <?php
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
      echo $row['col1'] . "\n";
    }
    echo "\n";
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
      echo $row['col1'] . "\n";
    }
    ?>

Результат выполнения приведённого примера:

    a1
    a10
    a2

    a1
    a2
    a10

### Смотрите также

- Pdo\Sqlite::createFunction() - Регистрирует пользовательскую функцию для вызова в SQL-инструкциях
- Pdo\Sqlite::createAggregate() - Регистрирует агрегирующую пользовательскую функцию для использования в SQL-выражениях
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Регистрирует пользовательскую функцию для вызова в SQL-инструкциях

### Описание

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Метод регистрирует пользовательскую PHP-функцию в SQLite для вызова в SQL-инструкциях. Пользовательскую функцию вызывают в триггерах или SQL-запросах наподобие `SELECT`, `UPDATE` или других предложениях с поддержкой вызова функций.

Подсказка

При совпадении названий метод переопределит встроенную SQL-функцию.

### Список параметров

`function_name`
  Название функции, которое указывается в SQL-инструкции.
`callback`
  Callback-функция для обработки пользовательской SQL-функции.

  > Замечание: SQLite поддерживает только значения скалярных типов, поэтому возврат из callback-функций значений других типов вызовет ошибку.

  Корректная сигнатура функции обратного вызова:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Первый аргумент SQL-функции.

  `values`

    Дополнительные аргументы SQL-функции.

`num_args`
  Количество аргументов, которое принимает SQL-функция. При установке значения `-1` SQL-функция примет произвольное количество аргументов.
`flags`
  Битовая маска флагов. Метод пока поддерживает только флаг `Pdo\Sqlite::DETERMINISTIC`, который указывает, что функция возвращает один и тот же результат при одинаковых входных данных в рамках одной SQL-инструкции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример регистрации пользовательской SQL-функции методом Pdo\Sqlite::createFunction()

В примере функция вычисляет дайджест строки по алгоритму SHA256, а затем инвертирует хеш. При выполнении SQL-инструкции БД возвращает результат, в котором пользовательская функция преобразовала каждое название файла. Данные, которые возвращаются в переменной $rows, содержат результат обработки.

Преимущество подхода состоит в автоматической обработке запроса пользовательской функцией вместо постобработки результата в цикле `foreach`.

    <?php

    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();

### Смотрите также

- Pdo\Sqlite::createAggregate() - Регистрирует агрегирующую пользовательскую функцию для использования в SQL-выражениях
- Pdo\Sqlite::createCollation() - Регистрирует определяемую пользователем функцию для использования в качестве функции сопоставления в SQL-выражениях
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Описание

### Описание

public function Pdo\Sqlite::loadExtension(string `$name`): void
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

Описание.

### Список параметров

`name`
  Описание.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

Описание условий, при которых метод выдаёт ошибки уровня `E_*` и (или) выбрасывает исключения подтипа Exception.

### Примеры

Пример #1 Пример работы метода Pdo\Sqlite::loadExtension()

Описание примера.

    <?php

    echo "Пример кода";

    ?>

Результат выполнения приведённого примера:

    Пример кода

### Примечания

> Замечание: Прочие заметки.

### Смотрите также

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Описание

### Описание

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

Описание.

### Список параметров

`table`
  Описание.
`column`
  Описание.
`rowid`
  Описание.
`dbname`
  Описание.
`flags`
  Константа семейства `Pdo\Sqlite::OPEN_*`

### Возвращаемые значения

Description.

### Ошибки

Описание условий, при которых метод выдаёт ошибки уровня `E_*` и (или) выбрасывает исключения подтипа Exception.

### Примеры

Пример #1 Пример работы метода Pdo\Sqlite::openBlob()

Описание примера.

    <?php

    echo "Пример кода";

    ?>

Результат выполнения приведённого примера:

    Пример кода

### Примечания

> Замечание: Прочие заметки.

### Смотрите также

- ClassName::otherMethodName()
- some_function()

## Содержание

- Pdo\Sqlite::createAggregate — Регистрирует агрегирующую пользовательскую функцию для использования в SQL-выражениях
- Pdo\Sqlite::createCollation — Регистрирует определяемую пользователем функцию для использования в качестве функции сопоставления в SQL-выражениях
- Pdo\Sqlite::createFunction — Регистрирует пользовательскую функцию для вызова в SQL-инструкциях
- Pdo\Sqlite::loadExtension — Описание
- Pdo\Sqlite::openBlob — Описание

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
  - Режимы выборки
- Подключения и управление подключениями
- Транзакции и автоматическая фиксация изменений
- Подготовленные запросы и хранимые процедуры
- Ошибки и их обработка
- Большие объекты
- PDO — Класс PDO
  - PDO::beginTransaction — Инициализация транзакции
  - PDO::commit — Фиксирует транзакцию
  - PDO::connect — Подключается к базе данных и возвращает объект подкласса PDO для драйвера, который поддерживает заданную БД
  - PDO::__construct — Создаёт объект PDO, который предоставляет соединение с базой данных
  - PDO::errorCode — Возвращает код SQLSTATE результата последней операции с базой данных
  - PDO::errorInfo — Получает расширенную информацию об ошибке, произошедшей в ходе последнего обращения к базе данных
  - PDO::exec — Выполняет SQL-запрос и возвращает количество затронутых строк
  - PDO::getAttribute — Получает атрибут соединения с базой данных
  - PDO::getAvailableDrivers — Возвращает массив доступных драйверов PDO
  - PDO::inTransaction — Проверяет, начата ли транзакция
  - PDO::lastInsertId — Возвращает ID последней вставленной строки или значение последовательности
  - PDO::prepare — Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
  - PDO::query — Подготавливает и выполняет выражение SQL без заполнителей
  - PDO::quote — Форматирует строку в SQL-литерал
  - PDO::rollBack — Откат транзакции
  - PDO::setAttribute — Устанавливает атрибут
- PDOStatement — Класс PDOStatement
  - PDOStatement::bindColumn — Связывает столбец с переменной PHP
  - PDOStatement::bindParam — Привязывает параметр запроса к переменной
  - PDOStatement::bindValue — Связывает параметр с заданным значением
  - PDOStatement::closeCursor — Закрывает курсор, переводя запрос в состояние готовности к повторному запуску
  - PDOStatement::columnCount — Возвращает количество столбцов в результирующем наборе
  - PDOStatement::debugDumpParams — Вывод информации о подготовленной SQL-команде в целях отладки
  - PDOStatement::errorCode — Получает код SQLSTATE, связанный с последней операцией в объекте PDOStatement
  - PDOStatement::errorInfo — Получение расширенной информации об ошибке, произошедшей в результате работы объекта PDOStatement
  - PDOStatement::execute — Выполняет подготовленный запрос
  - PDOStatement::fetch — Извлекает следующую строку из результирующего набора
  - PDOStatement::fetchAll — Выбирает строки, которые остались в наборе результатов
  - PDOStatement::fetchColumn — Возвращает данные одного столбца следующей строки результирующего набора
  - PDOStatement::fetchObject — Извлекает следующую строку и возвращает её в виде объекта
  - PDOStatement::getAttribute — Получение значения атрибута запроса PDOStatement
  - PDOStatement::getColumnMeta — Возвращает метаданные столбца в результирующей таблице
  - PDOStatement::getIterator — Получает итератор набора результатов
  - PDOStatement::nextRowset — Переход к следующему набору строк в результате запроса
  - PDOStatement::rowCount — Возвращает количество строк, которое затронул последний SQL-запрос
  - PDOStatement::setAttribute — Устанавливает атрибут объекту PDOStatement
  - PDOStatement::setFetchMode — Устанавливает режим выборки по умолчанию для объекта запроса
- PDORow — Класс PDORow
- PDOException — Исключение PDOException
- Драйверы модуля PDO
  - PDO-драйвер СУБД CUBRID — PDO_CUBRID: драйвер модуля PDO для СУБД CUBRID
  - PDO-драйвер СУБД MS SQL Server — PDO_DBLIB: драйвер модуля PDO для СУБД Microsoft SQL Server и Sybase
  - Pdo\Dblib — Класс Pdo\Dblib
  - PDO-драйвер СУБД Firebird — PDO_FIREBIRD: драйвер модуля PDO для СУБД Firebird
  - Pdo\Firebird — Класс Pdo\Firebird
  - PDO-драйвер СУБД IBM — PDO_IBM: драйвер модуля PDO для СУБД IBM
  - PDO-драйвер СУБД Informix — PDO_INFORMIX: драйвер модуля PDO для СУБД Informix
  - PDO-драйвер СУБД MySQL — PDO_MYSQL: драйвер модуля PDO для СУБД MySQL
  - Pdo\Mysql — Класс Pdo\Mysql
  - PDO-драйвер СУБД MS SQL Server — PDO_SQLSRV: драйвер модуля PDO для СУБД Microsoft SQL Server
  - PDO-драйвер СУБД Oracle — PDO_OCI: драйвер модуля PDO для СУБД Oracle
  - PDO-драйвер СУБД ODBC и DB2 — PDO_ODBC: драйвер модуля PDO для СУБД ODBC и DB2
  - Pdo\Odbc — Класс Pdo\Odbc
  - PDO-драйвер СУБД PostgreSQL — PDO_PGSQL: драйвер модуля PDO для СУБД PostgreSQL
  - Pdo\Pgsql — Класс Pdo\Pgsql
  - PDO-драйвер СУБД SQLite — PDO_SQLITE: драйвер модуля PDO для СУБД SQLite
  - Pdo\Sqlite — Класс Pdo\Sqlite

- DBA — Database (dbm-style) Abstraction Layer
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Dba\Connection — Класс Dba\Connection
  - Функции DBA
- ODBC — Модуль Unified ODBC
  - Установка и настройка
  - Предопределённые константы
  - Функции ODBC
  - Odbc\Connection — Класс Odbc\Connection
  - Odbc\Result — Класс Odbc\Result
- PDO — Модуль доступа к базам данных PHP Data Objects
  - Установка и настройка
  - Предопределённые константы
  - Подключения и управление подключениями
  - Транзакции и автоматическая фиксация изменений
  - Подготовленные запросы и хранимые процедуры
  - Ошибки и их обработка
  - Большие объекты
  - PDO — Класс PDO
  - PDOStatement — Класс PDOStatement
  - PDORow — Класс PDORow
  - PDOException — Исключение PDOException
  - Драйверы модуля PDO

# Модули для работы с базами данных отдельных производителей

# CUBRID

# Введение

Эти функции позволяют получить доступ серверам баз данных CUBRID. Больше информации о CUBRID можно найти на сайте » CUBRID.

Также посмотрите » Документацию CUBRID.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для того, чтобы эти функции были доступны, необходимо установить CUBRID и скомпилировать CUBRID PHP Library с его поддержкой.

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/cubrid.

DLL для этого модуля PECL пока недоступна. Смотрите также раздел сборка на Windows.

Инструкцию по ручной установке под Linux и Windows читайте в файле build-guide.html, включённом в пакет.

## Настройка во время выполнения

Настройки времени исполнения отсутствуют.

## Типы ресурсов

Существует четыре типа ресурсов, используемых в CUBRID. Первый - идентификатор соединения, второй - ресурс, хранящий результат запроса, и два последних содержат результаты запроса типов BLOB/CLOB.

## идентификатор соединения

Идентификатор соединения, возвращаемый функциями cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() и cubrid_pconnect_with_url().

## request identifier

Идентификатор запроса, возвращаемый функциями cubrid_prepare() и cubrid_execute().

## Идентификатор LOB

Идентификатор LOB, возвращаемый функцией cubrid_lob_get().

## LOB2 identifier

Идентификатор LOB, возвращаемый функцией cubrid_lob2_new() или взятый из результирующего набора.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Следующие константы указывают при выполнении SQL-запросов. Константы передают в функции cubrid_prepare() и cubrid_execute().

Флаги исполнения SQL-запроса CUBRID
Константа | Описание
--- | ---
`CUBRID_INCLUDE_OID` | Определяет, получать ли OID во время запроса.
`CUBRID_ASYNC` | Запуск запроса в асинхронном режиме.
`CUBRID_EXEC_QUERY_ALL` | Запуск запроса в синхронном режиме. Флаг устанавливают, когда выполняют множественные SQL-запросы.

Следующие константы указывают при извлечении результатов. Константы передают в функцию cubrid_fetch() и cubrid_fetch_array().

Флаги извлечения CUBRID
Константа | Описание
--- | ---
`CUBRID_NUM` | Получить результат в виде индексированного массива (первый индекс 0).
`CUBRID_ASSOC` | Получить результат в виде ассоциативного массива.
`CUBRID_BOTH` | Получить результат в виде и индексированного и ассоциативного массивов (по умолчанию).
`CUBRID_OBJECT` | Получить результат в виде объекта.
`CUBRID_LOB` | Константу CUBRID_LOB указывают при работе с LOB-объектами. Константу передают в функции cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() и cubrid_fetch_object().

Следующие константы используются при позиционировании курсора в результирующем наборе. Они передаются и возвращаются функцией cubrid_move_cursor().

Флаги позиционирования курсора CUBRID
Константа | Описание
--- | ---
`CUBRID_CURSOR_FIRST` | Переместить текущий курсов на первую запись.
`CUBRID_CURSOR_CURRENT` | Перемещать курсор относительно его текущей позиции. Используется по умолчанию.
`CUBRID_CURSOR_LAST` | Переместить текущий курсов на последнюю запись.
`CUBRID_CURSOR_SUCCESS` | Возвращается функцией cubrid_move_cursor() в случае успешного выполнения. Флаг удалён начиная с версии 8.4.1.
`CUBRID_NO_MORE_DATA` | Возвращается функцией cubrid_move_cursor() в случае возникновения ошибки. Флаг удалён начиная с версии 8.4.1.
`CUBRID_CURSOR_ERROR` | Возвращается функцией cubrid_move_cursor() в случае возникновения ошибки. Флаг удалён начиная с версии 8.4.1.

Следующие константы используются для задания режима автоматического подтверждения транзакций. Устанавливаются в функции cubrid_set_autocommit() или возвращаются cubrid_get_autocommit().

Флаги автоподтверждения транзакций CUBRID
Константа | Описание
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Разрешить режим автоматического подтверждения транзакции.
`CUBRID_AUTOCOMMIT_FALSE` | Запретить режим автоматического подтверждения транзакции.

Следующие константы можно использовать для задания параметров базы данных. Используются в функции cubrid_set_db_parameter().

Флаги параметров базы данных CUBRID
Константа | Описание
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Уровень изоляции для соединения.
`CUBRID_PARAM_LOCK_TIMEOUT` | Время ожидания транзакций.

Следующие константы используются для задания уровня изоляции для транзакций. Задаются в cubrid_set_db_parameter() и возвращаются из cubrid_get_db_parameter().

Флаги уровня изоляции транзакции CUBRID
Константа | Описание
--- | ---
`TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | Самый низкий уровень изоляции (1). Может произойти грязное, неповторяющиеся или фантомное чтение для кортежа и не повторяющееся чтение для таблицы.
`TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | Относительно низкий уровень изоляции (2). Грязного чтения не будет, но неповторяющееся или фантомное может произойти.
`TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | Стандартный уровень изоляции CUBRID (3). Может произойти грязное, неповторяющиеся или фантомное чтение для кортежа, но гарантируется повторяемость чтения для таблиц.
`TRAN_REP_CLASS_COMMIT_INSTANCE` | Относительно низкий уровень изоляции (4). Грязного чтения не будет, но неповторяющееся или фантомное может произойти.
`TRAN_REP_CLASS_REP_INSTANCE` | Относительно высокий уровень изоляции (5). Грязного и неповторяющегося чтения не будет, но фантомное может произойти.
`TRAN_SERIALIZABLE` | Наивысший уровень изоляции (6). Ни грязного, ни фантомного, ни неповторяющегося чтения не произойдёт.

Следующие константы используются при получении схемы базы дынных. Используются в функции cubrid_schema().

Флаги схемы CUBRID
Константа | Описание
--- | ---
`CUBRID_SCH_CLASS` | Получить имя и тип таблицы CUBRID.
`CUBRID_SCH_VCLASS` | Получить имя и тип представления CUBRID.
`CUBRID_SCH_QUERY_SPEC` | Получить SQL-код, которым создано представление.
`CUBRID_SCH_ATTRIBUTE` | Получить атрибуты столбца таблицы.
`CUBRID_SCH_CLASS_ATTRIBUTE` | Получить атрибуты таблицы.
`CUBRID_SCH_METHOD` | Получить метод экземпляра класса. Методы экземпляра класса вызываются в контексте экземпляра класса. Методы экземпляра класса вызываются чаще статических, поскольку бо́льшая часть операций запускается внутри экземпляра.
`CUBRID_SCH_CLASS_METHOD` | Получить метод класса. Методы класса вызываются в контексте класса, а не экземпляра класса, и выполняют следующие задачи: создают новый экземпляр класса, инициализируют начальное состояние объекта, получают доступ к атрибутам класса или обновляют атрибуты.
`CUBRID_SCH_METHOD_FILE` | Получить информацию о файле, в котором определён метод таблицы.
`CUBRID_SCH_SUPERCLASS` | Получить имя и тип таблицы, из которой наследуются атрибуты.
`CUBRID_SCH_SUBCLASS` | Получить имя и тип таблицы, в которой наследуются атрибуты текущей таблицы.
`CUBRID_SCH_CONSTRAINT` | Получить ограничения таблицы.
`CUBRID_SCH_TRIGGER` | получить триггеры таблицы.
`CUBRID_SCH_CLASS_PRIVILEGE` | Получить информацию о правах доступа к таблице.
`CUBRID_SCH_ATTR_PRIVILEGE` | Получить информацию о правах доступа к столбцу таблицы.
`CUBRID_SCH_DIRECT_SUPER_CLASS` | Получить таблицу, являющуюся прямым предком данной.
`CUBRID_SCH_PRIMARY_KEY` | Получить первичный ключ таблицы.
`CUBRID_SCH_IMPORTED_KEYS` | Получить импортированные ключи таблицы.
`CUBRID_SCH_EXPORTED_KEYS` | Получить экспортированные ключи таблицы.
`CUBRID_SCH_CROSS_REFERENCE` | Получить ссылочные отношения двух таблиц.

Следующие константы обозначают ошибки. Коды ошибок возвращает функция cubrid_error_code_facility().

Коды ошибок CUBRID
Константа | Описание
--- | ---
`CUBRID_FACILITY_DBMS` | Возникла ошибка в CUBRID dbms.
`CUBRID_FACILITY_CAS` | Возникла ошибка в cas брокера CUBRID.
`CUBRID_FACILITY_CCI` | Возникла ошибка в CUBRID cci.
`CUBRID_FACILITY_CLIENT` | Возникла ошибка в PHP-клиенте CUBRID.

# Примеры

Простой пример, в котором устанавливается соединение с CUBRID. В этом разделе рассказывается о самых базовых вещах и особенностях, на которые следует обратить внимание. Следующий код будет осуществлять соединение с CUBRID, что подразумевает, что сервер и брокер CUBRID запущены.

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

Пример #1 Пример извлечения данных

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc-kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * Задаём информация для соединения. host_ip - это IP адрес,
             * на котором запущен брокер CUBRID (например, localhost).
             * host_port - соответственно его порт.
             * Порт задаётся по умолчанию при установке.
             * Подробности можно узнать в "Administrator's Guide."
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            /**
             * Соединяемся с сервером CUBRID. Не производим фактического соединения, а
             * только получаем информацию о нем. Причина, по которой мы не делаем
             * фактического соединения в том, чтобы транзакции обрабатывались более
             * эффективно в трёхзвенной архитектуре.
             */
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Ошибка подключения к базе данных";
                exit;
            }
        ?>
        <?php
            $sql = "select sports, count(players) as players from event group by sports";
            /**
             * Запрашиваем у сервера CUBRID результат SQL-запроса.
             * Теперь производим фактическое соединение с сервером CUBRID.
             */
            $result = cubrid_execute($cubrid_con, $sql);

            if ($result) {
                /**
                 * Получаем имена столбцов из результирующего набора.
                 */
                $columns = cubrid_column_names($result);
                /**
                 * Получаем количество столбцов в результирующем наборе.
                 */
                $num_fields = cubrid_num_cols($result);
                /**
                 * Выводим имена столбцов на экран.
                 */
                echo "<tr>";

                while (list($key, $colname) = each($columns)) {
                    echo "<td align=center>$colname</td>";
                }

                echo "</tr>";

                /**
                 * получаем результаты из результирующего набора.
                 */
                while ($row = cubrid_fetch($result)) {
                    echo "<tr>";

                    for ($i = 0; $i < $num_fields; $i++) {
                        echo "<td align=center>";
                        echo $row[$i];
                        echo "</td>";
                    }

                    echo "</tr>";
                }
            }
            /**
             * Модуль PHP в CUBRID работает в трёхуровневой архитектуре. Даже когда
             * вызывается SELECT для обработки транзакций, он обрабатывается как часть
             * транзакции. action. Следовательно, транзакцию надо либо подтвердить, либо
             * откатить, даже когда вызывается SELECT.
             */
            cubrid_commit($cubrid_con);
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

Пример #2 Пример вставки данных

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc- kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * host_ip - IP адрес сервера, где установлен брокер CUBRID
             * host_port - порт, на котором он слушает
             * db_name - имя базы данных CUBRID
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Ошибка подключения к базе данных";
                exit;
            }
        ?>
        <?php
            $sql = "insert into olympic (host_year,host_nation,host_city,"
                . "opening_date,closing_date) values (2008, 'China', 'Beijing',"
                . "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
            $result = cubrid_execute($cubrid_con, $sql);
            if ($result) {
                /**
                 * Обработали успешно, можно фиксировать.
                 */
                cubrid_commit($cubrid_con);
                echo "Inserted successfully";
            } else {
                /**
                 * Произошла ошибка, значит выводим её на экран и откатываемся.
                 */
                echo cubrid_error_msg();
                cubrid_rollback($cubrid_con);
            }
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

# Функции CUBRID

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Связывает переменные с подготовленным запросом

### Описание

function cubrid_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

Функция cubrid_bind() используется для привязки значений к указанным меткам, либо знакам вопроса, в SQL-запросе, заданном cubrid_prepare(). Если не задан параметр `bind_value_type`, то будет использоваться строковый тип.

> Замечание: Если привязываемые данные имеют тип BLOB/CLOB, CUBRID попытается использовать их как потоки PHP. Если фактическое привязываемое значение не является потоком, то CUBRID конвертирует его в строку и будет считать полным путём к файлу, где эти данные лежат. Если тип данных, которые будут связаны явно является ENUM, то параметр `bind_value` должен быть элементом ENUM заданным в виде строки. В окружении сегмента CUBRID, `bind_value_type` должен быть включён в функцию cubrid_bind().

В следующей таблице приведены типы замещающих значений.

Привязка типов в CUBRID
Уровень поддержки | Тип привязки | Соответствующий SQL-тип
--- | --- | ---
Поддерживается | STRING | CHAR, VARCHAR
| NCHAR | NCHAR, NVARCHAR
| BIT | BIT, VARBIT
| NUMERIC or NUMBER | SHORT, INT, NUMERIC
| FLOAT | FLOAT
| DOUBLE | DOUBLE
| TIME | TIME
| DATE | DATE
| TIMESTAMP | TIMESTAMP
| OBJECT | OBJECT
| ENUM | ENUM
| BLOB | BLOB
| CLOB | CLOB
| NULL | NULL
Не поддерживается | SET | SET
| MULTISET | MULTISET
| SEQUENCE | SEQUENCE

### Список параметров

`req_identifier`
  Идентификатор запроса, полученный из cubrid_prepare().
`bind_index`
  Расположение связываемых параметров. Начинаются с 1.
`bind_value`
  Фактическое значения для привязки.
`bind_value_type`
  Тип связываемого значения. (По умолчанию не задано. Таким образом, по умолчанию используется тип STRING. Однако, вы должны явно указать тип для значений NCHAR, BIT, или BLOB/CLOB).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.1 | Добавлена поддержка типов данных BLOB/CLOB.

### Примеры

Пример #1 Пример использования cubrid_bind()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
    cubrid_bind($game_req, 1, $event_code, "number");
    cubrid_execute($game_req);

    printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
    while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
        $athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
        cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
        cubrid_execute($athlete_req);
        $row = cubrid_fetch_assoc($athlete_req);
        printf("%s\n", $row["name"]);
    }

    cubrid_close_request($game_req);
    cubrid_close_request($athlete_req);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    --- Dream Team (1992 United States men's Olympic basketball team) ---
    Stockton John
    Robinson David
    Pippen Scottie
    Mullin C.
    Malone Karl
    Laettner C.
    Jordan Michael
    Johnson Earvin
    Ewing Patrick
    Drexler Clyde
    Bird Larry
    Barkley Charles

Пример #2 Пример использования cubrid_bind() с BLOB/CLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        $fp = fopen("book.txt", "rb");

        cubrid_bind($req, 1, $fp, "clob");
        cubrid_execute($req);
    }
    ?>

Пример #3 Пример использования cubrid_bind() с BLOB/CLOB

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        cubrid_bind($req, 1, "cubrid_logo.png", "blob");
        cubrid_execute($req);
    }
    ?>

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_prepare() - Подготавливает SQL-выражение к выполнению

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Закрывает обработчик запроса

### Описание

function cubrid_close_prepare(resource `$req_identifier`): bool

Функция cubrid_close_prepare() закрывает обработчик запроса, который задали в параметр `req_identifier`, и высвобождает выделенную ему память. Эта функция — псевдоним функции cubrid_close_request().

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

В случае успешного выполнения функция возвращает `true`.

### Примеры

Пример #1 Пример использования функции cubrid_close_prepare()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    if ($con) {
        echo "connected successfully";

        $req = cubrid_execute(
            $con,
            "SELECT * FROM members",
            CUBRID_INCLUDE_OID | CUBRID_ASYNC
        );

        if ($req) {
            while (list($id, $name) = cubrid_fetch($req)) {
                echo $id;
                echo $name;
            }

            cubrid_close_prepare($req); // Вместо этой функции также вызывают функцию cubrid_close_request($req);
        }

        cubrid_disconnect($con);
    }

    ?>

### Смотрите также

- cubrid_close_request() - Закрывает обработчик запроса

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Закрывает обработчик запроса

### Описание

function cubrid_close_request(resource `$req_identifier`): bool

Функция cubrid_close_request() закрывает обработчик запроса, который задали в параметре `req_identifier`, и высвобождает выделенную ему память. Эта функция — псевдоним функции cubrid_close_prepare().

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

В случае успешного выполнения функция возвращает `true`.

### Примеры

Пример #1 Пример использования функции cubrid_close_request()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    if ($con) {
        echo "connected successfully";
        $req = cubrid_execute(
            $con,
            "select * from members",
            CUBRID_INCLUDE_OID | CUBRID_ASYNC
        );

        if ($req) {
            while (list($id, $name) = cubrid_fetch($req)) {
                echo $id;
                echo $name;
            }

            cubrid_close_request($req); // Вместо этой функции также вызывают функцию cubrid_close_prepare($req);
        }

        cubrid_disconnect($con);
    }

    ?>

### Смотрите также

- cubrid_close_prepare() - Закрывает обработчик запроса

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Получение контента столбца типа коллекция по OID

### Описание

function cubrid_col_get(resource `$conn_identifier`, string `$oid`, string `$attr_name`): array

Функция cubrid_col_get() используется для получения контента элемента типа коллекция (set, multiset, sequence) в виде массива.

### Список параметров

`conn_identifier`
  Идентификатор коллекции.
`oid`
  OID экземпляра, который вы хотите прочитать.
`attr_name`
  Имя атрибута, который вы хотите прочитать.

### Возвращаемые значения

Индексированный массив (начинается с 0), содержащий запрошенные элементы, в случае успеха.

`false` (для отличия ошибки от ситуации, когда атрибут содержит пустую коллекцию или NULL, в случае возникновения ошибки будет вызвано предупреждение; в этом случае нужно использовать функцию cubrid_error_code()), в случае неудачи.

### Примеры

Пример #1 Пример использования cubrid_col_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Получает количество элементов в столбце типа коллекция по OID

### Описание

function cubrid_col_size(resource `$conn_identifier`, string `$oid`, string `$attr_name`): int

Функция cubrid_col_size() используется для получения количества элементов в атрибуте типа коллекция (set, multiset, sequence).

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра.
`attr_name`
  Имя атрибута, с которым вы хотите работать.

### Возвращаемые значения

Количество элементов, в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.1 | Изменено возвращаемое значение: в случае неудачи возвращается `false`, а не -1.

### Примеры

Пример #1 Пример использования cubrid_col_size()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Получить имена столбцов в результирующем наборе

### Описание

function cubrid_column_names(resource `$req_identifier`): array

Функция cubrid_column_names() используется для получения имён столбцов в результирующем наборе, заданном в `req_identifier`.

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

Массив строк, содержащих имена столбцов, в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_column_names()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Смотрите также

- cubrid_prepare() - Подготавливает SQL-выражение к выполнению
- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_column_types() - Получить типы столбцов в результирующем наборе

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Получить типы столбцов в результирующем наборе

### Описание

function cubrid_column_types(resource `$req_identifier`): array

Функция cubrid_column_types() используется для получения типов столбцов в результирующем наборе, заданном в `req_identifier`.

### Список параметров

`req_identifier`
  Request identifier.

### Возвращаемые значения

Функция возвращает массив строк, содержащих типы столбцов, в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_column_types()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Смотрите также

- cubrid_column_names() - Получить имена столбцов в результирующем наборе
- cubrid_prepare() - Подготавливает SQL-выражение к выполнению
- cubrid_execute() - Выполняет подготовленный SQL-оператор

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Подтверждение транзакции

### Описание

function cubrid_commit(resource `$conn_identifier`): bool

Функция cubrid_commit() используется для подтверждения изменений, произведённых в транзакции в соединении `conn_identifier`, После вызова функции cubrid_commit(), соединение с сервером будет закрыто, но обработчик соединения всё ещё будет корректным.

В CUBRID PHP, режим авто-коммита для транзакций по умолчанию отключён. Вы можете разрешить или запретить его принудительно с помощью функции cubrid_set_autocommit(). Узнать текущий статус можно функцией cubrid_get_autocommit(). Перед тем как начать транзакцию, убедитесь, что авто-коммит запрещён.

### Список параметров

`conn_identifier`
  Идентификатор соединения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_commit()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;
    cubrid_set_autocommit($conn,false);
    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Смотрите также

- cubrid_rollback() - Откат транзакции
- cubrid_get_autocommit() - Возвращает настройку авто-коммита для соединения
- cubrid_set_autocommit() - Устанавливает режим авто-коммита для соединения

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Открывает соединение к серверу CUBRID

### Описание

function cubrid_connect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

Функция cubrid_connect() используется для создания соединения с сервером, используя его адрес, порт, имя базы данных, имени пользователя и пароля. Если логин и пароль не заданы, то по умолчанию будет использоваться соединение "PUBLIC".

### Список параметров

`host`
  Имя хоста или IP-адрес сервера CUBRID CAS.
`port`
  Порт сервера CUBRID CAS (BROKER_PORT в $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Имя базы данных.
`userid`
  Имя пользователя. Если не задано, то будет использовано имя по умолчанию "public".
`passwd`
  Пароль. Если не задан, то будет использоваться "".
`new_link`
  Если функция cubrid_connect_with_url() была вызвана повторно с такими же аргументами, новое соединение не будет создано, вместо него будет возвращён идентификатор уже существующего подключения. Параметр `new_link` меняет такое поведение и вынуждает cubrid_connect_with_url() в любом случае создать новое соединение, даже если функция cubrid_connect_with_url() ранее была вызвана с такими же аргументами.

### Возвращаемые значения

Идентификатор подключения в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_connect()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Смотрите также

- cubrid_pconnect() - Открывает постоянное соединение с сервером CUBRID
- cubrid_connect_with_url() - Создаёт окружение для соединения с сервером CUBRID
- cubrid_pconnect_with_url() - Открывает постоянное соединение с сервером CUBRID
- cubrid_disconnect() - Закрывает соединение с базой данных
- cubrid_close() - Закрывает соединение с базой данных

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Создаёт окружение для соединения с сервером CUBRID

### Описание

function cubrid_connect_with_url(
string `$conn_url`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

Функция cubrid_connect_with_url() используется для создания окружения для соединения с сервером посредством информации заданной в виде строки URL. Если в CUBRID разрешена функциональность высокой доступности, необходимо задать информация для соединения с резервным сервером, которая будет использоваться для соединения, если с основным что-то случится. Если логин и пароль не заданы, то по умолчанию будет использоваться соединение "PUBLIC".

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Имя хоста или IP-адрес основного сервера
- db_name : имя базы данных
- db_user : Имя пользователя
- db_password : пароль
- alhosts : Задаёт информацию о брокере резервного сервера, который будет использоваться в случае недоступности основного. Если вы зададите несколько резервных брокеров, то попытки соединения будут происходить в том же порядке, как они описаны в URL.
- rctime : Интервал между попытками подключения к активному брокеру, в котором произошёл сбой. После возникновения ошибки, система соединится с резервным брокером, указанным в althosts (failover), откатит незавершённые транзакции, и затем попытается соединиться с активным брокером основного узла через каждые rctime. Значение по умолчанию 600 секунд.
- login_timeout : Максимальное время (миллисекунды) ожидания авторизации. По умолчанию 0, что обозначает бесконечное время ожидания.
- query_timeout : Максимальное время (миллисекунды) ожидания выполнения запроса. По исчерпании этого времени на сервер будет отослано сообщение о прекращении запроса. Возвращённое значение запроса будет зависеть от настройки disconnect_on_query_timeout; даже если будет послано сообщение о прекращении запроса, он всё ещё может завершиться удачно.
- disconnect_on_query_timeout : Определяет, будет ли сразу после превышения времени ожидания запроса возвращена ошибка. По умолчанию `false`.

> Замечание: Символы `?` и `:` являются специальными в URL соединения и не могут быть использованы в пароле. Пример некорректного пароля, который нельзя использовать в строке соединения, потому, что в нем используются символы "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Пароли, содержащие `?` или `:` могут быть посланы отдельно. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_connect_with_url($url, "dba", "12?"); Если логин или пароль пусты, необходимо всё равно сохранять символы "`:`": $url = "CUBRID:localhost:33000:demodb:::";

### Список параметров

`conn_url`
  Строка, содержащая информацию для соединения.
`userid`
  Имя пользователя.
`passwd`
  пароль.
`new_link`
  Если функция cubrid_connect_with_url() была вызвана повторно с такими же аргументами, новое соединение не будет создано, вместо него будет возвращён идентификатор уже существующего подключения. Параметр `new_link` меняет такое поведение и вынуждает cubrid_connect_with_url() в любом случае создать новое соединение, даже если функция cubrid_connect_with_url() ранее была вызвана с такими же аргументами.

### Возвращаемые значения

Идентификатор подключения в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_connect_with_url() без задания свойств

    <?php
    $conn_url = "CUBRID:localhost:33000:demodb:dba::";
    $con = cubrid_connect_with_url($conn_url);

    if ($con) {
       echo "connected successfully";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

Пример #2 Пример использования cubrid_connect_with_url() с заданием свойств

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
    $con = cubrid_connect_with_url ($conn_url);

    if ($con) {
       echo "connected successfully";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Смотрите также

- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_pconnect() - Открывает постоянное соединение с сервером CUBRID
- cubrid_pconnect_with_url() - Открывает постоянное соединение с сервером CUBRID
- cubrid_disconnect() - Закрывает соединение с базой данных
- cubrid_close() - Закрывает соединение с базой данных

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Возвращает OID текущей позиции курсора

### Описание

function cubrid_current_oid(resource `$req_identifier`): string

Функция cubrid_current_oid() используется для получения oid текущего положения курсора в результирующем наборе. Для использования функции cubrid_current_oid(), запущенный запрос должен быть обновляемым, и при запуске запроса была задана опция `CUBRID_INCLUDE_OID`.

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

Oid текущего положения курсора, в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_current_oid()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $res = cubrid_get($conn, $oid);

    print_r($res);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Закрывает соединение с базой данных

### Описание

function cubrid_disconnect(resource `$conn_identifier` = ?): bool

Функция cubrid_disconnect() используется для закрытия обработчика соединения и отсоединения от сервера. Если какой либо обработчик запроса не будет закрыт к этому моменту, он будет принудительно закрыт. Функция аналогична функции совместимости CUBRID MySQL cubrid_close().

### Список параметров

`conn_identifier`
  Идентификатор соединения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_disconnect()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "connected successfully";

       $req = cubrid_execute( $con, "create table person(id int,name char(10))");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }

       $req = cubrid_execute( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Смотрите также

- cubrid_close() - Закрывает соединение с базой данных
- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_connect_with_url() - Создаёт окружение для соединения с сервером CUBRID

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Удаление экземпляра по OID

### Описание

function cubrid_drop(resource `$conn_identifier`, string `$oid`): bool

Функция cubrid_drop() используется для удаления экземпляра из из базы данных, заданного его `oid`.

### Список параметров

`conn_identifier`
  Connection identifier.
`oid`
  Oid экземпляра, который надо удалить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("--- Before Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    if (cubrid_drop($conn, $oid)) {
        cubrid_commit($conn);
    } else {
        cubrid_rollback($conn);
    }

    cubrid_close_request($req);

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("\n--- After Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    --- Before Drop: ---
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

    --- After Drop: ---
    array(4) {
      ["a"]=>
      string(1) "2"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "4"
        [1]=>
        string(1) "5"
        [2]=>
        string(1) "7"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "44"
        [1]=>
        string(2) "55"
        [2]=>
        string(2) "66"
        [3]=>
        string(3) "666"
      }
      ["d"]=>
      string(10) "b         "
    }

### Смотрите также

- cubrid_is_instance() - Проверяет, существует ли экземпляр, на который указывает OID

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Получить код ошибки

### Описание

function cubrid_error_code(): int

Функция cubrid_error_code() используется для получения кода произошедшей ошибки. Обычно вы можете получить код ошибки, если какая-либо функция вернула `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Код возникшей ошибки, или `0` (ноль), если ошибки не было.

### Примеры

Пример #1 Пример использования cubrid_error_code()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

    $req = @cubrid_execute($req);
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Результат выполнения приведённого примера:

    Error facility: 4
    Error code: -30015
    Error msg: Some parameter not binded

### Смотрите также

- cubrid_error_code_facility() - Получить код уровня, на котором произошла ошибка
- cubrid_error_msg() - Возвращает текст последней произошедшей ошибки

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Получить код уровня, на котором произошла ошибка

### Описание

function cubrid_error_code_facility(): int

Функция cubrid_error_code_facility() используется для выявления, на каком уровне произошла ошибка. Обычно вы можете получить код ошибки, если какая-либо функция вернула `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Коды уровней: `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI`, `CUBRID_FACILITY_CLIENT`.

### Примеры

Пример #1 Пример использования cubrid_error_code_facility()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = @cubrid_execute($conn, "SELECT * FROM unknown");
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Результат выполнения приведённого примера:

    Error facility: 1
    Error code: -493
    Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### Смотрите также

- cubrid_error_code() - Получить код ошибки
- cubrid_error_msg() - Возвращает текст последней произошедшей ошибки

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Возвращает текст последней произошедшей ошибки

### Описание

function cubrid_error_msg(): string

Функция cubrid_error_msg() используется для получения текста произошедшей ошибки. Обычно вы можете получить текст ошибки, если какая-либо функция вернула `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Текст ошибки.

### Примеры

Пример #1 Пример использования cubrid_error_msg()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    if (!@cubrid_schema($conn, 100000)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Результат выполнения приведённого примера:

    Error facility: 2
    Error code: -10015
    Error msg: Invalid T_CCI_SCH_TYPE value

### Смотрите также

- cubrid_error_code() - Получить код ошибки
- cubrid_error_code_facility() - Получить код уровня, на котором произошла ошибка

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Выполняет подготовленный SQL-оператор

### Описание

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function cubrid_execute(resource `$request_identifier`, int `$option` = 0): bool

Функция cubrid_execute() используется для выполнения данного SQL-оператора. Она выполняет запрос, используя `conn_identifier` и SQL, а затем возвращает созданный идентификатор запроса. Функция используется для простого выполнения запроса, когда привязка параметров не требуется. Кроме того, функция cubrid_execute() используется для выполнения подготовленного оператора с помощью cubrid_prepare() и cubrid_bind(). В это время вам необходимо указать аргументы `request_identifier` и `option`.

Параметр `option` используется для определения, следует ли получать OID после выполнения запроса и следует ли выполнять запрос в синхронном или асинхронном режиме. Константа `CUBRID_INCLUDE_OID` и `CUBRID_ASYNC` (или `CUBRID_EXEC_QUERY_ALL`, если необходимо выполнить несколько SQL-операторов) можно указать с помощью побитового оператора ИЛИ. Если не указано, ни один из них не выбран. Если установлен флаг `CUBRID_EXEC_QUERY_ALL`, для получения результатов запроса используется синхронный режим (sync_mode) и в таких случаях применяются следующие правила:

- Возвращаемое значение - результат первого запроса.
- Если в каком-либо запросе возникает ошибка, выполнение обрабатывается как сбой.
- В запросе, состоящем из q1 q2 q3, если ошибка возникает в q2 после успешного выполнения q1, результат q1 остаётся действительным. То есть предыдущее успешное выполнение запроса не откатывается в случае возникновения ошибки.
- В случае успешного выполнения запроса, результат второго запроса можно получить с помощью cubrid_next_result().

Если первым аргументом является `request_identifier` для выполнения функции cubrid_prepare() можно указать только `CUBRID_ASYNC`.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`sql`
  SQL для выполнения.
`option`
  Вариант выполнения запроса: `CUBRID_INCLUDE_OID`, `CUBRID_ASYNC`, `CUBRID_EXEC_QUERY_ALL`.
`request_identifier`
  Идентификатор cubrid_prepare().

### Возвращаемые значения

Идентификатор запроса в случае успешного выполнения запроса и если первым параметром является conn_identifier; `true`, в случае успешного выполнения запроса и первым аргументом request_identifier или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлен новый параметр `CUBRID_EXEC_QUERY_ALL`.

### Примеры

Пример #1 Пример использования cubrid_execute()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
    cubrid_bind($history_req, 1, $event_code, "number");
    cubrid_execute($history_req);

    printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
    while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
        printf("%-20s %-9s %-10s %-5s\n",
            $row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
    }

    cubrid_close_request($history_req);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    athlete              host_year score      unit
    Phelps Michael       2004      51.25      time

### Смотрите также

- cubrid_prepare() - Подготавливает SQL-выражение к выполнению
- cubrid_bind() - Связывает переменные с подготовленным запросом
- cubrid_next_result() - Получает результат следующего запроса при выполнении нескольких SQL-операторов
- cubrid_close_request() - Закрывает обработчик запроса
- cubrid_commit() - Подтверждение транзакции
- cubrid_rollback() - Откат транзакции

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Выбирает следующую строку из набора результатов

### Описание

function cubrid_fetch(resource `$result`, int `$type` = CUBRID_BOTH): mixed

Функция cubrid_fetch() используется для получения одной строки из результата запроса. Курсор автоматически переместится на следующую строку после получения результата.

### Список параметров

`result`
  `result`, полученный из cubrid_execute()
`type`
  Тип массива полученного результата CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. Для управления LOB-объектом, используйте CUBRID_LOB.

### Возвращаемые значения

Массив результатов или объект, в случае успешного выполнения процесса.

`false`, если строк больше нет; NULL в случае возникновения ошибки.

Результат может быть получен либо как массив, либо как объект, установка параметра `type` определяет, какой тип данных использовать. Переменной `type` можно присвоить одно из следующих значений:

- CUBRID_NUM : Числовой массив (начиная с 0)
- CUBRID_ASSOC : Ассоциативный массив
- CUBRID_BOTH : Числовой & ассоциативный массив (по умолчанию)
- CUBRID_OBJECT : объект, с именем атрибута в качестве имени столбца результата запроса

Если параметр `type` опущен, результат будет получен с использованием опции CUBRID_BOTH по умолчанию. Для получения результата запроса в виде объектных данных, имя столбца результата должно подчиняться правилам именования идентификаторов в PHP. Например, имя столбца, такое как "count(*)", не может быть получено в виде объекта.

### Примеры

Пример #1 Пример использования cubrid_fetch()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // для управления LOB-объектом, можно использовать cubrid_fetch($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_fetch_array() - Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
- cubrid_fetch_row() - Извлекает строку из результирующего набора в виде индексного массива
- cubrid_fetch_assoc() - Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_fetch_object() - Извлекает следующую строку как объект

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

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

### Описание

function cubrid_free_result(resource `$req_identifier`): bool

Функция освобождает память, занятую данными результата. Она возвращает `true` в случае успешного выполнения или `false` в случае возникновения ошибки. Стоит обратить внимание, что функция теперь может только освобождать буфер выборки клиента, и если необходимо освободить всю память, то нужно использовать функцию cubrid_close_request().

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_free_result()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
    $row = cubrid_fetch_assoc($req);
    var_dump($row);

    cubrid_free_result($req);
    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(5) {
      ["event_code"]=>
      string(5) "20005"
      ["athlete"]=>
      string(12) "Hayes Joanna"
      ["host_year"]=>
      string(4) "2004"
      ["score"]=>
      string(5) "12.37"
      ["unit"]=>
      string(4) "time"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Получает столбец, используя OID

### Описание

function cubrid_get(resource `$conn_identifier`, string `$oid`, mixed `$attr` = ?): mixed

Функция cubrid_get() используется для получения атрибута экземпляра данного `oid`. Вы можете получить один атрибут, используя строковый тип данных для аргумента `attr`, или множество атрибутов, используя тип данных массива для аргумента `attr`.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, который вы хотите прочитать.
`attr`
  Имя атрибута, который вы хотите прочитать.

### Возвращаемые значения

Содержимое запрошенного атрибута, когда процесс успешен; Когда `attr` установлен со строковым типом данных, результат возвращается в виде строки; если для `attr` задан тип данных массива (числовой массив, начинающийся с 0), то результат возвращается в ассоциативном массиве. Когда `attr` опущен, все атрибуты принимаются в виде массива.

`false`, если процесс завершился с ошибкой или результат NULL (если возникает ошибка, чтобы отличить пустую строку от NULL, печатается предупреждающее сообщение. Вы можете проверить ошибку, используя cubrid_error_code())

### Примеры

Пример #1 Пример использования cubrid_get()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Смотрите также

- cubrid_put() - Обновляет столбец с использованием OID

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Возвращает настройку авто-коммита для соединения

### Описание

function cubrid_get_autocommit(resource `$conn_identifier`): bool

Функция cubrid_get_autocommit() используется для определения, разрешён ли в этом соединении авто-коммит или нет.

Для CUBRID 8.4.0, авто-коммит транзакций запрещён по умолчанию.

Для CUBRID 8.4.0, авто-коммит транзакций разрешён по умолчанию.

### Список параметров

`conn_identifier`
  Идентификатор соединения.

### Возвращаемые значения

`true`, если авто-коммит разрешён.

`false`, если авто-коммит запрещён.

`null` в случае возникновения ошибки.

### Смотрите также

- cubrid_set_autocommit() - Устанавливает режим авто-коммита для соединения
- cubrid_commit() - Подтверждение транзакции

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Возвращает кодировку текущего соединения CUBRID

### Описание

function cubrid_get_charset(resource `$conn_identifier`): string

Эта функция возвращает кодировку текущего соединения CUBRID и аналогична функции совместимости CUBRID MySQL cubrid_client_encoding().

### Список параметров

`conn_identifier`
  Идентификатор соединения.

### Возвращаемые значения

Строка, содержащая кодировку текущего соединения CUBRID в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_charset()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Could not connect.');
    }

    printf("CUBRID current charset: %s\n", cubrid_get_charset($con));

    ?>

Результат выполнения приведённого примера:

    CUBRID current charset: iso8859-1

### Смотрите также

- cubrid_client_encoding() - Возвращает кодировку текущего соединения CUBRID

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Получает имя класса с помощью OID

### Описание

function cubrid_get_class_name(resource `$conn_identifier`, string `$oid`): string

Функция cubrid_get_class_name() используется для получения имени класса из параметра `oid`. Не работает при выборе данных из системных таблиц, например db_class.

### Список параметров

`conn_identifier`
  Идентификатор подключения.
`oid`
  OID экземпляра, существование которого необходимо проверить.

### Возвращаемые значения

Имя класса при успешном завершении процесса или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_class_name()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $class_name = cubrid_get_class_name($conn, $oid);

    print_r($class_name);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    code

### Смотрите также

- cubrid_is_instance() - Проверяет, существует ли экземпляр, на который указывает OID
- cubrid_drop() - Удаление экземпляра по OID

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Возвращает версию клиентской библиотеки

### Описание

function cubrid_get_client_info(): string

Функция возвращает строку, представляющую версию клиентской библиотеки.

### Список параметров

### Возвращаемые значения

Строка, представляющая версию клиентской библиотеки в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_client_info()

    <?php
    printf("%-30s %s\n", "Версия CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Ошибка подключения ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Информация о сервере:", $server_info);
    printf("%-30s %s\n", "Информация о клиенте:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Кодировка CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Версия CUBRID PHP:             9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Информация о сервере:          9.1.0.0212
    Информация о клиенте:          9.1.0

    Кодировка CUBRID:              iso8859-1

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Возвращает параметры базы данных CUBRID

### Описание

function cubrid_get_db_parameter(resource `$conn_identifier`): array

Функция возвращает параметры базы данных CUBRID или `false`, если возникла ошибка. Возвращается ассоциативный массив со значениями следующих параметров:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`
- `PARAM_MAX_STRING_LENGTH`
- `PARAM_AUTO_COMMIT`

Параметры базы данных
Параметр | Описание
--- | ---
PARAM_ISOLATION_LEVEL | Уровень изоляции транзакции.
LOCK_TIMEOUT | CUBRID предоставляет функцию времени ожидания блокировки, которая устанавливает время ожидания (в секундах) для блокировки до тех пор, пока не будет разрешена настройка блокировки транзакции. Значение по умолчанию для параметра lock_timeout_in_secs равно -1, что означает, что клиент приложения будет ждать бесконечно, пока блокировка транзакции не будет разрешена.
PARAM_AUTO_COMMIT | В CUBRID PHP режим автоматической фиксации отключён по умолчанию для управления транзакциями. Его можно установить с помощью cubrid_set_autocommit().

В следующей таблице показаны уровни изоляции от 1 до 6. Она состоит из схемы (строки) таблицы и уровня изоляции:

Уровни изоляции, поддерживаемые CUBRID
Имя | Описание
--- | ---
SERIALIZABLE (6) | На этом уровне изоляции проблем, связанных с параллелизмом (например, грязное чтение, неповторяющееся чтение, фантомное чтение и т.д.) не возникает.
REPEATABLE READ CLASS с REPEATABLE READ INSTANCES (5) | Другая транзакция T2 не может обновить схему таблицы A, пока транзакция T1 просматривает таблицу A. Транзакция T1 может испытывать фантомное чтение для записи R, которая была вставлена другой транзакцией T2, когда она повторно получает определённую запись.
REPEATABLE READ CLASS с READ COMMITTED INSTANCES (или CURSOR STABILITY) (4) | Другая транзакция T2 не может обновить схему таблицы A, пока транзакция T1 просматривает таблицу A. Транзакция T1 может испытывать чтение R (неповторяющееся чтение), которое было обновлено и зафиксировано другой транзакцией T2, когда она повторно получает запись R.
REPEATABLE READ CLASS с READ UNCOMMITTED INSTANCES (3) | Уровень изоляции по умолчанию. Другая транзакция T2 не может обновить схему таблицы A, пока транзакция T1 просматривает таблицу A. В транзакции T1 может произойти чтение R (грязное чтение) для записи, которая была обновлена, но не зафиксирована другой транзакцией T2.
READ COMMITTED CLASS с READ COMMITTED INSTANCES (2) | Транзакция T1 может испытывать чтение A' (неповторяющееся чтение) для таблицы, которая была обновлена и зафиксирована другой транзакцией T2, пока она просматривает таблицу A несколько раз. Транзакция T1 может испытывать чтение R' (неповторяющееся чтение) для записи, которая была обновлена и зафиксирована другой транзакцией T2, пока она повторно извлекает запись R.
READ COMMITTED CLASS с READ UNCOMMITTED INSTANCES (1) | Транзакция T1 может испытывать чтение A' (неповторяющееся чтение) для таблицы, которая была обновлена и зафиксирована другой транзакцией T2, в то время как она многократно просматривает таблицу A. Транзакция T1 может испытывать чтение R' (грязное чтение) для записи, которая была обновлена, но не зафиксирована другой транзакцией T2.

### Список параметров

`conn_identifier`
  Соединение CUBRID. Если идентификатор соединения не указан, предполагается последняя ссылка, открытая cubrid_connect().

### Возвращаемые значения

Ассоциативный массив с параметрами базы данных CUBRID в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | В результате изменился LOCK_TIMEOUT на PARAM_LOCK_TIMEOUT и MAX_STRING_LENGTH на PARAM_MAX_STRING_LENGTH.

### Примеры

Пример #1 Пример использования cubrid_get_db_parameter()

    <?php
    printf("%-30s %s\n", "Версия CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Информация о сервере:", $server_info);
    printf("%-30s %s\n", "Информация о клиенте:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Кодировка CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Версия CUBRID PHP:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Информация о сервере:             9.1.0.0212
    Информация о клиенте:             9.1.0

    Кодировка CUBRID:                iso8859-1

### Смотрите также

- cubrid_set_db_parameter() - Устанавливает параметры базы данных CUBRID
- cubrid_get_autocommit() - Возвращает настройку авто-коммита для соединения

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Получает значение времени ожидания запроса

### Описание

function cubrid_get_query_timeout(resource `$req_identifier`): int

Функция cubrid_get_query_timeout() используется для получения времени ожидания запроса.

### Список параметров

`req_identifier`
  Идентификатор запроса.

### Возвращаемые значения

Возвращает значение времени ожидания текущего запроса в миллисекундах в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_query_timeout()

    <?php

    $host = "localhost";
    $port = 33000;
    $db = "demodb";

    $conn =
    cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

    $req = cubrid_prepare($conn, "SELECT * FROM code");

    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_set_query_timeout($req, 1000);
    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_close($conn);
    ?>

Результат выполнения приведённого примера:

    int(5000)
    int(1000)

### Смотрите также

- cubrid_set_query_timeout() - Устанавливает время ожидания выполнения запроса

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Возвращает версию сервера CUBRID

### Описание

function cubrid_get_server_info(resource `$conn_identifier`): string

Функция возвращает строку, представляющую версию сервера CUBRID.

### Список параметров

`conn_identifier`
  Соединение CUBRID.

### Возвращаемые значения

Строка, представляющая версию сервера CUBRID в случае успешного выполнения, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_server_info()

    <?php
    printf("%-30s %s\n", "Версия CUBRID PHP:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Ошибка подключения ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Информация о сервере:", $server_info);
    printf("%-30s %s\n", "Информация о клиенте:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Кодировка CUBRID:", $charset);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Версия CUBRID PHP:             9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Информация о сервере:          9.1.0.0212
    Информация о клиенте:          9.1.0

    Кодировка CUBRID:              iso8859-1

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Возвращает идентификатор, сгенерированный для последнего обновлённого столбца `AUTO_INCREMENT`

### Описание

function cubrid_insert_id(resource `$conn_identifier` = ?): string

Функция cubrid_insert_id() возвращает идентификатор, сгенерированный для столбца AUTO_INCREMENT, который обновляется предыдущим запросом INSERT. Она возвращает 0, если предыдущий запрос не генерирует новые строки, или FALSE в случае возникновения ошибки.

> Замечание: CUBRID поддерживает AUTO_INCREMENT для более чем одного столбца в таблице. В большинстве случаев в таблице будет один столбец AUTO_INCREMENT. Если имеется несколько столбцов AUTO_INCREMENT, данную функцию не следует использовать, даже если она вернёт значение.

### Список параметров

`conn_identifier`
  Идентификатор соединения, полученный ранее при вызове cubrid_connect().

### Возвращаемые значения

Строка, представляющая идентификатор, сгенерированный для столбца AUTO_INCREMENT предыдущим запросом в случае успешного выполнения.

0, если предыдущий запрос не сгенерировал новые строки.

`false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Возвращаемое значение в виде массива заменено на строку; Удалён первый параметр class_name.

### Примеры

Пример #1 Пример использования cubrid_insert_id()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
    }

    $id = cubrid_insert_id();
    var_dump($id);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Проверяет, существует ли экземпляр, на который указывает OID

### Описание

function cubrid_is_instance(resource `$conn_identifier`, string `$oid`): int

Функция cubrid_is_instance() используется, чтобы проверить, существует ли экземпляр, на который указывает данный `oid`, или нет.

### Список параметров

`conn_identifier`
  Идентификатор подключения.
`oid`
  OID экземпляра, существование которого требуется проверить.

### Возвращаемые значения

1, если такой экземпляр существует;

0, если такого экземпляра не существует;

-1 в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_is_instance()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT host_year, medal, game_date
    FROM game
    WHERE athlete_code IN
        (SELECT code FROM athlete WHERE name='Thorpe Ian');
    EOD;

    $req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);

    $res = cubrid_is_instance ($conn, $oid);
    if ($res == 1) {
        echo "Экземпляр, на который указывает $oid, существует.\n";
    } else if ($res == 0){
        echo "Экземпляр, на который указывает $oid, не существует.\n";
    } else {
        echo "Ошибка\n";
    }

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Экземпляр, на который указывает @0|0|0, не существует.

### Смотрите также

- cubrid_drop() - Удаление экземпляра по OID
- cubrid_get_class_name() - Получает имя класса с помощью OID

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Закрывает данные BLOB/CLOB

### Описание

function cubrid_lob_close(array `$lob_identifier_array`): bool

cubrid_lob_close() используется для закрытия всех BLOB/CLOB, возвращаемых функцией cubrid_lob_get().

### Список параметров

`lob_identifier_array`
  Массив идентификаторов LOB, возвращённый cubrid_lob_get().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob_close()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Размер документа: ".cubrid_lob_size($lobs[0])." байтов";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob_get() - Получает данные BLOB/CLOB
- cubrid_lob_size() - Получает размер данных BLOB/CLOB
- cubrid_lob_export() - Экспортирует данные BLOB/CLOB в файл
- cubrid_lob_send() - Читает данные BLOB/CLOB и отправляет их прямо в браузер

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Экспортирует данные BLOB/CLOB в файл

### Описание

function cubrid_lob_export(resource `$conn_identifier`, resource `$lob_identifier`, string `$path_name`): bool

cubrid_lob_export() используется для получения данных BLOB/CLOB из базы данных CUBRID и сохранения их содержимого в файл. Чтобы использовать данную функцию, необходимо сначала использовать cubrid_lob_get(), чтобы получить информацию BLOB/CLOB из CUBRID.

### Список параметров

`conn_identifier`
  Идентификатор подключения.
`lob_identifier`
  Идентификатор LOB.
`path_name`
  Имя пути к файлу.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob_export()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Размер документа: ".cubrid_lob_size($lobs[0])." байтов";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob_get() - Получает данные BLOB/CLOB
- cubrid_lob_close() - Закрывает данные BLOB/CLOB
- cubrid_lob_size() - Получает размер данных BLOB/CLOB
- cubrid_lob_send() - Читает данные BLOB/CLOB и отправляет их прямо в браузер

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Получает данные BLOB/CLOB

### Описание

function cubrid_lob_get(resource `$conn_identifier`, string `$sql`): array

cubrid_lob_get() используется для получения метаинформации BLOB/CLOB из базы данных CUBRID, CUBRID получает BLOB/CLOB, выполняя оператор SQL, и возвращает все LOB в виде массива ресурсов. Необходимо убедиться, что SQL возвращает только один столбец, и его тип данных - BLOB или CLOB.

Не стоит забывать об использовании cubrid_lob_close() для освобождения LOB, если они больше не нужны.

### Список параметров

`conn_identifier`
  Идентификатор подключения.
`sql`
  Выполняемый оператор SQL.

### Возвращаемые значения

Возвращает массив LOB-ресурсов в случае успешного выполнения процесса или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob_get()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Размер документа: ".cubrid_lob_size($lobs[0])." байтов";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob_close() - Закрывает данные BLOB/CLOB
- cubrid_lob_size() - Получает размер данных BLOB/CLOB
- cubrid_lob_export() - Экспортирует данные BLOB/CLOB в файл
- cubrid_lob_send() - Читает данные BLOB/CLOB и отправляет их прямо в браузер

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Читает данные BLOB/CLOB и отправляет их прямо в браузер

### Описание

function cubrid_lob_send(resource `$conn_identifier`, resource `$lob_identifier`): bool

cubrid_lob_send() считывает данные BLOB/CLOB и передаёт их прямо в браузер. Чтобы использовать данную функцию, необходимо сначала использовать cubrid_lob_get(), чтобы получить информацию BLOB/CLOB из CUBRID.

### Список параметров

`conn_identifier`
  Идентификатор подключения.
`lob_identifier`
  Идентификатор LOB.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob_send()

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

    cubrid_lob_send($conn, $lobs[0]);
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob_get() - Получает данные BLOB/CLOB
- cubrid_lob_close() - Закрывает данные BLOB/CLOB
- cubrid_lob_size() - Получает размер данных BLOB/CLOB
- cubrid_lob_export() - Экспортирует данные BLOB/CLOB в файл

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Получает размер данных BLOB/CLOB

### Описание

function cubrid_lob_size(resource `$lob_identifier`): string

cubrid_lob_size() используется для получения размера данных BLOB/CLOB.

### Список параметров

`lob_identifier`
  Идентификатор LOB.

### Возвращаемые значения

Строка, представляющая размер LOB-данных в случае успешного выполнения процесса, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Тип возвращаемого значения изменён с int на string.

### Примеры

Пример #1 Пример использования cubrid_lob_size()

    <?php
    $lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
    echo "Размер документа:".cubrid_lob_size($lobs[0]);
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    ?>

### Смотрите также

- cubrid_lob_get() - Получает данные BLOB/CLOB
- cubrid_lob_close() - Закрывает данные BLOB/CLOB
- cubrid_lob_export() - Экспортирует данные BLOB/CLOB в файл
- cubrid_lob_send() - Читает данные BLOB/CLOB и отправляет их прямо в браузер

# cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Связывает объект LOB или строку в виде объекта LOB с подготовленным оператором в качестве параметров

### Описание

function cubrid_lob2_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

Функция cubrid_lob2_bind() используется для привязки данных BLOB/CLOB к соответствующей псевдопеременной в операторе SQL, который был передан в cubrid_prepare(). Если параметр `bind_value_type` не указан, по умолчанию будет использоваться строка "BLOB". Но если ранее использовалась функция cubrid_lob2_new(), `bind_value_type` будет соответствовать параметру `type` в cubrid_lob2_new() по умолчанию.

### Список параметров

`req_identifier`
  Идентификатор запроса, полученный в результате работы cubrid_prepare().
`bind_index`
  Расположение параметров привязки. Начинается с 1.
`bind_value`
  Фактическое значение для привязки.
`bind_value_type`
  Значение должно быть равно "BLOB" или "CLOB", регистр не учитывается. Если значение не указано, по умолчанию используется "BLOB".

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob2_bind()

    <?php
    // Таблица: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

    cubrid_bind($req,1, 3);

    $lob = cubrid_lob2_new($conn, 'CLOB');
    cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_bind($req, 1, 4);

    cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_new() - Создаёт объект LOB
- cubrid_lob2_close() - Закрывает объект LOB

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Закрывает объект LOB

### Описание

function cubrid_lob2_close(resource `$lob_identifier`): bool

Функция cubrid_lob2_close() используется для закрытия объекта LOB, возвращённого функцией cubrid_lob2_new() или полученного из результирующего набора.

### Список параметров

`lob_identifier`
  Идентификатор LOB, возвращённый функцией cubrid_lob2_new() или полученный из результирующего набора.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_new() - Создаёт объект LOB

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Экспортирует LOB-объект в файл

### Описание

function cubrid_lob2_export(resource `$lob_identifier`, string `$file_name`): bool

Функция cubrid_lob2_export() используется для сохранения содержимого данных BLOB/CLOB в файл. Чтобы использовать эту функцию, необходимо использовать cubrid_lob2_new() или сначала получить LOB-объект из базы данных CUBRID. Если файл уже существует, операция завершится ошибкой. Функция не будет влиять на положение курсора LOB-объекта. Она управляет всем LOB-объектом.

### Список параметров

`lob_identifier`
  Идентификатор LOB, полученный в результате cubrid_lob2_new() или полученный из набора результатов.
`filename`
  Имя файла, в который вы хотите импортировать данные BLOB/CLOB. Также поддерживается путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob2_export()

    <?php
    // Таблица: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $req = cubrid_prepare($conn, "select * from doc");

    cubrid_execute($req);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

    $row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

    cubrid_lob2_export($row[1], "doc_3.txt");

    cubrid_lob2_close($row[1]);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_new() - Создаёт объект LOB
- cubrid_lob2_close() - Закрывает объект LOB
- cubrid_lob2_import() - Импортирует данные BLOB/CLOB из файла
- cubrid_lob2_bind() - Связывает объект LOB или строку в виде объекта LOB с подготовленным оператором в качестве параметров

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Импортирует данные BLOB/CLOB из файла

### Описание

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

Функция cubrid_lob2_import() используется для сохранения содержимого данных BLOB/CLOB из файла. Чтобы использовать эту функцию, необходимо использовать cubrid_lob2_new() или сначала получить LOB-объект из базы данных CUBRID. Если файл не существует, операция завершится ошибкой. Функция не будет влиять на положение курсора LOB-объекта. Она управляет всем LOB-объектом.

### Список параметров

`lob_identifier`
  Идентификатор LOB, полученный в результате cubrid_lob2_new() или полученный из набора результатов.
`filename`
  Имя файла, в который вы хотите импортировать данные BLOB/CLOB. Также поддерживается путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob2_export()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // или cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_new() - Создаёт объект LOB
- cubrid_lob2_close() - Закрывает объект LOB
- cubrid_lob2_export() - Экспортирует LOB-объект в файл
- cubrid_lob2_bind() - Связывает объект LOB или строку в виде объекта LOB с подготовленным оператором в качестве параметров

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Создаёт объект LOB

### Описание

function cubrid_lob2_new(resource `$conn_identifier` = ?, string `$type` = "BLOB"): resource

Функция cubrid_lob2_new() используется для создания объекта LOB (как BLOB, так и CLOB). Её следует использовать перед привязкой объекта LOB.

### Список параметров

`conn_identifier`
  Идентификатор подключения. Если идентификатор соединения не указан, предполагается последнее подключение, открытое с помощью cubrid_connect() или cubrid_connect_with_url().
`type`
  Значение должно быть равно "BLOB" или "CLOB", регистр не учитывается. По умолчанию используется значение "BLOB".

### Возвращаемые значения

Идентификатор LOB в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_close() - Закрывает объект LOB

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Производит чтение из данных BLOB/CLOB

### Описание

function cubrid_lob2_read(resource `$lob_identifier`, int `$len`): string

Функция cubrid_lob2_read() считывает `len` байтов из данных LOB и возвращает прочитанные байты.

### Список параметров

`lob_identifier`
  Идентификатор LOB, возвращённый функцией cubrid_lob2_new() или полученный из результирующего набора.
`len`
  Длина из буфера, используемая для чтения из данных LOB.

### Возвращаемые значения

Возвращает содержимое в виде строки, `false`, если данных больше нет, или `null` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_lob2_read() 1

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    print "текущая позиция - " . cubrid_lob2_tell($row[1]) . "\n";

    cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

    print "\nпозиция после движения вперед - " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 12);

    print "\nпозиция после чтения - " . cubrid_lob2_tell($row[1]) . "\n";

    print $data . "\n";

    cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

    print "\nпозиция после повторного движения вперед - " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 20);
    print $data . "\n";

    cubrid_disconnect($conn);
    ?>

Пример #2 Пример использования cubrid_lob2_read() 2

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    while (true) {
        if ($data = cubrid_lob2_read($row[1], 1024)) {
            print $data . "\n";
        }
        elseif ($data === false) {
            print "Данных больше нет\n";
            break;
        }
        else {
            print "Произошла ошибка\n";
            break;
        }
    }

    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Перемещает курсор LOB-объекта

### Описание

function cubrid_lob2_seek(resource `$lob_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

Функция cubrid_lob2_seek() используется для перемещения позиции курсора LOB-объекта на значение, заданное в параметре `offset`, в направлении, заданном в параметре `origin`.

Чтобы установить параметр `origin`, вы можете использовать `CUBRID_CURSOR_FIRST`, чтобы установить позицию курсора, перемещающегося вперёд на `offset` единиц от начала LOB-объекта. В этом случае параметр `offset` должен быть положительным значением.

Если вы используете `CUBRID_CURSOR_CURRENT` для `origin`, вы можете двигаться вперёд или назад, `offset` может быть положительным или отрицательным.

Если вы используете `CUBRID_CURSOR_LAST` для `origin`, вы можете перемещать назад на единицу `offset` с конца LOB-объекта. В этом случае параметр `offset` должен быть положительным значением.

### Список параметров

`lob_identifier`
  Идентификатор LOB в результате работы функции cubrid_lob2_new() или полученный из набора результатов.
`offset`
  Количество единиц, на которое нужно переместить курсор.
`origin`
  Параметр может иметь следующие значения: CUBRID_CURSOR_FIRST: двигаться вперёд от начала LOB-объекта. CUBRID_CURSOR_CURRENT: двигаться вперёд или назад от текущей позиции. CUBRID_CURSOR_LAST: двигаться назад с конца LOB-объекта.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob2_seek()

    <?php
    // test_lob (id INT, contents CLOB)
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
    cubrid_lob2_write($lob, "beautiful");

    cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 5);

    echo $data."\n";

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Перемещает курсор LOB-объекта

### Описание

function cubrid_lob2_seek64(resource `$lob_identifier`, string `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

Функция cubrid_lob2_seek64() используется для перемещения позиции курсора LOB-объекта на значение, заданное в параметре `offset`, в направлении, заданном в параметре `origin`. Если значение параметра `offset` больше, чем можно сохранить целочисленные данные, вы можете использовать эту функцию.

Чтобы установить параметр `origin`, вы можете использовать `CUBRID_CURSOR_FIRST`, чтобы установить позицию курсора, перемещающегося вперёд на `offset` единиц от начала LOB-объекта. В этом случае параметр `offset` должен быть положительным значением.

Если вы используете `CUBRID_CURSOR_CURRENT` для `origin`, вы можете двигаться вперёд или назад, `offset` может быть положительным или отрицательным.

Если вы используете `CUBRID_CURSOR_LAST` для `origin`, вы можете перемещать назад на единицу `offset` с конца LOB-объекта. В этом случае параметр `offset` должен быть положительным значением.

> Замечание: Если вы используете эту функцию для перемещения позиции курсора LOB-объекта, вы должны передать `offset` в качестве строки.

### Список параметров

`lob_identifier`
  Идентификатор LOB в результате работы функции cubrid_lob2_new() или полученный из набора результатов.
`offset`
  Количество единиц, на которое нужно переместить курсор.
`origin`
  Параметр может иметь следующие значения: CUBRID_CURSOR_FIRST: двигаться вперёд от начала LOB-объекта. CUBRID_CURSOR_CURRENT: двигаться вперёд или назад от текущей позиции. CUBRID_CURSOR_LAST: двигаться назад с конца LOB-объекта.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования: cubrid_lob2_seek64()

    <?php
    // test_lob (id INT, contents CLOB)
    // Длина данных doc_1.txt должна быть больше 20101029056306120215.

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // или cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);

    $req = cubrid_execute($conn, "select * from test_lob");
    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob = $row[1];

    cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 20);
    echo $data."\n";
    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Получает размер LOB-объекта

### Описание

function cubrid_lob2_size(resource `$lob_identifier`): int

Функция cubrid_lob2_size() используется для получения размера LOB-объекта.

### Список параметров

`lob_identifier`
  Идентификатор LOB в результате работы функции cubrid_lob2_new() или полученный из набора результатов.

### Возвращаемые значения

Возвращает размер LOB-объекта в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Получает размер LOB-объекта

### Описание

function cubrid_lob2_size64(resource `$lob_identifier`): string

Функция cubrid_lob2_size64() используется для получения размера LOB-объекта. Если размер LOB-объекта больше, чем могут быть сохранены целочисленные данные, вы можете использовать эту функцию и она вернёт размер в виде строки.

### Список параметров

`lob_identifier`
  Идентификатор LOB в результате работы функции cubrid_lob2_new() или полученный из набора результатов.

### Возвращаемые значения

Возвращает размер LOB-объекта в виде строки в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Сообщает положение курсора LOB-объекта

### Описание

function cubrid_lob2_tell(resource `$lob_identifier`): int

Функция cubrid_lob2_tell() используется для определения положения курсора LOB-объекта.

### Список параметров

`lob_identifier`
  Идентификатор Lob в результате cubrid_lob2_new() или полученный из набора результатов.

### Возвращаемые значения

Возвращает позицию курсора LOB-объекта, когда он будет успешно обработан или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Сообщает положение курсора LOB-объекта

### Описание

function cubrid_lob2_tell64(resource `$lob_identifier`): string

Функция cubrid_lob2_tell64() используется для определения положения курсора LOB-объекта. Если размер LOB-объекта больше, чем могут быть сохранены целочисленные данные, вы можете использовать эту функцию и она вернёт информацию о позиции в виде строки.

### Список параметров

`lob_identifier`
  Идентификатор Lob в результате cubrid_lob2_new() или полученный из набора результатов.

### Возвращаемые значения

Возвращает позицию курсора LOB-объекта в виде строки в случае успешного выполнения или `false`, если возникла ошибка.

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_write() - Записывает в LOB-объект
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Записывает в LOB-объект

### Описание

function cubrid_lob2_write(resource `$lob_identifier`, string `$buf`): bool

Функция cubrid_lob2_write() считывает данные из `buf` и сохраняет их в LOB-объект. Обратите внимание, что функция может только добавлять символы.

### Список параметров

`lob_identifier`
  Идентификатор LOB, полученный в результате cubrid_lob2_new() или полученный из набора результатов.
`buf`
  Данные, которые необходимо записать в LOB-объект.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

Пример #2 Пример использования cubrid_lob2_write()

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
    $lob1 = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob1, "cubrid php driver");
    cubrid_lob2_bind($req, 1, $lob1);
    cubrid_execute($req);

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob2 = $row[1];
    cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

    $pos = cubrid_lob2_tell($lob2);
    print "позиция перед записью: $pos\n";

    cubrid_lob2_write($lob2, "Hello world");

    $pos = cubrid_lob2_tell($lob2);
    print "позиция после записи: $pos\n";

    cubrid_disconnect($conn);
    ?>

### Смотрите также

- cubrid_lob2_read() - Производит чтение из данных BLOB/CLOB
- cubrid_lob2_seek() - Перемещает курсор LOB-объекта
- cubrid_lob2_seek64() - Перемещает курсор LOB-объекта
- cubrid_lob2_tell() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64() - Сообщает положение курсора LOB-объекта
- cubrid_lob2_size() - Получает размер LOB-объекта
- cubrid_lob2_size64() - Получает размер LOB-объекта

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Устанавливает блокировку чтения для данного OID

### Описание

function cubrid_lock_read(resource `$conn_identifier`, string `$oid`): bool

Функция cubrid_lock_read() используется для установки блокировки чтения экземпляра, на который указывает данный `oid`.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, на который необходимо установить блокировку чтения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lock_read()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_read($conn, $oid);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Смотрите также

- cubrid_lock_write() - Устанавливает блокировку записи для данного OID

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Устанавливает блокировку записи для данного OID

### Описание

function cubrid_lock_write(resource `$conn_identifier`, string `$oid`): bool

Функция cubrid_lock_write() используется для установки блокировки записи экземпляра, на который указывает данный `oid`.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, на который необходимо установить блокировку записи.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_lock_write()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_write($conn, $oid);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Смотрите также

- cubrid_lock_read() - Устанавливает блокировку чтения для данного OID

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Перемещает курсор в результате

### Описание

function cubrid_move_cursor(resource `$req_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

Функция cubrid_move_cursor() используется для перемещения текущего положения курсора `req_identifier` на значение, заданное в аргументе `offset`, в направлении, заданном в аргументе `origin`. Чтобы установить аргумент `origin`, вы можете использовать `CUBRID_CURSOR_FIRST` для первой части результата, `CUBRID_CURSOR_CURRENT` для текущего местоположения результата или `CUBRID_CURSOR_LAST` для последней части результата. Если аргумент `origin` не указан явно, тогда функция использует `CUBRID_CURSOR_CURRENT` в качестве значения по умолчанию.

Если значение диапазона перемещения курсора превышает допустимый предел, то курсор перемещается в следующее место после допустимого диапазона для курсора. Например, если вы переместите 20 единиц в результате с размером 10, то курсор переместится на 11-е место и вернёт `CUBRID_NO_MORE_DATA`.

### Список параметров

`req_identifier`
  Идентификатор запроса.
`offset`
  Количество единиц, на которые нужно переместить курсор.
`origin`
  Место, из которого вы хотите переместить курсор: `CUBRID_CURSOR_FIRST`, `CUBRID_CURSOR_CURRENT` или `CUBRID_CURSOR_LAST`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_move_cursor()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(2) {
      [0]=>
      string(1) "G"
      [1]=>
      string(4) "Gold"
    }
    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Получает результат следующего запроса при выполнении нескольких SQL-операторов

### Описание

function cubrid_next_result(resource `$result`): bool

Функция cubrid_next_result() используется для получения результатов следующего запроса, если выполняется несколько SQL-операторов и для cubrid_execute() установлен флаг `CUBRID_EXEC_QUERY_ALL`.

### Список параметров

`result`
  `result` из вызова функции cubrid_execute().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_next_result()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
    $res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

    get_result_info($res);
    cubrid_next_result($res);
    get_result_info($res);

    function get_result_info($req)
    {
        printf("\n------------ get_result_info --------------------\n");

        $row_num = cubrid_num_rows($req);
        $col_num = cubrid_num_cols($req);

        $column_name_list = cubrid_column_names($req);
        $column_type_list = cubrid_column_types($req);

        $column_last_name = cubrid_field_name($req, $col_num - 1);
        $column_last_table = cubrid_field_table($req, $col_num - 1);

        $column_last_type = cubrid_field_type($req, $col_num - 1);
        $column_last_len = cubrid_field_len($req, $col_num - 1);

        $column_1_flags = cubrid_field_flags($req, 1);

        printf("%-30s %d\n", "Количество строк:", $row_num);
        printf("%-30s %d\n", "Количество столбцов:", $col_num);
        printf("\n");

        printf("%-30s %-30s %-15s\n", "Названия столбцов", "Типы столбцов", "Длина столбцов");
        printf("------------------------------------------------------------------------------\n");

        $size = count($column_name_list);
        for($i = 0; $i < $size; $i++) {
            $column_len = cubrid_field_len($req, $i);
            printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
        }
        printf("\n\n");

        printf("%-30s %s\n", "Название последнего столбца:", $column_last_name);
        printf("%-30s %s\n", "Таблица последнего столбца:", $column_last_table);
        printf("%-30s %s\n", "Тип последнего столбца:", $column_last_type);
        printf("%-30s %d\n", "Длина последнего столбца:", $column_last_len);
        printf("%-30s %s\n", "Флаги второго столбца:", $column_1_flags);

        printf("\n\n");
    }
    ?>

Результат выполнения приведённого примера:

    ------------ get_result_info --------------------
    Row count:                     6
    Column count:                  2

    Названия столбцов                 Типы столбцов                   Длина столбцов
    ------------------------------------------------------------------------------
    s_name                         char                           1
    f_name                         varchar                        6

    Название последнего столбца:          f_name
    Таблица последнего столбца:           code
    Тип последнего столбца:              varchar
    Длина последнего столбца:            6
    Флаги второго столбца:

    ------------ get_result_info --------------------
    Количество строк:                    4
    Количество столбцов:                  5

    Названия столбцов                 Типы столбцов                   Длина столбцов
    ------------------------------------------------------------------------------
    event_code                     integer                        11
    athlete                        varchar                        40
    host_year                      integer                        11
    score                          varchar                        10
    unit                           varchar                        5

    Название последнего столбца:      unit
    Таблица последнего столбца:       history
    Тип последнего столбца:          varchar
    Длина последнего столбца:        5
    Флаги второго столбца:          not_null primary_key unique_key

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Возвращает количество столбцов в наборе результатов

### Описание

function cubrid_num_cols(resource `$result`): int

Функция cubrid_num_cols() используется для получения количества столбцов из результата запроса. Её можно использовать только в том случае, если выполняемый запрос является оператором `SELECT`.

### Список параметров

`result`
  Результат.

### Возвращаемые значения

Количество столбцов в случае успешного выполнения.

`false`, если SQL-выражение не является SELECT.

### Примеры

Пример #1 Пример использования cubrid_num_cols()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Количество строк: %d\nКоличество столбцов: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Количество строк: 6
    Количество столбцов: 2

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_num_rows() - Получить количество строк в наборе результатов

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Получить количество строк в наборе результатов

### Описание

function cubrid_num_rows(resource `$result`): int

Функция cubrid_num_rows() используется для получения количества строк результата запроса. Может использоваться для операторов `SELECT`. Для запросов `INSERT`, `UPDATE` или `DELETE`, используйте функцию cubrid_affected_rows().

Примечание: Функцию cubrid_num_rows() можно использовать только для синхронного запроса; функция возвращает 0, если используется для асинхронного запроса.

### Список параметров

`result`
  `result` из вызова функций cubrid_execute(), cubrid_query() и cubrid_prepare()

### Возвращаемые значения

Количество строк в случае успешного выполнения процесса.

0, если запрос был выполнен в асинхронном режиме.

-1, если SQL-оператор не является SELECT.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_num_rows()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Количество строк: %d\nКоличество столбцов: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Количество строк: 6
    Количество столбцов: 2

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_num_cols() - Возвращает количество столбцов в наборе результатов
- cubrid_affected_rows() - Возвращает количество строк, которые затронул последний SQL-запрос

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Открывает постоянное соединение с сервером CUBRID

### Описание

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Устанавливает постоянное соединение с сервером CUBRID.

cubrid_pconnect() действует очень похоже на cubrid_connect() с двумя основными отличиями:

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

Во-вторых, соединение с SQL-сервером не будет закрыто по окончании выполнения скрипта. Вместо этого ссылка останется открытой для использования в будущем (cubrid_close() или cubrid_disconnect() не закроет ссылки, установленные cubrid_pconnect()).

Поэтому этот тип ссылки называется "постоянным".

### Список параметров

`host`
  Имя хоста или IP-адрес сервера CUBRID CAS.
`port`
  Номер порта CUBRID CAS-сервера (BROKER_PORT настроенный в $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Имя базы данных.
`userid`
  Имя пользователя базы данных.
`passwd`
  Пароль пользователя.

### Возвращаемые значения

Идентификатор соединения в случае успешного выполнения процесса или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_pconnect()

    <?php
    printf("%-30s %s\n", "Версия PHP CUBRID:", cubrid_version());

    printf("\n");

    $conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Ошибка соединения ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Информация о сервере:", $server_info);
    printf("%-30s %s\n", "Информация о клиенте:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "Кодировка CUBRID:", $charset);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Версия PHP CUBRID:             9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Информация о сервере:             9.1.0.0212
    Информация о клиенте:             9.1.0

    Кодировка CUBRID:                iso8859-1

### Смотрите также

- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_connect_with_url() - Создаёт окружение для соединения с сервером CUBRID
- cubrid_pconnect_with_url() - Открывает постоянное соединение с сервером CUBRID
- cubrid_disconnect() - Закрывает соединение с базой данных
- cubrid_close() - Закрывает соединение с базой данных

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Открывает постоянное соединение с сервером CUBRID

### Описание

function cubrid_pconnect_with_url(string `$conn_url`, string `$userid` = ?, string `$passwd` = ?): resource

Устанавливает постоянное соединение с сервером CUBRID.

cubrid_pconnect_with_url() действует очень похоже на cubrid_connect_with_url() с двумя основными отличиями:

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

Во-вторых, соединение с SQL-сервером не будет закрыто по окончании выполнения скрипта. Вместо этого ссылка останется открытой для использования в будущем (cubrid_close() или cubrid_disconnect() не закроет ссылки, установленные cubrid_pconnect_with_url()).

Поэтому этот тип ссылки называется "постоянным".

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : Имя хоста или IP-адрес основной базы данных
- db_name : Имя базы данных
- db_user : Имя пользователя базы данных
- db_password : Пароль пользователя базы данных
- alhosts : Задаёт информацию о брокере резервного сервера, который будет использоваться в случае недоступности основного. Если вы зададите несколько резервных брокеров, то попытки соединения будут происходить в том же порядке, как они описаны в URL.
- rctime : Интервал между попытками подключения к активному брокеру, в котором произошёл сбой. После возникновения ошибки, система соединится с резервным брокером, указанным в althosts (failover), откатит незавершённые транзакции, и затем попытается соединиться с активным брокером основного узла через каждые rctime. Значение по умолчанию 600 секунд.
- login_timeout : Максимальное время (миллисекунды) ожидания авторизации. По умолчанию 0, что обозначает бесконечное время ожидания.
- query_timeout : Максимальное время (миллисекунды) ожидания выполнения запроса. По исчерпании этого времени на сервер будет отослано сообщение о прекращении запроса. Возвращённое значение запроса будет зависеть от настройки disconnect_on_query_timeout; даже если будет послано сообщение о прекращении запроса, он всё ещё может завершиться удачно.
- disconnect_on_query_timeout : Определяет, будет ли сразу после превышения времени ожидания запроса возвращена ошибка. По умолчанию `false`.

> Замечание: Символы `?` и `:` являются специальными в URL соединения и не могут быть использованы в пароле. Пример некорректного пароля, который нельзя использовать в строке соединения, потому, что в нем используются символы "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Пароли, содержащие `?` или `:` могут быть посланы отдельно. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_pconnect_with_url ($url, "dba", "12?"); Если логин или пароль пусты, необходимо всё равно сохранять символы "`:`": $url = "CUBRID:localhost:33000:demodb:::";

### Список параметров

`conn_url`
  Строка, содержащая информацию для соединения.
`userid`
  Имя пользователя базы данных.
`passwd`
  Пароль пользователя.

### Возвращаемые значения

Функция возвращает идентификатор соединения в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_pconnect_with_url() без задания свойств

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "соединение успешно выполнено";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

Пример #2 Пример использования функции cubrid_pconnect_with_url() с указанием URL со свойствами

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "соединение успешно выполнено";
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

### Смотрите также

- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_connect_with_url() - Создаёт окружение для соединения с сервером CUBRID
- cubrid_pconnect() - Открывает постоянное соединение с сервером CUBRID
- cubrid_disconnect() - Закрывает соединение с базой данных
- cubrid_close() - Закрывает соединение с базой данных

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Подготавливает SQL-выражение к выполнению

### Описание

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

Функция cubrid_prepare() компилирует SQL-выражение для данного дескриптора соединения и возвращает дескриптор, представляющий предварительно скомпилированное выражение.

Подготовленное выражение можно выполнять несколько раз, что эффективно при многократном выполнении или при обработке больших данных. Можно использовать только одно выражение, а параметр можно отметить вопросительным знаком (`?`) в соответствующем месте SQL-выражения. Добавьте параметр при привязке значения в выражении `VALUES` оператора `INSERT` или в выражении `WHERE`. Обратите внимание, что значение можно привязать к параметру только с помощью функции cubrid_bind().

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`prepare_stmt`
  Подготовленный запрос.
`option`
  Опция возврата OID `CUBRID_INCLUDE_OID`.

### Возвращаемые значения

Идентификатор запроса в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_prepare()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT g.event_code, e.name
    FROM game g
    JOIN event e ON g.event_code=e.code
    WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
    EOD;

    $req = cubrid_prepare($conn, $sql);

    cubrid_bind($req, 1, 2004);
    cubrid_bind($req, 2, 2000);
    cubrid_execute($req);

    $row_num = cubrid_num_rows($req);
    printf("%d соревнований пройдут на олимпиаде 2004, но не в 2000. Например:\n\n", $row_num);

    printf("%-15s %s\n", "Код соревнования", "Название");
    printf("----------------------------\n");

    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);
    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    27 соревнований пройдут на олимпиаде 2004, но не в 2000. Например:

    Код соревнования   Название
    ----------------------------
    20063           +91kg
    20070           64kg

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_bind() - Связывает переменные с подготовленным запросом

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Обновляет столбец с использованием OID

### Описание

function cubrid_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr` = ?,
mixed `$value`
): bool

Функция cubrid_put() используется для обновления атрибута экземпляра данного `oid`.

Вы можете обновить один атрибут, используя строковый тип данных для установки `attr`. В таком случае вы можете использовать данные целого числа, числа с плавающей запятой или числа строкового типа в качестве аргумента `value`. Чтобы обновить несколько атрибутов, вы можете пропустить аргумент `attr` и установить аргумент `value` в виде ассоциативного массива.

### Список параметров

`conn_identifier`
  Идентификатор соединения
`oid`
  OID экземпляра, который необходимо обновить
`attr`
  Имя атрибута, который необходимо обновить
`value`
  Новое значение, которое необходимо присвоить атрибуту

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Смотрите также

- cubrid_get() - Получает столбец, используя OID
- cubrid_set_add() - Вставляет один элемент для установки столбца типа с помощью OID
- cubrid_set_drop() - Удаляет элемент из столбца заданного типа, используя OID
- cubrid_seq_insert() - Вставляет элемент в столбец типа последовательности, используя OID
- cubrid_seq_drop() - Удаляет элемент из столбца типа последовательности, используя OID
- cubrid_seq_put() - Обновляет значение элемента столбца типа последовательности, используя OID

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Откат транзакции

### Описание

function cubrid_rollback(resource `$conn_identifier`): bool

Функция cubrid_rollback() выполняет откат транзакции, на которую указывает `conn_identifier`, которая в данный момент выполняется.

Соединение с сервером закрывается после вызова cubrid_rollback(). Однако дескриптор соединения всё ещё действителен.

### Список параметров

`conn_identifier`
  Connection identifier.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_rollback()

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
    cubrid_set_autocommit($conn,false);

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    if (!cubrid_execute($conn, $sql)) {
        printf("Ошибка объекта: %d\nКод ошибки: %d\nСообщение об ошибке: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Смотрите также

- cubrid_commit() - Подтверждение транзакции
- cubrid_disconnect() - Закрывает соединение с базой данных

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Получает запрошенную информацию о схеме

### Описание

function cubrid_schema(
resource `$conn_identifier`,
int `$schema_type`,
string `$class_name` = ?,
string `$attr_name` = ?
): array

Функция cubrid_schema() используется для получения запрошенной информации о схеме из базы данных. Вы должны указать `class_name`, если вы хотите получить информацию об определённом классе, `attr_name`, если вы хотите получить информацию об определённом атрибуте (может использоваться только с `CUBRID_SCH_ATTR_PRIVILEGE`).

Результат функции cubrid_schema() возвращается в виде двумерного массива (столбец(ассоциативный массив) * строка(числовой массив)). В следующих таблицах показаны типы схем и структура столбцов результирующего массива, которые должны быть возвращены на основе типа схемы.

Состав результата каждого типа
Схема | Номер столбца | Имя столбца | Значение
--- | --- | --- | ---
CUBRID_SCH_CLASS | 1 | NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_VCLASS | 1 | NAME |
| 2 | TYPE | 1:vclass
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`schema_type`
  Данные схемы, которые вы хотите узнать.
`class_name`
  Класс, для которого вы хотите узнать схему.
`attr_name`
  Атрибут, для которого вы хотите узнать схему.

### Возвращаемые значения

Массив, содержащий информацию о схеме, в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.1 | Изменено возвращаемое значение: если процесс завершился с ошибкой, возвращается false, а не -1.

### Примеры

Пример #1 Пример использования cubrid_schema()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    printf("\n--- Первичный ключ ---\n");
    $pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
    var_dump($pk);

    printf("\n--- Внешние ключи ---\n");
    $fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
    var_dump($fk);

    printf("\n--- Атрибут столбца ---\n");
    $attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
    var_dump($attr);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    --- Первичный ключ ---
    array(3) {
      [0]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "3"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [1]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "2"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [2]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(9) "host_year"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
    }

    --- Внешние ключи ---
    array(2) {
      [0]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(7) "athlete"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(20) "fk_game_athlete_code"
        ["PK_NAME"]=>
        string(15) "pk_athlete_code"
      }
      [1]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(5) "event"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(18) "fk_game_event_code"
        ["PK_NAME"]=>
        string(13) "pk_event_code"
      }
    }

    --- Атрибут столбца ---
    array(1) {
      [0]=>
      array(13) {
        ["ATTR_NAME"]=>
        string(4) "area"
        ["DOMAIN"]=>
        string(1) "7"
        ["SCALE"]=>
        string(1) "2"
        ["PRECISION"]=>
        string(2) "10"
        ["INDEXED"]=>
        string(1) "0"
        ["NON_NULL"]=>
        string(1) "0"
        ["SHARED"]=>
        string(1) "0"
        ["UNIQUE"]=>
        string(1) "0"
        ["DEFAULT"]=>
        NULL
        ["ATTR_ORDER"]=>
        string(1) "4"
        ["CLASS_NAME"]=>
        string(7) "stadium"
        ["SOURCE_CLASS"]=>
        string(7) "stadium"
        ["IS_KEY"]=>
        string(1) "0"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Удаляет элемент из столбца типа последовательности, используя OID

### Описание

function cubrid_seq_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`
): bool

Функция cubrid_seq_drop() используется для удаления элемента, который вы запрашиваете из данного атрибута типа последовательности в базе данных.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, с которым вы хотите работать.
`attr_name`
  Имя атрибута, из которого вы хотите удалить элемент.
`index`
  Индекс элемента, который вы хотите удалить (начиная с 1).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_seq_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_drop($conn, $oid, "c", 4);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(3) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
    }

### Смотрите также

- cubrid_seq_insert() - Вставляет элемент в столбец типа последовательности, используя OID
- cubrid_seq_put() - Обновляет значение элемента столбца типа последовательности, используя OID

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Вставляет элемент в столбец типа последовательности, используя OID

### Описание

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

Функция cubrid_seq_insert() используется для вставки элемента в атрибут типа последовательности в запрошенном месте.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, с которым вы хотите работать.
`attr_name`
  Имя атрибута, в который вы хотите вставить экземпляр.
`index`
  Расположение элемента, в который вы хотите вставить элемент (начиная с 1).
`seq_element`
  Содержимое элемента, который вы хотите вставить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_seq_insert()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(5) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
      [4]=>
      string(2) "44"
    }

### Смотрите также

- cubrid_seq_drop() - Удаляет элемент из столбца типа последовательности, используя OID
- cubrid_seq_put() - Обновляет значение элемента столбца типа последовательности, используя OID

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Обновляет значение элемента столбца типа последовательности, используя OID

### Описание

function cubrid_seq_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

Функция cubrid_seq_put() используется для обновления содержимого запрошенного элемента в атрибуте sequent type с использованием OID.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, с которым вы хотите работать.
`attr_name`
  Имя атрибута, который вы хотите обновить элемент.
`index`
  Индекс (начиная с 1) элемента, который вы хотите обновить.
`seq_element`
  Новый контент, который вы хотите использовать для обновления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_seq_put()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_put($conn, $oid, "c", 1, "111");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(4) {
      [0]=>
      string(3) "111"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }

### Смотрите также

- cubrid_seq_drop() - Удаляет элемент из столбца типа последовательности, используя OID
- cubrid_seq_insert() - Вставляет элемент в столбец типа последовательности, используя OID

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Вставляет один элемент для установки столбца типа с помощью OID

### Описание

function cubrid_set_add(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

Функция cubrid_set_add() используется для вставки одного элемента в заданный вами атрибут типа (set, multiset, sequence).

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  OID экземпляра, с которым вы хотите работать.
`attr_name`
  Имя атрибута, который вы хотите вставить элемент.
`set_element`
  Содержимое элемента, который вы хотите вставить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_set_add()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_add($conn, $oid, "b", "4");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(4) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
      [3]=>
      string(1) "4"
    }

### Смотрите также

- cubrid_seq_drop() - Удаляет элемент из столбца типа последовательности, используя OID

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Устанавливает режим авто-коммита для соединения

### Описание

function cubrid_set_autocommit(resource `$conn_identifier`, bool `$mode`): bool

Функция cubrid_set_autocommit() используется для установки режима авто-коммита для соединения.

В CUBRID PHP, авто-коммит транзакций по умолчанию запрещён. Если вы его включите, все ожидающие транзакции будут автоматически подтверждены.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`mode`
  Режим авто-коммита. Одна из двух констант:
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- cubrid_get_autocommit() - Возвращает настройку авто-коммита для соединения
- cubrid_commit() - Подтверждение транзакции

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Устанавливает параметры базы данных CUBRID

### Описание

function cubrid_set_db_parameter(resource `$conn_identifier`, int `$param_type`, int `$param_value`): bool

Функция cubrid_set_db_parameter() используется для установки параметров базы данных CUBRID. Он может установить следующие параметры базы данных CUBRID:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`

> Замечание: Режим автоматической фиксации может быть установлен с помощью cubrid_set_autocommit().

### Список параметров

`conn_identifier`
  CUBRID соединение. Если идентификатор соединения не указан, предполагается последняя ссылка, открываемая cubrid_connect().
`param_type`
  Тип параметра базы данных.
`param_value`
  Значение уровня изоляции (1-6) или значение времени ожидания блокировки (в секундах).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_get_db_parameter()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $params = cubrid_get_db_parameter($conn);
    var_dump($params);

    cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
    cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

    $params_new = cubrid_get_db_parameter($conn);
    var_dump($params_new);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(3)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(0)
    }
    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(2)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(1)
    }

### Смотрите также

- cubrid_get_db_parameter() - Возвращает параметры базы данных CUBRID
- cubrid_set_autocommit() - Устанавливает режим авто-коммита для соединения

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Удаляет элемент из столбца заданного типа, используя OID

### Описание

function cubrid_set_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

Функция cubrid_set_drop() используется для удаления элемента, который вы запрашиваете из заданного атрибута типа набора (set, multiset) базы данных.

### Список параметров

`conn_identifier`
  Connection identifier.
`oid`
  OID экземпляра, с которым вы хотите работать.
`attr_name`
  Имя атрибута, из которого вы хотите удалить элемент.
`set_element`
  Содержимое элемента, который вы хотите удалить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_set_drop()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_drop($conn, $oid, "b", "1");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### Смотрите также

- cubrid_set_add() - Вставляет один элемент для установки столбца типа с помощью OID

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Устанавливает время ожидания выполнения запроса

### Описание

function cubrid_set_query_timeout(resource `$req_identifier`, int `$timeout`): bool

Функция cubrid_set_query_timeout() используется для установки времени ожидания выполнения запроса.

### Список параметров

`req_identifier`
  Request identifier.
`timeout`
  Время ожидания, в миллисекундах.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- cubrid_get_query_timeout() - Получает значение времени ожидания запроса

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Получить версию модуля CUBRID PHP

### Описание

function cubrid_version(): string

Функция cubrid_version() используется для получения версии модуля CUBRID PHP.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Информация о версии (например "8.3.1.0001").

### Примеры

Пример #1 Пример использования cubrid_version()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Смотрите также

- cubrid_error_code() - Получить код ошибки
- cubrid_error_code_facility() - Получить код уровня, на котором произошла ошибка

## Содержание

- cubrid_bind — Связывает переменные с подготовленным запросом
- cubrid_close_prepare — Закрывает обработчик запроса
- cubrid_close_request — Закрывает обработчик запроса
- cubrid_col_get — Получение контента столбца типа коллекция по OID
- cubrid_col_size — Получает количество элементов в столбце типа коллекция по OID
- cubrid_column_names — Получить имена столбцов в результирующем наборе
- cubrid_column_types — Получить типы столбцов в результирующем наборе
- cubrid_commit — Подтверждение транзакции
- cubrid_connect — Открывает соединение к серверу CUBRID
- cubrid_connect_with_url — Создаёт окружение для соединения с сервером CUBRID
- cubrid_current_oid — Возвращает OID текущей позиции курсора
- cubrid_disconnect — Закрывает соединение с базой данных
- cubrid_drop — Удаление экземпляра по OID
- cubrid_error_code — Получить код ошибки
- cubrid_error_code_facility — Получить код уровня, на котором произошла ошибка
- cubrid_error_msg — Возвращает текст последней произошедшей ошибки
- cubrid_execute — Выполняет подготовленный SQL-оператор
- cubrid_fetch — Выбирает следующую строку из набора результатов
- cubrid_free_result — Освобождает память, занятую данными результата
- cubrid_get — Получает столбец, используя OID
- cubrid_get_autocommit — Возвращает настройку авто-коммита для соединения
- cubrid_get_charset — Возвращает кодировку текущего соединения CUBRID
- cubrid_get_class_name — Получает имя класса с помощью OID
- cubrid_get_client_info — Возвращает версию клиентской библиотеки
- cubrid_get_db_parameter — Возвращает параметры базы данных CUBRID
- cubrid_get_query_timeout — Получает значение времени ожидания запроса
- cubrid_get_server_info — Возвращает версию сервера CUBRID
- cubrid_insert_id — Возвращает идентификатор, сгенерированный для последнего обновлённого столбца AUTO_INCREMENT
- cubrid_is_instance — Проверяет, существует ли экземпляр, на который указывает OID
- cubrid_lob_close — Закрывает данные BLOB/CLOB
- cubrid_lob_export — Экспортирует данные BLOB/CLOB в файл
- cubrid_lob_get — Получает данные BLOB/CLOB
- cubrid_lob_send — Читает данные BLOB/CLOB и отправляет их прямо в браузер
- cubrid_lob_size — Получает размер данных BLOB/CLOB
- cubrid_lob2_bind — Связывает объект LOB или строку в виде объекта LOB с подготовленным оператором в качестве параметров
- cubrid_lob2_close — Закрывает объект LOB
- cubrid_lob2_export — Экспортирует LOB-объект в файл
- cubrid_lob2_import — Импортирует данные BLOB/CLOB из файла
- cubrid_lob2_new — Создаёт объект LOB
- cubrid_lob2_read — Производит чтение из данных BLOB/CLOB
- cubrid_lob2_seek — Перемещает курсор LOB-объекта
- cubrid_lob2_seek64 — Перемещает курсор LOB-объекта
- cubrid_lob2_size — Получает размер LOB-объекта
- cubrid_lob2_size64 — Получает размер LOB-объекта
- cubrid_lob2_tell — Сообщает положение курсора LOB-объекта
- cubrid_lob2_tell64 — Сообщает положение курсора LOB-объекта
- cubrid_lob2_write — Записывает в LOB-объект
- cubrid_lock_read — Устанавливает блокировку чтения для данного OID
- cubrid_lock_write — Устанавливает блокировку записи для данного OID
- cubrid_move_cursor — Перемещает курсор в результате
- cubrid_next_result — Получает результат следующего запроса при выполнении нескольких SQL-операторов
- cubrid_num_cols — Возвращает количество столбцов в наборе результатов
- cubrid_num_rows — Получить количество строк в наборе результатов
- cubrid_pconnect — Открывает постоянное соединение с сервером CUBRID
- cubrid_pconnect_with_url — Открывает постоянное соединение с сервером CUBRID
- cubrid_prepare — Подготавливает SQL-выражение к выполнению
- cubrid_put — Обновляет столбец с использованием OID
- cubrid_rollback — Откат транзакции
- cubrid_schema — Получает запрошенную информацию о схеме
- cubrid_seq_drop — Удаляет элемент из столбца типа последовательности, используя OID
- cubrid_seq_insert — Вставляет элемент в столбец типа последовательности, используя OID
- cubrid_seq_put — Обновляет значение элемента столбца типа последовательности, используя OID
- cubrid_set_add — Вставляет один элемент для установки столбца типа с помощью OID
- cubrid_set_autocommit — Устанавливает режим авто-коммита для соединения
- cubrid_set_db_parameter — Устанавливает параметры базы данных CUBRID
- cubrid_set_drop — Удаляет элемент из столбца заданного типа, используя OID
- cubrid_set_query_timeout — Устанавливает время ожидания выполнения запроса
- cubrid_version — Получить версию модуля CUBRID PHP

# Функции совместимости CUBRID MySQL

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Возвращает количество строк, которые затронул последний SQL-запрос

### Описание

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function cubrid_affected_rows(resource `$req_identifier` = ?): int

Функция cubrid_affected_rows() получает количество строк, которые затронул последний SQL-запрос наподобие INSERT, DELETE или UPDATE.

### Список параметров

`conn_identifier`
  Идентификатор соединения CUBRID. Если не задали, функция возьмёт последнее соединение, которое открыли функцией cubrid_connect().
`req_identifier`
  Идентификатор запроса, который вернули функции cubrid_prepare() или cubrid_execute(). Функция использует последний запрос, который вернули функции cubrid_prepare() или cubrid_execute(), если значение параметра не задали.

### Возвращаемые значения

Функция в случае успешного выполнения возвращает количество строк, которые затронул последний SQL-запрос.

Функция возвращает значение -1, если тип запроса не соответствовал INSERT, DELETE или UPDATE.

Функция возвращает `false`, если идентификатор запроса не указали и отсутствуют выполненные запросы.

### Примеры

Пример #1 Пример использования функции cubrid_affected_rows()

    <?php

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
    $sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
    $req = cubrid_prepare($conn, $sql_stmt);

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($req);
    }
    cubrid_commit($conn);

    $req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
    var_dump(cubrid_affected_rows());
    var_dump(cubrid_affected_rows($conn));
    var_dump(cubrid_affected_rows($req));

    cubrid_disconnect($conn);

    print "Готово!";

    ?>

Результат выполнения приведённого примера:

    int(10)
    int(10)
    int(10)
    Готово!

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Возвращает кодировку текущего соединения CUBRID

### Описание

function cubrid_client_encoding(resource `$conn_identifier` = ?): string

Функция возвращает кодировку текущего соединения CUBRID и аналогична функции cubrid_get_encoding().

### Список параметров

`conn_identifier`
  Идентификатор соединения. Если не задано, то будет использовано последнее открытое с помощью cubrid_connect() соединение.

### Возвращаемые значения

Строка, содержащая кодировку текущего соединения CUBRID в случае успешного выполнения.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_client_encoding()

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Не получилось подключиться.');
    }

    printf("Текущая кодировка CUBRID: %s\n", cubrid_client_encoding($con));

    ?>

Результат выполнения приведённого примера:

    Текущая кодировка CUBRID: iso8859-1

### Смотрите также

- cubrid_get_charset() - Возвращает кодировку текущего соединения CUBRID

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Закрывает соединение с базой данных

### Описание

function cubrid_close(resource `$conn_identifier` = ?): bool

Функция cubrid_close() используется для закрытия обработчика соединения и отсоединения от сервера. Если какой-либо обработчик запроса не будет закрыт к этому моменту, он будет принудительно закрыт. Функция аналогична функции CUBRID cubrid_disconnect().

### Список параметров

`conn_identifier`
  Идентификатор соединения. Если не задано, то будет использовано последнее открытое с помощью cubrid_connect() соединение.

### Возвращаемые значения

`true`, в случае успешного выполнения.

`false`, в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_close()

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "подключение успешно выполнено";
       $req = cubrid_execute ( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_close ($con);
    }
    ?>

### Смотрите также

- cubrid_disconnect() - Закрывает соединение с базой данных
- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_connect_with_url() - Создаёт окружение для соединения с сервером CUBRID

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Перемещает внутренний указатель строки в наборе результатов CUBRID-запроса

### Описание

function cubrid_data_seek(resource `$result`, int `$row_number`): bool

Функция перемещает внутренний указатель строки результатов CUBRID-запроса на строку, номер которой указали в аргументе `row_number`. Функция работает с указателем, который связан с заданным идентификатором набора результатов. Функции наподобие cubrid_fetch_assoc() хранят текущее значение с номером строки.

### Список параметров

`result`
  Результат.
`row_number`
  Номер строки, который требуется установить как новое значение указателя в наборе результатов.

### Возвращаемые значения

Функция возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_data_seek()

    <?php

    $conn = cubrid_connect("127.0.0.1", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_data_seek($req, 0);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 2);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 4);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }
    array(2) {
      [0]=>
      string(1) "S"
      [1]=>
      string(6) "Silver"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Получает имя базы данных из результата функции cubrid_list_dbs

### Описание

function cubrid_db_name(array `$result`, int `$index`): string

Функция извлекает имя базы данных из результата вызова функции cubrid_list_dbs().

### Список параметров

`result`
  Указатель на результат вызова функции cubrid_list_dbs().
`index`
  Индекс в результирующем наборе.

### Возвращаемые значения

Функция возвращает имя базы данных в случае успешного выполнения или `false`, если возникла ошибка. Если вернулось `false`, функция cubrid_error() поможет определить причину ошибки.

### Примеры

Пример #1 Пример использования функции cubrid_db_name()

    <?php

    error_reporting(E_ALL);

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $db_list = cubrid_list_dbs($conn);

    $i = 0;
    $cnt = count($db_list);
    while ($i < $cnt) {
        echo cubrid_db_name($db_list, $i) . "\n";
        $i++;
    }

    ?>

Результат выполнения приведённого примера:

    demodb

### Смотрите также

- cubrid_list_dbs() - Получает массив со списком баз данных CUBRID

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Возвращает код ошибки предыдущей операции CUBRID

### Описание

function cubrid_errno(resource `$conn_identifier` = ?): int

Возвращает код ошибки предыдущей операции CUBRID.

Функция cubrid_errno() используется для получения кода произошедшей ошибки. Обычно вы можете получить код ошибки, если какая-либо функция вернула `false`.

### Список параметров

`conn_identifier`
  Идентификатор соединения. Если не задано, то будет использовано последнее открытое с помощью cubrid_connect() соединение.

### Возвращаемые значения

Код возникшей ошибки, или `0` (ноль), если ошибки не было.

### Примеры

Пример #1 Пример использования cubrid_errno()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Код ошибки: ", cubrid_errno($con);
        echo "Текст ошибки: ", cubrid_error($con);
    }
    ?>

Результат выполнения приведённого примера:

    Код ошибки: -493 Текст ошибки: Syntax: Unknown class "person". select id, [name] from person

### Смотрите также

- cubrid_error() - Возвращает текст последней произошедшей ошибки
- cubrid_error_code() - Получить код ошибки
- cubrid_error_msg() - Возвращает текст последней произошедшей ошибки

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Возвращает текст последней произошедшей ошибки

### Описание

function cubrid_error(resource `$connection` = ?): string

Функция cubrid_error() используется для получения текста произошедшей ошибки. Обычно вы можете получить текст ошибки, если какая-либо функция вернула `false`.

### Список параметров

`connection`
  Идентификатор соединения.

### Возвращаемые значения

Текст ошибки.

### Примеры

Пример #1 Пример использования cubrid_error()

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Код ошибки: ", cubrid_errno($con);
        echo "Текст ошибки: ", cubrid_error($con);
    }
    ?>

Результат выполнения приведённого примера:

    Код ошибки: -493 Текст ошибки: Syntax: Unknown class "person". select id, [name] from person

### Смотрите также

- cubrid_errno() - Возвращает код ошибки предыдущей операции CUBRID
- cubrid_error_code() - Получить код ошибки
- cubrid_error_msg() - Возвращает текст последней произошедшей ошибки

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу

### Описание

function cubrid_fetch_array(resource `$result`, int `$type` = CUBRID_BOTH): array

Функция cubrid_fetch_array() извлекает одну строку из результирующего набора. После извлечения курсор автоматически передвинется на следующую строку.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute().
`type`
  Тип массива для извлечения: CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. Если вам нужно оперировать объектами типа LOB - используйте CUBRID_LOB.

### Возвращаемые значения

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

`false`, если строк больше нет; NULL, когда процесс завершается с ошибкой.

Тип возвращаемого массива зависит от заданного типа. По умолчанию используется CUBRID_BOTH, что ведёт к извлечению как ассоциативного, так и индексированного массивов, но это поведение можно переопределить параметром `type`. Значения, допустимые для параметра `type`:

- CUBRID_NUM : Индексированный массив (первый элемент имеет индекс 0)
- CUBRID_ASSOC : Ассоциативный массив
- CUBRID_BOTH : И тот и другой одновременно (по умолчанию)

### Примеры

Пример #1 Пример использования функции cubrid_fetch_array()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // Если вам нужно оперировать объектами LOB - используйте
    // cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_fetch() - Выбирает следующую строку из набора результатов
- cubrid_fetch_row() - Извлекает строку из результирующего набора в виде индексного массива
- cubrid_fetch_assoc() - Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_fetch_object() - Извлекает следующую строку как объект

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Извлекает строку из результирующего набора в виде ассоциативного массива

### Описание

function cubrid_fetch_assoc(resource `$result`, int `$type` = ?): array

Функция возвращает ассоциативный массив, соответствующей строке в результирующем наборе на которую указывает внутренний указатель. После извлечения внутренний указатель перемещается на следующую строку. Если строки закончились, то функция вернёт `false`.

### Список параметров

`result`
  `Result`, полученный из cubrid_execute()
`type`
  Может быть только CUBRID_LOB. Этот параметр используется только если вам необходимо оперировать объектами LOB.

### Возвращаемые значения

Функция возвращает ассоциативный массив в случае успешного выполнения.

Функция возвращает `false`, если строк больше нет; `null`, когда процесс завершается с ошибкой.

### Примеры

Пример #1 Пример использования функции cubrid_fetch_assoc()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_assoc($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // Если вам нужно оперировать объектами LOB - используйте
    // cubrid_fetch_assoc($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_fetch() - Выбирает следующую строку из набора результатов
- cubrid_fetch_row() - Извлекает строку из результирующего набора в виде индексного массива
- cubrid_fetch_array() - Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
- cubrid_fetch_object() - Извлекает следующую строку как объект

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Получает информацию о столбце набора результатов в виде объекта

### Описание

function cubrid_fetch_field(resource `$result`, int `$field_offset` = 0): object

Функция возвращает объект, в свойствах которого содержится информация о столбце. Свойства объекта:

`name`
  имя столбца
`table`
  имя таблицы
`def`
  значение столбца по умолчанию
`max_length`
  максимальная длина столбца
`not_null`
  1, если не может быть NULL
`primary_key`
  1, если является первичным ключом
`unique_key`
  1, если является уникальным ключом
`multiple_key`
  1, если является неуникальным ключом
`numeric`
  1, если содержит числовое значение
`blob`
  1, если содержит BLOB
`type`
  тип столбца
`unsigned`
  1, если беззнаковый тип
`zerofill`
  1, если дополняется нулями

### Список параметров

`result`
  `Result`, полученный из cubrid_execute()
`field_offset`
  Числовой индекс столбца. Если не задан, то будет извлечён следующий, не извлечённый этой функцией, столбец. `field_offset` начинается с нуля.

### Возвращаемые значения

Функция возвращает объект с описанными свойствами в случае успешного выполнения.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения функцией cubrid_fetch_field() информации о столбце в наборе результатов

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "имя столбца:", $field->name);
    printf("%-30s %s\n", "имя таблицы:", $field->table);
    printf("%-30s \"%s\"\n", "значение столбца по умолчанию:", $field->def);
    printf("%-30s %d\n", "максимальная длина столбца:", $field->max_length);
    printf("%-30s %d\n", "не может быть NULL:", $field->not_null);
    printf("%-30s %d\n", "является первичным ключом:", $field->primary_key);
    printf("%-30s %d\n", "является уникальным ключом:", $field->unique_key);
    printf("%-30s %d\n", "является неуникальным ключом:", $field->multiple_key);
    printf("%-30s %d\n", "содержит числовое значение:", $field->numeric);
    printf("%-30s %d\n", "содержит BLOB:", $field->blob);
    printf("%-30s %s\n", "тип столбца:", $field->type);
    printf("%-30s %d\n", "беззнаковый тип:", $field->unsigned);
    printf("%-30s %d\n", "дополняется нулями:", $field->zerofill);

    cubrid_close_request($req);

    cubrid_disconnect($conn);

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16681"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-9-30"
    }

    --- Field Properties ---
    имя столбца:                         athlete_code
    имя таблицы:                         game
    значение столбца по умолчанию:          ""
    максимальная длина столбца:             0
    не может быть NULL:                  1
    является первичным ключом:             1
    является уникальным ключом:            1
    является неуникальным ключом:           0
    содержит числовое значение:             1
    содержит BLOB:                       0
    тип столбца:                         integer
    беззнаковый тип:                      0
    дополняется нулями:                    0

# cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Возвращает массив, содержащий длины всех столбцов текущей строки

### Описание

function cubrid_fetch_lengths(resource `$result`): array

Функция возвращает индексированный массив, содержащий длины столбцов в текущей строке из результирующего набора, или `false` в случае возникновения ошибки.

> Замечание: Если столбец типа BLOB/CLOB, то для получения его длины используйте cubrid_lob_size().

### Список параметров

`result`
  `Result` полученный из cubrid_execute()

### Возвращаемые значения

Индексированный массив.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_fetch_lengths()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $row = cubrid_fetch_row($result);
    print_r($row);

    $lens = cubrid_fetch_lengths($result);
    print_r($lens);

    cubrid_disconnect($conn);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => 2004
        [1] => 20085
        [2] => 15118
        [3] => 30134
        [4] => AUS
        [5] => G
        [6] => 2004-8-20
    )
    Array
    (
        [0] => 4
        [1] => 5
        [2] => 5
        [3] => 5
        [4] => 3
        [5] => 1
        [6] => 10
    )

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Извлекает следующую строку как объект

### Описание

function cubrid_fetch_object(
resource `$result`,
string `$class_name` = ?,
array `$params` = ?,
int `$type` = ?
): object

Функция возвращает объект со свойствами, имена которых равны именам столбцов результирующего набора, а значения, соответственно, значениям.

### Список параметров

`result`
  `Result` полученный из cubrid_execute()
`class_name`
  Имя класса, который будет использован для создания объекта. Если не задано, то будет использован stdClass (stdClass - базовый, пустой, класс PHP, который используется при преобразовании прочих типов в объекты).
`params`
  Необязательный массив параметров для передачи в конструктор `class_name`.
`type`
  Допускается только CUBRID_LOB. Используется при работе с объектами типа LOB.

### Возвращаемые значения

Функция возвращает объект, в случае успешного выполнения.

Функция возвращает `false`, если строк больше нет; `null`, когда процесс завершается с ошибкой.

### Примеры

Пример #1 Пример использования функции cubrid_fetch_object()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $res = cubrid_execute($conn, "SELECT * FROM code");

    var_dump(cubrid_fetch_object($res));

    // В случае работы с LOB используйте cubrid_fetch_object($res, CUBRID_LOB)

    class demodb_code {
        public $s_name = null;
        public $f_name = null;

        public function toString() {
            var_dump($this);
        }
    }

    var_dump(cubrid_fetch_object($res, "demodb_code"));

    // В случае работы с LOB используйте cubrid_fetch_object($res, "demodb_code", CUBRID_LOB)

    class demodb_code_construct extends demodb_code {
        public function __construct($s, $f) {
            $this->s_name = $s;
            $this->f_name = $f;
        }
    }

    var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

    // В случае работы с LOB используйте cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    var_dump(cubrid_fetch_object($res));

    cubrid_close_request($res);
    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "X"
      ["f_name"]=>
      string(5) "Mixed"
    }
    object(demodb_code)#1 (2) {
      ["s_name"]=>
      string(1) "W"
      ["f_name"]=>
      string(5) "Woman"
    }
    object(demodb_code_construct)#1 (2) {
      ["s_name"]=>
      string(6) "s_name"
      ["f_name"]=>
      string(6) "f_name"
    }
    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "B"
      ["f_name"]=>
      string(6) "Bronze"
    }

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_fetch() - Выбирает следующую строку из набора результатов
- cubrid_fetch_array() - Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
- cubrid_fetch_assoc() - Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_fetch_row() - Извлекает строку из результирующего набора в виде индексного массива

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Извлекает строку из результирующего набора в виде индексного массива

### Описание

function cubrid_fetch_row(resource `$result`, int `$type` = ?): array

Функция возвращает ассоциативный массив, соответствующей строке в результирующем наборе на которую указывает внутренний указатель. После извлечения внутренний указатель перемещается на следующую строку. Первый элемент имеет индекс 0.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute().
`type`
  Допускается только CUBRID_LOB. Функция использует этот параметр, только когда требуется оперировать объектами LOB.

### Возвращаемые значения

Функция возвращает индексный массив в случае успешного выполнения.

Функция возвращает `false`, если строк больше нет; `null`, когда процесс завершается с ошибкой.

### Примеры

Пример #1 Пример использования функции cubrid_fetch_row()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "наименование", "площадь", "мест", "адрес");
    while ($row = cubrid_fetch_row($req)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // При работе с объектами LOB вызывают cubrid_fetch_row($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    наименование                                площадь     мест  адрес
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Смотрите также

- cubrid_execute() - Выполняет подготовленный SQL-оператор
- cubrid_fetch() - Выбирает следующую строку из набора результатов
- cubrid_fetch_array() - Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
- cubrid_fetch_assoc() - Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_fetch_object() - Извлекает следующую строку как объект

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Получает строку, которая содержит флаги столбца по заданному индексу

### Описание

function cubrid_field_flags(resource `$result`, int `$field_offset`): string

Функция возвращает строку, содержащую флаги столбца по указанному индексу, разделённые пробелом. Вы можете разбить строку на отдельные части с помощью explode. Возможные значения флагов: `not_null`, `primary_key`, `unique_key`, `foreign_key`, `auto_increment`, `shared`, `reverse_index`, `reverse_unique` и `timestamp`.

### Список параметров

`result`
  `Result` полученный из cubrid_execute()
`field_offset`
  Индекс поля в строке результирующего набора. Значение параметра `field_offset` начинается с 0. Если значение `field_offset` не задали, функция вызовет ошибку уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает строку с флагами в случае успешного выполнения.

Функция возвращает `false` в случае некорректного значения field_offset.

Функция возвращает -1, если SQL-запрос отличался от SELECT.

### Примеры

Пример #1 Пример использования функции cubrid_field_flags()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Имя поля", "Флаги поля");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Наименование поля                Флаги поля
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Получает максимальную длину указанного столбца

### Описание

function cubrid_field_len(resource `$result`, int `$field_offset`): int

Функция возвращает максимальную длину указанного столбца в случае успешного выполнения или `false`, если возникла ошибка.

### Список параметров

`result`
  `Result` полученный из cubrid_execute()
`field_offset`
  Индекс поля в строке результирующего набора. Значение `field_offset` начинается с 0. Если значение параметра `field_offset` не задали, функция вызовет ошибку уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает максимальную длину в случае успешного выполнения.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_field_len()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Наименование столбца", "Тип столбца", "Максимальная длина столбца");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Наименование столбца                   Тип столбца                   Максимальная длина столбца
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Получает имя заданного столбца

### Описание

function cubrid_field_name(resource `$result`, int `$field_offset`): string

Функция возвращает имя заданного столбца в случае успешного выполнения или `false`, если возникла ошибка.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute().
`field_offset`
  Индекс поля в строке результирующего набора. `field_offset` начинается с 0. Если `field_offset` не задан, то будет вызвана ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает имя столбца в случае успешного выполнения.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_field_name()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Наименование поля", "Флаги поля");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Наименование поля                 Флаги поля
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Перемещает внутренний указатель результирующего набора на заданный столбец

### Описание

function cubrid_field_seek(resource `$result`, int `$field_offset` = 0): bool

Функция перемещает внутренний указатель результирующего набора на указанный столбец. Это смещение используется функцией cubrid_fetch_field(), если не указан параметр offset. Возвращает `true` либо `false` в зависимости от успешности выполнения.

### Список параметров

`result`
  Значение `result`, который вернула функция cubrid_execute().
`field_offset`
  Индекс поля в строке результирующего набора. `field_offset` начинается с 0. Если `field_offset` не задан, то будет вызвана ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true` в случае успешного выполнения.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_field_seek()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Свойства поля ---\n");
    printf("%-30s %s\n", "имя столбца:", $field->name);
    printf("%-30s %s\n", "имя таблицы:", $field->table);
    printf("%-30s \"%s\"\n", "значение столбца по умолчанию:", $field->def);
    printf("%-30s %d\n", "максимальная длина столбца:", $field->max_length);
    printf("%-30s %d\n", "не может быть NULL:", $field->not_null);
    printf("%-30s %d\n", "является уникальным ключом:", $field->unique_key);
    printf("%-30s %d\n", "является неуникальным ключом:", $field->multiple_key);
    printf("%-30s %d\n", "содержит числовое значение:", $field->numeric);
    printf("%-30s %s\n", "тип столбца:", $field->type);

    cubrid_close_request($req);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16132"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-09-30"
    }

    --- Свойства поля ---
    имя столбца:                         athlete_code
    имя таблицы:                         game
    значение столбца по умолчанию:           ""
    максимальная длина столбца:             0
    не может быть NULL:                  1
    является уникальным ключом:             1
    является неуникальным ключом:           0
    содержит числовое значение:             1
    тип столбца:                          integer

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Получает имя таблицы, которой принадлежит столбец

### Описание

function cubrid_field_table(resource `$result`, int `$field_offset`): string

Функция возвращает имя таблицы, которая содержит указанный столбец. Функция полезна при работе с большими JOIN-запросами.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute()
`field_offset`
  Индекс поля в строке результирующего набора. `field_offset` начинается с 0. Если `field_offset` не задан, то будет вызвана ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает имя таблицы в случае успешного выполнения.

Функция возвращает `false` если задали некорректное значение field_offset.

Функция возвращает -1, если SQL-запрос отличался от SELECT.

### Примеры

Пример #1 Пример использования функции cubrid_field_table()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Таблица поля", "Наименовение поля", "Тип поля");

    for($i = 0; $i < $col_num; $i++) {
        printf(
            "%-15s %-15s %s\n",
            cubrid_field_table($result, $i),
            cubrid_field_name($result, $i),
            cubrid_field_type($result, $i)
        );
    }

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Таблица поля      Наименовение поля  Тип поля
    code            s_name          char
    code            f_name          varchar

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Получает тип столбца

### Описание

function cubrid_field_type(resource `$result`, int `$field_offset`): string

Функция возвращает тип столбца. Тип принимает следующие значения: "int", "real", "string" и т. д.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute().
`field_offset`
  Индекс поля в строке результирующего набора. `field_offset` начинается с 0. Если `field_offset` не задан, то будет вызвана ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает тип столбца в случае успешного выполнения.

Функция возвращает `false`, если задали некорректное значение field_offset.

Функция возвращает -1, если SQL-запрос отличался от SELECT.

### Примеры

Пример #1 Пример использования функции cubrid_field_type()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Таблица поля", "Наименование поля", "Тип поля");

    for($i = 0; $i < $col_num; $i++) {
        printf(
            "%-15s %-15s %s\n",
            cubrid_field_table($result, $i),
            cubrid_field_name($result, $i),
            cubrid_field_type($result, $i)
        );
    }

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Таблица поля      Наименование поля  Тип поля
    code            s_name          char
    code            f_name          varchar

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Получает массив со списком баз данных CUBRID

### Описание

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

Функция возвращает массив со списком баз данных CUBRID

### Список параметров

`conn_identifier`
  The CUBRID connection.

### Возвращаемые значения

Функция возвращает индексный массив со списком баз данных.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_list_dbs()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");

    $db_list = cubrid_list_dbs($conn);
    var_dump($db_list);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    array(1) {
      [0]=>
      string(6) "demodb"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Получает количество столбцов в результирующем наборе

### Описание

function cubrid_num_fields(resource `$result`): int

Функция возвращает количество столбцов в результирующем наборе или `false`, если возникла ошибка.

### Список параметров

`result`
  `result`, полученный из cubrid_execute(), cubrid_query() или cubrid_prepare()

### Возвращаемые значения

Функция возвращает количество столбцов в случае успешного выполнения.

Функция возвращает -1, если SQL-запрос отличался от SELECT.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_num_fields()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_fields($req);

    printf("Количество строк: %d\nКоличество столбцов: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    Количество строк: 6
    Количество столбцов: 2

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Проверяет, живо ли соединение к серверу и переподключает его, если нет

### Описание

function cubrid_ping(resource `$conn_identifier` = ?): bool

Проверяет, живо ли соединение к серверу.

### Список параметров

`conn_identifier`
  Идентификатор соединения. Если не задано, то будет использовано последнее открытое с помощью cubrid_connect() соединение.

### Возвращаемые значения

Возвращает `true`, если соединение работает, иначе `false`.

### Примеры

Пример #1 Пример использования cubrid_ping()

    <?php
    set_time_limit(0);

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    /* Предположим, что это ну очень длинный запрос */
    $sql = "select * from athlete";
    $result = cubrid_query($sql);
    if (!$result) {
        echo 'Запрос #1 завершился с ошибкой, выходим.';
        exit;
    }

    /* Проверяем, живо ли ещё соединение и пересоздаем его, если нет */
    if (!cubrid_ping($conn)) {
        echo 'Потеряно соединение, выходим после запроса #1';
        exit;
    }
    cubrid_free_result($result);

    /* Так так, соединение работает. Тогда ещё один запрос! */
    $sql2 = "select * from code";
    $result2 = cubrid_query($sql2);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Отправляет запрос CUBRID

### Описание

function cubrid_query(string `$query`, resource `$conn_identifier` = ?): resource

Функция cubrid_query() посылает уникальный запрос (множественные запросы не поддерживаются) текущей активной базе данных, заданной идентификатором соединения `conn_identifier`.

### Список параметров

`query`
  SQL-запрос Данные в запросе должны быть корректно экранированы.
`conn_identifier`
  Идентификатор соединения. Если не задано, то будет использовано последнее, открытое с помощью cubrid_connect() соединение.

### Возвращаемые значения

Для SELECT, SHOW, DESCRIBE, EXPLAIN и прочих запросов, которые возвращают результирующий набор, функция cubrid_query() возвращает resource в случае успешного выполнения и `false`, если возникла ошибка.

Для других типов SQL-запросов наподобие INSERT, UPDATE, DELETE, DROP и т. д функция cubrid_query() возвращает `true` или `false` в зависимости от результата выполнения.

Возвращённый результат можно передавать в функцию cubrid_fetch_array() и ей подобные для работы с полученными данными.

Используйте cubrid_num_rows() для определения количества возвращённых оператором SELECT строк или cubrid_affected_rows() для определения количества затронутых строк, для запросов изменяющих данные, таких как DELETE, INSERT, REPLACE и UPDATE.

cubrid_query() также может завершиться с ошибкой и вернуть `false`, если пользователь не имеет прав на доступ к таблице, используемой в запросе.

### Примеры

Пример #1 Некорректный запрос

Следующий запрос содержит синтаксическую ошибку, так что cubrid_query() вернёт `false`.

    <?php

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    $result = cubrid_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Некорректный запрос: ' . cubrid_error());
    }

    ?>

Пример #2 Корректный запрос

Следующий запрос корректен, так что cubrid_query() вернёт resource.

    <?php
    // Какие нибудь значения
    $firstname = 'fred';
    $lastname  = 'fox';

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    cubrid_execute($conn,"DROP TABLE if exists friends");
    cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
    cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
    cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
    // Сформулируем запрос
    // Это лучший путь для выполнения запроса
    // Другие примеры смотрите cubrid_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
    cubrid_real_escape_string($firstname),
    cubrid_real_escape_string($lastname));

    // Выполняем запрос
    $result = cubrid_query($query);

    // Проверяем результат
    // Показывает сам запрос и ошибку. полезно при отладке.
    if (!$result) {
        $message  = 'Некорректный запрос: ' . cubrid_error() . "\n";
        $message .= 'Всего запросов: ' . $query;
        die($message);
    }

    // Используем результат
    // Попытка распечатать $result не позволит получить доступ к информации в ресурсе
    // Должна быть использована одна из функций cubrid
    // Смотрите cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row() и т.д.
    while ($row = cubrid_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Освобождаем ресурсы. В принципе можно и не делать, так как
    // они будут автоматически освобождены после завершения работы скрипта
    cubrid_free_result($result);
    ?>

### Смотрите также

- cubrid_connect() - Открывает соединение к серверу CUBRID
- cubrid_error() - Возвращает текст последней произошедшей ошибки
- cubrid_real_escape_string() - Экранирует специальные символы в SQL-запросе
- cubrid_result() - Получает значение конкретного поля конкретной строки
- cubrid_fetch_assoc() - Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_unbuffered_query() - Выполняет запрос без загрузки результата в память

# cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Экранирует специальные символы в SQL-запросе

### Описание

function cubrid_real_escape_string(string `$unescaped_string`, resource `$conn_identifier` = ?): string

Функция возвращает экранированную версию переданной строки. Она экранирует символы: `'`. В целом, одинарная кавычка используется для обёртывания символьной строки. Также можно использовать двойные кавычки, в зависимости от значения ansi_quotes. Если ansi_quotes установлен в «no», то строка обёрнутая в двойные кавычки будет рассматриваться как строка символов, а не как идентификатор. Значение по умолчанию — «yes». Если требуется одинарная кавычка как часть строки, ставят две одинарные кавычки подряд.

### Список параметров

`unescaped_string`
  Строка, которую необходимо экранировать
`conn_identifier`
  Идентификатор соединения CUBRID. Функция использует последнее соединение, которое вернула функция cubrid_connect(), если значение параметра не задали.

### Возвращаемые значения

Функция возвращает экранированную строку.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования cubrid_real_escape_string()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");

    $unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
    $escaped_str = cubrid_real_escape_string($unescaped_str);

    $len = strlen($unescaped_str);

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
    cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

    $req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
    $row = cubrid_fetch_assoc($req);

    var_dump($row);

    cubrid_close_request($req);
    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["t"]=>
      string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Получает значение конкретного поля конкретной строки

### Описание

function cubrid_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Функция возвращает значение конкретного поля конкретной строки из результирующего набора.

### Список параметров

`result`
  Значение `result`, которое вернула функция cubrid_execute().
`row`
  Номер извлекаемой строки набора, начиная с 0.
`field`
  Имя или индекс столбца `field`, которое требуется извлечь. Как значение передают индекс столбца, имя столбца или имя таблицы с именем столбца с точкой в качестве разделителя (tablename.fieldname). Если имя столбца — псевдоним («SELECT foo AS bar FROM...»), вместо реального имени столбца указывают псевдоним. Функция извлечёт первый столбец, если параметр не определили.

### Возвращаемые значения

Функция возвращает значение заданного столбца в случае успешного выполнения (NULL, если значение равно null).

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_result()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $result = cubrid_result($req, 0);
    var_dump($result);

    $result = cubrid_result($req, 0, 1);
    var_dump($result);

    $result = cubrid_result($req, 5, "f_name");
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);

    ?>

Результат выполнения приведённого примера:

    string(1) "X"
    string(5) "Mixed"
    string(4) "Gold"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Выполняет запрос без загрузки результата в память

### Описание

function cubrid_unbuffered_query(string `$query`, resource `$conn_identifier` = ?): resource

Функция выполняет запрос без ожидания результатов выполнения запроса. Функция возвращает значение по мере генерации результирующего набора.

### Список параметров

`query`
  SQL-запрос
`conn_identifier`
  Идентификатор соединения CUBRID. Функция использует последнее соединение, которое вернула функция cubrid_connect(), если значение параметра не задали.

### Возвращаемые значения

Для инструкций SELECT, SHOW, DESCRIBE или EXPLAIN в случае успешного выполнения возвращается ресурс идентификатор запроса.

Для других типов SQL-инструкций наподобие UPDATE, DELETE, DROP и т.д. функция в случае успешного выполнения возвращает `true`.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции cubrid_unbuffered_query()

    <?php

    $link = cubrid_connect("localhost", 30000, "demodb", "dba", "");

    if (!$link) {
        die('Не удалось соединиться.');
    }

    $query = "select * from code";
    $result = cubrid_unbuffered_query($query, $link);

    while ($row = cubrid_fetch($result)) {
        var_dump($row);
    }

    cubrid_close_request($result);
    cubrid_disconnect($link);

    ?>

### Примечания

> Замечание: У преимуществ функции cubrid_unbuffered_query() есть цена: не получится использовать функции cubrid_num_rows() и cubrid_data_seek() для результирующего набора, который возвращает функция cubrid_unbuffered_query().

## Содержание

- cubrid_affected_rows — Возвращает количество строк, которые затронул последний SQL-запрос
- cubrid_client_encoding — Возвращает кодировку текущего соединения CUBRID
- cubrid_close — Закрывает соединение с базой данных
- cubrid_data_seek — Перемещает внутренний указатель строки в наборе результатов CUBRID-запроса
- cubrid_db_name — Получает имя базы данных из результата функции cubrid_list_dbs
- cubrid_errno — Возвращает код ошибки предыдущей операции CUBRID
- cubrid_error — Возвращает текст последней произошедшей ошибки
- cubrid_fetch_array — Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
- cubrid_fetch_assoc — Извлекает строку из результирующего набора в виде ассоциативного массива
- cubrid_fetch_field — Получает информацию о столбце набора результатов в виде объекта
- cubrid_fetch_lengths — Возвращает массив, содержащий длины всех столбцов текущей строки
- cubrid_fetch_object — Извлекает следующую строку как объект
- cubrid_fetch_row — Извлекает строку из результирующего набора в виде индексного массива
- cubrid_field_flags — Получает строку, которая содержит флаги столбца по заданному индексу
- cubrid_field_len — Получает максимальную длину указанного столбца
- cubrid_field_name — Получает имя заданного столбца
- cubrid_field_seek — Перемещает внутренний указатель результирующего набора на заданный столбец
- cubrid_field_table — Получает имя таблицы, которой принадлежит столбец
- cubrid_field_type — Получает тип столбца
- cubrid_list_dbs — Получает массив со списком баз данных CUBRID
- cubrid_num_fields — Получает количество столбцов в результирующем наборе
- cubrid_ping — Проверяет, живо ли соединение к серверу и переподключает его, если нет
- cubrid_query — Отправляет запрос CUBRID
- cubrid_real_escape_string — Экранирует специальные символы в SQL-запросе
- cubrid_result — Получает значение конкретного поля конкретной строки
- cubrid_unbuffered_query — Выполняет запрос без загрузки результата в память

# Устаревшие псевдонимы и функции CUBRID

# cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Читает данные из экземпляра GLO и записывает их в файл

### Описание

function cubrid_load_from_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

Функция cubrid_load_from_glo() используется для чтения данных из экземпляра GLO и записи их в заданный файл.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  Oid экземпляра glo из которого вы хотите прочитать данные.
`file_name`
  Имя целевого файла.

### Возвращаемые значения

`true` в случае успешного выполнения.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_load_from_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_load_from_glo ($con, $oid, "output.jpg");
       if ($res) {
          echo "Картинка была изменена";
       }
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: cubrid_load_from_glo()

> Замечание: Функция удалена в CUBRID 3.1.

### Смотрите также

- cubrid_new_glo() - Создаёт экземпляр glo
- cubrid_save_to_glo() - Сохраняет запрошенный файл в экземпляре GLO
- cubrid_send_glo() - Чтение данных из glo и вывод их в стандартное устройство вывода

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Создаёт экземпляр glo

### Описание

function cubrid_new_glo(resource `$conn_identifier`, string `$class_name`, string `$file_name`): string

Функция cubrid_new_glo() используется для создания экземпляра glo в запрошенном классе (glo класс). Glo создаётся типа LO, и хранится в файле `file_name`.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`class_name`
  Имя класса, в котором вы собираетесь создать glo.
`file_name`
  Имя целевого файла.

### Возвращаемые значения

Oid созданного экземпляра в случае успешного выполнения.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_new_glo()

    <?php
    $oid = cubrid_new_glo ($con, "glo", "input.jpg");
    if ($oid){
       // тип "image" – "object"
       $req = cubrid_execute ($con, "insert into person(image) values($oid)");
       if ($req) {
          echo "картинка была обновлена";
          cubrid_close_request ($req);
          cubrid_commit($con);
       }
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: cubrid_new_glo()

> Замечание: Функция удалена в CUBRID 3.1.

### Смотрите также

- cubrid_save_to_glo() - Сохраняет запрошенный файл в экземпляре GLO
- cubrid_load_from_glo() - Читает данные из экземпляра GLO и записывает их в файл
- cubrid_send_glo() - Чтение данных из glo и вывод их в стандартное устройство вывода

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Сохраняет запрошенный файл в экземпляре GLO

### Описание

function cubrid_save_to_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

Функция cubrid_save_to_glo() используется для сохранения запрошенного файла в экземпляре glo.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  Oid экземпляра glo в котором вы хотите сохранить файл.
`file_name`
  Имя целевого файла.

### Возвращаемые значения

`true` в случае успешного выполнения.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_save_to_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_save_to_glo ($con, $oid, "input.jpg");
       if ($res) {
          echo "изображение изменено";
       }
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: cubrid_save_to_glo()

> Замечание: Функция удалена в CUBRID 3.1.

### Смотрите также

- cubrid_new_glo() - Создаёт экземпляр glo
- cubrid_load_from_glo() - Читает данные из экземпляра GLO и записывает их в файл
- cubrid_send_glo() - Чтение данных из glo и вывод их в стандартное устройство вывода

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Чтение данных из glo и вывод их в стандартное устройство вывода

### Описание

function cubrid_send_glo(resource `$conn_identifier`, string `$oid`): int

Функция cubrid_send_glo() используется для чтения данных из glo и вывода их в стандартное устройство вывода PHP.

### Список параметров

`conn_identifier`
  Идентификатор соединения.
`oid`
  Oid экземпляра glo из которого вы хотите прочитать данные.

### Возвращаемые значения

`true` в случае успешного выполнения.

`false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования cubrid_send_glo()

    <?php
    $req = cubrid_execute ($con, "select image from person where id =1");
    if ($req) {
      list ($oid) = cubrid_fetch($req);
      cubrid_close_request($req);
      Header ("Content-type: image/jpeg");
      cubrid_send_glo ($con, $oid);
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: cubrid_send_glo()

> Замечание: Функция удалена в CUBRID 3.1.

### Смотрите также

- cubrid_new_glo() - Создаёт экземпляр glo
- cubrid_save_to_glo() - Сохраняет запрошенный файл в экземпляре GLO
- cubrid_load_from_glo() - Читает данные из экземпляра GLO и записывает их в файл

## Содержание

- cubrid_load_from_glo — Читает данные из экземпляра GLO и записывает их в файл
- cubrid_new_glo — Создаёт экземпляр glo
- cubrid_save_to_glo — Сохраняет запрошенный файл в экземпляре GLO
- cubrid_send_glo — Чтение данных из glo и вывод их в стандартное устройство вывода

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Примеры
- Функции CUBRID
  - cubrid_bind — Связывает переменные с подготовленным запросом
  - cubrid_close_prepare — Закрывает обработчик запроса
  - cubrid_close_request — Закрывает обработчик запроса
  - cubrid_col_get — Получение контента столбца типа коллекция по OID
  - cubrid_col_size — Получает количество элементов в столбце типа коллекция по OID
  - cubrid_column_names — Получить имена столбцов в результирующем наборе
  - cubrid_column_types — Получить типы столбцов в результирующем наборе
  - cubrid_commit — Подтверждение транзакции
  - cubrid_connect — Открывает соединение к серверу CUBRID
  - cubrid_connect_with_url — Создаёт окружение для соединения с сервером CUBRID
  - cubrid_current_oid — Возвращает OID текущей позиции курсора
  - cubrid_disconnect — Закрывает соединение с базой данных
  - cubrid_drop — Удаление экземпляра по OID
  - cubrid_error_code — Получить код ошибки
  - cubrid_error_code_facility — Получить код уровня, на котором произошла ошибка
  - cubrid_error_msg — Возвращает текст последней произошедшей ошибки
  - cubrid_execute — Выполняет подготовленный SQL-оператор
  - cubrid_fetch — Выбирает следующую строку из набора результатов
  - cubrid_free_result — Освобождает память, занятую данными результата
  - cubrid_get — Получает столбец, используя OID
  - cubrid_get_autocommit — Возвращает настройку авто-коммита для соединения
  - cubrid_get_charset — Возвращает кодировку текущего соединения CUBRID
  - cubrid_get_class_name — Получает имя класса с помощью OID
  - cubrid_get_client_info — Возвращает версию клиентской библиотеки
  - cubrid_get_db_parameter — Возвращает параметры базы данных CUBRID
  - cubrid_get_query_timeout — Получает значение времени ожидания запроса
  - cubrid_get_server_info — Возвращает версию сервера CUBRID
  - cubrid_insert_id — Возвращает идентификатор, сгенерированный для последнего обновлённого столбца AUTO_INCREMENT
  - cubrid_is_instance — Проверяет, существует ли экземпляр, на который указывает OID
  - cubrid_lob_close — Закрывает данные BLOB/CLOB
  - cubrid_lob_export — Экспортирует данные BLOB/CLOB в файл
  - cubrid_lob_get — Получает данные BLOB/CLOB
  - cubrid_lob_send — Читает данные BLOB/CLOB и отправляет их прямо в браузер
  - cubrid_lob_size — Получает размер данных BLOB/CLOB
  - cubrid_lob2_bind — Связывает объект LOB или строку в виде объекта LOB с подготовленным оператором в качестве параметров
  - cubrid_lob2_close — Закрывает объект LOB
  - cubrid_lob2_export — Экспортирует LOB-объект в файл
  - cubrid_lob2_import — Импортирует данные BLOB/CLOB из файла
  - cubrid_lob2_new — Создаёт объект LOB
  - cubrid_lob2_read — Производит чтение из данных BLOB/CLOB
  - cubrid_lob2_seek — Перемещает курсор LOB-объекта
  - cubrid_lob2_seek64 — Перемещает курсор LOB-объекта
  - cubrid_lob2_size — Получает размер LOB-объекта
  - cubrid_lob2_size64 — Получает размер LOB-объекта
  - cubrid_lob2_tell — Сообщает положение курсора LOB-объекта
  - cubrid_lob2_tell64 — Сообщает положение курсора LOB-объекта
  - cubrid_lob2_write — Записывает в LOB-объект
  - cubrid_lock_read — Устанавливает блокировку чтения для данного OID
  - cubrid_lock_write — Устанавливает блокировку записи для данного OID
  - cubrid_move_cursor — Перемещает курсор в результате
  - cubrid_next_result — Получает результат следующего запроса при выполнении нескольких SQL-операторов
  - cubrid_num_cols — Возвращает количество столбцов в наборе результатов
  - cubrid_num_rows — Получить количество строк в наборе результатов
  - cubrid_pconnect — Открывает постоянное соединение с сервером CUBRID
  - cubrid_pconnect_with_url — Открывает постоянное соединение с сервером CUBRID
  - cubrid_prepare — Подготавливает SQL-выражение к выполнению
  - cubrid_put — Обновляет столбец с использованием OID
  - cubrid_rollback — Откат транзакции
  - cubrid_schema — Получает запрошенную информацию о схеме
  - cubrid_seq_drop — Удаляет элемент из столбца типа последовательности, используя OID
  - cubrid_seq_insert — Вставляет элемент в столбец типа последовательности, используя OID
  - cubrid_seq_put — Обновляет значение элемента столбца типа последовательности, используя OID
  - cubrid_set_add — Вставляет один элемент для установки столбца типа с помощью OID
  - cubrid_set_autocommit — Устанавливает режим авто-коммита для соединения
  - cubrid_set_db_parameter — Устанавливает параметры базы данных CUBRID
  - cubrid_set_drop — Удаляет элемент из столбца заданного типа, используя OID
  - cubrid_set_query_timeout — Устанавливает время ожидания выполнения запроса
  - cubrid_version — Получить версию модуля CUBRID PHP
- Функции совместимости CUBRID MySQL
  - cubrid_affected_rows — Возвращает количество строк, которые затронул последний SQL-запрос
  - cubrid_client_encoding — Возвращает кодировку текущего соединения CUBRID
  - cubrid_close — Закрывает соединение с базой данных
  - cubrid_data_seek — Перемещает внутренний указатель строки в наборе результатов CUBRID-запроса
  - cubrid_db_name — Получает имя базы данных из результата функции cubrid_list_dbs
  - cubrid_errno — Возвращает код ошибки предыдущей операции CUBRID
  - cubrid_error — Возвращает текст последней произошедшей ошибки
  - cubrid_fetch_array — Извлекает строки из результирующего набора в виде ассоциативного массива, индексного массива или обоих сразу
  - cubrid_fetch_assoc — Извлекает строку из результирующего набора в виде ассоциативного массива
  - cubrid_fetch_field — Получает информацию о столбце набора результатов в виде объекта
  - cubrid_fetch_lengths — Возвращает массив, содержащий длины всех столбцов текущей строки
  - cubrid_fetch_object — Извлекает следующую строку как объект
  - cubrid_fetch_row — Извлекает строку из результирующего набора в виде индексного массива
  - cubrid_field_flags — Получает строку, которая содержит флаги столбца по заданному индексу
  - cubrid_field_len — Получает максимальную длину указанного столбца
  - cubrid_field_name — Получает имя заданного столбца
  - cubrid_field_seek — Перемещает внутренний указатель результирующего набора на заданный столбец
  - cubrid_field_table — Получает имя таблицы, которой принадлежит столбец
  - cubrid_field_type — Получает тип столбца
  - cubrid_list_dbs — Получает массив со списком баз данных CUBRID
  - cubrid_num_fields — Получает количество столбцов в результирующем наборе
  - cubrid_ping — Проверяет, живо ли соединение к серверу и переподключает его, если нет
  - cubrid_query — Отправляет запрос CUBRID
  - cubrid_real_escape_string — Экранирует специальные символы в SQL-запросе
  - cubrid_result — Получает значение конкретного поля конкретной строки
  - cubrid_unbuffered_query — Выполняет запрос без загрузки результата в память
- Устаревшие псевдонимы и функции CUBRID
  - cubrid_load_from_glo — Читает данные из экземпляра GLO и записывает их в файл
  - cubrid_new_glo — Создаёт экземпляр glo
  - cubrid_save_to_glo — Сохраняет запрошенный файл в экземпляре GLO
  - cubrid_send_glo — Чтение данных из glo и вывод их в стандартное устройство вывода

# dBase

# Введение

> Замечание:

> Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 5.3.0.

Эти функции позволяют получить доступ к записям, хранящимся в DBase-формате (DBF) баз данных.

Внимание

Мы не рекомендуем использовать файлы DBase файлы для использования в промышленной эксплуатации. Лучше выберите » SQLite или какую-либо настоящую базу данных; » MySQL или » Postgres являются наиболее частым выбором при работе с PHP. Поддержка dBase больше нужна для импорта и экспорта данных вашей базы данных, поскольку формат её файлов понятен большинству пакетов электронных таблиц (например, Excel).

Предостережение

С версии dbase 7.0.0, база данных автоматически блокируется с помощью flock(). Ранее поддержки блокировок не было, так что два конкурирующих процесса веб-сервера, изменяющие один и тот же файл dBase могли с лёгкостью испортить базу. Такое может произойти даже и в dbase 7.0.0+ на системах, которые реализуют блокировку на уровне процесса с многопоточными SAPI.

База данных dBase является просто последовательностью файлов с фиксированной длиной записи. Записи добавляются в конец файла и удалённые записи будут (физически) хранится до вызова dbase_pack().

Поддерживаются только dbf-файлы уровня 3 (dBASE III+) - 5 (dBASE V). Доступные типы полей dBase:

Типы полей
Поле | dBase тип | Формат | Дополнительная информация
--- | --- | --- | ---
`M` | Memo | n/a | Тип не поддерживается PHP, такое поле будет игнорироваться
`D` | Date | `YYYYMMDD` | Длина поля ограничена 8
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) Проверка на корректность не производится. Доступно с dbase 7.0.0.
`N` | Number | Число | Вы должны указать длину и точность (количество цифр после десятичной точки).
`F` | Float | Число с плавающей точкой | То же, что и `N`.
`C` | String | A string | Вы должны указать длину. При получении данных, строка будет дополнена справа пробелами до заявленной длины. Более длинные строки будут обрезаны без предупреждения.
`L` | Boolean | `T` или `Y` для `true`, `F` или `N` для `false`, `?` - не инициализировано. | С dbase 7.0.0, возвращается как bool (`true` или `false`), или `null` для не инициализированных полей. Ранее возвращалось как int (`1` или `0`).

> Замечание:

> Начиная с dbase 7.0.0 поддерживаются обнуляемые поля для баз данных `DBASE_TYPE_FOXPRO`. Если поле обнуляемое. При передаче `null` будет установлен соответствующий флаг и, при дальнейшем извлечении поля, будет возвращено значение `null`.

> Замечание:

> Поддержки для индексов и memo-полей нет.

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/dbase.

## Типы ресурсов

В модуле dbase 7.0.0 определили ресурс `dbase`, который возвращается функциями dbase_open() и dbase_create().

# Предопределённые константы

Модуль не содержит констант.

`DBASE_VERSION` (string)
  Версия модуля. (Доступно с dbase 7.0.0)
`DBASE_RDONLY` (int)
  Открыть базу данных только для чтения. Используется с dbase_open(). (Доступно с dbase 7.0.0)
`DBASE_RDWR` (int)
  Открыть базу данных для чтения и записи. Используется с dbase_open(). (Доступно с 7.0.0)
`DBASE_TYPE_DBASE` (int)
  Создать базу данных типа dBASE. Используется с dbase_create(). (Доступно с 7.0.0)
`DBASE_TYPE_FOXPRO` (int)
  Создать базу данных типа FoxPro. Используется с dbase_create(). (Доступно с 7.0.0)

# dBase

## Примеры

Большинство примеров в документации требуют наличие базы данных dBase. Мы будем использовать /tmp/test.dbf ,которую создали в примере с dbase_create().

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Добавляет запись в базу данных

### Описание

function dbase_add_record(resource `$database`, array `$data`): bool

Функция добавляет данные в базу данных.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

`data`

  Индексный массив с данными. В аргументе передают массив, в котором количество элементов равно количеству полей в базе данных, иначе функция dbase_add_record() завершится ошибкой.

  > Замечание:

  > При передаче в параметр записи, которую вернула функция dbase_get_record(), вначале сбрасывают в записи ключ с именем `deleted` (прим пер. — unset(record['deleted']).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример вставки записи в базу данных dBase

    <?php

    // Открываем БД в режиме чтения и записи
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
        dbase_add_record(
            $db,
            array(
                date('Ymd'),
                'Maxim Topolov',
                '23',
                'max@example.com',
                'T',
            )
        );

        dbase_close($db);
    }

    ?>

### Смотрите также

- dbase_delete_record() - Удаляет запись из базы данных
- dbase_replace_record() - Заменяет запись в базе данных

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Закрывает базу данных

### Описание

function dbase_close(resource `$database`): bool

Функция закрывает ресурс базы данных.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример закрытия файла базы данных dBase

    <?php

    // Открываем БД в режиме чтения
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
        // Получаем данные

        dbase_close($db);
    }

    ?>

### Смотрите также

- dbase_open() - Открывает базу данных
- dbase_create() - Создаёт базу данных

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Создаёт базу данных

### Описание

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

Функция dbase_create() создаёт базу данных dBase с заданным определением. Функция не очищает файл базы данных, если файл уже существует. Файл принудительно очищают функцией dbase_pack().

> Замечание: На поведение этой функции влияет значение директивы open_basedir.

### Список параметров

`path`

  Путь к базе данных. Параметр принимает относительный или абсолютный путь к файлу, в котором dBase сохранит данные.

`fields`

  Массив массивов, в котором каждый массив описывает формат одного поля базы данных. Каждое поле состоит из имени, символа, которым указывается тип поля, и необязательных значений длины, точности и флага, который определяет, допускает ли поле значение NULL. Типы файлов, которые поддерживает база данных dBase, перечисляет раздел введения.

  > Замечание:

  > Ограничение длины названия полей составляет 10 символов.

`type`

  Тип базы данных, которую требуется создать: `DBASE_TYPE_DBASE` или `DBASE_TYPE_FOXPRO`.

### Возвращаемые значения

Функция возвращает ресурс базы данных, если функция успешно создала базу данных, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Добавили параметр `type`.
PECL-модуль dbase 7.0.0 | Значение возврата теперь принадлежит типу resource, а не int.

### Примеры

Пример #1 Пример создания файла базы данных dBase

    <?php

    // «Определение» базы данных
    $def = array(
        array("date",     "D"),
        array("name",     "C", 50),
        array("age",      "N", 3, 0),
        array("email",    "C", 128),
        array("ismember", "L")
    );

    // Создаём БД
    if (!dbase_create('/tmp/test.dbf', $def)) {
        echo "Ошибка, невозможно создать базу данных\n";
    }

    ?>

### Смотрите также

- dbase_open() - Открывает базу данных
- dbase_close() - Закрывает базу данных

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Удаляет запись из базы данных

### Описание

function dbase_delete_record(resource `$database`, int `$number`): bool

Функция помечает запись, которую требуется удалить из базы данных.

> Замечание:

> Записи удаляют из базы данных функцией dbase_pack().

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

`number`

  Целое число в диапазоне от 1 до количества записей в базе дынных. Количество записей возвращает функция dbase_numrecords().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Смотрите также

- dbase_add_record() - Добавляет запись в базу данных
- dbase_replace_record() - Заменяет запись в базе данных

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Получает информацию, которую хранит заголовок базы данных

### Описание

function dbase_get_header_info(resource `$database`): array

Функция возвращает информацию о структуре столбцов ресурса базы данных.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

### Возвращаемые значения

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

Каждый элемент массива содержит ассоциативный массив с информацией о столбце БД со следующими ключами:

name
  Название столбца.
type
  Тип столбца БД dBase в понятном для человека виде: date, boolean и т. д. Типы полей, которые поддерживает база данных, перечисляет вводный раздел.
length
  Максимальный размер значения в байтах, которое хранится в столбце (включая "precision" — прим. пер.).
precision
  Количество цифр десятичной точности для столбца.
format
  Спецификатор формата в стиле функции printf(), который рекомендуется для столбца.
offset
  Байт смещения столбца от начала строки записи.

Функция возвращает `false`, если информацию из заголовка базы данных невозможно прочитать.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример отображения информации заголовка файла базы данных dBase

    <?php

    // Путь к файлу БД
    $db_path = "/tmp/test.dbf";

    // Открываем файл БД
    $dbh = dbase_open($db_path, 0)
        or die("Ошибка! Невозможно открыть файл '$db_path'.")
    ;

    // Получаем информацию о столбцах
    $column_info = dbase_get_header_info($dbh);

    // Отображение информации
    print_r($column_info);

    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Получает запись из базы данных как индексный массив

### Описание

function dbase_get_record(resource `$database`, int `$number`): array

Функция получает запись из базы данных в виде индексного массива.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

`number`

  Индекс записи в диапазоне от `1` до значения, которое возвращает вызов `dbase_numrecords($dbase_identifier)`. Индекс строится на основании единицы, а не нуля.

### Возвращаемые значения

Функция возвращает индексный массив с записью. Массив также включит ассоциативный ключ с именем `deleted`, значение которого равно 1, если запись пометили для удаления. Подробнее о пометке записи для удаления рассказывает описание функции dbase_delete_record().

Функция преобразует тип значения каждого поля в PHP-тип, который соответствует значению, за исключением:

- Значения с типом Date остаются строками.
- Значения с типом DateTime преобразовываются в строки.
- Целые числа, которые выходят за пределы диапазона `PHP_INT_MIN`..`PHP_INT_MAX`, преобразовываются в строки.
- До dbase 7.0.0 логические значение — тип `L` — преобразовываются в `1` или `0`.

Функция dbase_get_record() возвращает `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Смотрите также

- dbase_get_record_with_names() - Получает запись из базы данных в виде ассоциативного массива

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Получает запись из базы данных в виде ассоциативного массива

### Описание

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Функция получает запись из базы данных dBase в виде ассоциативного массива (вместе с именами соответствующих полей).

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

`number`

  Индекс записи в диапазоне от `1` до значения, которое вернёт вызов `dbase_numrecords($dbase_identifier)`.

### Возвращаемые значения

Ассоциативный массив с записью, которую функция получила из БД. Массив также включит ключ с именем `deleted`, значение которого равно 1, если запись пометили для удаления. Подробнее о пометке записи для удаления рассказывает описание функции dbase_delete_record(). Поэтому функцией невозможно получить значение поля с именем `delete`.

Функция преобразует тип значения каждого поля в PHP-тип, который соответствует значению, за исключением:

- Значения с типом Date остаются строками.
- Значения с типом DateTime преобразовываются в строки.
- Целые числа, которые выходят за пределы диапазона `PHP_INT_MIN`..`PHP_INT_MAX`, преобразовываются в строки.
- До dbase 7.0.0 логические значение — тип `L` — преобразовываются в `1` или `0`.

Функция dbase_get_record_with_names() возвращает `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример получения списка участников, которых зарегистрировали в базе данных

    <?php

    // Открываем базу в режиме чтения
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
        $record_numbers = dbase_numrecords($db);
        for ($i = 1; $i <= $record_numbers; $i++) {
            $row = dbase_get_record_with_names($db, $i);

            if ($row['ismember'] == 1) {
                echo "Member #$i: " . trim($row['name']) . "\n";
            }
        }
    }
    // Прим. пер. —
    // к значениям записи, которую получили функцией dbase_get_record_with_names,
    // обращаются по имени: $row['ismember'],
    // а к значениям записи, которую получили функцией dbase_get_record, —
    // по индексу на основе единицы: $row[4]
    ?>

### Смотрите также

- dbase_get_record() - Получает запись из базы данных как индексный массив

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Получает количество полей базы данных

### Описание

function dbase_numfields(resource `$database`): int

Функция получает количество столбцов в базе данных.

> Замечание:

> Поля номеруются от 0 до значения выражения `dbase_numfields($db) - 1`, тогда как записи базы данных от 1 до значения выражения `dbase_numrecords($db)`.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

### Возвращаемые значения

Функция возвращает количество полей в базе данных или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-пакет dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример получения количества полей базы данных функцией dbase_numfields()

    <?php

    $rec = dbase_get_record(
        $db,
        $recno
    );

    $nf  = dbase_numfields($db);

    for ($i = 0; $i < $nf; $i++) {
        echo $rec[$i], "\n";
    }

    ?>

### Смотрите также

- dbase_numrecords() - Получает количество записей в базе данных

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Получает количество записей в базе данных

### Описание

function dbase_numrecords(resource `$database`): int

Функция получает количество записей (строк) в базе данных.

> Замечание:

> Записи, которые пометили для удаления, тоже учитываются.

> Замечание:

> Записи базы данных нумеруются от 1 до значения выражения `dbase_numrecords($db)`, тогда как поля нумеруются от 0 до значения выражения `dbase_numfields($db) - 1`.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

### Возвращаемые значения

Функция возвращает количество записей в базе данных, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример перебора записей базы данных

    <?php

    // Открываем БД только для чтения
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $record_numbers = dbase_numrecords($db);

      for ($i = 1; $i <= $record_numbers; $i++) {
          $record = dbase_get_record($db, $i);

          if (!$record['deleted']) {
              // Обрабатываем переменную $record с записью из БД
          } else {
              // Обрабатываем переменную $record с записью из БД,
              // которую пометили для удаления, или игнорируем запись
          }
      }
    }

    ?>

### Смотрите также

- dbase_numfields() - Получает количество полей базы данных

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Открывает базу данных

### Описание

function dbase_open(string `$path`, int `$mode`): resource|false

Функция dbase_open() открывает базу данных dBase в заданном режиме доступа.

> Замечание: На поведение этой функции влияет значение директивы open_basedir.

### Список параметров

`path`

  Путь к базе данных. Параметр принимает относительный или абсолютный путь к файлу, в котором БД dBase сохранит данные.

`mode`

  Целое число, которое соответствует аналогичному значению в системном вызове open(). Обычно 0 означает режим чтения, 1 — режим записи, а 2 — режим чтения и записи.

  > Замечание:

  > Невозможно открыть файл базы данных dBase в режиме только для записи, поскольку тогда функция не считает информацию из заголовка БД. Поэтому нельзя указывать 1 как значение режима `mode`.

  С dbase 7.0.0 режим `mode` устанавливают константами `DBASE_RDONLY` и `DBASE_RDWR`.

### Возвращаемые значения

В случае успешного выполнения функция возвращает ресурс базы данных или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример открытия файла базы данных dBase

    <?php

    // Открываем БД в режиме чтения
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // Считываем данные

      dbase_close($db);
    }

    ?>

### Смотрите также

- dbase_create() - Создаёт базу данных
- dbase_close() - Закрывает базу данных

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Упаковывает базу данных — фиксирует удаление записей из БД

### Описание

function dbase_pack(resource `$database`): bool

Функция упаковывает базу данных путём безвозвратного удаления записей, которые пометили для удаления функцией dbase_delete_record(). Обратите внимание, функция усечёт файл после успешной упаковки, в отличие от команды PACK в dBASE III.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример очистки базы данных dBase

    <?php

    // Открываем БД в режиме чтения и записи
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
        $record_numbers = dbase_numrecords($db);

        for ($i = 1; $i <= $record_numbers; $i++) {
            dbase_delete_record($db, $i);
        }

        // Стираем записи в базе данных
        dbase_pack($db);
    }

    ?>

### Смотрите также

- dbase_delete_record() - Удаляет запись из базы данных

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Заменяет запись в базе данных

### Описание

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Функция заменяет запись в базе данных заданными данными.

### Список параметров

`database`

  Ресурс базы данных, который возвращает функция dbase_open() или dbase_create().

`data`

  Индексный массив данных. В параметр передают массив, в котором количество элементов равняется количеству полей в базе данных, иначе в функции dbase_replace_record() возникает ошибка.

  > Замечание:

  > При передаче в параметр записи, которую вернула функция dbase_get_record(), вначале сбрасывают в записи ключ с именем `deleted` (прим пер. — unset(record['deleted']).

`number`

  Параметр принимает целое число в диапазоне от 1 до числа записей в базе данных, которое вернула функция dbase_numrecords().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль dbase 7.0.0 | Параметр `database` теперь принимает аргумент с типом resource, а не int.

### Примеры

Пример #1 Пример обновления записи в базе данных

    <?php

    // Открываем БД в режиме чтения и записи
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
        // Получаем старую запись
        $row = dbase_get_record_with_names($db, 1);

        // Сбрасываем метку 'deleted'
        unset($row['deleted']);

        // Устанавливаем в поле даты текущую дату
        $row['date'] = date('Ymd');

        // Преобразовываем переменную $row в массив
        $row = array_values($row);

        // Заменяем запись
        dbase_replace_record($db, $row, 1);

        // Закрываем БД
        dbase_close($db);
    }

    ?>

### Примечания

> Замечание:

> При получении записей функциями dbase_get_record() и dbase_get_record_with_names() поле логического типа возвращается как целочисленное (int) значение `0` и `1`. Перед обратной записью целочисленные значения преобразовывают в правильные значения, которые в БД принимает поле логического типа, иначе в БД попадёт значение `0`.

### Смотрите также

- dbase_add_record() - Добавляет запись в базу данных
- dbase_delete_record() - Удаляет запись из базы данных

## Содержание

- dbase_add_record — Добавляет запись в базу данных
- dbase_close — Закрывает базу данных
- dbase_create — Создаёт базу данных
- dbase_delete_record — Удаляет запись из базы данных
- dbase_get_header_info — Получает информацию, которую хранит заголовок базы данных
- dbase_get_record — Получает запись из базы данных как индексный массив
- dbase_get_record_with_names — Получает запись из базы данных в виде ассоциативного массива
- dbase_numfields — Получает количество полей базы данных
- dbase_numrecords — Получает количество записей в базе данных
- dbase_open — Открывает базу данных
- dbase_pack — Упаковывает базу данных — фиксирует удаление записей из БД
- dbase_replace_record — Заменяет запись в базе данных

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- dBase
  - dbase_add_record — Добавляет запись в базу данных
  - dbase_close — Закрывает базу данных
  - dbase_create — Создаёт базу данных
  - dbase_delete_record — Удаляет запись из базы данных
  - dbase_get_header_info — Получает информацию, которую хранит заголовок базы данных
  - dbase_get_record — Получает запись из базы данных как индексный массив
  - dbase_get_record_with_names — Получает запись из базы данных в виде ассоциативного массива
  - dbase_numfields — Получает количество полей базы данных
  - dbase_numrecords — Получает количество записей в базе данных
  - dbase_open — Открывает базу данных
  - dbase_pack — Упаковывает базу данных — фиксирует удаление записей из БД
  - dbase_replace_record — Заменяет запись в базе данных

# Firebird/InterBase

# Введение

Внимание

Модуль не поддерживается и больше неактуален. Однако исходный код модуля по-прежнему доступен доступен для скачивания через систему GIT репозитория PECL по адресу: » https://github.com/php/pecl-database-interbase.

Firebird является реляционной базой данных, реализующая множество возможностей ISO SQL-2003 и работающая на Linux, Windows и различных Unix-платформах. Firebird высокопроизводительная, отлично работающая в условиях конкурентного доступа БД, предоставляющая мощный язык разработки встроенных процедур и триггеров. Она, под разными именами, используется в промышленных системах начиная с 1981.

InterBase - это имя проприетарного варианта RDBMS с закрытым исходным кодом, которая разрабатывается компанией Embarcadero/Inprise. Более подробно можно почитать по ссылке » http://www.embarcadero.com/products/interbase.

Firebird - это коммерчески независимый проект (сообщество) программистов на C++, технических советников и прочих участников сообщества, разрабатывающих и расширяющих мультиплатформенную систему управления реляционными базами данных, основанную на коде открытым компанией Inprise Corp (она же Embarcadero) под лицензией InterBase Public License v.1.0 on 25 July, 2000. Более подробно о Firebird читайте тут » http://www.firebirdsql.org/.

> Замечание: Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 7.4.0 Модуль поддерживает InterBase версии 6 и выше и Firebird версии 2.0 и выше.

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 7.4.0

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://github.com/FirebirdSQL/php-firebird.

Для включения поддержки Firebird/InterBase, сконфигурируйте PHP с опцией --with-interbase[=DIR], где DIR указывает на директорию установки Firebird/InterBase (по умолчанию /usr).

> Замечание: Замечания для пользователей Win32/Win64
> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: fbclient.dll,gds32.dll

> При установке сервера Firebird/InterBase на ту же машину, на которой запускается PHP, эти DLL-библиотеки уже должны присутствовать и путь к файлу fbclient.dll,gds32.dll (gds32.dll создаётся установщиком для старых приложений) уже будет прописан в переменной PATH.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Конфигурационные опции InterBase
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
ibase.allow_persistent | "1" | `INI_SYSTEM` |
ibase.max_persistent | "-1" | `INI_SYSTEM` |
ibase.max_links | "-1" | `INI_SYSTEM` |
ibase.default_db | NULL | `INI_SYSTEM` |
ibase.default_user | NULL | `INI_ALL` |
ibase.default_password | NULL | `INI_ALL` |
ibase.default_charset | NULL | `INI_ALL` |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | `INI_ALL` |
ibase.dateformat | "%Y-%m-%d" | `INI_ALL` |
ibase.timeformat | "%H:%M:%S" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`ibase.allow_persistent` bool
  Разрешено ли использовать постоянные соединения к Firebird/InterBase.
`ibase.max_persistent` int
  Максимальное количество постоянных соединений для процесса. Если данное ограничение будет превышено, то функция ibase_pconnect() будет возвращать непостоянные соединения.
`ibase.max_links` int
  Максимальное количество соединений с Firebird/InterBase на процесс, включая постоянные.
`ibase.default_db` string
  База данных по умолчанию. Если вызывать ibase_[p]connect() без указания имени базы данных, то будет использовано это значение. Если данный параметр установлен и включён безопасный режим SQL, то будут разрешены соединения только с этой базой.
`ibase.default_user` string
  Имя пользователя по умолчанию.
`ibase.default_password` string
  Пароль по умолчанию.
`ibase.default_charset` string
  Кодировка по умолчанию.
`ibase.timestampformat` string
`ibase.dateformat` string
`ibase.timeformat` string
  Эти директивы используются для установки формата даты и времени. Данные форматы будут использоваться как при получении результирующего набора, содержащего поля соответствующих типов, так и при связывании значений с параметрами запроса.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Следующие константы можно задавать в функции ibase_trans() для определения поведения транзакций.

Флаги транзакций Firebird/InterBase
Константа | Описание
--- | ---
IBASE_DEFAULT | Настройки по умолчанию для новой транзакции. Это значение определяется клиентской библиотекой, которое в большинстве случаев равно IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT.
IBASE_READ | Начинает транзакцию в режиме только на чтение.
IBASE_WRITE | Начинает транзакцию в режиме чтения и записи.
IBASE_CONSISTENCY | Начинает транзакцию с уровнем изоляции 'consistency' (согласование). Это означает, что транзакция не может читать из таблиц, в которые вносятся изменения параллельными (конкурирующими) транзакциями.
IBASE_CONCURRENCY | Начинает транзакцию с уровнем изоляции 'concurrency' (или 'snapshot', 'моментальный снимок'). Это означает, что транзакция имеет доступ ко всем таблицам, но не может видеть изменения других транзакций после снимка.
IBASE_COMMITTED | Начинает транзакцию с уровнем изоляции 'read committed' (читать фиксированное). Этот флаг должен быть объединён с `IBASE_REC_VERSION` или `IBASE_REC_NO_VERSION`. Этот уровень изоляции позволяет получить доступ к изменениям, совершенными после начала транзакции. Если указан флаг `IBASE_REC_NO_VERSION`, только последняя версия изменений может быть прочитана. Если указан флаг `IBASE_REC_VERSION`, то можно читать изменения, находящиеся в очереди в параллельных транзакциях.
IBASE_WAIT | Флаг, указывающий, что транзакция должна ждать при возникновении конфликта транзакций.
IBASE_NOWAIT | Флаг, указывающий, что транзакция должна вернуть ошибку при возникновении конфликта транзакций.

Следующие константы можно задавать в функциях ibase_fetch_row(), ibase_fetch_assoc() или ibase_fetch_object(), для управления поведением извлечением данных.

Флаги извлечения Firebird/InterBase
Константа | Описание
--- | ---
IBASE_FETCH_BLOBS | Также можно использовать `IBASE_TEXT` для обеспечения обратной совместимости. Вынуждает извлекать объекты BLOB целиком, а не только их идентификаторы.
IBASE_FETCH_ARRAYS | Вынуждает извлекать массивы целиком, а не только их идентификаторы. Идентификаторы массивов можно использоваться только для операций вставки, так как на данный момент отсутствуют какие-либо другие функции для работы с ними.
IBASE_UNIXTIME | Вынуждает поля типа дата/время извлекаться не как строки, а как временные метки Unix (количество секунд, прошедших с 1 января 1970 00:00 UTC). Может вызвать проблемы на некоторых системах, если необходимо работать с более ранними датами.

Следующие константы используются для передачи в запросы и сервисные функции API (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() и ibase_maintain_db()). За подробностями обратитесь к документации Firebird/InterBase.

`IBASE_BKP_IGNORE_CHECKSUMS`
`IBASE_BKP_IGNORE_LIMBO`
  Опция для ibase_backup()
`IBASE_BKP_METADATA_ONLY`
  Опция для ibase_backup()
`IBASE_BKP_NO_GARBAGE_COLLECT`
  Опция для ibase_backup()
`IBASE_BKP_OLD_DESCRIPTIONS`
  Опция для ibase_backup()
`IBASE_BKP_NON_TRANSPORTABLE`
  Опция для ibase_backup()
`IBASE_BKP_CONVERT`
  Опция для ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
  Опция для ibase_restore()
`IBASE_RES_NO_SHADOW`
  Опция для ibase_restore()
`IBASE_RES_NO_VALIDITY`
  Опция для ibase_restore()
`IBASE_RES_ONE_AT_A_TIME`
  Опция для ibase_restore()
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
  Опция для ibase_restore()
`IBASE_RES_USE_ALL_SPACE`
  Опция для ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Опция для ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Опция для ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
  Опция для ibase_server_info()
`IBASE_SVC_IMPLEMENTATION`
  Опция для ibase_server_info()
`IBASE_SVC_GET_ENV`
  Опция для ibase_server_info()
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Опция для ibase_server_info()

# Функции Firebird/InterBase

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — Псевдоним ibase_add_user()

### Описание

Псевдоним функции ibase_add_user().

### Смотрите также

- fbird_modify_user() - Псевдоним ibase_modify_user
- fbird_delete_user() - Псевдоним ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — Псевдоним ibase_affected_rows()

### Описание

Псевдоним функции ibase_affected_rows().

### Смотрите также

- fbird_query() - Псевдоним ibase_query
- fbird_execute() - Псевдоним ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — Псевдоним ibase_backup()

### Описание

Псевдоним функции ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — Псевдоним ibase_blob_add()

### Описание

Псевдоним функции ibase_blob_add().

### Смотрите также

- fbird_blob_cancel() - Отменяет создание BLOB
- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_create() - Псевдоним ibase_blob_create
- fbird_blob_import() - Псевдоним ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Отменяет создание BLOB

### Описание

function fbird_blob_cancel(resource `$blob_handle`): bool

Эта функция прекращает использование BLOB, если он ещё не был закрыт fbird_blob_close().

### Список параметров

`blob_handle`
  Дескриптор BLOB, открытый с помощью fbird_blob_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_create() - Псевдоним ibase_blob_create
- fbird_blob_import() - Псевдоним ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — Псевдоним ibase_blob_close()

### Описание

Псевдоним функции ibase_blob_close().

### Смотрите также

- fbird_blob_create() - Псевдоним ibase_blob_create
- fbird_blob_cancel() - Отменяет создание BLOB
- fbird_blob_open() - Псевдоним ibase_blob_open
- fbird_blob_import() - Псевдоним ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — Псевдоним ibase_blob_create()

### Описание

Псевдоним функции ibase_blob_create().

### Смотрите также

- fbird_blob_add() - Псевдоним ibase_blob_add
- fbird_blob_cancel() - Отменяет создание BLOB
- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_import() - Псевдоним ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — Псевдоним ibase_blob_echo()

### Описание

Псевдоним функции ibase_blob_echo().

### Смотрите также

- fbird_blob_open() - Псевдоним ibase_blob_open
- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_get() - Псевдоним ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — Псевдоним ibase_blob_get()

### Описание

Псевдоним функции ibase_blob_get().

### Смотрите также

- fbird_blob_open() - Псевдоним ibase_blob_open
- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_echo() - Псевдоним ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — Псевдоним ibase_blob_import()

### Описание

Псевдоним функции ibase_blob_import().

### Смотрите также

- fbird_blob_add() - Псевдоним ibase_blob_add
- fbird_blob_cancel() - Отменяет создание BLOB
- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_create() - Псевдоним ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — Псевдоним ibase_blob_info()

### Описание

Псевдоним функции ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — Псевдоним ibase_blob_open()

### Описание

Псевдоним функции ibase_blob_open().

### Смотрите также

- fbird_blob_close() - Псевдоним ibase_blob_close
- fbird_blob_echo() - Псевдоним ibase_blob_echo
- fbird_blob_get() - Псевдоним ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — Псевдоним ibase_close()

### Описание

Псевдоним функции ibase_close().

### Смотрите также

- fbird_connect() - Псевдоним ibase_connect
- fbird_pconnect() - Псевдоним ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — Псевдоним ibase_commit()

### Описание

Псевдоним функции ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — Псевдоним ibase_commit_ret()

### Описание

Псевдоним функции ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — Псевдоним ibase_connect()

### Описание

Псевдоним функции ibase_connect().

### Смотрите также

- fbird_pconnect() - Псевдоним ibase_pconnect
- fbird_close() - Псевдоним ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — Псевдоним ibase_db_info()

### Описание

Псевдоним функции ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — Псевдоним ibase_delete_user()

### Описание

Псевдоним функции ibase_delete_user().

### Смотрите также

- fbird_add_user() - Псевдоним ibase_add_user
- fbird_modify_user() - Псевдоним ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — Псевдоним ibase_drop_db()

### Описание

Псевдоним функции ibase_drop_db().

### Смотрите также

- fbird_connect() - Псевдоним ibase_connect
- fbird_pconnect() - Псевдоним ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — Псевдоним ibase_errcode()

### Описание

Псевдоним функции ibase_errcode().

### Смотрите также

- fbird_errmsg() - Псевдоним ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — Псевдоним ibase_errmsg()

### Описание

Псевдоним функции ibase_errmsg().

### Смотрите также

- fbird_errcode() - Псевдоним ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — Псевдоним ibase_execute()

### Описание

Псевдоним функции ibase_execute().

### Смотрите также

- fbird_query() - Псевдоним ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — Псевдоним ibase_fetch_assoc()

### Описание

Псевдоним функции ibase_fetch_assoc().

### Смотрите также

- fbird_fetch_row() - Псевдоним ibase_fetch_row
- fbird_fetch_object() - Псевдоним ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — Псевдоним ibase_fetch_object()

### Описание

Псевдоним функции ibase_fetch_object().

### Смотрите также

- fbird_fetch_row() - Псевдоним ibase_fetch_row
- fbird_fetch_assoc() - Псевдоним ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — Псевдоним ibase_fetch_row()

### Описание

Псевдоним функции ibase_fetch_row().

### Смотрите также

- fbird_fetch_assoc() - Псевдоним ibase_fetch_assoc
- fbird_fetch_object() - Псевдоним ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — Псевдоним ibase_field_info()

### Описание

Псевдоним функции ibase_field_info().

### Смотрите также

- fbird_num_fields() - Псевдоним ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — Псевдоним ibase_free_event_handler()

### Описание

Псевдоним функции ibase_free_event_handler().

### Смотрите также

- fbird_set_event_handler() - Псевдоним ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — Псевдоним ibase_free_query()

### Описание

Псевдоним функции ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — Псевдоним ibase_free_result()

### Описание

Псевдоним функции ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — Псевдоним ibase_gen_id()

### Описание

Псевдоним функции ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — Псевдоним ibase_maintain_db()

### Описание

Псевдоним функции ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — Псевдоним ibase_modify_user()

### Описание

Псевдоним функции ibase_modify_user().

### Смотрите также

- fbird_add_user() - Псевдоним ibase_add_user
- fbird_delete_user() - Псевдоним ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — Псевдоним ibase_name_result()

### Описание

Псевдоним функции ibase_name_result().

### Смотрите также

- fbird_prepare() - Псевдоним ibase_prepare
- fbird_execute() - Псевдоним ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — Псевдоним ibase_num_fields()

### Описание

Псевдоним функции ibase_num_fields().

### Смотрите также

- fbird_field_info() - Псевдоним ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — Псевдоним ibase_num_params()

### Описание

Псевдоним функции ibase_num_params().

### Смотрите также

- fbird_prepare() - Псевдоним ibase_prepare
- fbird_param_info() - Псевдоним ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — Псевдоним ibase_param_info()

### Описание

Псевдоним функции ibase_param_info().

### Смотрите также

- fbird_field_info() - Псевдоним ibase_field_info
- fbird_num_params() - Псевдоним ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — Псевдоним ibase_pconnect()

### Описание

Псевдоним функции ibase_pconnect().

### Смотрите также

- fbird_close() - Псевдоним ibase_close
- fbird_connect() - Псевдоним ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — Псевдоним ibase_prepare()

### Описание

Псевдоним функции ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — Псевдоним ibase_query()

### Описание

Псевдоним функции ibase_query().

### Смотрите также

- fbird_errmsg() - Псевдоним ibase_errmsg
- fbird_fetch_row() - Псевдоним ibase_fetch_row
- fbird_fetch_object() - Псевдоним ibase_fetch_object
- fbird_free_result() - Псевдоним ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — Псевдоним ibase_restore()

### Описание

Псевдоним функции ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — Псевдоним ibase_rollback()

### Описание

Псевдоним функции ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — Псевдоним ibase_rollback_ret()

### Описание

Псевдоним функции ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — Псевдоним ibase_server_info()

### Описание

Псевдоним функции ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — Псевдоним ibase_service_attach()

### Описание

Псевдоним функции ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — Псевдоним ibase_service_detach()

### Описание

Псевдоним функции ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — Псевдоним ibase_set_event_handler()

### Описание

Псевдоним функции ibase_set_event_handler().

### Смотрите также

- fbird_free_event_handler() - Псевдоним ibase_free_event_handler
- fbird_wait_event() - Псевдоним ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — Псевдоним ibase_trans()

### Описание

Псевдоним функции ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — Псевдоним ibase_wait_event()

### Описание

Псевдоним функции ibase_wait_event().

### Смотрите также

- fbird_set_event_handler() - Псевдоним ibase_set_event_handler
- fbird_free_event_handler() - Псевдоним ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Добавляет пользователя в безопасную базу данных

### Описание

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Список параметров

`service_handle`
  Дескриптор службы сервера базы данных.
`user_name`
  Имя для входа нового пользователя базы данных.
`password`
  Пароль нового пользователя.
`first_name`
  Имя нового пользователя базы данных.
`middle_name`
  Отчество нового пользователя базы данных.
`last_name`
  Фамилия нового пользователя базы данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_modify_user() - Изменяет пользователя в безопасной базе данных
- ibase_delete_user() - Удаляет пользователя из безопасной базы данных

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Возвращает количество строк, на которые повлиял предыдущий запрос

### Описание

function ibase_affected_rows(resource `$link_identifier` = ?): int

Эта функция возвращает количество строк, на которые повлиял предыдущий запрос (INSERT, UPDATE или DELETE), который был выполнен из указанного контекста транзакции.

### Список параметров

`link_identifier`
  Контекст транзакции. Если `link_identifier` является ресурсом соединения, используется его транзакция по умолчанию.

### Возвращаемые значения

Возвращает количество строк в виде целого числа.

### Смотрите также

- ibase_query() - Выполняет запрос к базе данных InterBase
- ibase_execute() - Выполняет предварительно подготовленный запрос

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Инициирует задание резервного копирования в диспетчере служб и немедленно возвращает

### Описание

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Эта функция передаёт аргументы на (удалённый) сервер базы данных. Там начинается новый процесс резервного копирования. Поэтому вы не получите никаких ответов.

### Список параметров

`service_handle`
  Ранее открытое соединение с сервером базы данных.
`source_db`
  Абсолютный путь к файлу базы данных на сервере базы данных. Вы также можете использовать псевдоним базы данных.
`dest_file`
  Путь к файлу резервной копии на сервере базы данных.
`options`

  Дополнительные опции для передачи на сервер базы данных для резервного копирования. Параметр `options` может быть комбинацией из следующих констант: `IBASE_BKP_IGNORE_CHECKSUMS`, `IBASE_BKP_IGNORE_LIMBO`, `IBASE_BKP_METADATA_ONLY`, `IBASE_BKP_NO_GARBAGE_COLLECT`, `IBASE_BKP_OLD_DESCRIPTIONS`, `IBASE_BKP_NON_TRANSPORTABLE` или `IBASE_BKP_CONVERT`. Прочтите раздел о Предопределённые константы для получения дополнительной информации.

`verbose`
  Поскольку процесс резервного копирования выполняется на сервере базы данных, у вас нет шансов получить его вывод. Этот аргумент бесполезен.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Поскольку процесс резервного копирования выполняется на (удалённом) сервере, эта функция просто передаёт ему аргументы. Пока аргументы корректны, вы не получите `false`.

### Примеры

Пример #1 Пример использования ibase_backup()

    <?php

    // Соединение к серверу базы данных по IP-адресу и порту
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Запуск процесса резервного копирования на сервере базы данных
    // Резервное копирование базы данных сотрудников, используя полный путь к /srv/backup/employees.fbk
    // Не используйте никаких специальных аргументов
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Освобождение подключённого соединения
    ibase_service_detach ($service);
    ?>

Пример #2 Пример использования ibase_backup() с аргументами

    <?php

    // Подключиться к серверу базы данных по имени и порту по умолчанию
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Запуск процесс резервного копирования на сервере базы данных
    // Резервное копирование базы данных сотрудников с использованием псевдонима в /srv/backup/employees.fbk.
    // Резервное копирование только метаданных. Не создавайте переносную резервную копию.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Освобождение подключённого соединения
    ibase_service_detach ($service);
    ?>

### Смотрите также

- ibase_restore() - Запускает задачу восстановления в диспетчере служб и немедленно возвращается

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Добавляет данные во вновь созданный BLOB-объект

### Описание

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() добавляет данные в BLOB-объект, созданный с помощью ibase_blob_create().

### Список параметров

`blob_handle`
  Дескриптор BLOB-объекта, открытого с помощью ibase_blob_create().
`data`
  Данные для добавления.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- ibase_blob_cancel() - Отменяет создания BLOB-объекта
- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_create() - Создаёт новый BLOB-объект для заполнения данными
- ibase_blob_import() - Создаёт BLOB-объект, копирует в него файл и закрывает его

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Отменяет создания BLOB-объекта

### Описание

function ibase_blob_cancel(resource `$blob_handle`): bool

Эта функция отбрасывает BLOB-объект, если он ещё не был закрыт с помощью ibase_blob_close().

### Список параметров

`blob_handle`
  Дескриптор BLOB-объекта, открытый с помощью ibase_blob_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_create() - Создаёт новый BLOB-объект для заполнения данными
- ibase_blob_import() - Создаёт BLOB-объект, копирует в него файл и закрывает его

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — Закрывает BLOB-объект

### Описание

function ibase_blob_close(resource `$blob_handle`): mixed

Эта функция закрывает BLOB-объект, открытый для чтения с помощью ibase_blob_open() или ibase_blob_create().

### Список параметров

`blob_handle`
  BLOB-объект, открытый с помощью ibase_blob_create() или ibase_blob_open().

### Возвращаемые значения

Если BLOB-объект читался, функция возвращает `true` в случае успешного выполнения, если BLOB записывался, функция возвращает строку, содержащую идентификатор BLOB-объекта, который был назначен ей базой данных. В случае неудачи функция возвращает `false`.

### Смотрите также

- ibase_blob_cancel() - Отменяет создания BLOB-объекта
- ibase_blob_open() - Открывает BLOB-объект для извлечения частей данных

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Создаёт новый BLOB-объект для заполнения данными

### Описание

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() создаёт новый BLOB-объект для заполнения данными.

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указано, предполагается последняя открытая ссылка.

### Возвращаемые значения

Возвращает дескриптор BLOB-объекта для последующего использования с ibase_blob_add() или `false`, если возникла ошибка.

### Смотрите также

- ibase_blob_add() - Добавляет данные во вновь созданный BLOB-объект
- ibase_blob_cancel() - Отменяет создания BLOB-объекта
- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_import() - Создаёт BLOB-объект, копирует в него файл и закрывает его

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Выводит содержимое BLOB-объекта в браузер

### Описание

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

Функция открывает BLOB-объект для чтения и отправляет его содержимое на стандартный вывод (в большинстве случаев – браузер).

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.
`blob_id`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_blob_open() - Открывает BLOB-объект для извлечения частей данных
- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_get() - Получает количество байтов от открытого BLOB-объекта

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Получает количество байтов от открытого BLOB-объекта

### Описание

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

Функция возвращает не более `len` байт из BLOB-объекта, который был открыт для чтения с помощью ibase_blob_open().

> Замечание: Невозможно прочитать из BLOB-объекта, который был открыт для записи с помощью ibase_blob_create().

### Список параметров

`blob_handle`
  BLOB-объект, открытый с помощью ibase_blob_open().
`len`
  Размер возвращаемых данных.

### Возвращаемые значения

Возвращает не более `len` байт из BLOB-объекта или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования ibase_blob_get()

    <?php
    $result    = ibase_query("SELECT blob_value FROM table");
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
    ?>

Хотя этот пример делает не больше, чем 'ibase_blob_echo($data->BLOB_VALUE)', он показывает, как получить информацию в $variable для дальнейших манипуляций.

### Смотрите также

- ibase_blob_open() - Открывает BLOB-объект для извлечения частей данных
- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_echo() - Выводит содержимое BLOB-объекта в браузер

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Создаёт BLOB-объект, копирует в него файл и закрывает его

### Описание

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

Функция создаёт BLOB-объект, считывает в него весь файл, закрывает его и возвращает назначенный идентификатор BLOB-объекта.

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.
`file_handle`
  Дескриптор файла - возвращаемый функцией fopen().

### Возвращаемые значения

Возвращает идентификатор BLOB-объекта в случае успешного выполнения, или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования ibase_blob_import()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $filename = '/tmp/bar';

    $fd = fopen($filename, 'r');
    if ($fd) {

        $blob = ibase_blob_import($dbh, $fd);
        fclose($fd);

        if (!is_string($blob)) {
            // импорт не удался
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // запись не удалась
            }
        }
    } else {
        // невозможно открыть файл данных
    }
    ?>

### Смотрите также

- ibase_blob_add() - Добавляет данные во вновь созданный BLOB-объект
- ibase_blob_cancel() - Отменяет создания BLOB-объекта
- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_create() - Создаёт новый BLOB-объект для заполнения данными

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Возвращает длину BLOB-объекта и другую полезную информацию

### Описание

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Возвращает длину BLOB-объекта и другую полезную информацию.

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.
`blob_id`
  Идентификатор BLOB-объекта.

### Возвращаемые значения

Возвращает массив, содержащий информацию о BLOB-объекте. Возвращаемая информация состоит из длины BLOB-объекта, количества содержащихся в нем сегментов, размера самого большого сегмента и того, является ли он BLOB-потоком или сегментированным BLOB-объектом.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Открывает BLOB-объект для извлечения частей данных

### Описание

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Открывает существующий BLOB-объект для чтения.

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.
`blob_id`
  Идентификатор BLOB-объекта.

### Возвращаемые значения

Возвращает дескриптор BLOB-объекта для последующего использования с помощью ibase_blob_get() или `false`, если возникла ошибка.

### Смотрите также

- ibase_blob_close() - Закрывает BLOB-объект
- ibase_blob_echo() - Выводит содержимое BLOB-объекта в браузер
- ibase_blob_get() - Получает количество байтов от открытого BLOB-объекта

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Закрывает соединение с базой данных InterBase

### Описание

function ibase_close(resource `$connection_id` = `null`): bool

Закрывает ссылку на базу данных InterBase, связанную с идентификатором соединения, полученным с помощью ibase_connect(). Транзакция по умолчанию для ссылки зафиксирована, остальные транзакции отменены.

### Список параметров

`connection_id`
  Идентификатор ссылки InterBase, полученный с помощью ibase_connect(). Если не указан, предполагается последняя открытая ссылка.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_connect() - Открывает соединение с базой данных
- ibase_pconnect() - Открывает постоянное соединение с базой данных InterBase

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Фиксирует транзакцию

### Описание

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Фиксирует транзакцию.

### Список параметров

`link_or_trans_identifier`
  Если вызывается без аргумента, функция фиксирует транзакцию по умолчанию для ссылки по умолчанию. Если аргумент – идентификатор соединения, транзакция по умолчанию соответствующего соединения будет зафиксирована. Если аргумент – идентификатор транзакции, соответствующая транзакция будет зафиксирована.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Фиксирует транзакцию, не закрывая её

### Описание

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Фиксирует транзакцию, не закрывая её.

### Список параметров

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Открывает соединение с базой данных

### Описание

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Устанавливает соединение с сервером Firebird/InterBase.

В случае повторного вызова ibase_connect() с теми же аргументами новая ссылка не будет установлена, вместо этого будет возвращён идентификатор уже открытой ссылки. Ссылка на сервер будет закрыта, как только завершится выполнение скрипта, если только она не была закрыта ранее явным вызовом ibase_close().

### Список параметров

`database`
  Аргумент `database` должен быть корректным путём к файлу базы данных на сервере, на котором он находится. Если сервер не является локальным, перед ним должно стоять префикс 'hostname:' (TCP / IP), 'hostname/port:' (TCP/IP с сервером interbase на настраиваемом порту TCP), '//hostname/' (NetBEUI), в зависимости от используемого протокола соединения.
`username`
  Имя пользователя. Может быть установлено с помощью директивы `ibase.default_user` php.ini.
`password`
  Пароль для `username`. Может быть установлен с помощью директивы `ibase.default_password` php.ini.
`charset`
  `charset` является набором символов по умолчанию для базы данных.
`buffers`
  `buffers` - это количество буферов базы данных, выделяемых для кеша на стороне сервера. Если 0 или не указано, сервер выбирает свой собственный по умолчанию.
`dialect`
  `dialect` выбирает диалект SQL по умолчанию для любого оператора, выполняемого в соединении, по умолчанию он соответствует максимальному из поддерживаемых клиентских библиотек.
`role`
  Функционально только с InterBase 5 и выше.
`sync`

### Возвращаемые значения

Возвращает идентификатор ссылки Firebird/InterBase в случае успешного выполнения или `false` в случае возникновения ошибки.

### Ошибки

Если вы получите какую-то ошибку, например "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (происходит, когда вы пытаетесь использовать некоторые символы с ударениями), при использовании этого и после ibase_query() вы должны установить набор символов (например, ISO8859_1 или ваш текущий набор символов).

### Примеры

Пример #1 Пример использования ibase_connect()

    <?php
    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email, "\n";
    }
    ibase_free_result($sth);
    ibase_close($dbh);
    ?>

### Смотрите также

- ibase_pconnect() - Открывает постоянное соединение с базой данных InterBase
- ibase_close() - Закрывает соединение с базой данных InterBase

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Запрашивает статистику базы данных

### Описание

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Удаляет пользователя из безопасной базы данных

### Описание

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### Список параметров

`service_handle`
  Дескриптор службы сервера базы данных.
`user_name`
  Имя пользователя, которого вы хотите удалить из базы данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_add_user() - Добавляет пользователя в безопасную базу данных
- ibase_modify_user() - Изменяет пользователя в безопасной базе данных

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Удаляет базу данных

### Описание

function ibase_drop_db(resource `$connection` = `null`): bool

Функция удаляет базу данных, которая была открыта либо с помощью ibase_connect(), либо ibase_pconnect(). База данных закрывается и удаляется с сервера.

### Список параметров

`connection`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_connect() - Открывает соединение с базой данных
- ibase_pconnect() - Открывает постоянное соединение с базой данных InterBase

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Возвращает код ошибки

### Описание

function ibase_errcode(): int

Возвращает код ошибки, полученный в результате последнего вызова функции InterBase.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код ошибки в виде целого числа или `false`, если ошибки не произошло.

### Смотрите также

- ibase_errmsg() - Возвращает сообщение об ошибке

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Возвращает сообщение об ошибке

### Описание

function ibase_errmsg(): string

Возвращает сообщение об ошибке, полученное в результате последнего вызова функции InterBase.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сообщение об ошибке в виде строки или `false` если ошибки не произошло.

### Смотрите также

- ibase_errcode() - Возвращает код ошибки

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Выполняет предварительно подготовленный запрос

### Описание

function ibase_execute(resource `$query`, mixed `...$values`): resource

Выполняет запрос, подготовленный с помощью ibase_prepare().

Это намного эффективнее, чем использование ibase_query(), если вы повторяете один и тот же тип запроса несколько раз, изменяя только некоторые параметры.

### Список параметров

`query`
  Запрос InterBase, подготовленный с помощью ibase_prepare().
`values`

### Возвращаемые значения

Если запрос вызывает ошибку, возвращает `false`. Если запрос выполнен успешно, и есть (возможно пустой) набор результатов (как при запросе SELECT), возвращает идентификатор результата. Если запрос выполнен успешно и результатов не было, возвращается `true`.

> Замечание: Функция возвращает количество строк, затронутых запросом (если > 0 и применимо к типу оператора). Если запрос выполнен успешно, но не затронул ни одну строку (например, UPDATE несуществующей записи), вернёт `true`.

### Примеры

Пример #1 Пример использования ibase_execute()

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Eric',
        5 => 'Filip',
        7 => 'Larry'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### Смотрите также

- ibase_query() - Выполняет запрос к базе данных InterBase

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Извлекает строку результата из запроса в виде ассоциативного массива

### Описание

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Извлекает строку результата из запроса в виде ассоциативного массива

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

### Список параметров

`result`
  Дескриптор результата.
`fetch_flag`
  `fetch_flag` представляет собой комбинацию констант `IBASE_TEXT` и `IBASE_UNIXTIME` ORed. Передача `IBASE_TEXT` заставит функцию возвращать содержимое BLOB-объектов вместо идентификаторов BLOB-объектов. Передача `IBASE_UNIXTIME` заставит функцию возвращать значения даты/времени как метки времени Unix, а не как отформатированные строки.

### Возвращаемые значения

Возвращает ассоциативный массив, соответствующий выбранной строке. Последующие вызовы вернут следующую строку в наборе результатов или `false`, если строк больше нет.

### Смотрите также

- ibase_fetch_row() - Извлекает строку из базы данных InterBase
- ibase_fetch_object() - Получает объект из базы данных InterBase

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Получает объект из базы данных InterBase

### Описание

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Извлекает строку как псевдообъект из заданного идентификатора результата.

Последующие вызовы ibase_fetch_object() вернут следующую строку в наборе результатов.

### Список параметров

`result_id`
  Идентификатор результата InterBase, полученный с помощью ibase_query() или ibase_execute().
`fetch_flag`
  `fetch_flag` представляет собой комбинацию констант `IBASE_TEXT` и `IBASE_UNIXTIME` ORed. Передача `IBASE_TEXT` заставит функцию возвращать содержимое BLOB-объектов вместо идентификаторов BLOB-объектов. Передача `IBASE_UNIXTIME` заставит функцию возвращать значения даты/времени как метки времени Unix, а не как отформатированные строки.

### Возвращаемые значения

Возвращает объект с информацией о строке или `false`, если строк больше нет.

### Примеры

Пример #1 Пример использования ibase_fetch_object()

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
    ?>

### Смотрите также

- ibase_fetch_row() - Извлекает строку из базы данных InterBase
- ibase_fetch_assoc() - Извлекает строку результата из запроса в виде ассоциативного массива

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Извлекает строку из базы данных InterBase

### Описание

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() извлекает одну строку данных из данного набора результатов.

Последующие вызовы ibase_fetch_row() вернут следующую строку в наборе результатов или `false`, если строк больше нет.

### Список параметров

`result_identifier`
  Идентификатор результата InterBase.
`fetch_flag`
  `fetch_flag` представляет собой комбинацию констант `IBASE_TEXT` и `IBASE_UNIXTIME` ORed. Передача `IBASE_TEXT` заставит функцию возвращать содержимое BLOB-объектов вместо идентификаторов BLOB-объектов. Передача `IBASE_UNIXTIME` заставит функцию возвращать значения даты/времени как метки времени Unix, а не как отформатированные строки.

### Возвращаемые значения

Возвращает массив, соответствующий выбранной строке, или `false`, если строк больше нет. Каждый столбец результата сохраняется в смещении массива, начиная со смещения 0.

### Смотрите также

- ibase_fetch_assoc() - Извлекает строку результата из запроса в виде ассоциативного массива
- ibase_fetch_object() - Получает объект из базы данных InterBase

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Получает информацию о поле

### Описание

function ibase_field_info(resource `$result`, int `$field_number`): array

Возвращает массив с информацией о поле после выполнения запроса select.

### Список параметров

`result`
  Идентификатор результата InterBase.
`field_number`
  Смещение поля.

### Возвращаемые значения

Возвращает массив со следующими ключами: `name`, `alias`, `relation`, `length` и `type`.

### Примеры

Пример #1 Пример использования ibase_field_info()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "Имя: ". $col_info['name']. "\n";
        echo "Псевдоним: ". $col_info['alias']. "\n";
        echo "Связь: ". $col_info['relation']. "\n";
        echo "Длина: ". $col_info['length']. "\n";
        echo "Тип: ". $col_info['type']. "\n";
    }
    ?>

### Смотрите также

- ibase_num_fields() - Возвращает количество полей в результирующем наборе

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Отменяет зарегистрированный обработчик события

### Описание

function ibase_free_event_handler(resource `$event`): bool

Функция отменяет, зарегистрированный обработчик события, указанный в `event`. Callback-функция больше не будет вызываться для событий, для которых она была зарегистрирована.

### Список параметров

`event`
  Ресурс события, созданный ibase_set_event_handler().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_set_event_handler() - Регистрирует callback-функцию, которая будет вызываться при публикации событий

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Освобождает память, выделенную на подготовку запроса

### Описание

function ibase_free_query(resource `$query`): bool

Освобождает подготовленный запрос.

### Список параметров

`query`
  Запрос, подготовленный с помощью ibase_prepare().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Освобождает набор результатов

### Описание

function ibase_free_result(resource `$result_identifier`): bool

Освобождает набор результатов.

### Список параметров

`result_identifier`
  Набор результатов, созданных с помощью ibase_query() или ibase_execute().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Увеличивает указанный генератор и возвращает его новое значение

### Описание

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Возвращаемые значения

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

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Выполняет команду обслуживания на сервере базы данных

### Описание

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Изменяет пользователя в безопасной базе данных

### Описание

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Список параметров

`service_handle`
  Дескриптор службы сервера базы данных.
`user_name`
  Имя пользователя базы данных для изменения.
`password`
  Новый пароль пользователя.
`first_name`
  Новое имя пользователя.
`middle_name`
  Новое отчество пользователя.
`last_name`
  Новая фамилия пользователя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- ibase_add_user() - Добавляет пользователя в безопасную базу данных
- ibase_delete_user() - Удаляет пользователя из безопасной базы данных

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Присваивает имя набору результатов

### Описание

function ibase_name_result(resource `$result`, string `$name`): bool

Функция присваивает имя набору результатов. Имя может быть использовано позже в запросах UPDATE|DELETE ... WHERE CURRENT OF `name`.

### Список параметров

`result`
  Набор результатов InterBase.
`name`
  Имя для назначения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования ibase_name_result()

    <?php
    $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
    ?>

### Смотрите также

- ibase_prepare() - Подготавливает запрос для последующего связывания псевдопеременных и выполнения
- ibase_execute() - Выполняет предварительно подготовленный запрос

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Возвращает количество полей в результирующем наборе

### Описание

function ibase_num_fields(resource `$result_id`): int

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

### Список параметров

`result_id`
  Идентификатор результата InterBase.

### Возвращаемые значения

Возвращает количество полей в виде целого числа.

### Примеры

Пример #1 Пример использования ibase_num_fields()

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "Имя: " . $col_info['name'] . "\n";
        echo "Псевдоним: " . $col_info['alias'] . "\n";
        echo "Связь: " . $col_info['relation'] . "\n";
        echo "Длина: " . $col_info['length'] . "\n";
        echo "Тип: " . $col_info['type'] . "\n";
    }
    ?>

### Смотрите также

- ibase_field_info() - Получает информацию о поле

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Возвращает количество параметров в подготовленном запросе

### Описание

function ibase_num_params(resource `$query`): int

Эта функция возвращает количество параметров в подготовленном запросе, указанном `query`. Это количество связывающих аргументов, которые должны присутствовать при вызове ibase_execute().

### Список параметров

`query`
  Дескриптор подготовленного запроса.

### Возвращаемые значения

Возвращает количество параметров в виде целого числа.

### Смотрите также

- ibase_prepare() - Подготавливает запрос для последующего связывания псевдопеременных и выполнения
- ibase_param_info() - Возвращает информацию о параметре в подготовленном запросе

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Возвращает информацию о параметре в подготовленном запросе

### Описание

function ibase_param_info(resource `$query`, int `$param_number`): array

Возвращает массив с информацией о параметре после подготовки запроса.

### Список параметров

`query`
  Дескриптор подготовленного запроса InterBase.
`param_number`
  Смещение параметра.

### Возвращаемые значения

Возвращает массив со следующими ключами: `name`, `alias`, `relation`, `length` и `type`.

### Смотрите также

- ibase_field_info() - Получает информацию о поле
- ibase_num_params() - Возвращает количество параметров в подготовленном запросе

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Открывает постоянное соединение с базой данных InterBase

### Описание

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Открывает постоянное соединение с базой данных InterBase.

Принцип работы ibase_pconnect() очень похож на ibase_connect() с двумя основными отличиями.

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

Во-вторых, соединение с сервером InterBase не будет закрыто по окончании выполнения скрипта. Вместо этого ссылка останется открытой для использования в дальнейшем (ibase_close() не будет закрывать ссылки, установленные ibase_pconnect()). Поэтому этот тип ссылки называется "постоянным".

### Список параметров

`database`
  Аргумент `database` должен быть допустимым путём к файлу базы данных на сервере, на котором он находится. Если сервер не является локальным, он должен иметь префикс 'hostname:' (TCP/IP), '//hostname/' (NetBEUI) или 'hostname@' (IPX/SPX), в зависимости от используемого протокола подключения.
`username`
  Имя пользователя. Можно установить с помощью директивы php.ini `ibase.default_user`.
`password`
  Пароль для `username`. Можно установить с помощью директивы php.ini `ibase.default_password`.
`charset`
  `charset` - набор символов по умолчанию для базы данных.
`buffers`
  `buffers` - количество буферов базы данных, выделяемых для кеша на стороне сервера. Если значение равно 0 или опущено, сервер выбирает собственное значение по умолчанию.
`dialect`
  `dialect` выбирает диалект SQL по умолчанию для любого выражения, выполняемого в соединении, и по умолчанию выбирает самый высокий диалект, поддерживаемый клиентскими библиотеками. Работает только с InterBase 6 и выше.
`role`
  Работает только с InterBase 5 и выше.
`sync`

### Возвращаемые значения

Возвращает идентификатор ссылки InterBase в случае успешного выполнения или `false` в случае возникновения ошибки.

### Смотрите также

- ibase_close() - Закрывает соединение с базой данных InterBase
- ibase_connect() - Открывает соединение с базой данных

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Подготавливает запрос для последующего связывания псевдопеременных и выполнения

### Описание

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$trans`, string `$query`): resource

Подготавливает запрос для последующего связывания псевдопеременных и выполнения (с помощью ibase_execute()).

### Список параметров

`query`
  Запрос InterBase.
`link_identifier`
  Идентификатор ссылки InterBase, возвращаемый функцией ibase_connect(). Если не указан, предполагается последняя открытая ссылка.
`trans`
  Дескриптор транзакции InterBase, с которой должен быть связан запрос. Если не указан, предполагается транзакция соединения по умолчанию.

### Возвращаемые значения

Возвращает дескриптор подготовленного запроса или `false` в случае возникновения ошибки.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Выполняет запрос к базе данных InterBase

### Описание

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Выполняет запрос к базе данных InterBase.

### Список параметров

`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.
`query`
  Запрос InterBase.
`bind_args`

### Возвращаемые значения

Если запрос вызывает ошибку, возвращает `false`. В случае успешного выполнения и наличия (возможно, пустого) результирующего набора (например, с запросом SELECT) возвращает идентификатор результата. Если запрос был успешным и результатов не было, возвращает `true`.

> Замечание: В PHP 5.0.0 и выше эта функция будет возвращать количество строк, затронутых запросом, для операторов INSERT, UPDATE и DELETE. Чтобы сохранить обратную совместимость, она будет возвращать `true` для этих операций, если запрос выполнен успешно без затрагивания каких-либо строк.

### Ошибки

Если вы получаете сообщение об ошибке вроде "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (это происходит, когда вы пытаетесь использовать какой-либо символ с диакритическими знаками) при использовании этой функции и после использования ibase_query(), вы должны установить символьную кодировку (ISO8859_1 или вашу текущую символьную кодировку).

### Примеры

Пример #1 Пример использования ibase_query()

    <?php

    $host = 'localhost:/path/to/your.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### Смотрите также

- ibase_errmsg() - Возвращает сообщение об ошибке
- ibase_fetch_row() - Извлекает строку из базы данных InterBase
- ibase_fetch_object() - Получает объект из базы данных InterBase
- ibase_free_result() - Освобождает набор результатов

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Запускает задачу восстановления в диспетчере служб и немедленно возвращается

### Описание

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Эта функция передаёт аргументы (удалённому) серверу базы данных. Там она начинает новый процесс восстановления. Поэтому вы не получите никакого ответа.

### Список параметров

`service_handle`
  Ранее открытое соединение с сервером базы данных.
`source_file`
  Абсолютный путь на сервере, где находится файл резервной копии.
`dest_db`
  Путь для создания новой базы данных на сервере. Вы также можете использовать псевдоним базы данных.
`options`

  Дополнительные параметры для передачи на сервер базы данных для восстановления. Параметр `options` может быть комбинацией следующих констант: `IBASE_RES_DEACTIVATE_IDX`, `IBASE_RES_NO_SHADOW`, `IBASE_RES_NO_VALIDITY`, `IBASE_RES_ONE_AT_A_TIME`, `IBASE_RES_REPLACE`, `IBASE_RES_CREATE`, `IBASE_RES_USE_ALL_SPACE`, `IBASE_PRP_PAGE_BUFFERS`, `IBASE_PRP_SWEEP_INTERVAL`, `IBASE_RES_CREATE`. Читайте раздел о Предопределённые константы для получения дополнительной информации.

`verbose`
  Поскольку процесс восстановления выполняется на сервере базы данных, у вас нет возможности получить вывод. Этот аргумент бесполезен.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Поскольку процесс восстановления выполняется на (удалённом) сервере, эта функция просто передаёт ему аргументы. Если аргументы недействительны, то вернётся `false`.

### Примеры

Пример #1 Пример использования ibase_restore()

    <?php

    // Подключение к серверу базы данных по ip-адресу и порту
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Запуск процесса восстановления на сервере базы данных
    // Восстановление резервной копии employee в новую базу данных emps.fdb
    // Не используйте никаких специальных аргументов
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Освобождение соединения
    ibase_service_detach ($service);
    ?>

Пример #2 Пример использования ibase_restore() с аргументами

    <?php

    // Присоединение к серверу базы данных по имени и порту по умолчанию
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Запуск процесса восстановления на сервере базы данных
    // Восстановление базы данных employee с использованием псевдонима.
    // Восстановление без индексов. Замена существующей базы данных.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Освобождение прикрепленного соединения
    ibase_service_detach ($service);
    ?>

### Смотрите также

- ibase_backup() - Инициирует задание резервного копирования в диспетчере служб и немедленно возвращает

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Откатывает транзакцию

### Описание

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Откатывает транзакцию.

### Список параметров

`link_or_trans_identifier`
  Если вызывается без аргумента, эта функция откатывает транзакцию по умолчанию для ссылки по умолчанию. Если аргумент является идентификатором соединения, транзакция по умолчанию для соответствующего соединения будет отменена. Если аргумент является идентификатором транзакции, соответствующая транзакция будет отменена.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Откатывает транзакцию, не закрывая её

### Описание

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Откатывает транзакцию, не закрывая её.

### Список параметров

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Запрашивает информацию о сервере базы данных

### Описание

function ibase_server_info(resource `$service_handle`, int `$action`): string

### Список параметров

`service_handle`
  Ранее созданное соединение с сервером базы данных.
`action`
  Допустимая константа.

### Возвращаемые значения

Возвращает смешанные типы в зависимости от контекста.

### Примеры

Пример #1 Пример использования ibase_service_attach()

    <?php
        // Присоединение к удаленному серверу Firebird
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Присоединение прошло успешно.

            // Вывод информации
            echo "Версия сервера: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
            echo "Реализация сервера: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
            echo "Пользователи сервера: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
            echo "Директория сервера: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
            echo "Путь блокировки сервера: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
            echo "Путь к библиотекам сервера: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
            echo "Путь пользователя базы данных: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
            echo "Установленные соединения: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

            // Отсоединение от сервера (отключение)
            ibase_service_detach($service);

        }
        else {
            // Вывод сообщения в случае возникновения ошибки
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

Результат выполнения приведённого примера:

    Версия сервера: LI-V3.0.4.33054 Firebird 3.0
    Реализация сервера: Firebird/Linux/AMD/Intel/x64
    Пользователи сервера: Array
    (
        [0] => Array
            (
                [user_name] => SYSDBA
                [first_name] => Sql
                [middle_name] => Server
                [last_name] => Administrator
                [user_id] => 0
                [group_id] => 0
            )

    )

    Директория сервера: /etc/firebird/
    Путь блокировки сервера: /tmp/firebird/
    Путь к библиотекам сервера: /usr/lib64/firebird/lib/
    Путь пользователя базы данных: /var/lib/firebird/secdb/security3.fdb
    Установленные соединения: Array
    (
        [attachments] => 3
        [databases] => 2
        [0] => /srv/firebird/poss.fdb
        [1] => /srv/firebird/employees.fdb
    )

# ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — Подключается к диспетчеру служб

### Описание

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### Список параметров

`host`
  Имя или IP-адрес хоста базы данных. Вы можете указать порт, добавив '/' и номер порта. Если порт не указан, будет использоваться порт 3050.
`dba_username`
  Имя любого действительного пользователя.
`dba_password`
  Пароль пользователя.

### Возвращаемые значения

Возвращает идентификатор ссылки Interbase / Firebird в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования ibase_service_attach()

    <?php
        // Присоединение к удаленному серверу Firebird по IP-адресу
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Присоединение прошло успешно.
            // Возврат версии сервера (что-то вроде 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Возврат реализации сервера (что-то вроде 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Отсоединение от сервера (отключение)
            ibase_service_detach($service);

            // Вывод информации
            echo "Версия сервера: " . $server_version . "<br/>";
            echo "Реализация сервера: " . $server_implementation;
        }
        else {
            // Вывод сообщения в случае возникновения ошибки
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

Пример #2 Пример использования ibase_service_attach() с синтаксисом `hostname/port`

    <?php
        // Присоединение к удаленному серверу Firebird по имени. Используется порт 3050.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Присоединение прошло успешно.
            // Возврат версии сервера (что-то вроде 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Возврат реализации сервера (что-то вроде 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Отсоединение от сервера (отключение)
            ibase_service_detach($service);

            // Вывод информации
            echo "Версия сервера: " . $server_version . "<br/>";
            echo "Реализация сервера: " . $server_implementation;
        }
        else {
            // Вывод сообщения в случае возникновения ошибки
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### Смотрите также

- ibase_service_detach() - Отключается от диспетчера служб

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Отключается от диспетчера служб

### Описание

function ibase_service_detach(resource `$service_handle`): bool

### Список параметров

`service_handle`
  Ранее созданное соединение с сервером базы данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования ibase_service_detach()

    <?php
        // Присоединение к удаленному серверу Firebird по IP-адресу
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Присоединение прошло успешно.
            // Возврат версии сервера (что-то вроде 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Возврат реализации сервера (что-то вроде 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Отсоединение от сервера (отключение)
            if(ibase_service_detach($service) == FALSE) {
                echo "Ошибка при отсоединении от службы.";
            }
            else {
                echo "Отсоединение от службы прошло успешно.";
            }

        }
        else {
            // Вывод сообщения в случае возникновения ошибки
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Регистрирует callback-функцию, которая будет вызываться при публикации событий

### Описание

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$even_names`): resource
function ibase_set_event_handler(
resource `$connection`,
callable `$event_handler`,
string `$event_name`,
string `...$event_names`
): resource

Функция регистрирует пользовательскую функцию PHP в качестве обработчика событий для указанных событий.

### Список параметров

`event_handler`
  Callback-функция вызывается с именем события и ресурсом ссылки в качестве аргументов всякий раз, когда одно из указанных событий публикуется базой данных. Callback-функция должна возвращать `false`, если обработчик события должен быть отменён. Любое другое возвращаемое значение игнорируется. Функция принимает до 15 аргументов события.
`event_name`
  Наименование события.
`event_names`
  Разрешено максимум 15 событий.

### Возвращаемые значения

Возвращаемое значение является ресурсом события. Этот ресурс можно использовать для освобождения обработчика событий с помощью ibase_free_event_handler().

### Примеры

Пример #1 Пример использования ibase_set_event_handler()

    <?php

    function event_handler($event_name, $link)
    {
        if ($event_name == "NEW ORDER") {
            // обрабатываем новый заказ
            ibase_query($link, "UPDATE orders SET status='handled'");
        } else if ($event_name == "DB_SHUTDOWN") {
            // отменяем обработчик событий
            return false;
        }
    }

    ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
    ?>

### Смотрите также

- ibase_free_event_handler() - Отменяет зарегистрированный обработчик события
- ibase_wait_event() - Ждём, пока событие будет опубликовано в базе данных

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Начинает транзакцию

### Описание

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Начинает транзакцию.

> Замечание: Первый вызов ibase_trans() не вернёт транзакцию соединения по умолчанию. Все транзакции, запущенные с помощью ibase_trans(), будут отменены в конце скрипта, если они не были зафиксированы, или будут отменены с помощью ibase_commit() или ibase_rollback().

> Замечание: Эта функция принимает несколько аргументов `trans_args` и `link_identifier`. Это позволяет выполнять транзакции через несколько соединений с базой данных, которые фиксируются с использованием алгоритма двухэтапной фиксации. Это означает, что вы можете рассчитывать на то, что обновления будут успешными в каждой базе данных или завершатся ошибкой в каждой базе данных. Это НЕ означает, что вы можете использовать таблицы из разных баз данных в одном запросе! Если вы используете транзакции в нескольких базах данных, вам нужно будет указать как `link_id`, так и `transaction_id` в вызовах ibase_query() и ibase_prepare().

### Список параметров

`trans_args`
  `trans_args` может быть комбинацией `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` и `IBASE_NOWAIT`.
`link_identifier`
  Идентификатор ссылки InterBase. Если не указан, предполагается последняя открытая ссылка.

### Возвращаемые значения

Возвращает дескриптор транзакции или `false` в случае возникновения ошибки.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Ждём, пока событие будет опубликовано в базе данных

### Описание

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

Функция приостанавливает выполнение сценария до тех пор, пока одно из указанных событий не будет опубликовано в базе данных. Имя события, которое было опубликовано, возвращается. Функция принимает до 15 аргументов события.

### Список параметров

`event_name`
  Название события.
`event_names`

### Возвращаемые значения

Возвращает название события, которое было опубликовано.

### Смотрите также

- ibase_set_event_handler() - Регистрирует callback-функцию, которая будет вызываться при публикации событий
- ibase_free_event_handler() - Отменяет зарегистрированный обработчик события

## Содержание

- fbird_add_user — Псевдоним ibase_add_user
- fbird_affected_rows — Псевдоним ibase_affected_rows
- fbird_backup — Псевдоним ibase_backup
- fbird_blob_add — Псевдоним ibase_blob_add
- fbird_blob_cancel — Отменяет создание BLOB
- fbird_blob_close — Псевдоним ibase_blob_close
- fbird_blob_create — Псевдоним ibase_blob_create
- fbird_blob_echo — Псевдоним ibase_blob_echo
- fbird_blob_get — Псевдоним ibase_blob_get
- fbird_blob_import — Псевдоним ibase_blob_import
- fbird_blob_info — Псевдоним ibase_blob_info
- fbird_blob_open — Псевдоним ibase_blob_open
- fbird_close — Псевдоним ibase_close
- fbird_commit — Псевдоним ibase_commit
- fbird_commit_ret — Псевдоним ibase_commit_ret
- fbird_connect — Псевдоним ibase_connect
- fbird_db_info — Псевдоним ibase_db_info
- fbird_delete_user — Псевдоним ibase_delete_user
- fbird_drop_db — Псевдоним ibase_drop_db
- fbird_errcode — Псевдоним ibase_errcode
- fbird_errmsg — Псевдоним ibase_errmsg
- fbird_execute — Псевдоним ibase_execute
- fbird_fetch_assoc — Псевдоним ibase_fetch_assoc
- fbird_fetch_object — Псевдоним ibase_fetch_object
- fbird_fetch_row — Псевдоним ibase_fetch_row
- fbird_field_info — Псевдоним ibase_field_info
- fbird_free_event_handler — Псевдоним ibase_free_event_handler
- fbird_free_query — Псевдоним ibase_free_query
- fbird_free_result — Псевдоним ibase_free_result
- fbird_gen_id — Псевдоним ibase_gen_id
- fbird_maintain_db — Псевдоним ibase_maintain_db
- fbird_modify_user — Псевдоним ibase_modify_user
- fbird_name_result — Псевдоним ibase_name_result
- fbird_num_fields — Псевдоним ibase_num_fields
- fbird_num_params — Псевдоним ibase_num_params
- fbird_param_info — Псевдоним ibase_param_info
- fbird_pconnect — Псевдоним ibase_pconnect
- fbird_prepare — Псевдоним ibase_prepare
- fbird_query — Псевдоним ibase_query
- fbird_restore — Псевдоним ibase_restore
- fbird_rollback — Псевдоним ibase_rollback
- fbird_rollback_ret — Псевдоним ibase_rollback_ret
- fbird_server_info — Псевдоним ibase_server_info
- fbird_service_attach — Псевдоним ibase_service_attach
- fbird_service_detach — Псевдоним ibase_service_detach
- fbird_set_event_handler — Псевдоним ibase_set_event_handler
- fbird_trans — Псевдоним ibase_trans
- fbird_wait_event — Псевдоним ibase_wait_event
- ibase_add_user — Добавляет пользователя в безопасную базу данных
- ibase_affected_rows — Возвращает количество строк, на которые повлиял предыдущий запрос
- ibase_backup — Инициирует задание резервного копирования в диспетчере служб и немедленно возвращает
- ibase_blob_add — Добавляет данные во вновь созданный BLOB-объект
- ibase_blob_cancel — Отменяет создания BLOB-объекта
- ibase_blob_close — Закрывает BLOB-объект
- ibase_blob_create — Создаёт новый BLOB-объект для заполнения данными
- ibase_blob_echo — Выводит содержимое BLOB-объекта в браузер
- ibase_blob_get — Получает количество байтов от открытого BLOB-объекта
- ibase_blob_import — Создаёт BLOB-объект, копирует в него файл и закрывает его
- ibase_blob_info — Возвращает длину BLOB-объекта и другую полезную информацию
- ibase_blob_open — Открывает BLOB-объект для извлечения частей данных
- ibase_close — Закрывает соединение с базой данных InterBase
- ibase_commit — Фиксирует транзакцию
- ibase_commit_ret — Фиксирует транзакцию, не закрывая её
- ibase_connect — Открывает соединение с базой данных
- ibase_db_info — Запрашивает статистику базы данных
- ibase_delete_user — Удаляет пользователя из безопасной базы данных
- ibase_drop_db — Удаляет базу данных
- ibase_errcode — Возвращает код ошибки
- ibase_errmsg — Возвращает сообщение об ошибке
- ibase_execute — Выполняет предварительно подготовленный запрос
- ibase_fetch_assoc — Извлекает строку результата из запроса в виде ассоциативного массива
- ibase_fetch_object — Получает объект из базы данных InterBase
- ibase_fetch_row — Извлекает строку из базы данных InterBase
- ibase_field_info — Получает информацию о поле
- ibase_free_event_handler — Отменяет зарегистрированный обработчик события
- ibase_free_query — Освобождает память, выделенную на подготовку запроса
- ibase_free_result — Освобождает набор результатов
- ibase_gen_id — Увеличивает указанный генератор и возвращает его новое значение
- ibase_maintain_db — Выполняет команду обслуживания на сервере базы данных
- ibase_modify_user — Изменяет пользователя в безопасной базе данных
- ibase_name_result — Присваивает имя набору результатов
- ibase_num_fields — Возвращает количество полей в результирующем наборе
- ibase_num_params — Возвращает количество параметров в подготовленном запросе
- ibase_param_info — Возвращает информацию о параметре в подготовленном запросе
- ibase_pconnect — Открывает постоянное соединение с базой данных InterBase
- ibase_prepare — Подготавливает запрос для последующего связывания псевдопеременных и выполнения
- ibase_query — Выполняет запрос к базе данных InterBase
- ibase_restore — Запускает задачу восстановления в диспетчере служб и немедленно возвращается
- ibase_rollback — Откатывает транзакцию
- ibase_rollback_ret — Откатывает транзакцию, не закрывая её
- ibase_server_info — Запрашивает информацию о сервере базы данных
- ibase_service_attach — Подключается к диспетчеру служб
- ibase_service_detach — Отключается от диспетчера служб
- ibase_set_event_handler — Регистрирует callback-функцию, которая будет вызываться при публикации событий
- ibase_trans — Начинает транзакцию
- ibase_wait_event — Ждём, пока событие будет опубликовано в базе данных

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции Firebird/InterBase
  - fbird_add_user — Псевдоним ibase_add_user
  - fbird_affected_rows — Псевдоним ibase_affected_rows
  - fbird_backup — Псевдоним ibase_backup
  - fbird_blob_add — Псевдоним ibase_blob_add
  - fbird_blob_cancel — Отменяет создание BLOB
  - fbird_blob_close — Псевдоним ibase_blob_close
  - fbird_blob_create — Псевдоним ibase_blob_create
  - fbird_blob_echo — Псевдоним ibase_blob_echo
  - fbird_blob_get — Псевдоним ibase_blob_get
  - fbird_blob_import — Псевдоним ibase_blob_import
  - fbird_blob_info — Псевдоним ibase_blob_info
  - fbird_blob_open — Псевдоним ibase_blob_open
  - fbird_close — Псевдоним ibase_close
  - fbird_commit — Псевдоним ibase_commit
  - fbird_commit_ret — Псевдоним ibase_commit_ret
  - fbird_connect — Псевдоним ibase_connect
  - fbird_db_info — Псевдоним ibase_db_info
  - fbird_delete_user — Псевдоним ibase_delete_user
  - fbird_drop_db — Псевдоним ibase_drop_db
  - fbird_errcode — Псевдоним ibase_errcode
  - fbird_errmsg — Псевдоним ibase_errmsg
  - fbird_execute — Псевдоним ibase_execute
  - fbird_fetch_assoc — Псевдоним ibase_fetch_assoc
  - fbird_fetch_object — Псевдоним ibase_fetch_object
  - fbird_fetch_row — Псевдоним ibase_fetch_row
  - fbird_field_info — Псевдоним ibase_field_info
  - fbird_free_event_handler — Псевдоним ibase_free_event_handler
  - fbird_free_query — Псевдоним ibase_free_query
  - fbird_free_result — Псевдоним ibase_free_result
  - fbird_gen_id — Псевдоним ibase_gen_id
  - fbird_maintain_db — Псевдоним ibase_maintain_db
  - fbird_modify_user — Псевдоним ibase_modify_user
  - fbird_name_result — Псевдоним ibase_name_result
  - fbird_num_fields — Псевдоним ibase_num_fields
  - fbird_num_params — Псевдоним ibase_num_params
  - fbird_param_info — Псевдоним ibase_param_info
  - fbird_pconnect — Псевдоним ibase_pconnect
  - fbird_prepare — Псевдоним ibase_prepare
  - fbird_query — Псевдоним ibase_query
  - fbird_restore — Псевдоним ibase_restore
  - fbird_rollback — Псевдоним ibase_rollback
  - fbird_rollback_ret — Псевдоним ibase_rollback_ret
  - fbird_server_info — Псевдоним ibase_server_info
  - fbird_service_attach — Псевдоним ibase_service_attach
  - fbird_service_detach — Псевдоним ibase_service_detach
  - fbird_set_event_handler — Псевдоним ibase_set_event_handler
  - fbird_trans — Псевдоним ibase_trans
  - fbird_wait_event — Псевдоним ibase_wait_event
  - ibase_add_user — Добавляет пользователя в безопасную базу данных
  - ibase_affected_rows — Возвращает количество строк, на которые повлиял предыдущий запрос
  - ibase_backup — Инициирует задание резервного копирования в диспетчере служб и немедленно возвращает
  - ibase_blob_add — Добавляет данные во вновь созданный BLOB-объект
  - ibase_blob_cancel — Отменяет создания BLOB-объекта
  - ibase_blob_close — Закрывает BLOB-объект
  - ibase_blob_create — Создаёт новый BLOB-объект для заполнения данными
  - ibase_blob_echo — Выводит содержимое BLOB-объекта в браузер
  - ibase_blob_get — Получает количество байтов от открытого BLOB-объекта
  - ibase_blob_import — Создаёт BLOB-объект, копирует в него файл и закрывает его
  - ibase_blob_info — Возвращает длину BLOB-объекта и другую полезную информацию
  - ibase_blob_open — Открывает BLOB-объект для извлечения частей данных
  - ibase_close — Закрывает соединение с базой данных InterBase
  - ibase_commit — Фиксирует транзакцию
  - ibase_commit_ret — Фиксирует транзакцию, не закрывая её
  - ibase_connect — Открывает соединение с базой данных
  - ibase_db_info — Запрашивает статистику базы данных
  - ibase_delete_user — Удаляет пользователя из безопасной базы данных
  - ibase_drop_db — Удаляет базу данных
  - ibase_errcode — Возвращает код ошибки
  - ibase_errmsg — Возвращает сообщение об ошибке
  - ibase_execute — Выполняет предварительно подготовленный запрос
  - ibase_fetch_assoc — Извлекает строку результата из запроса в виде ассоциативного массива
  - ibase_fetch_object — Получает объект из базы данных InterBase
  - ibase_fetch_row — Извлекает строку из базы данных InterBase
  - ibase_field_info — Получает информацию о поле
  - ibase_free_event_handler — Отменяет зарегистрированный обработчик события
  - ibase_free_query — Освобождает память, выделенную на подготовку запроса
  - ibase_free_result — Освобождает набор результатов
  - ibase_gen_id — Увеличивает указанный генератор и возвращает его новое значение
  - ibase_maintain_db — Выполняет команду обслуживания на сервере базы данных
  - ibase_modify_user — Изменяет пользователя в безопасной базе данных
  - ibase_name_result — Присваивает имя набору результатов
  - ibase_num_fields — Возвращает количество полей в результирующем наборе
  - ibase_num_params — Возвращает количество параметров в подготовленном запросе
  - ibase_param_info — Возвращает информацию о параметре в подготовленном запросе
  - ibase_pconnect — Открывает постоянное соединение с базой данных InterBase
  - ibase_prepare — Подготавливает запрос для последующего связывания псевдопеременных и выполнения
  - ibase_query — Выполняет запрос к базе данных InterBase
  - ibase_restore — Запускает задачу восстановления в диспетчере служб и немедленно возвращается
  - ibase_rollback — Откатывает транзакцию
  - ibase_rollback_ret — Откатывает транзакцию, не закрывая её
  - ibase_server_info — Запрашивает информацию о сервере базы данных
  - ibase_service_attach — Подключается к диспетчеру служб
  - ibase_service_detach — Отключается от диспетчера служб
  - ibase_set_event_handler — Регистрирует callback-функцию, которая будет вызываться при публикации событий
  - ibase_trans — Начинает транзакцию
  - ibase_wait_event — Ждём, пока событие будет опубликовано в базе данных

# IBM DB2, Cloudscape и Apache Derby

# Введение

Эти функции позволят вам получить доступ к базам данных IBM DB2 Universal Database, IBM Cloudscape и Apache Derby, используя DB2 Call Level Interface (DB2 CLI).

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для соединения с IBM DB2 Universal Database под Linux, UNIX и Windows, IBM Cloudscape или Apache Derby, вы должны установить клиента IBM DB2 Universal Database на той же машине, где будет работать PHP. Модуль разрабатывался и тестировался с DB2 версии 8.2.

Для соединения с IBM DB2 Universal Database под z/OS или iSeries, вам нужен IBM DB2 Connect или эквивалентное ПО, способное быть шлюзом DRDA.

## Требования под Linux или Unix

Для доступа к функциям модуля из PHP, вам необходимо сначала задать экземпляр DB2 с которым вы будете работать. Его можно задать в php.ini с помощью опции `ibm_db2.instance_name` или вы можете создать профиль экземпляра DB2.

Если вы, к примеру, создадите экземпляр DB2 с именем `db2inst1` в /home/db2inst1/, вы можете добавить следующую запись в php.ini:

    ibm_db2.instance_name=db2inst1

Если вы не задали имя экземпляра php.ini, вы должны выполнить следующую команду, изменяющую переменные окружения, для доступа к DB2:

    bash$ source /home/db2inst1/sqllib/db2profile

Для разрешения доступа вашему веб-серверу к функциям модуля, вы должны либо задать опцию `ibm_db2.instance_name` в php.ini, либо обеспечить выставление соответствующих переменных окружения DB2 в вашем скрипте запуска веб-сервера (обычно это /etc/init.d/httpd или /etc/init.d/apache).

## Установка

Чтобы собрать модуль ibm_db2, необходимо установить в систему файлы заголовков и библиотеки для разработки приложений СУБД DB2. Система DB2 не устанавливает их по умолчанию, поэтому, возможно, придётся вернуться к установщику DB2 и добавить эти настройки. Клиент разработки приложений (Application Development Client) DB2 включает файлы заголовков и доступен для бесплатного скачивания с » сайта поддержки реляционной системы управления базами данных IBM DB2 Universal Database (DB2 UDB).

Если файлы заголовков и библиотеки для разработки DB2-приложений добавлены в операционную систему Linux или Unix, в которой база DB2 уже была установлена, нужно запустить команду db2iupdt -e, чтобы обновить символические ссылки на них в этом экземпляре DB2.

Модуль ibm_db2 — это модуль » PECL, так что следуйте инструкции «Установка PECL-модулей» для его установки в PHP. Чтобы указать расположение файлов заголовков и библиотек DB2, команду configure запускают как показано ниже:

    bash$ ./configure --with-IBM_DB2=/path/to/DB2

По умолчанию, configure использует путь /opt/IBM/db2/V8.1.

> Замечание: Замечание для пользователей IIS
> Если драйвер ibm_db2 работает на сервере Microsoft Internet Information Server (IIS), возможно, потребуется сделать следующее:

> - Установите DB2 с расширенной безопасностью операционной системы.
> - Добавьте путь к исполняемому файлу PHP в системную переменную окружения PATH (по умолчанию C:\php\).
> - Создайте ещё одну системную переменную окружения, содержащую путь к PHP.INI (например: PHPRC = C:\php\).
> - Добавьте учётную запись пользователя IUSR_COMPUTERNAME в группу DB2USERS.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

ibm_db2 Опции настройки
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
ibm_db2.binmode | "1" | `INI_ALL` |
ibm_db2.i5_all_pconnect | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.6.5.
ibm_db2.i5_allow_commit | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.4.9.
ibm_db2.i5_blank_userid | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_char_trim | "0" | `INI_SYSTEM` | Доступно с ibm_db2 2.1.0.
ibm_db2.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.5.0.
ibm_db2.i5_guard_profile | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_ignore_userid | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.8.0.
ibm_db2.i5_job_sort | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.8.4.
ibm_db2.i5_log_verbose | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_max_pconnect | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_override_ccsid | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_servermode_subsystem | NULL | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.i5_sys_naming | "0" | `INI_SYSTEM` | Доступно с ibm_db2 1.9.7.
ibm_db2.instance_name | NULL | `INI_SYSTEM` | Доступно с ibm_db2 1.0.2.

Краткое разъяснение конфигурационных директив.

`ibm_db2.binmode` int

  Опция управляет в PHP-приложении режимом конвертации из бинарных данных и обратно.

  - 1 (DB2_BINARY)
  - 2 (DB2_CONVERT)
  - 3 (DB2_PASSTHRU)
`ibm_db2.i5_all_pconnect` int

  Опция делает все соединения постоянными в операционной системе IBM i. По существу, вызовы функции db2_connect() прозрачно становятся вызовами функции db2_pconnect(). Значение по умолчанию — `0`. Опция полезна, если постоянные соединения работают быстрее. В новых приложениях опцию не указыают.

  - 0 — разрешается устанавливать постоянные и непостоянные соединения.
  - 1 — Все соединения постоянны.
`ibm_db2.i5_allow_commit` int

  Опция управляет режимом изоляции транзакций. По умолчанию эта опция равна `0`, поэтому контроль обязательств не будет использован. Эту опцию можно переопределить при подключении, если ключ массива `i5_commit` установлен в переданном в функцию db2_connect() или db2_pconnect() массиве настроек подключения.

  - 0 — контроль обязательств не используется.
  - 1 — read uncommitted, возможно грязное чтение.
  - 2 — read committed, грязное чтение не возможно.
  - 3 — repeatable read, грязное и неповторяющееся чтение не возможны.
  - 4 — serializeable, грязное чтение, неповторяющееся чтение и фантомы не возможны.
`ibm_db2.i5_blank_userid` int

  Опция определяет, разрешать ли пустой идентификатор пользователя в операционной системе IBM i. Значение по умолчанию — `0`. В отличие от опции `ibm_db2.i5_ignore_userid` эта опция не заставляет все идентификаторы пользователей быть пустыми или изменять поведение задания, но просто разрешает передавать пустой идентификатор пользователя для подключения к СУБД Db2 в качестве текущего пользователя.

  - 0 — Не разрешать передачу пустого идентификатора пользователя.
  - 1 — Разрешать передачу пустого идентификатора пользователя.
`ibm_db2.i5_char_trim` int

  Опция определяет, требуется ли обрезать концы строк в операционной системе IBM i. Это повышает удобство, поскольку во многих таблицах фиксированные размеры столбцов, дополненные пробелами. Значение этой опции по умолчанию — `0`.

  - 0 — Столбцы не обрезаются.
  - 1 — Пробелы в конце столбцов возвращаемых символов будут удалены.
`ibm_db2.i5_dbcs_alloc` int

  Опция влияет на стратегию распределения внутреннего буфера в операционных системах IBM i. Значение по умолчанию — `0`. Если эта опция установлена, выделяются буферы большего размера, если база данных недооценивает размер строки при преобразовании между кодировками. Для этой опции нужно в шесть раз больше памяти для буферов (чтобы учесть предельно возможные последовательности UTF-8), но может быть нужна, если возвращаются обрезанные данные.

  - 0 — Выделяется минимальный размер буферов.
  - 1 — Выделяется максимальный размер буферов.
`ibm_db2.i5_guard_profile` int

  Опция проверяет, был ли переключён профиль пользователя базы данных при подключении к постоянному соединению с базой данных в операционной системе IBM i, и если так, отключается от базы данных. По умолчанию для этой опции установлено значение `0`.

  - 0 — Не проверять смену профилей.
  - 1 — Проверять смену профилей, и если так, — отключать.
`ibm_db2.i5_log_verbose` int

  Опция устанавливает, будут ли диагностические сообщения SQL наподобие предупреждений и ошибок отправляться в журнал ошибок PHP в операционной системе IBM i. Обычно в PHP-лог отправляется только короткое сообщение о сбое (например, «выполнение выражения не удалось»), поскольку по умолчанию значение этой опции установлено как `0`. Обратите внимание, что всё ещё можно и даже нужно вызывать функцию db2_stmt_errormsg() вручную как часть проверки того, не завершится ли функция неудачно.

  - 0 — Регистрируются только короткие сообщения.
  - 1 — В дополнение к коротким сообщениям регистрируются диагностические сообщения SQL.
`ibm_db2.i5_ignore_userid` int

  Опция игнорирует идентификатор пользователя при подключении к базе данных при работе в операционной системе IBM i и запускает функционал SQL/CLI внутри задания PHP, а не отдельного задания. По умолчанию значение опции равно `0`. При включении опция больше не использует отдельное задание сервера базы данных и использует только текущий профиль пользователя для базы данных, игнорируя имя пользователя и пароль, которые передали в функции db2_connect() и db2_pconnect().

  - 0 — Использует заданные учётные данные и задание сервера SQL/CLI.
  - 1 — Использует пустые учётные данные и запускает SQL/CLI в задании PHP.
`ibm_db2.i5_job_sort` int

  Управляет опцией сортировки заданий в операционной системе IBM i. Значение по умолчанию — `0`. Это соответствует значению атрибута SQL/CLI `SQL_ATTR_CONN_SORT_SEQUENCE` в IBM i.

  - 0 — Применяет настройку сортировки `*HEX`, сортировка по байтам.
  - 1 — Применяет последовательность сортировки заданий, которую установили для PHP-задания.
  - 2 — Применяет последовательность сортировки заданий, которую установили для задания базы данных.
`ibm_db2.i5_max_pconnect` int
  Опция влияет на количество повторных запросов через постоянное соединение при работе в операционной системе IBM i. Значение по умолчанию — `0`, что означает — постоянное соединение доступно для повторных запросов. Параметр помогает обойти проблемы долгоработающего задания базы данных — при утечке памяти в процедуре, но это явно не долгосрочное решение.
`ibm_db2.i5_override_ccsid` int
  Идентификатор PASE CCSID для преобразования символов из кода EBCDIC в операционной системе IBM i. По умолчанию — `0`, который выберет значение по умолчанию идентификатор CCSID для задания окружения PASE, который будет взят из настроек языкового стандарта окружения PASE. Например, установка для этой опции значения `1208` будет использовать кодировку UTF-8. Опцию изменяют, только если CCSID-идентификатор задания PASE-окружения не соответствует идентификатору CCSID, который ожидался, и языковой стандарт нельзя изменить. Подробнее о CCSID-идентификаторах в операционной системы IBM i рассказывает » документация IBM. О сопоставлении языковых стандартов в окружении PASE системы IBM i с идентификаторами CCSID рассказывает другая » страница документации IBM.
`ibm_db2.i5_sys_naming` int

  Опция управляет режимом именования при подключении к системе IBM i. Значение по умолчанию — `0`. Режим именования влияет на способ разрешения имён и разрешённый синтаксис имён. Если задано значение `0`, для уточнения имён она будет использовать точки, а для разрешения имён — библиотеку по умолчанию или идентификатор пользователя. Если задано значение `1`, для уточнения имён она будет использовать слеши, а для разрешения имён — список библиотек заданий.

  - 0 — Применять режим именования SQL («SCHEMA.TABLE»).
  - 1 — Применять режим системного именования («LIBRARY/FILE»).
  О режимах именования в системе IBM i рассказывает » документации IBM.
`ibm_db2.i5_servermode-subsystem` string
  Опция изменяет подсистему, под которой выполняются задания сервера базы данных системы IBM i. Значение по умолчанию — `null`, поэтому задания для QSQSRVR-заданий выполняются в подсистеме по умолчанию.
`ibm_db2.instance_name` string

  В операционных системах Linux и UNIX опция определяет имя экземпляра для каталогизированных подключений к базе данных. Значение по умолчанию — `null`. Значение опции переопределяет настройку переменной окружения DB2INSTANCE.

  Опция игнорируется в операционных системах Windows.

## Типы ресурсов

Модуль ibm_db2 возвращает три типа ресурсов: ресурс соединения, ресурс оператора и ресурс результирующего набора.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`DB2_BINARY` (int)
  Указывает, что бинарные данные должны быть возвращены как есть. Этот режим используется по умолчанию.
`DB2_CONVERT` (int)
  Указывает, что бинарные данные должны конвертироваться в шестнадцатеричный формат и возвращаться как строка ASCII.
`DB2_PASSTHRU` (int)
  Указывает, что бинарные данные должны быть конвертированы в `null`.
`DB2_SCROLLABLE` (int)
  Курсор "scrollable" - перематываемый. Этот режим разрешает случайный доступ к строкам в результирующем наборе, но в данный момент поддерживается только для IBM DB2 Universal Database.
`DB2_FORWARD_ONLY` (int)
  Курсор "forward-only" - только вперёд. Используется по умолчанию и поддерживается всеми серверами баз данных.
`DB2_PARAM_IN` (int)
  Указанная переменная PHP должна быть привязана как параметр IN для хранимой процедуры.
`DB2_PARAM_OUT` (int)
  Указанная переменная PHP должна быть привязана как параметр OUT для хранимой процедуры.
`DB2_PARAM_INOUT` (int)
  Указанная переменная PHP должна быть привязана как параметр INOUT для хранимой процедуры.
`DB2_PARAM_FILE` (int)
  Указывает, что столбец должен быть привязан непосредственно к файлу для ввода.
`DB2_AUTOCOMMIT_ON` (int)
  Указывает, что необходимо включить режим автоподтверждения транзакции.
`DB2_AUTOCOMMIT_OFF` (int)
  Указывает, что необходимо отключить режим автоподтверждения транзакции.
`DB2_DOUBLE` (int)
  Указывает, что переменная должна быть связана как тип данных DOUBLE, FLOAT или REAL.
`DB2_LONG` (int)
  Указывает, что переменная должна быть связана как тип данных SMALLINT, INTEGER или BIGINT.
`DB2_CHAR` (int)
  Указывает, что переменная должна быть связана как тип данных CHAR или VARCHAR.
`DB2_CASE_NATURAL` (int)
  Указывает, что имена столбцов должны возвращаться как есть, без изменения регистра символов.
`DB2_CASE_LOWER` (int)
  Указывает, что имена столбцов должны возвращаться в нижнем регистре.
`DB2_CASE_UPPER` (int)
  Указывает, что имена столбцов должны возвращаться в верхнем регистре.
`DB2_DEFERRED_PREPARE_ON` (int)
  Указывает, что для данного ресурса оператора должен быть включён режим отложенной подготовки запроса.
`DB2_DEFERRED_PREPARE_OFF` (int)
  Указывает, что для данного ресурса оператора должен быть отключён режим отложенной подготовки запроса.

# Функции IBM DB2

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Возвращает или устанавливает режим автоподтверждения транзакций для соединения

### Описание

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Возвращает или устанавливает режим автоподтверждения транзакций для указанного соединения.

### Список параметров

`connection`
  Переменная содержащая активный ресурс подключения, полученный с помощью db2_connect() или db2_pconnect().
`value`

  Одна из следующих констант:

  `DB2_AUTOCOMMIT_OFF`
    Отключает автоподтверждение.
  `DB2_AUTOCOMMIT_ON`
    Включает автоподтверждение.

### Возвращаемые значения

Если в db2_autocommit() передать только параметр `connection`, она вернёт значение текущего режима для этого соединения в виде целого числа принимающего значение `DB2_AUTOCOMMIT_OFF`, если автоподтверждение отключено и `DB2_AUTOCOMMIT_ON`, если включено.

Если в db2_autocommit() переданы оба параметра, `connection` и `autocommit`, она попытается установить для заданного соединения указанный режим автоподтверждения. Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение текущего режима автоподтверждения транзакций

В следующем примере мы создадим соединение с отключённым автоподтверждением и проверим его с помощью db2_autocommit().

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- автоподтверждение включено.";
    } else {
        print "$ac -- автоподтверждение отключено.";
    }
    ?>

Результат выполнения приведённого примера:

    0 -- автоподтверждение отключено.

Пример #2 Установка режима автоподтверждения транзакции

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

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);

    // Включаем автоподтверждение
    $rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
    if ($rc) {
        print "Автоподтверждение успешно включено.\n";
    }

    // ппроверяет текущий режим
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- автоподтверждение включено.";
    } else {
        print "$ac -- автоподтверждение отключено.";
    }
    ?>

Результат выполнения приведённого примера:

    Автоподтверждение успешно включено.
    1 -- автоподтверждение включено.

### Смотрите также

- db2_connect() - Возвращает соединение с базой данных
- db2_pconnect() - Возвращает постоянное соединение с базой данных

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Связывает переменную PHP с параметром SQL-выражения

### Описание

function db2_bind_param(
resource `$stmt`,
int `$parameter_number`,
string `$variable_name`,
int `$parameter_type` = `DB2_PARAM_IN`,
int `$data_type` = 0,
int `$precision` = -1,
int `$scale` = 0
): bool

Связывает переменную PHP с параметром SQL-выражения в ресурсе выражения, возвращаемом db2_prepare(). Эта функция даёт больший контроль над типом параметра, типом данных, точностью и масштабом для параметра, чем простая передача переменной как части необязательного входного массива в db2_execute().

### Список параметров

`stmt`
  Подготовленное выражение, возвращаемое db2_prepare().
`parameter_number`
  Задаёт позицию параметра, которая нумеруется с 1, в подготовленном выражении.
`variable_name`
  Строка, определяющая имя переменной PHP для привязки к параметру, заданному `parameter_number`.
`parameter_type`
  Константа, которая определяет, должна ли переменная PHP быть привязана к параметру SQL как входной параметр (`DB2_PARAM_IN`), выходной параметр (`DB2_PARAM_OUT`) или как параметр, который принимает ввод и возвращает вывод (`DB2_PARAM_INOUT`). Чтобы избежать перегрузки памяти, можно также указать `DB2_PARAM_FILE`, чтобы привязать переменную PHP к имени файла, который содержит данные большого объекта (BLOB, CLOB или DBCLOB).
`data_type`
  Константа, указывающая тип данных SQL, с которым должна быть связана переменная PHP: `DB2_BINARY`, `DB2_CHAR`, `DB2_DOUBLE` или `DB2_LONG`.
`precision`
  Задаёт точность, с которой переменная должна быть привязана к базе данных. Этот параметр также можно использовать для получения выходных значений XML из хранимых процедур. Неотрицательное значение указывает максимальный размер данных XML, которые будут извлечены из базы данных. Если этот параметр не используется, для получения выходного значения XML из хранимой процедуры предполагается значение по умолчанию 1 МБ.
`scale`
  Задаёт масштаб, с которым переменная должна быть привязана к базе данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Привязка переменных PHP к подготовленному выражению

SQL-выражение в данном примере использует два входных параметра в предложении WHERE. Вызывается db2_bind_param(), чтобы связать две переменные PHP с соответствующими параметрами SQL. Обратите внимание, что переменные PHP не нужно объявлять или присваивать перед вызовом db2_bind_param(); в этом примере `$lower_limit` присваивается значение перед вызовом db2_bind_param(), а `$upper_limit` присваивается значение после вызова db2_bind_param(). Перед вызовом db2_execute() переменные должны быть связаны, а параметрам, принимающим ввод, должно быть присвоено любое значение. db2_execute().

    <?php

    $sql = 'SELECT name, breed, weight FROM animals
        WHERE weight > ? AND weight < ?';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    // Можно объявить переменную перед вызовом db2_bind_param()
    $lower_limit = 1;

    db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

    // Также можно объявить переменную после вызова db2_bind_param()
    $upper_limit = 15.0;

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            print "{$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

Результат выполнения приведённого примера:

    Pook, cat, 3.2
    Rickety Ride, goat, 9.7
    Peaches, dog, 12.3

Пример #2 Вызов хранимых процедур с параметрами IN и OUT

Хранимая процедура match_animal в данном примере принимает три разных параметра:

1. входной параметр (IN), который принимает имя первого животного в качестве входных данных
2. параметр ввода-вывода (INOUT), который принимает имя второго животного в качестве входных данных и возвращает строку `TRUE`, если животное в базе данных совпадает с этим именем
3. выходной параметр (OUT), который возвращает сумму веса двух идентифицированных животных

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

    <?php

    $sql = 'CALL match_animal(?, ?, ?)';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    $name = "Peaches";
    $second_name = "Rickety Ride";
    $weight = 0;

    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
    db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

    print "Values of bound parameters _before_ CALL:\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    if (db2_execute($stmt)) {
        print "Values of bound parameters _after_ CALL:\n";
        print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

        print "Results:\n";
        while ($row = db2_fetch_array($stmt)) {
            print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

Результат выполнения приведённого примера:

    Values of bound parameters _before_ CALL:
      1: Peaches 2: Rickety Ride 3: 0

    Values of bound parameters _after_ CALL:
      1: Peaches 2: TRUE 3: 22

    Results:
      Peaches, dog, 12.3
      Pook, cat, 3.2
      Rickety Ride, goat, 9.7

Пример #3 Вставка большого двоичного объекта (BLOB) напрямую из файла

Данные для больших объектов обычно хранятся в файлах, таких как документы XML или аудиофайлы. Вместо того, чтобы считывать весь файл в переменную PHP и затем связывать эту переменную PHP с SQL-выражением, можно избежать некоторых накладных расходов на память, привязав файл напрямую к входному параметру SQL-выражения. В данном примере показано, как привязать файл напрямую к столбцу BLOB.

    <?php
    $stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

    $picture = "/opt/albums/spook/grooming.jpg";
    $rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
    $rc = db2_execute($stmt);
    ?>

### Смотрите также

- db2_execute() - Выполняет подготовленный SQL-запрос
- db2_prepare() - Подготавливает SQL-запрос к выполнению

# db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — Возвращает объект со свойствами, описывающими клиента DB2

### Описание

function db2_client_info(resource `$connection`): stdClass|false

Эта функция возвращает объект с доступными только на чтение свойствами, возвращающими информацию о клиенте DB2. Эти свойства перечислены в следующей таблице:

Свойства клиента DB2
Имя свойства | Возвращаемый тип | Описание
--- | --- | ---
APPL_CODEPAGE | int | Кодовая страница приложения.
CONN_CODEPAGE | int | Кодовая страница текущего соединения.
DATA_SOURCE_NAME | string | Имя источника данных (DSN) использовавшееся для создания текущего соединения.
DRIVER_NAME | string | Имя библиотеки реализующей спецификацию DB2 Call Level Interface (CLI).
DRIVER_ODBC_VER | string | Версия ODBC, которую поддерживает клиент DB2. Возвращает строку "MM.mm", где MM - мажор, а mm - минор. Клиент DB2 всегда возвращает "03.51".
DRIVER_VER | string | Версия клиента в виде строки "MM.mm.uuuu", где MM - мажор, mm - минор, а uuuu - уровень обновления. К примеру, "08.02.0001" означает мажорную версию 8, минорную 2 и уровень обновления 1.
ODBC_SQL_CONFORMANCE | string | Уровень поддержки клиентом грамматики ODBC SQL: MINIMUM Минимальная поддержка грамматики ODBC SQL. CORE Базовая поддержка грамматики ODBC SQL. EXTENDED Расширенная поддержка грамматики ODBC SQL.
ODBC_VER | string | Версия ODBC, которую поддерживает драйвер ODBC. Возвращает строку формата "MM.mm.rrrr", где MM - мажор, mm - минор и rrrr - версия релиза. Клиент DB2 всегда возвращает "03.01.0000".

### Список параметров

`connection`
  Задаёт активное соединение DB2.

### Возвращаемые значения

В случае успешного выполнения возвращает объект или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования db2_client_info()

Для получения информации вы должны передать корректный ресурс соединения в db2_client_info().

    <?php
    $conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
    $client = db2_client_info( $conn );

    if ($client) {
        echo "DRIVER_NAME: ";           var_dump( $client->DRIVER_NAME );
        echo "DRIVER_VER: ";            var_dump( $client->DRIVER_VER );
        echo "DATA_SOURCE_NAME: ";      var_dump( $client->DATA_SOURCE_NAME );
        echo "DRIVER_ODBC_VER: ";       var_dump( $client->DRIVER_ODBC_VER );
        echo "ODBC_VER: ";              var_dump( $client->ODBC_VER );
        echo "ODBC_SQL_CONFORMANCE: ";  var_dump( $client->ODBC_SQL_CONFORMANCE );
        echo "APPL_CODEPAGE: ";         var_dump( $client->APPL_CODEPAGE );
        echo "CONN_CODEPAGE: ";         var_dump( $client->CONN_CODEPAGE );
    }
    else {
        echo "Error retrieving client information.
         Perhaps your database connection was invalid.";
    }
    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    DRIVER_NAME: string(8) "libdb2.a"
    DRIVER_VER: string(10) "08.02.0001"
    DATA_SOURCE_NAME: string(6) "SAMPLE"
    DRIVER_ODBC_VER: string(5) "03.51"
    ODBC_VER: string(10) "03.01.0000"
    ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
    APPL_CODEPAGE: int(819)
    CONN_CODEPAGE: int(819)

### Смотрите также

- db2_server_info() - Возвращает объект со свойствами, описывающими сервер базы данных DB2

# db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — Закрывает соединение с базой данных

### Описание

function db2_close(resource `$connection`): bool

Функция закрывает соединение с базой DB2, созданное с помощью db2_connect() и возвращает соответствующие ресурсы серверу баз данных.

Если вы попытаетесь закрыть постоянное соединение, созданное с помощью db2_pconnect(), то запрос на закрытие будет проигнорирован и соединение будет доступно для последующего использования.

### Список параметров

`connection`
  Активное соединение с DB2.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Закрытие соединения

Следующий пример демонстрирует успешную попытку закрыть соединение с IBM DB2, Cloudscape, или базой данных Apache Derby.

    <?php
    $conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
    $rc = db2_close($conn);
    if ($rc) {
        echo "Соединение закрыто.";
    }
    ?>

Результат выполнения приведённого примера:

    Соединение закрыто.

### Смотрите также

- db2_connect() - Возвращает соединение с базой данных
- db2_pclose() - Закрывает постоянное соединение с базой данных
- db2_pconnect() - Возвращает постоянное соединение с базой данных

# db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы

### Описание

function db2_column_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы.

### Список параметров

`connection`
  Ресурс соединения с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз DB2, работающих на серверах OS/390 или z/OS. В остальных случаях указывайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Для выбора всех схем укажите `null` или пустую строку.
`table_name`
  Имя таблицы или представления. Для выбора всех таблиц укажите `null` или пустую строку.
`column_name`
  Имя столбца. Для выбора всех столбцов укажите `null` или пустую строку.

### Возвращаемые значения

Возвращает ресурс оператора с результирующим набором, содержащим строки, описывающие привилегии заданных условиями столбцов. Строки содержат следующие поля:

Имя столбца | Описание
--- | ---
TABLE_CAT | Имя каталога. Если таблица не имеет каталогов, то это поле будет содержать NULL.
TABLE_SCHEM | Имя схемы.
TABLE_NAME | Имя таблицы или представления.
COLUMN_NAME | Имя столбца.
GRANTOR | Идентификатор пользователя, установившего привилегию.
GRANTEE | Идентификатор пользователя, для которого установлена привилегия.
PRIVILEGE | Установленная привилегия.
IS_GRANTABLE | Может ли GRANTEE выдавать эту привилегию другим пользователям.

### Смотрите также

- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы

### Описание

function db2_columns(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Returns a result set listing the columns and associated metadata for a table.

### Список параметров

`connection`
  Ресурс соединения с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз DB2, работающих на серверах OS/390 или z/OS. В остальных случаях указывайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Для выбора всех схем укажите `'%'`.
`table_name`
  Имя таблицы или представления. Для выбора всех таблиц укажите `null` или пустую строку.
`column_name`
  Имя столбца. Для выбора всех столбцов укажите `null` или пустую строку.

### Возвращаемые значения

Возвращает ресурс оператора с результирующим набором, содержащим строки, описывающие заданные условиями столбцы. Строки содержат следующие поля:

Имя столбца | Описание
--- | ---
TABLE_CAT | Имя каталога. Если таблица не имеет каталогов, то это поле будет содержать NULL.
TABLE_SCHEM | Имя схемы.
TABLE_NAME | Имя таблицы или представления.
COLUMN_NAME | Имя столбца.
DATA_TYPE | Тип данных SQL в виде целого числа.
TYPE_NAME | Текстовое представление типа данных.
COLUMN_SIZE | Размер столбца в виде целого числа.
BUFFER_LENGTH | Максимальное количество байт, необходимое для хранения данных из этого столбца.
DECIMAL_DIGITS | Количество цифр после запятой, или `null`, если не применимо.
NUM_PREC_RADIX | Целое число, равное `10` (если длина числа измеряется в десятичных цифрах), `2` (если длина измеряется в битах), или `null` (если не применимо).
NULLABLE | Целое число, определяющее, может ли столбец принимать значение NULL.
REMARKS | Описание столбца.
COLUMN_DEF | Значение поля по умолчанию.
SQL_DATA_TYPE | Целое число, определяющее длину записи.
SQL_DATETIME_SUB | Возвращает целое число, описывающее подтип данных Datrtime или `null`, если не применимо.
CHAR_OCTET_LENGTH | Максимальная длина в октетах для символьных типов данных. Совпадает с COLUMN_SIZE для однобайтовых символьных данных или `null` для несимвольных данных.
ORDINAL_POSITION | Порядковый номер столбца в таблице. Начинаются с 1.
IS_NULLABLE | Строка равная 'YES', если столбец может быть NULL и 'NO', если нет.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — Подтверждает транзакцию

### Описание

function db2_commit(resource `$connection`): bool

Подтверждает текущую транзакцию на указанном соединении и начинает новую. По умолчанию, в PHP, используется автоподтверждение транзакций, так что функция db2_commit() нужна только в том случае, если вы принудительно отключили автоподтверждение транзакций для соединения.

### Список параметров

`connection`
  Переменная содержащая активный ресурс подключения, полученный с помощью db2_connect() или db2_pconnect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- db2_autocommit() - Возвращает или устанавливает режим автоподтверждения транзакций для соединения
- db2_rollback() - Откатывает транзакцию

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения

### Описание

function db2_conn_error(?resource `$connection` = `null`): string

Возвращает значение SQLSTATE, представляющее причину, по которой последняя попытка подключения к базе данных завершилась неудачей. Поскольку db2_connect() возвращает `false` в случае неудачной попытки подключения, не нужно передавать никаких параметров в db2_conn_error() для получения значения SQLSTATE.

Однако, если соединение было успешным, но со временем стало недействительным, можно передать параметр `connection`, чтобы получить значение SQLSTATE для конкретного соединения.

Чтобы узнать, что означает значение SQLSTATE, вы можете ввести следующую команду в командной строке DB2 Command Line Processor: `db2 '? `sqlstate-value`'`. Также можно вызвать db2_conn_errormsg(), чтобы получить явное сообщение об ошибке и соответствующее значение SQLCODE.

### Список параметров

`connection`
  Ресурс подключения, связанный с подключением, которое изначально было успешным, но со временем стало недействительным.

### Возвращаемые значения

Возвращает значение SQLSTATE, полученное в результате неудачной попытки подключения. Возвращает пустую строку, если при последней попытке подключения ошибок не возникло.

### Примеры

Пример #1 Получение значения SQLSTATE для неудачной попытки подключения

В данном примере показано, как вернуть значение SQLSTATE после преднамеренной передачи недопустимых параметров в db2_connect().

    <?php
    $conn = db2_connect('badname', 'baduser', 'badpassword');
    if (!$conn) {
        print "SQLSTATE value: " . db2_conn_error();
    }
    ?>

Результат выполнения приведённого примера:

    SQLSTATE value: 08001

### Смотрите также

- db2_conn_errormsg() - Возвращает последнее сообщение об ошибке подключения и значение SQLCODE
- db2_connect() - Возвращает соединение с базой данных
- db2_stmt_error() - Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором
- db2_stmt_errormsg() - Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — Возвращает последнее сообщение об ошибке подключения и значение SQLCODE

### Описание

function db2_conn_errormsg(?resource `$connection` = `null`): string

Возвращает сообщение об ошибке и значение SQLCODE, представляющее причину, по которой последняя попытка подключения к базе данных завершилась неудачей. Поскольку db2_connect() возвращает `false` в случае неудачной попытки подключения, не нужно передавать никаких параметров в db2_conn_errormsg() для получения соответствующего сообщения об ошибке и значения SQLCODE.

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

### Список параметров

`connection`
  Ресурс подключения, связанный с подключением, которое изначально было успешным, но со временем стало недействительным.

### Возвращаемые значения

Возвращает строку, содержащую сообщение об ошибке и значение SQLCODE, полученное в результате неудачной попытки подключения. Если при последней попытке подключения ошибок не возникло, db2_conn_errormsg() возвращает пустую строку.

### Примеры

Пример #1 Получение сообщения об ошибке, возвращённого при неудачной попытке подключения

В данном примере показано, как вернуть сообщение об ошибке и значение SQLCODE после преднамеренной передачи недопустимых параметров в db2_connect().

    <?php
    $conn = db2_connect('badname', 'baduser', 'badpassword');
    if (!$conn) {
        print db2_conn_errormsg();
    }
    ?>

Результат выполнения приведённого примера:

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "BADNAME" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### Смотрите также

- db2_conn_error() - Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения
- db2_connect() - Возвращает соединение с базой данных
- db2_stmt_error() - Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором
- db2_stmt_errormsg() - Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения

# db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — Возвращает соединение с базой данных

### Описание

function db2_connect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Функция создаёт новое соединение с базой данных IBM DB2 Universal Database, IBM Cloudscape или базой данных Apache Derby.

### Список параметров

`database`
  Для каталогизированного соединения с базой данных параметр `database` представляет собой псевдоним базы данных в клиентском каталоге DB2.

  Для некаталогизированного подключения к базе данных параметр `database` представляет собой полную строку подключения в следующем формате:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Замечание:

  > При подключении к БД Db2 на ОС IBM i базовая система вызывает функцию » SQLDriverConnect, которая принимает только имя источника данных DSN, идентификатор пользователя UID и пароль PWD для » строки подключения. Вот так:

  >     DSN=database;UID=username;PWD=password;

  где параметры представляют следующие значения:
  `database`
    Имя базы данных.
  `hostname`
    Имя хоста или IP-адрес сервера базы данных.
  `port`
    Порт TCP/IP, который используется базой данных для принятия запросов.
  `username`
    Имя пользователя, под которым выполняется подключение к базе данных.
  `password`
    Пароль, с которым выполняется подключение к базе данных.
`username`
  Имя пользователя, под которым выполняется подключение к базе данных. Для некаталогизированных соединений необходимо передать значение `null` или пустую строку.
`password`
  Пароль, с которым выполняется подключение к базе данных. Для некаталогизированных соединений необходимо передать значение `null` или пустую строку.
`options`

  Ассоциативный массив параметров подключения, которые влияют на поведение подключения, в котором допустимые ключи массива включают:

  `autocommit`
    Передача значения `DB2_AUTOCOMMIT_ON` включает автоматическую фиксацию (autocommit) для этого дескриптора соединения. Передача значения `DB2_AUTOCOMMIT_OFF` выключает автоматическую фиксацию (autocommit) для этого дескриптора соединения.
  `DB2_ATTR_CASE`
    Передача значения `DB2_CASE_NATURAL` указывает, что имена столбцов возвращаются в естественном регистре. Передача значения `DB2_CASE_LOWER` указывает, что имена столбцов возвращаются в нижнем регистре. Передача значения `DB2_CASE_UPPER` указывает, что имена столбцов возвращаются в верхнем регистре.
  `CURSOR`
    Передача значения `DB2_FORWARD_ONLY` задаёт курсор, который двигается только вперёд, для ресурса оператора. Данный тип курсора используется по умолчанию, он поддерживается всеми серверами баз данных. Передача значения `DB2_SCROLLABLE` задаёт прокручиваемый курсор для ресурса оператора. Этот режим включает произвольный доступ к строкам в наборе результатов, но в настоящее время поддерживается только IBM DB2 Universal Database.

  Эта новая опция доступна в модуле ibm_db2 версии 1.7.0 и новее.

  `trustedcontext`
    Передача значения DB2_TRUSTED_CONTEXT_ENABLE включает доверенный контекст для этого дескриптора соединения. Этот параметр нельзя установить функцией db2_set_option(). Этот ключ работает только тогда, когда базу данных каталогизировали (даже если база данных локальная) или если укажут полное DSN-имя при создании соединения. Чтобы каталогизировать базу данных, выполняют следующие команды:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
                  db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
                  db2 "update dbm cfg using svcename <SERVICENAME>"
                  db2set DB2COMM=TCPIP

  Эти новые опции ОС i5/OS доступны в модуле ibm_db2 версии 1.5.1 и новее.

  `i5_lib`
    Символьное значение, которое указывает библиотеку по умолчанию, которая будет использоваться для разрешения неквалифицированных ссылок на файлы. Это недопустимо, если соединение использует режим именования системы.
  `i5_naming`
    Значение `DB2_I5_NAMING_ON` включает режим именования системы DB2 UDB CLI iSeries. Файлы квалифицируются через слеш (/) в качестве разделителя. Неквалифицированные файлы разрешаются с использованием списка библиотек для работы. Значение `DB2_I5_NAMING_OFF` выключает режим именования по умолчанию DB2 UDB CLI, который представляет собой именование SQL. Файлы квалифицируются через точку (.) в качестве разделителя. Неквалифицированные файлы разрешаются с использованием либо библиотеки по умолчанию, либо текущего идентификатора пользователя.
  `i5_commit`

    Атрибут `i5_commit` требуется установить перед вызовом функции db2_connect(). Если значение изменяется после установки соединения, и соединение установлено с удалённым источником данных, изменение не вступит в силу до следующего успешного вызова функции db2_connect() для дескриптора соединения.

    > Замечание: Параметр `ibm_db2.i5_allow_commit`==0 файла php.ini или настройка `DB2_I5_TXN_NO_COMMIT` используется по умолчанию, но может быть изменён через параметр `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` — Контроль транзакций не используется. `DB2_I5_TXN_READ_UNCOMMITTED` — Возможны грязные чтения, неповторяющиеся чтения и фантомы. `DB2_I5_TXN_READ_COMMITTED` — Грязное чтение невозможно. Возможны неповторяющиеся чтения и фантомы `DB2_I5_TXN_REPEATABLE_READ` — Грязные чтения и неповторяющиеся чтения невозможны. Возможны фантомы. `DB2_I5_TXN_SERIALIZABLE` — Транзакции сериализуемы. Грязные чтения, неповторяющиеся чтения и фантомы невозможны.
  `i5_query_optimize`
    `DB2_FIRST_IO` — Все запросы оптимизированы с целью максимально быстрого возврата первой страницы вывода. Эта цель хорошо работает, когда вывод контролируется пользователем, который, скорее всего, отменит запрос после просмотра первой страницы выходных данных. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, учитывают цель, указанную в предложении. `DB2_ALL_IO` — Все запросы оптимизированы с целью выполнить весь запрос до завершения в кратчайшие сроки. Это хороший вариант, когда выходные данные запроса записываются в файл или отчёт, или когда интерфейс ставит выходные данные в очередь. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, учитывают цель, указанную в предложении. Это значение по умолчанию.
  `i5_dbcs_alloc`
    Значение `DB2_I5_DBCS_ALLOC_ON` включает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS. Значение `DB2_I5_DBCS_ALLOC_OFF` отключает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS. Замечание: параметр `ibm_db2.i5_dbcs_alloc`==0 файла php.ini или параметр `DB2_I5_DBCS_ALLOC_OFF` — значение по умолчанию, но его можно изменить через параметр `i5_dbcs_alloc`.
  `i5_date_fmt`
    `DB2_I5_FMT_ISO` — Используется формат даты Международной организации по стандартизации ISO (yyyy-mm-dd). Это значение по умолчанию. `DB2_I5_FMT_USA` — Используется формат даты США (mm/dd/yyyy). `DB2_I5_FMT_EUR` — Используется европейский формат даты (dd.mm.yyyy). `DB2_I5_FMT_JIS` — Используется формат даты японского промышленного стандарта (yyyy-mm-dd). `DB2_I5_FMT_MDY` — Используется формат даты mm/dd/yyyy. `DB2_I5_FMT_DMY` — Используется формат даты dd/mm/yyyy. `DB2_I5_FMT_YMD` — Используется формат даты yy/mm/dd. `DB2_I5_FMT_JUL` — Используется юлианский формат даты (yy/ddd). `DB2_I5_FMT_JOB` — Используется задание по умолчанию.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` — В качестве разделителя даты используется косая черта ( / ). Это значение по умолчанию. `DB2_I5_SEP_DASH` — В качестве разделителя даты используется дефис ( - ). `DB2_I5_SEP_PERIOD` — В качестве разделителя даты используется точка ( . ). `DB2_I5_SEP_COMMA` — В качестве разделителя даты используется запятая ( , ). `DB2_I5_SEP_BLANK` — В качестве разделителя даты используется пробел. `DB2_I5_SEP_JOB` — Используется задание по умолчанию.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` — Используется формат времени Международной организации по стандартизации ISO (hh.mm.ss). Это значение по умолчанию. `DB2_I5_FMT_USA` — Используется формат времени США (hh:mmxx, где xx — обозначение AM или PM). `DB2_I5_FMT_EUR` — Используется европейский формат времени (hh.mm.ss). `DB2_I5_FMT_JIS` — Используется японский промышленный стандартный формат времени (hh:mm:ss). `DB2_I5_FMT_HMS` — Используется формат hh:mm:ss.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` — В качестве разделителя времени используется двоеточие ( : ). Это значение по умолчанию. `DB2_I5_SEP_PERIOD` — В качестве разделителя времени используется точка ( . ). `DB2_I5_SEP_COMMA` — В качестве разделителя времени используется запятая ( , ). `DB2_I5_SEP_BLANK` — В качестве разделителя времени используется пробел. `DB2_I5_SEP_JOB` — Используется задание по умолчанию.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` — В качестве десятичного разделителя используется точка ( . ). Это значение по умолчанию. `DB2_I5_SEP_COMMA` — В качестве десятичного разделителя используется запятая ( , ). `DB2_I5_SEP_JOB` — Используется задание по умолчанию.

  Данная новая опция ОС i5/OS доступна в модуле ibm_db2 версии 1.8.0 и новее.

  `i5_libl`
    Символьное значение, которое указывает список библиотек, который будет использоваться для разрешения неквалифицированных ссылок на файлы. Укажите элементы списка библиотек через пробелы: 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Замечание: Параметр `i5_libl` вызывает qsys2/qcmdexc('cmd',cmdlen), который доступен только в ОС i5/OS V5R4 и новее.

### Возвращаемые значения

Функция возвращает ресурс дескриптора подключения, если попытка подключения успешна. Функция db2_connect() возвращает `false`, елси возникла ошибка подключения.

### Примеры

Пример #1 Пример создания каталогизированного соединения

Каталогизированные соединения требуют, предварительной каталогизации базы данных через Command Line Processor (CLP) или Configuration Assistant базы данных DB2.

    <?php

    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        echo "Соединение установлено.";
        db2_close($conn);
    } else {
        echo "Не удалось установить соединение.";
    }

    ?>

Результат выполнения приведённого примера:

    Соединение установлено.

Пример #2 Пример создания некаталогизированного соединения

Некаталогизированное соединение разрешает динамически подключаться к базе данных.

    <?php

    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $hostname = 'localhost';
    $port = 50000;

    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
        "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;"
    ;

    $conn = db2_connect($conn_string, '', '');

    if ($conn) {
        echo "Соединение установлено.";
        db2_close($conn);
    } else {
        echo "Не удалось установить соединение.";
    }

    ?>

Результат выполнения приведённого примера:

    Соединение установлено.

Пример #3 Пример создания соединения с отключённой автофиксацией по умолчанию

Передача массива параметров в функцию db2_connect() разрешает изменять поведение дескриптора соединения по умолчанию.

    <?php

    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

    $conn = db2_connect($database, $user, $password, $options);

    if ($conn) {
        echo "Соединение установлено.\n";

        if (db2_autocommit($conn)) {
            echo "Автофиксация включена.\n";
        } else {
            echo "Автофиксация выключена.\n";
        }

        db2_close($conn);
    } else {
        echo "Не удалось установить соединение.";
    }

    ?>

Результат выполнения приведённого примера:

    Соединение установлено.
    Автофиксация выключена.

Пример #4 Лучшая производительность ОС i5/OS

Чтобы добиться максимальной производительности PHP-приложения, которое работает с модулем ibm_db2 1.5.1 операционной системы i5/OS, указывают хост по умолчанию, идентификатор пользователя и пароль для функции db2_connect().

    <?php

    $library = "ADC";
    $i5 = db2_connect("", "", "", array("i5_lib" => "qsys2"));

    $result = db2_exec(
        $i5,
        "SELECT * FROM systables WHERE table_schema = '$library'"
    );

    while ($row = db2_fetch_both($result)) {
        echo $row['TABLE_NAME'] . "<br>";
    }

    db2_close($i5);

    ?>

Результат выполнения приведённого примера:

    ANIMALS
    NAMES
    PICTURES

Пример #5 Пример работы с доверенным контекстом

Пример показывает, как включить доверенный контекст, переключить пользователей и получить текущий идентификатор пользователя.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;"
        . "PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";

    $options = array("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_connect($dsn, "", "", $options);

    if ($tc_conn) {
        echo "Явное доверенное соединение установлено.\n";

        if (db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            // Выполнение работы в качестве пользователя с идентификатором 1

            // Переключение на доверенного пользователя
            $parameters = array(
                "trusted_user" => $tc_user,
                "trusted_password" => $tcuser_pass
            );
            $res = db2_set_option($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            // Продолжение выполнения работы в качестве доверенного пользователя

            if ($userBefore != $userAfter) {
                echo "Пользователь был переключён." . "\n";
            }
        }

        db2_close($tc_conn);
    } else {
        echo "Не удалось установить явное доверенное соединение.\n";
    }

    ?>

Результат выполнения приведённого примера:

    Явное доверенное соединение установлено.
    Пользователь был переключён.

### Смотрите также

- db2_close() - Закрывает соединение с базой данных
- db2_pconnect() - Возвращает постоянное соединение с базой данных

# db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — Возвращает тип курсора, который используется в ресурсе оператора

### Описание

function db2_cursor_type(resource `$stmt`): int

Возвращает тип курсора, который используется в ресурсе оператора.

### Список параметров

`stmt`
  Корректный ресурс оператора.

### Возвращаемые значения

Функция возвращает либо значение константы `DB2_FORWARD_ONLY`, если ресурс инструкции использует курсор только для прямого перемещения, либо `DB2_SCROLLABLE`, если ресурс инструкции использует прокручиваемый курсор.

### Смотрите также

- db2_prepare() - Подготавливает SQL-запрос к выполнению

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — Экранирует отдельные символы

### Описание

function db2_escape_string(string `$string_literal`): string

Функция добавляет обратные слеши перед специальными символами в строковом аргументе.

### Список параметров

`string_literal`
  Строка, которая содержит символы, которые требуется экранировать. Символы, которые необходимо экранировать: `\x00`, `\n`, `\r`, `\`, `'`, `"` и `\x1a`.

### Возвращаемые значения

Функция возвращает параметр `string_literal` с экранированными специальными символами.

### Примеры

Пример #1 Пример использования функции db2_escape_string()

Результат выполнения функции db2_escape_string()

    <?php

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $str[0] = "All characters: \x00 , \n , \r , \ , ' , \" , \x1a .";
        $str[1] = "Backslash (\). Single quote ('). Double quote (\")";
        $str[2] = "The NULL character \0 must be quoted as well";
        $str[3] = "Intersting characters: \x1a , \x00 .";
        $str[4] = "Nothing to quote";
        $str[5] = 200676;
        $str[6] = "";

        foreach( $str as $string ) {
            echo "db2_escape_string: " . db2_escape_string($string). "\n";
        }
    }

    ?>

Результат выполнения приведённого примера:

    db2_escape_string: All characters: \0 , \n , \r , \\ , \' , \" , \Z .
    db2_escape_string: Backslash (\\). Single quote (\'). Double quote (\")
    db2_escape_string: The NULL character \0 must be quoted as well
    db2_escape_string: Intersting characters: \Z , \0 .
    db2_escape_string: Nothing to quote
    db2_escape_string: 200676
    db2_escape_string:

### Смотрите также

- db2_prepare() - Подготавливает SQL-запрос к выполнению

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Выполняет SQL-запрос напрямую

### Описание

function db2_exec(resource `$connection`, string `$statement`, array `$options` = []): resource|false

Выполняет SQL-запрос напрямую.

Если вы планируете интерполировать переменные PHP в SQL-запрос, имейте в виду, что это одна из наиболее распространённых уязвимостей безопасности. Рассмотрите возможность вызова db2_prepare() для подготовки SQL-запроса с маркерами параметров для входных значений. Затем вы можете вызвать db2_execute(), чтобы передать входные значения и избежать атак SQL-инъекций.

Если вы планируете многократно выполнять один и тот же SQL-запрос с разными параметрами, рассмотрите возможность вызова db2_prepare() и db2_execute(), чтобы сервер базы данных мог повторно использовать свой план доступа и повысить эффективность вашей базы данных.

### Список параметров

`connection`
  Допустимая переменная ресурса соединения с базой данных, возвращаемого функцией db2_connect() или db2_pconnect().
`statement`
  SQL-запрос. Запрос не может содержать маркеры параметров.
`options`
  Ассоциативный массив, содержащий параметры оператора. Параметр можно использовать для запроса прокручиваемого курсора на серверах баз данных, поддерживающих эту функцию. Описание допустимых опций оператора смотрите в разделе db2_set_option().

### Возвращаемые значения

Возвращает ресурс оператора, в случае успешного выполнения SQL-запроса или `false`, если базе данных не удалось выполнить SQL-запрос.

### Примеры

Пример #1 Создание таблицы с помощью db2_exec()

В следующем примере db2_exec() используется для выполнения набора DDL-запросов в процессе создания таблицы.

    <?php
    $conn = db2_connect($database, $user, $password);

    // Создание таблицы test
    $create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
        name CHAR(16), weight DECIMAL(7,2))';
    $result = db2_exec($conn, $create);
    if ($result) {
        print "Таблица создана.\n";
    }

    // Наполнение таблицы test
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
        array(3, 'gold fish', 'Bubbles', 0.1),
        array(4, 'budgerigar', 'Gizmo', 0.2),
        array(5, 'goat', 'Rickety Ride', 9.7),
        array(6, 'llama', 'Sweater', 150)
    );

    foreach ($animals as $animal) {
        $rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
          VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
        if ($rc) {
            print "Добавлена запись... ";
        }
    }
    ?>

Результат выполнения приведённого примера:

    Таблица создана.
    Добавлена запись... Добавлена запись... Добавлена запись... Добавлена запись... Добавлена запись... Добавлена запись... Добавлена запись...

Пример #2 Выполнение запроса SELECT с прокручиваемым курсором

В следующем примере показано, как запросить прокручиваемый курсор для SQL-запроса, выданного функцией db2_exec().

    <?php
    $conn = db2_connect($database, $user, $password);
    $sql = "SELECT name FROM animals
        WHERE weight < 10.0
        ORDER BY name";
    if ($conn) {
        require_once 'prepare.inc';
        $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
        while ($row = db2_fetch_array($stmt)) {
            print "$row[0]\n";
        }
    }
    ?>

Результат выполнения приведённого примера:

    Bubbles
    Gizmo
    Pook
    Rickety Ride

Пример #3 Получение XML-данных как SQL ResultSet

В следующем примере показано, как работать с документами, хранящимися в столбце XML с помощью базы данных SAMPLE. Используя довольно простой SQL/XML, этот пример возвращает некоторые узлы в XML-документе в формате SQL ResultSet, с которым знакомо большинство пользователей.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = \'Kathy Smith\'
        ';
    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Пример #4 Выполнение "JOIN" с данными XML

Следующий пример работает с документами, хранящимися в 2 разных столбцах XML в базе данных SAMPLE. Он создаёт 2 временные таблицы из XML-документов из 2 разных столбца и возвращает SQL ResultSet с информацией о статусе доставки для клиента.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
        SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
        FROM
        XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" BIGINT PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) as A,
        PURCHASEORDER AS B,
        XMLTABLE (
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
        COLUMNS
        "PONUM"  BIGINT PATH \'@PoNum\',
        "STATUS" VARCHAR (50) PATH \'@Status\'
        ) as C
        WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = \'Kathy Smith\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }

    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Пример #5 Возврат SQL-данных как части большого XML-документа

Следующий пример работает с частью документов PRODUCT.DESCRIPTION в базе данных SAMPLE. Он создаёт XML-документ, содержащий описание продукта (данные XML) и информацию о ценах (данные SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
            } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = \'100-100-01\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
    }
    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Смотрите также

- db2_execute() - Выполняет подготовленный SQL-запрос
- db2_prepare() - Подготавливает SQL-запрос к выполнению

# db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — Выполняет подготовленный SQL-запрос

### Описание

function db2_execute(resource `$stmt`, array `$parameters` = []): bool

db2_execute() выполняет SQL-запрос, подготовленный с помощью db2_prepare().

Если SQL-запрос возвращает набор результатов, например, инструкция SELECT или CALL для хранимой процедуры, которая возвращает один или несколько наборов результатов, вы можете получить строку как массив из ресурса `stmt`, используя db2_fetch_assoc(), db2_fetch_both()или db2_fetch_array(). В качестве альтернативы вы можете использовать db2_fetch_row() для перемещения указателя набора результатов на следующую строку и выборки столбца из этой строки с помощью db2_result().

Обратитесь к db2_prepare() для краткого обсуждения преимуществ использования db2_prepare() и db2_execute() вместо db2_exec().

### Список параметров

`stmt`
  Подготовленный запрос, возвращаемый функцией db2_prepare().
`parameters`
  Массив входных параметров, соответствующих любым маркерам параметров, содержащимся в подготовленном запросе.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Подготовка и выполнение SQL-запроса с маркерами параметров

В следующем примере подготавливается запрос INSERT, который принимает четыре маркера параметров, а затем выполняет итерацию по массиву массивов, содержащих входные значения, которые необходимо передать в db2_execute().

    <?php
    $pet = array(0, 'cat', 'Pook', 3.2);

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';

    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        $result = db2_execute($stmt, $pet);
        if ($result) {
            print "Успешно добавлен новый питомец.";
        }
    }
    ?>

Результат выполнения приведённого примера:

    Успешно добавлен новый питомец.

Пример #2 Вызов хранимой процедуры с параметром OUT

В следующем примере подготавливается запрос CALL, который принимает один маркер параметра, представляющий параметр OUT, связывает переменную PHP `$my_pets` с параметром с помощью db2_bind_param(), а затем вызывает db2_execute() для выполнения запроса CALL. После выполнения запроса CALL хранимой процедуры значение `$num_pets` изменяется, чтобы отразить значение, возвращаемое хранимой процедурой для этого параметра OUT.

    <?php
    $num_pets = 0;
    $res = db2_prepare($conn, "CALL count_my_pets(?)");
    $rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
    $rc = db2_execute($res);
    print "У меня $num_pets домашних животных!";
    ?>

Результат выполнения приведённого примера:

    У меня 7 домашних животных!

Пример #3 Возврат XML-данных как SQL ResultSet

В следующем примере показано, как работать с документами, хранящимися в столбце XML с помощью базы данных SAMPLE. Используя довольно простой SQL/XML, этот пример возвращает некоторые узлы в XML-документе в формате SQL ResultSet, с которым знакомо большинство пользователей.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = ?
        ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
        }
    }
    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Пример #4 Выполнение "JOIN" с данными XML

Следующий пример работает с документами, хранящимися в 2 разных столбцах XML в базе данных SAMPLE. Он создаёт 2 временные таблицы из XML-документов из 2 разных столбца и возвращает SQL ResultSet с информацией о статусе доставки для клиента.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
    FROM
    XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" BIGINT PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) as A,
    PURCHASEORDER AS B,
    XMLTABLE (
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
    COLUMNS
    "PONUM"  BIGINT PATH \'@PoNum\',
    "STATUS" VARCHAR (50) PATH \'@Status\'
    ) as C
    WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
        }
    }

    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Пример #5 Возврат SQL-данных как части большого XML-документа

Следующий пример работает с частью документов PRODUCT.DESCRIPTION в базе данных SAMPLE. Он создаёт XML-документ, содержащий описание продукта (данные XML) и информацию о ценах (данные SQL).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
                } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $pid = "100-100-01";

    if ($stmt) {
        db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
        }
    }

    db2_close($conn);

    ?>

Результат выполнения приведённого примера:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Смотрите также

- db2_exec() - Выполняет SQL-запрос напрямую
- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_prepare() - Подготавливает SQL-запрос к выполнению
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов

### Описание

function db2_fetch_array(resource `$stmt`, int `$row_number` = -1): array|false

Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов. Индекс столбцов начинается с 0.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий набор результатов.
`row_number`
  Запрашивает конкретную строку по индексу (начинается с 1) из набора результатов. Передача параметра приводит к предупреждению PHP, если в наборе результатов используется курсор "forward-only".

### Возвращаемые значения

Возвращает индексированный массив (начинается с 0) со значениями столбцов, индексированными по позиции столбца, представляющий следующую или запрошенную строку в наборе результатов. Возвращает `false`, если в наборе результатов не осталось строк или если строка, запрошенная `row_number`, не существует в наборе результатов.

### Примеры

Пример #1 Перебор курсором "forward-only"

Если вы вызываете db2_fetch_array() без определённого номера строки, он автоматически получает следующую строку в наборе результатов.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_array($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Пример #2 Получение определённых строк с помощью db2_fetch_array() из прокручиваемого курсора

Если в вашем наборе результатов используется прокручиваемый курсор, вы можете вызвать db2_fetch_array() с определённым номером строки. В следующем примере извлекается каждая вторая строка в наборе результатов, начиная со второй строки.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_array($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
        $i = $i + 2;
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Смотрите также

- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_object() - Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов

### Описание

function db2_fetch_assoc(resource `$stmt`, int `$row_number` = -1): array|false

Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий набор результатов.
`row_number`
  Запрашивает конкретную строку по индексу (начинается с 1) из набора результатов. Передача параметра приводит к предупреждению PHP, если в наборе результатов используется курсор "forward-only".

### Возвращаемые значения

Возвращает ассоциативный массив со значениями столбцов, проиндексированными по имени столбца, представляющий следующую или запрошенную строку в наборе результатов. Возвращает `false`, если в наборе результатов не осталось строк или если строка, запрошенная `row_number`, не существует в наборе результатов.

### Примеры

Пример #1 Перебор курсором "forward-only"

Если вы вызываете db2_fetch_assoc() без определённого номера строки, он автоматически получает следующую строку в наборе результатов.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_assoc($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Пример #2 Получение определённых строк с помощью db2_fetch_assoc() из прокручиваемого курсора

Если в вашем наборе результатов используется прокручиваемый курсор, вы можете вызвать db2_fetch_assoc() с определённым номером строки. В следующем примере извлекается каждая вторая строка в наборе результатов, начиная со второй строки.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_assoc($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Смотрите также

- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_object() - Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов

### Описание

function db2_fetch_both(resource `$stmt`, int `$row_number` = -1): array|false

Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов. Обратите внимание, что строка, возвращаемая db2_fetch_both(), требует больше памяти, чем массивы с одним индексом, возвращаемые db2_fetch_assoc() или db2_fetch_array().

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий набор результатов.
`row_number`
  Запрашивает конкретную строку по индексу (начинается с 1) из набора результатов. Передача параметра приводит к предупреждению PHP, если в наборе результатов используется курсор "forward-only".

### Возвращаемые значения

Возвращает ассоциативный массив со значениями столбцов, проиндексированными как по имени столбца, так и по индексу столбца (начиная с 0). Массив представляет следующую или запрошенную строку в наборе результатов. Возвращает `false`, если в наборе результатов не осталось строк или если строка, запрошенная `row_number`, не существует в наборе результатов.

### Примеры

Пример #1 Перебор курсором "forward-only"

Если вы вызываете db2_fetch_both() без определённого номера строки, он автоматически получает следующую строку в наборе результатов. В следующем примере доступ к столбцам в возвращаемом массиве осуществляется как по имени столбца, так и по числовому индексу.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_both($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row[0], $row['BREED'], $row[3]);
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Пример #2 Получение определённых строк с помощью db2_fetch_both() из прокручиваемого курсора

Если в вашем наборе результатов используется прокручиваемый курсор, вы можете вызвать db2_fetch_both() с определённым номером строки. В следующем примере извлекается каждая вторая строка в наборе результатов, начиная со второй строки.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_both($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row['NAME'], $row[2], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

Результат выполнения приведённого примера:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Смотрите также

- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_object() - Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — Возвращает объект со свойствами, представляющими столбцы в выбранной строке

### Описание

function db2_fetch_object(resource `$stmt`, int `$row_number` = -1): stdClass|false

Возвращает объект, в котором каждое свойство представляет столбец, возвращённый в строке, полученной из набора результатов.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий набор результатов.
`row_number`
  Запрашивает конкретную строку по индексу (начинается с 1) из набора результатов. Передача параметра приводит к предупреждению PHP, если в наборе результатов используется курсор "forward-only".

### Возвращаемые значения

Возвращает объект, представляющий одну строку в наборе результатов. Свойства объекта сопоставляются с именами столбцов в наборе результатов.

Серверы баз данных IBM DB2, Cloudscape и Apache Derby обычно переводят имена столбцов в верхний регистр, поэтому свойства объекта будут отражать этот регистр.

Если запрос SELECT вызывает скалярную функцию для изменения значения столбца, серверы баз данных возвращают номер столбца как имя столбца в наборе результатов. Если требуется более осмысленное имя столбца и свойство объекта, вы можете использовать конструкцию AS, чтобы присвоить имя столбцу в наборе результатов.

Возвращает `false`, если ни одна строка не была получена.

### Примеры

Пример #1 Пример использования db2_fetch_object()

В следующем примере выполняется запрос SELECT со скалярной функцией RTRIM, которая удаляет пробелы в конце столбца. Вместо того, чтобы создавать объект со свойствами "BREED" и "2", мы используем конструкцию AS в запросе SELECT для присвоения имени "name" изменённому столбцу. Сервер базы данных переводит имена столбцов в верхний регистр, в результате чего получается объект со свойствами "BREED" и "NAME".

    <?php
    $conn = db2_connect($database, $user, $password);

    $sql = "SELECT breed, RTRIM(name) AS name
        FROM animals
        WHERE id = ?";

    if ($conn) {
        $stmt = db2_prepare($conn, $sql);
        db2_execute($stmt, array(0));

        while ($pet = db2_fetch_object($stmt)) {
            echo "Иди сюда, {$pet->NAME}, мой маленький {$pet->BREED}!";
        }
        db2_close($conn);
    }
    ?>

Результат выполнения приведённого примера:

    Иди сюда, Пушок, мой маленький котёнок!

### Смотрите также

- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — Устанавливает указатель набора результатов на следующую строку или запрошенную строку

### Описание

function db2_fetch_row(resource `$stmt`, int `$row_number` = -1): bool

Используйте db2_fetch_row() для итерации по набору результатов или для указания на определённую строку в наборе результатов, если вы запросили прокручиваемый курсор.

Чтобы получить отдельные поля из набора результатов, вызовите функцию db2_result().

Вместо того, чтобы вызывать db2_fetch_row() и db2_result(), большинство приложений будет вызывать одну из функций db2_fetch_assoc(), db2_fetch_both() или db2_fetch_array(), чтобы продвинуть указатель набора результатов и вернуть полную строку в виде массива.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`.
`row_number`
  С помощью прокручиваемых курсоров вы можете запросить конкретный номер строки в наборе результатов. Нумерация строк начинается с 1.

### Возвращаемые значения

Возвращает `true`, если запрошенная строка существует в наборе результатов. Возвращает `false`, если запрошенная строка не существует в наборе результатов.

### Примеры

Пример #1 Итерации по набору результатов

В следующем примере показано, как выполнить итерацию по набору результатов с помощью db2_fetch_row() и получить столбцы из набора результатов с помощью db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 1);
        print "$name $breed";
    }
    ?>

Результат выполнения приведённого примера:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

Пример #2 Рекомендуемые альтернативы db2_fetch_row/db2_result для i5/OS

В i5/OS рекомендуется использовать db2_fetch_both(), db2_fetch_array() или db2_fetch_object() вместо db2_fetch_row()/db2_result(). Обычно у db2_fetch_row()/db2_result() больше проблем с различными типами столбцов при преобразовании `EBCDIC` в `ASCII`, включая возможное усечение в `DBCS` приложениях. Вы также можете обнаружить, что производительность db2_fetch_both(), db2_fetch_array() и db2_fetch_object() превосходит db2_fetch_row()/db2_result().

    <?php
      $conn = db2_connect("","","");
      $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_both($stmt)){
        echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_array($stmt)){
        echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_object($stmt)){
        echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
      }
      db2_close($conn);
    ?>

Результат выполнения приведённого примера:

    db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
    db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
    db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
    db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

### Смотрите также

- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_object() - Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — Возвращает максимальное количество байтов, необходимое для отображения столбца

### Описание

function db2_field_display_size(resource `$stmt`, int|string `$column`): int|false

Возвращает максимальное количество байтов, необходимое для отображения столбца в наборе результатов.

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть целое число, представляющее индекс столбца (начиная с 0) или строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает целочисленное значение с максимальным количеством байтов, необходимых для отображения указанного столбца. Если указанный столбец не существует в наборе результатов, db2_field_display_size() возвращает `false`.

### Смотрите также

- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — Возвращает имя столбца в наборе результатов

### Описание

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

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

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть целое число, представляющее индекс столбца (начиная с 0) или строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает строку, содержащую имя указанного столбца. Если указанный столбец не существует в наборе результатов, db2_field_name() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — Возвращает позицию указанного столбца в наборе результатов

### Описание

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

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

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть целое число, представляющее индекс столбца (начиная с 0) или строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает целое число, содержащее индекс (начиная с 0) указанного столбца в наборе результатов. Если указанный столбец не существует в наборе результатов, db2_field_num() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — Возвращает точность указанного столбца в наборе результатов

### Описание

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

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

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть целое число, представляющее индекс столбца (начиная с 0) или строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает целое число, содержащее точность указанного столбца. Если указанный столбец не существует в наборе результатов, db2_field_precision() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — Возвращает масштаб указанного столбца в наборе результатов

### Описание

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

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

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть целое число, представляющее индекс столбца (начиная с 0) или строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает целое число, содержащее масштаб указанного столбца. Если указанный столбец не существует в наборе результатов, db2_field_scale() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — Возвращает тип данных указанного столбца в наборе результатов

### Описание

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Возвращает тип данных указанного столбца в наборе результатов.

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть либо целое число, представляющее позицию столбца с индексом 0, либо строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает строку, содержащую определённый тип данных указанного столбца. Если указанный столбец не существует в наборе результатов, db2_field_type() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — Возвращает ширину текущего значения указанного столбца в наборе результатов

### Описание

function db2_field_width(resource `$stmt`, int|string `$column`): int|false

Возвращает ширину текущего значения указанного столбца в наборе результатов. Это максимальная ширина столбца для типа данных фиксированной длины или фактическая ширина столбца для типа данных переменной длины.

### Список параметров

`stmt`
  Задаёт ресурс оператора, содержащий набор результатов.
`column`
  Задаёт столбец в наборе результатов. Это может быть либо целое число, представляющее позицию столбца с индексом 0, либо строка, содержащая имя столбца.

### Возвращаемые значения

Возвращает целое число, содержащее ширину указанного столбца символьного или двоичного типа данных в наборе результатов. Если указанный столбец не существует в наборе результатов, db2_field_width() возвращает `false`.

### Смотрите также

- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов

# db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — Возвращает набор результатов, в котором перечислены внешние ключи таблицы

### Описание

function db2_foreign_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

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

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Если `schema` равно `null`, db2_foreign_keys() соответствует схеме для текущего соединения.
`table_name`
  Название таблицы.

### Возвращаемые значения

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

Название столбца | Описание
--- | ---
PKTABLE_CAT | Название каталога таблицы, содержащей первичный ключ. Значение NULL, если в этой таблице нет каталогов.
PKTABLE_SCHEM | Название схемы таблицы, содержащей первичный ключ.
PKTABLE_NAME | Название таблицы, содержащей первичный ключ.
PKCOLUMN_NAME | Название столбца, содержащего первичный ключ.
FKTABLE_CAT | Название каталога таблицы, содержащей внешний ключ. Значение NULL, если в этой таблице нет каталогов.
FKTABLE_SCHEM | Название схемы таблицы, содержащей внешний ключ.
FKTABLE_NAME | Название таблицы, содержащей внешний ключ.
FKCOLUMN_NAME | Название столбца, содержащего внешний ключ.
KEY_SEQ | Индекс (начиная с 1) столбца в ключе.
UPDATE_RULE | Целочисленное значение, представляющее действие, применяемое к внешнему ключу, если операция SQL - UPDATE.
DELETE_RULE | Целочисленное значение, представляющее действие, применяемое к внешнему ключу, если операция SQL - DELETE.
FK_NAME | Имя внешнего ключа.
PK_NAME | Имя первичного ключа.
DEFERRABILITY | Целочисленное значение, представляющее, является ли возможность отсрочки внешнего ключа: SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE или SQL_NOT_DEFERRABLE.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — Освобождает ресурсы, связанные с набором результатов

### Описание

function db2_free_result(resource `$stmt`): bool

Освобождает ресурсы системы и базы данных, связанные с набором результатов. Эти ресурсы неявно освобождаются при завершении скрипта, но вы можете вызвать db2_free_result(), чтобы явно освободить ресурсы набора результатов до завершения скрипта.

### Список параметров

`stmt`
  Допустимый ресурс выражения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- db2_free_stmt() - Освобождает ресурсы, связанные с указанным ресурсом выражения

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — Освобождает ресурсы, связанные с указанным ресурсом выражения

### Описание

function db2_free_stmt(resource `$stmt`): bool

Освобождает ресурсы системы и базы данных, связанные с ресурсом выражения. Эти ресурсы неявно освобождаются при завершении скрипта, но вы можете вызвать db2_free_stmt(), чтобы явно освободить ресурсы выражения до окончания работы скрипта.

### Список параметров

`stmt`
  Допустимый ресурс выражения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- db2_free_result() - Освобождает ресурсы, связанные с набором результатов

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — Извлекает значение параметра для ресурса оператора или ресурса соединения

### Описание

function db2_get_option(resource `$resource`, string `$option`): string|false

Извлекает значение указанного параметра для ресурса оператора или ресурса соединения.

### Список параметров

`resource`
  Допустимый ресурс оператора, возвращаемый db2_prepare() или допустимый ресурс соединения, возвращаемый db2_connect() или db2_pconnect().
`option`

  Допустимый оператор или варианты подключения. Следующие новые параметры доступны в ibm_db2 версии 1.6.0. Они предоставляют полезную информацию для отслеживания, которую можно установить во время выполнения с помощью db2_get_option().

  > Замечание: Предыдущие версии ibm_db2 не поддерживают эти новые параметры. Когда устанавливается значение в каждой опции, некоторые серверы могут не обрабатывать всю предоставленную длину и могут усекать значение. Чтобы обеспечить правильное преобразование данных, указанных в каждой опции, при передаче в хост-систему, используйте только символы от A до Z, от 0 до 9, знак подчёркивания (_) или точку (.).

  `userid`

    `SQL_ATTR_INFO_USERID` - Указатель на символьную строку с завершающим нулём, используемую для идентификации ID пользователя клиента, отправляемого на сервер базы данных хоста при использовании DB2 Connect.

    > Замечание: Серверы DB2 для z/OS и OS/390 поддерживают длину до 16 символов. Идентификатор пользователя не следует путать с идентификатором пользователя для аутентификации, он используется только для целей идентификации и не используется для какой-либо авторизации.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` - Указатель на символьную строку с завершающим нулём, используемую для идентификации учётной строки клиента, отправляемой на сервер базы данных хоста при использовании DB2 Connect.

    > Замечание: Серверы DB2 для z/OS и OS/390 поддерживают длину до 200 символов.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` - Указатель на символьную строку с завершающим нулём, используемую для идентификации имени клиентского приложения, отправляемого на сервер базы данных хоста при использовании DB2 Connect.

    > Замечание: Серверы DB2 для z/OS и OS/390 поддерживают длину до 32 символов.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` - Указатель на символьную строку с завершающим нулём, используемую для идентификации имени клиентского приложения, отправляемого на сервер базы данных хоста при использовании DB2 Connect.

    > Замечание: Серверы DB2 для z/OS и OS/390 поддерживают длину до 18 символов.

В следующей таблице указаны параметры, совместимые с доступными типами ресурсов:

Матрица параметров ресурсов
Ключ | Значение | Тип ресурса
--- | --- | ---
|  | Connection | Statement | Result Set
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Возвращаемые значения

Возвращает текущую настройку атрибута подключения, предоставленную в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка и получение параметров через ресурс подключения

    <?php
    /* Параметры подключения к базе данных */
    $database = 'SAMPLE';
    $user     = 'db2inst1';
    $password = 'ibmdb2';

    /* Получение ресурса подключения */
    $conn = db2_connect($database, $user, $password);

    echo "Атрибуты клиента, передаваемые через строку подключения:\n";

    /* Создайте массив ассоциативных опций с допустимыми парами "ключ-значение" */
    /* Назначьте атрибуты через строку подключения */
    /* Доступ к указанным параметрам */
    $options1 = array('userid' => 'db2inst1');
    $conn1 = db2_connect($database, $user, $password, $options1);
    $val = db2_get_option($conn1, 'userid');
    echo $val . "\n";

    $options2 = array('acctstr' => 'account');
    $conn2 = db2_connect($database, $user, $password, $options2);
    $val = db2_get_option($conn2, 'acctstr');
    echo $val . "\n";

    $options3 = array('applname' => 'myapp');
    $conn3 = db2_connect($database, $user, $password, $options3);
    $val = db2_get_option($conn3, 'applname');
    echo $val . "\n";

    $options4 = array('wrkstnname' => 'workstation');
    $conn4 = db2_connect($database, $user, $password, $options4);
    $val = db2_get_option($conn4, 'wrkstnname');
    echo $val . "\n";

    echo "Атрибуты клиента прошли после подключения:\n";

    /* Create the associative options array with valid key-value pairs */
    /* Assign the attributes after a connection is made */
    /* Access the options specified */
    $options5 = array('userid' => 'db2inst1');
    $conn5 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn5, $options5, 1);
    $val = db2_get_option($conn5, 'userid');
    echo $val . "\n";

    $options6 = array('acctstr' => 'account');
    $conn6 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn6, $options6, 1);
    $val = db2_get_option($conn6, 'acctstr');
    echo $val . "\n";

    $options7 = array('applname' => 'myapp');
    $conn7 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn7, $options7, 1);
    $val = db2_get_option($conn7, 'applname');
    echo $val . "\n";

    $options8 = array('wrkstnname' => 'workstation');
    $conn8 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn8, $options8, 1);
    $val = db2_get_option($conn8, 'wrkstnname');
    echo $val . "\n";
    ?>

Результат выполнения приведённого примера:

    Атрибуты клиента, передаваемые через строку подключения
    db2inst1
    account
    myapp
    workstation
    Атрибуты клиента прошли после подключения:
    db2inst1
    account
    myapp
    workstation

### Смотрите также

- db2_connect() - Возвращает соединение с базой данных
- db2_cursor_type() - Возвращает тип курсора, который используется в ресурсе оператора
- db2_exec() - Выполняет SQL-запрос напрямую
- db2_set_option() - Устанавливает опции для ресурса соединения или ресурса запроса
- db2_pconnect() - Возвращает постоянное соединение с базой данных
- db2_prepare() - Подготавливает SQL-запрос к выполнению

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — Возвращает автоматически сгенерированный идентификатор последнего запроса на добавление, успешно выполненного в этом соединении

### Описание

function db2_last_insert_id(resource `$resource`): ?string

Возвращает автоматически сгенерированный идентификатор последнего запроса на добавление, успешно выполненного в этом соединении.

На результат этой функции не влияет ни одно из следующего:

- Оператор INSERT для одной строки с VALUES для таблицы без столбца идентификаторов.
- Оператор INSERT для нескольких строк с VALUES.
- Оператор INSERT с полной выборкой.
- Оператор ROLLBACK TO SAVEPOINT.

### Список параметров

`resource`
  Допустимый ресурс подключения, возвращаемый db2_connect() или db2_pconnect(). Значение этого параметра не может быть ресурсом оператора или ресурсом набора результатов.

### Возвращаемые значения

Возвращает автоматически сгенерированный идентификатор последнего запроса на добавление, успешно выполненного в этом соединении.

### Примеры

Пример #1 Пример использования db2_last_insert_id()

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

    <?php

    $database = "SAMPLE";
    $user = "db2inst1";
    $password = "ibmdb2";

    $conn = db2_connect($database, $user, $password);
    if($conn) {
        $createTable = "CREATE TABLE lastInsertID
          (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
        $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

        $stmt = @db2_exec($conn, $createTable);

        /* Проверка на вставку одной строки. */
        $stmt = db2_exec($conn, $insertTable);
        $ret =  db2_last_insert_id($conn);
        if($ret) {
            echo "Последний идентификатор : " . $ret . "\n";
        } else {
            echo "Последний идентификатор отсутствует.\n";
        }

        db2_close($conn);
    }
    else {
        echo "Ошибка соединения.";
    }
    ?>

Результат выполнения приведённого примера:

    Последний идентификатор : 1

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — Получает определённый пользователем размер LOB-файлов при каждом вызове

### Описание

function db2_lob_read(resource `$stmt`, int `$colnum`, int `$length`): string|false

Используйте db2_lob_read() для итерации по указанному столбцу набора результатов и получения заданного пользователем размера LOB-данных.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий LOB-данные.
`colnum`
  Допустимый номер столбца в наборе результатов ресурса `stmt`.
`length`
  Размер LOB-данных, извлекаемых из ресурса `stmt`.

### Возвращаемые значения

Возвращает количество данных, указанных пользователем. Возвращает `false`, если данные не могут быть получены.

### Примеры

Пример #1 Итерации по разным типам данных

    <?php

    /* Параметры подключения к базе данных */
    $db = 'SAMPLE';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Получение ресурса подключения */
    $conn = db2_connect($db,$username,$password);

    if ($conn) {
        $drop = 'DROP TABLE clob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
        $variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_clob FROM clob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Чтение LOB-данных */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }

        $drop = 'DROP TABLE blob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
        $variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_blob FROM blob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Чтение LOB-данных */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }
    } else {
        echo 'Нет соединения: ' . db2_conn_errormsg();
    }

    ?>

Результат выполнения приведённого примера:

    Loop 0: THIS I
    Loop 1: S A CL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  CLOB
    Loop 6: TEST.
    Loop 0: THIS I
    Loop 1: S A BL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  BLOB
    Loop 6: TEST.

### Смотрите также

- db2_bind_param() - Связывает переменную PHP с параметром SQL-выражения
- db2_exec() - Выполняет SQL-запрос напрямую
- db2_execute() - Выполняет подготовленный SQL-запрос
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_prepare() - Подготавливает SQL-запрос к выполнению
- db2_result() - Возвращает один столбец из строки в наборе результатов

# db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — Запрашивает следующий набор результатов из хранимой процедуры

### Описание

function db2_next_result(resource `$stmt`): resource|false

Хранимая процедура может возвращать ноль или более наборов результатов. Хотя вы обрабатываете первый набор результатов точно так же, как и результаты, возвращаемые простым оператором SELECT, для получения второго и последующих наборов результатов из хранимой процедуры вы должны вызвать функцию db2_next_result() и вернуть результат в переменную PHP с уникальным именем.

### Список параметров

`stmt`
  Подготовленный оператор, возвращаемый функцией db2_exec() или db2_execute().

### Возвращаемые значения

Возвращает новый ресурс оператора, содержащий следующий набор результатов, если хранимая процедура вернула другой набор результатов. Возвращает `false`, если хранимая процедура не вернула другой набор результатов.

### Примеры

Пример #1 Вызов хранимой процедуры, возвращающей несколько наборов результатов

В следующем примере вызывается хранимая процедура, которая возвращает три набора результатов. Первый набор результатов извлекается непосредственно из того же ресурса операторов, для которого вызывается оператор CALL, а второй и третий наборы результатов извлекаются из ресурсов операторов, возвращаемых вызовами функции db2_next_result().

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
      $stmt = db2_exec($conn, 'CALL multiResults()');

      print "Получение первого набора результатов\n";
      while ($row = db2_fetch_array($stmt)) {
        var_dump($row);
      }

      print "\nПолучение второго набора результатов\n";
      $res = db2_next_result($stmt);
      if ($res) {
        while ($row = db2_fetch_array($res)) {
          var_dump($row);
        }
      }

      print "\nПолучение третьего набора результатов\n";
      $res2 = db2_next_result($stmt);
      if ($res2) {
        while ($row = db2_fetch_array($res2)) {
          var_dump($row);
        }
      }

      db2_close($conn);
    }
    ?>

Результат выполнения приведённого примера:

    Получение первого набора результатов
    array(2) {
      [0]=>
      string(16) "Bubbles         "
      [1]=>
      int(3)
    }
    array(2) {
      [0]=>
      string(16) "Gizmo           "
      [1]=>
      int(4)
    }

    Получение второго набора результатов
    array(4) {
      [0]=>
      string(16) "Sweater         "
      [1]=>
      int(6)
      [2]=>
      string(5) "llama"
      [3]=>
      string(6) "150.00"
    }
    array(4) {
      [0]=>
      string(16) "Smarty          "
      [1]=>
      int(2)
      [2]=>
      string(5) "horse"
      [3]=>
      string(6) "350.00"
    }

    Получение третьего набора результатов
    array(1) {
      [0]=>
      string(16) "Bubbles         "
    }
    array(1) {
      [0]=>
      string(16) "Gizmo           "
    }

# db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — Возвращает количество полей в результирующем наборе

### Описание

function db2_num_fields(resource `$stmt`): int|false

Возвращает количество полей в результирующем наборе. Это полезно при обработке результирующих наборов динамически сформированных запросов, или в случае использования хранимых процедур.

### Список параметров

`stmt`
  Корректный ресурс оператора, содержащий результирующий набор.

### Возвращаемые значения

Возвращает число полей в результирующем наборе или `false`, если передан некорректный ресурс оператора.

### Примеры

Пример #1 Получение количества полей в результирующем наборе

Следующий пример демонстрирует получение количества полей в результирующем наборе.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, $sql);
    $columns = db2_num_fields($stmt);

    echo "В результирующем наборе {$columns} столбцов.";
    ?>

Результат выполнения приведённого примера:

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

### Смотрите также

- db2_execute() - Выполняет подготовленный SQL-запрос
- db2_field_display_size() - Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name() - Возвращает имя столбца в наборе результатов
- db2_field_num() - Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision() - Возвращает точность указанного столбца в наборе результатов
- db2_field_scale() - Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type() - Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width() - Возвращает ширину текущего значения указанного столбца в наборе результатов

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — Возвращает количество строк, затронутых SQL-запросом

### Описание

function db2_num_rows(resource `$stmt`): int|false

Возвращает количество строк, удалённых, добавленных или обновлённых SQL-запросом.

Чтобы определить количество строк, которые будут возвращены оператором SELECT, введите SELECT COUNT(*) с теми же параметрами, что и предполагаемый оператор SELECT и получите значение.

Если логика вашего приложения проверяет количество строк, возвращаемых оператором SELECT и ветвей, если количество строк равно 0, рассмотрите возможность изменения вашего приложения, чтобы попытаться вернуть первую строку одной из функций db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array() или db2_fetch_row() и переходите, если функция выборки возвращает `false`.

> Замечание: Если вы выполняете оператор SELECT с помощью прокручиваемого курсора, db2_num_rows() возвращает количество строк, возвращаемых оператором SELECT. Однако накладные расходы, связанные с прокручиваемыми курсорами, значительно ухудшают производительность вашего приложения, поэтому, если это единственная причина, по которой вы рассматриваете возможность использования прокручиваемых курсоров, вам следует использовать курсор "forward-only" и либо вызвать SELECT COUNT(*), либо полагаться на логическое значение (bool), которое возвращает значение функций выборки для достижения эквивалентной функциональности с гораздо большей производительностью.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`, содержащий набор результатов.

### Возвращаемые значения

Возвращает количество строк, затронутых последним SQL-оператором, выданным указанным дескриптором оператора, или `false`, если возникла ошибка.

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Закрывает постоянное соединение с базой данных

### Описание

function db2_pclose(resource `$connection`): bool

Функция закрывает клиентское соединение DB2, созданное с помощью db2_pconnect() и возвращает соответствующие ресурсы серверу базы данных.

> Замечание: Эта функция доступна только в i5/OS в ответ на запросы системного администратора i5/OS.

Если у вас есть постоянное клиентское соединение DB2, созданное с помощью db2_pconnect(), вы можете использовать эту функцию, чтобы закрыть соединение. Чтобы избежать значительных потерь производительности соединения, эту функцию следует использовать только в редких случаях, когда постоянное соединение перестало отвечать или постоянное соединение не будет требоваться в течение длительного периода времени.

### Список параметров

`connection`
  Задаёт активное соединение клиента DB2.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Закрытие постоянного соединения

В следующем примере демонстрируется успешная попытка закрыть соединение с базой данных IBM DB2 i5/OS.

    <?php
    $conn = db2_pconnect('', '', '');
    $rc = db2_pclose($conn);
    if ($rc) {
        echo "Соединение было успешно закрыто.";
    }
    ?>

Результат выполнения приведённого примера:

    Соединение было успешно закрыто.

### Смотрите также

- db2_close() - Закрывает соединение с базой данных
- db2_pconnect() - Возвращает постоянное соединение с базой данных

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Возвращает постоянное соединение с базой данных

### Описание

function db2_pconnect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Функция возвращает постоянное соединение с базой данных IBM DB2 Universal Database, IBM Cloudscape или Apache Derby.

Дополнительную информацию о постоянных соединениях даёт раздел «Постоянные соединения с базами данных».

Вызов функции db2_close() при постоянном соединении каждый раз возвращает `true`, но базовое клиентское DB2-соединение остаётся открытым и ожидает обслуживания следующего соответствующего запроса функции db2_pconnect().

Пользователи, которые используют модуль ibm_db2 версии 1.9.0 или новее, должны знать, что модуль выполнит откат транзакции для постоянных соединений в конце запроса, чем завершит транзакцию. Это предотвращает перенос блока транзакции на следующий запрос, который использует это соединение, если выполнение скрипта завершается раньше, чем блок транзакции.

### Список параметров

`database`
  Для каталогизированного подключения к базе данных параметр `database` представляет псевдоним базы данных в клиентском каталоге БД DB2.

  Для некаталогизированного подключения к базе данных параметр `database` представляет полную строку подключения в следующем формате:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Замечание:

  > При подключении к БД Db2 на ОС IBM i базовая система вызывает функцию » SQLDriverConnect, которая принимает только имя источника данных DSN, идентификатор пользователя UID и пароль PWD для » строки подключения. Вот так:

  >     DSN=database;UID=username;PWD=password;

  где параметры представляют следующие значения:
  `database`
    Имя базы данных.
  `hostname`
    Имя хоста или IP-адрес сервера базы данных.
  `port`
    Порт TCP/IP, который используется базой данных для принятия запросов.
  `username`
    Имя пользователя, под которым выполняется подключение к базе данных.
  `password`
    Пароль, с которым выполняется подключение к базе данных.
`username`
  Имя пользователя, под которым выполняется подключение к базе данных.
`password`
  Пароль, который используется при подключении к базе данных.
`options`

  Ассоциативный массив параметров подключения, которые влияют на поведение подключения, в котором допустимые ключи массива включают:

  `autocommit`
    Передача значения `DB2_AUTOCOMMIT_ON` включает автоматическую фиксацию для этого дескриптора соединения. Передача значения `DB2_AUTOCOMMIT_OFF` выключает автоматическую фиксацию для этого дескриптора соединения.
  `DB2_ATTR_CASE`
    Передача значения `DB2_CASE_NATURAL` указывает, что имена столбцов возвращаются в естественном регистре. Передача значения `DB2_CASE_LOWER` указывает, что имена столбцов возвращаются в нижнем регистре. Передача значения `DB2_CASE_UPPER` указывает, что имена столбцов возвращаются в верхнем регистре.
  `CURSOR`
    Передача значения `DB2_FORWARD_ONLY` задаёт курсор только вперёд для ресурса оператора. Это тип курсора по умолчанию, который поддерживается на всех серверах баз данных. Передача значения `DB2_SCROLLABLE` задаёт прокручиваемый курсор для ресурса оператора. Этот режим включает произвольный доступ к строкам в наборе результатов, но пока поддерживается только СУБД DB2 Universal Database операционной системы IBM.

  Следующая новая опция доступна в модуле ibm_db2 версии 1.7.0 и новее.

  `trustedcontext`
    Передача значения DB2_TRUSTED_CONTEXT_ENABLE включает доверенный контекст для этого дескриптора соединения. Параметр нельзя установить функцией db2_set_option(). Ключ работает только тогда, когда базу данных каталогизировали (даже если база данных локальная) или если указали полное DSN-имя при создании соединения. Чтобы каталогизировать базу данных, вызывают следующие команды:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  Следующие новые параметры ОС i5/OS доступны в модуле ibm_db2 версии 1.5.1 и новее.

  Подсказка

  Конфликтующие атрибуты соединения, которые используются вместе с постоянными соединениями, могут привести к неопределённым результатам в ОС i5/OS. Требуется установить политики сайта для каждого приложения, которое использует каждый профиль пользователя с постоянным подключением. При работе с постоянными соединениями предлагается значение по умолчанию: DB2_AUTOCOMMIT_ON.

  `i5_lib`
    Символьное значение, которое указывает библиотеку по умолчанию, которая будет использоваться для разрешения неквалифицированных ссылок на файлы. Недопустимо, если соединение использует режим именования системы.
  `i5_naming`
    Значение `DB2_I5_NAMING_ON` включает режим именования системы DB2 UDB CLI iSeries. Файлы квалифицируются через разделитель в виде слеша (/). Неквалифицированные файлы разрешаются через список библиотек для задания. Значение `DB2_I5_NAMING_OFF` отключает режим именования по умолчанию CLI DB2 UDB, который представляет собой именование SQL. Файлы квалифицируются через разделитель в виде точки (.). Неквалифицированные файлы разрешаются либо через библиотеки по умолчанию, либо через текущий идентификатор пользователя.
  `i5_commit`

    Атрибут `i5_commit` требуется установить до вызова функции db2_pconnect(). Изменение не вступит в силу до следующего успешного вызова функции db2_pconnect() для дескриптора соединения, если значение изменяется после установки соединения, и соединение установилось с удалённым источником данных.

    > Замечание: Параметр `ibm_db2.i5_allow_commit`==0 файла php.ini или параметр `DB2_I5_TXN_NO_COMMIT` — значение по умолчанию, но он доступен для изменения через параметр `i5_commit`.

    `DB2_I5_TXN_NO_COMMIT` — Контроль фиксации не используется. `DB2_I5_TXN_READ_UNCOMMITTED` — Грязное чтение, неповторимые reads, and phantoms are possible. `DB2_I5_TXN_READ_COMMITTED` — Грязное чтение невозможно. Возможны неповторяющееся чтение и фантомы. `DB2_I5_TXN_REPEATABLE_READ` — Грязное чтение и неповторяющиеся читки невозможны. Возможны фантомы. `DB2_I5_TXN_SERIALIZABLE` — Транзакции сериализуемы. Грязное чтение, неповторяющееся чтение и фантомы невозможны.
  `i5_query_optimize`
    `DB2_FIRST_IO` Все запросы оптимизированы с целью максимально быстрого возврата первой страницы вывода. Эта цель хорошо работает, когда вывод контролируется пользователем, который, скорее всего, отменит запрос после просмотра первой страницы выходных данных. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, соответствуют цели, указанной в предложении. `DB2_ALL_IO` Все запросы оптимизированы с целью выполнить весь запрос о завершения в кратчайшие сроки. Это хороший вариант, когда выходные данные запроса записываются в файл или отчёт или когда интерфейс ставит выходные данные в очередь. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, соответствуют цели, указанной в предложении. Это значение по умолчанию.
  `i5_dbcs_alloc`
    `DB2_I5_DBCS_ALLOC_ON` Значение включает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS.

    `DB2_I5_DBCS_ALLOC_OFF` Значение выключает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS.

    > Замечание: Параметр `ibm_db2.i5_dbcs_alloc`==0 файла php.ini или параметр `DB2_I5_DBCS_ALLOC_OFF` — значение по умолчанию, но его можно изменить через параметр `i5_dbcs_alloc`.

  `i5_date_fmt`
    `DB2_I5_FMT_ISO` — Формат даты Международной организации по стандартизации ISO yyyy-mm-dd. Это значение по умолчанию. `DB2_I5_FMT_USA` — Формат даты США mm/dd/yyyy. `DB2_I5_FMT_EUR` — Европейский формат даты dd.mm.yyyy. `DB2_I5_FMT_JIS` — Японский формат даты yyyy-mm-dd. `DB2_I5_FMT_MDY` — Формат даты mm/dd/yyyy. `DB2_I5_FMT_DMY` — Формат даты dd/mm/yyyy. `DB2_I5_FMT_YMD` — Формат даты yy/mm/dd. `DB2_I5_FMT_JUL` — Используется юлианский формат даты yy/ddd. `DB2_I5_FMT_JOB` — Используется задание по умолчанию.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` — Разделитель даты — слеш (/). Это значение по умолчанию. `DB2_I5_SEP_DASH` — Разделитель даты — дефис (-). `DB2_I5_SEP_PERIOD` — Разделитель даты — точка (.). `DB2_I5_SEP_COMMA` — Разделитель даты — запятая (,). `DB2_I5_SEP_BLANK` — Разделитель даты — пробел. `DB2_I5_SEP_JOB` — Задание по умолчанию.
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` — Формат времени Международной организации по стандартизации ISO hh.mm.ss. Это значение по умолчанию. `DB2_I5_FMT_USA` — Формат времени США hh:mmxx, где xx — это AM или PM. `DB2_I5_FMT_EUR` — Европейский формат времени hh.mm.ss. `DB2_I5_FMT_JIS` — Японский промышленный стандартный формат времени hh:mm:ss. `DB2_I5_FMT_HMS` — Формат hh:mm:ss.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` — Разделитель времени — двоеточие (:). Это значение по умолчанию. `DB2_I5_SEP_PERIOD` — Разделитель времени — точка (.). `DB2_I5_SEP_COMMA` — Разделитель времени — запятая (,). `DB2_I5_SEP_BLANK` — Разделитель времени — пробел. `DB2_I5_SEP_JOB` — Задание по умолчанию.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` — Десятичный разделитель — точка (.). Это значение по умолчанию. `DB2_I5_SEP_COMMA` — Десятичный разделитель — запятая (,). `DB2_I5_SEP_JOB` — Задание по умолчанию.

  Следующая новая опция ОС i5/OS доступна в модуле ibm_db2 версии 1.8.0 и новее.

  `i5_libl`

    Символьное значение, которое указывает список библиотек, через которые будут разрешаться неквалифицированные ссылки на файлы. Элементы списка библиотек указывают через пробелы: 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Замечание: Библиотека i5_libl вызывает qsys2/qcmdexc ('cmd',cmdlen), который доступен только в ОС i5/OS V5R4 и новее.

### Возвращаемые значения

Функция возвращает ресурс дескриптора подключения в случае успешной попытки подключения. Функция db2_pconnect() пытается переиспользовать существующий ресурс подключения, который точно соответствует параметрам `database`, `username` и `password`. Функция db2_pconnect() возвращает `false`, если возникла ошибка подключения.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль ibm_db2 1.9.0 | Активные транзакции в постоянном соединении будут откатываться в конце каждого запроса.
PECL-модуль ibm_db2 1.8.0 | Параметр `i5_libl` доступен пользователям i5/OS.
PECL-модуль ibm_db2 1.7.0 | Доступен параметр `trustedcontext`.
PECL-модуль ibm_db2 1.5.1 | Параметры `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` и `i5_decimal_sep` доступны для пользователей i5/OS.

### Примеры

Пример #1 Пример возврата постоянного соединения с базой данных функцией db2_pconnect()

В следующем примере первый вызов функции db2_pconnect() возвращает новый ресурс постоянного соединения. Второй вызов функции db2_pconnect() возвращает ресурс постоянного соединения, который просто переиспользует первый ресурс постоянного соединения.

    <?php

    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $pconn = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Постоянное соединение успешно установилось.";
    } else {
        echo "Постоянное соединение завершилось ошибкой.";
    }

    $pconn2 = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Второе постоянное соединение успешно установилось.";
    } else {
        echo "Второе постоянное соединение завершилось ошибкой";
    }

    ?>

Результат выполнения приведённого примера:

    Постоянное соединение успешно установилось.
    Второе постоянное соединение успешно установилось.

Пример #2 Пример работы с доверенным контекстом

Следующий пример показывает, как включить доверенный контекст, переключить пользователей и получить текущий идентификатор пользователя.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;"
        . "PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";

    $options = array("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_pconnect($dsn, "", "", $options);
    if ($tc_conn) {
        echo "Явное доверенное соединение успешно установилось.\n";

        if (db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            // Поработайте как пользователь 1.

            // Переход на доверенного пользователя
            $parameters = array(
                "trusted_user" => $tc_user,
                "trusted_password" => $tcuser_pass
            );

            $res = db2_set_option($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            // Сделайте больше в качестве доверенного пользователя.

            if ($userBefore != $userAfter) {
                echo "Пользователь переключился." . "\n";
            }
        }

        db2_close($tc_conn);
    } else {
        echo "Явное доверенное соединение завершилось ошибкой.\n";
    }

    ?>

Результат выполнения приведённого примера:

    Явное доверенное соединение успешно установилось
    Пользователь переключился.

### Смотрите также

- db2_connect() - Возвращает соединение с базой данных

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Подготавливает SQL-запрос к выполнению

### Описание

function db2_prepare(resource `$connection`, string `$statement`, array `$options` = []): resource|false

db2_prepare() создаёт подготовленный SQL-запрос, который может включать 0 или более маркеров параметров (символов `?`), представляющих входные параметры, параметры вывода или входные параметры и параметры вывода. Вы можете передать параметры подготовленному запросу, используя db2_bind_param() или только для входных значений в виде массива, переданного в db2_execute().

Использование подготовленных запросов в вашем приложении даёт три основных преимущества:

- Производительность: при использовании подготовленного запроса, сервер базы данных создаёт оптимизированный план доступа для извлечения данных с помощью этого запроса. Последующее выполнение подготовленного запроса с помощью db2_execute() позволяет операторам повторно использовать этот план доступа и позволяет избежать накладных расходов на динамическое создание нового плана доступа для каждого выполняемого вами запроса.
- Безопасность: при использовании подготовленного запроса, вы можете включить маркеры параметров для входных значений. Когда вы выполняете подготовленный запрос с входными значениями для заполнителей, сервер базы данных проверяет каждое входное значение, чтобы убедиться, что тип соответствует определению столбца или определению параметра.
- Расширенный функционал: Маркеры параметров не только позволяют передавать входные значения в подготовленные SQL-запросы, они также позволяют извлекать параметры OUT и INOUT из хранимых процедур с помощью db2_bind_param().

### Список параметров

`connection`
  Допустимая переменная ресурса подключения к базе данных, возвращаемая функцией db2_connect() или db2_pconnect().
`statement`
  SQL-запрос, необязательно содержащий один или несколько маркеров параметров.
`options`
  Ассоциативный массив, содержащий параметры запроса. Параметры можно использовать для запроса прокручиваемого курсора на серверах баз данных, поддерживающих эту функцию. Описание допустимых опций запроса смотрите в разделе db2_set_option().

### Возвращаемые значения

Возвращает ресурс оператора, если SQL-запрос был успешно проанализирован и подготовлен сервером базы данных. Возвращает `false`, если сервер базы данных вернул ошибку. Вы можете определить, какая ошибка была возвращена, вызвав db2_stmt_error() или db2_stmt_errormsg().

### Примеры

Пример #1 Подготовка и выполнение SQL-запроса с маркерами параметров

В следующем примере подготавливается запрос INSERT, который принимает четыре маркера параметров, а затем выполняет итерацию по массиву массивов, содержащих входные значения, которые необходимо передать в db2_execute().

    <?php
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
    );

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';
    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        foreach ($animals as $animal) {
            $result = db2_execute($stmt, $animal);
        }
    }
    ?>

### Смотрите также

- db2_bind_param() - Связывает переменную PHP с параметром SQL-выражения
- db2_execute() - Выполняет подготовленный SQL-запрос
- db2_stmt_error() - Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором
- db2_stmt_errormsg() - Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения

# db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — Возвращает набор результатов, содержащий первичные ключи таблицы

### Описание

function db2_primary_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Возвращает набор результатов, содержащий первичные ключи таблицы.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Если `schema` равен `null`, db2_primary_keys() соответствует схеме для текущего соединения.
`table_name`
  Название таблицы.

### Возвращаемые значения

Возвращает ресурс оператора с набором результатов, содержащим строки, описывающие первичные ключи для указанной таблицы. Набор результатов состоит из следующих столбцов:

Название столбца | Описание
--- | ---
TABLE_CAT | Название каталога для таблицы, содержащей первичный ключ. Значение NULL, если в этой таблице нет каталогов.
TABLE_SCHEM | Название схемы таблицы, содержащей первичный ключ.
TABLE_NAME | Название таблицы, содержащей первичный ключ.
COLUMN_NAME | Название столбца, содержащего первичный ключ.
KEY_SEQ | Индекс столбца (начиная с 1) в ключе.
PK_NAME | Имя первичного ключа.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — Возвращает набор результатов со списком параметров хранимой процедуры

### Описание

function db2_procedure_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`,
?string `$parameter`
): resource

Возвращает набор результатов, в котором перечислены параметры для одной или нескольких хранимых процедур.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая процедуры. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`procedure`
  Название процедуры. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`parameter`
  Имя параметра. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков. Если параметр равен `null`, возвращаются все параметры для указанных хранимых процедур.

### Возвращаемые значения

Возвращает ресурс оператора с набором результатов, содержащим строки, описывающие параметры для хранимых процедур, соответствующие указанным параметрам. Строки состоят из следующих столбцов:

Название столбца | Описание
--- | ---
PROCEDURE_CAT | Каталог, содержащий таблицу. Значение `null`, если в этой таблице нет каталогов.
PROCEDURE_SCHEM | Имя схемы, содержащей хранимую процедуру.
PROCEDURE_NAME | Название процедуры.
COLUMN_NAME | Название параметра.
COLUMN_TYPE | Целочисленное значение, представляющее тип параметра:
Возвращаемое значение | Тип параметра
--- | ---
1 (SQL_PARAM_INPUT) | Входной (IN) параметр.
2 (SQL_PARAM_INPUT_OUTPUT) | Входной параметр/параметр вывода (INOUT).
3 (SQL_PARAM_OUTPUT) | Параметр (OUT) вывода.
DATA_TYPE | Тип данных SQL для параметра, представленный как целочисленное значение.
TYPE_NAME | Строка, представляющая тип данных для параметра.
COLUMN_SIZE | Целочисленное значение, представляющее размер параметра.
BUFFER_LENGTH | Максимальное количество байтов, необходимое для хранения данных для этого параметра.
DECIMAL_DIGITS | Масштаб параметра или `null`, если масштаб не применим.
NUM_PREC_RADIX | Целочисленное значение либо `10` (представляющее точный числовой тип данных), либо `2` (представляющее приблизительный числовой тип данных), либо `null` (представляющий тип данных, для которого основание системы счисления не применимо).
NULLABLE | Целочисленное значение, показывающее, допускает ли параметр значение NULL или нет.
REMARKS | Описание параметра.
COLUMN_DEF | Значение параметра по умолчанию.
SQL_DATA_TYPE | Целочисленное значение, представляющее размер параметра.
SQL_DATETIME_SUB | Возвращает целочисленное значение, представляющее код подтипа datetime или `null` для типов данных SQL, к которым это не относится.
CHAR_OCTET_LENGTH | Максимальная длина в октетах для параметра символьного типа данных, который соответствует COLUMN_SIZE для однобайтовых данных набора символов или `null` для несимвольных типов данных.
ORDINAL_POSITION | Индекс параметра (начиная с 1) в операторе CALL.
IS_NULLABLE | Строковое значение, где "YES" означает, что параметр принимает или возвращает значения `null` и "NO" означает, что параметр не принимает и не возвращает значения `null`.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных

### Описание

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая процедуры. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`procedure`
  Название процедуры. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.

### Возвращаемые значения

Возвращает ресурс оператора с набором результатов, содержащим строки, описывающие хранимые процедуры, соответствующие указанным параметрам. Строки состоят из следующих столбцов:

Название столбца | Описание
--- | ---
PROCEDURE_CAT | Каталог, содержащий таблицу. Значение `null`, если в этой таблице нет каталогов.
PROCEDURE_SCHEM | Имя схемы, содержащей хранимую процедуру.
PROCEDURE_NAME | Название процедуры.
NUM_INPUT_PARAMS | Количество входных (IN) параметров для хранимой процедуры.
NUM_OUTPUT_PARAMS | Количество параметров вывода (OUT) для хранимой процедуры.
NUM_RESULT_SETS | Количество наборов результатов, возвращаемых хранимой процедурой.
REMARKS | Любые комментарии о хранимой процедуре.
PROCEDURE_TYPE | Всегда возвращает `1`, указывая, что хранимая процедура не возвращает возвращаемое значение.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — Возвращает один столбец из строки в наборе результатов

### Описание

function db2_result(resource `$stmt`, int|string `$column`): ?mixed

Используйте db2_result(), чтобы вернуть значение указанного столбца в текущей строке набора результатов. Вы должны вызвать db2_fetch_row() перед вызовом db2_result(), чтобы установить положение указателя набора результатов.

### Список параметров

`stmt`
  Допустимый ресурс `stmt`.
`column`
  Либо целочисленный индекс столбца (начиная с 0) в наборе результатов, либо строка, соответствующая имени столбца.

### Возвращаемые значения

Возвращает значение запрошенного поля, если поле существует в наборе результатов. Возвращает `null`, если поле не существует и выдаёт предупреждение.

### Примеры

Пример #1 Пример использования db2_result()

В следующем примере показано, как выполнить итерацию по набору результатов с помощью db2_fetch_row() и получить столбцы из набора результатов с помощью db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 'BREED');
        print "$name $breed";
    }
    ?>

Результат выполнения приведённого примера:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

### Смотрите также

- db2_fetch_array() - Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc() - Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both() - Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_object() - Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_fetch_row() - Устанавливает указатель набора результатов на следующую строку или запрошенную строку

# db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — Откатывает транзакцию

### Описание

function db2_rollback(resource `$connection`): bool

Откатывает текущую транзакцию на указанном соединении и начинает новую. По умолчанию, в PHP, используется автоподтверждение транзакций, так что функция db2_rollback() нужна только в том случае, если вы принудительно отключили автоподтверждение транзакций для соединения.

### Список параметров

`connection`
  Переменная содержащая активный ресурс подключения, полученный с помощью db2_connect() или db2_pconnect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Откат операции DELETE

В следующем примере мы посчитаем количество строк в таблице, отключим автоподтверждение транзакций, удалим все строки в таблице и убедимся, что их стало `0`. После этого мы используем функцию db2_rollback() и проверим, что число строк в таблице стало таким же, как и до удаления - это подтвердит, что транзакция успешно откатилась.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Отключаем автоподтверждение
        db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

        // Удаляем все строки из ANIMALS
        db2_exec($conn, "DELETE FROM animals");

        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Откатываем операцию DELETE
        db2_rollback( $conn );

        $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";
        db2_close($conn);
    }
    ?>

Результат выполнения приведённого примера:

    7
    0
    7

### Смотрите также

- db2_autocommit() - Возвращает или устанавливает режим автоподтверждения транзакций для соединения
- db2_commit() - Подтверждает транзакцию

# db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — Возвращает объект со свойствами, описывающими сервер базы данных DB2

### Описание

function db2_server_info(resource `$connection`): stdClass|false

Функция возвращает объект со свойствами только для чтения, которые возвращают информацию о сервере баз данных IBM DB2, Cloudscape или Apache Derby. В следующей таблице перечислены свойства сервера базы данных:

Свойства сервера базы данных
Название свойства | Тип возвращаемого значения | Описание
--- | --- | ---
DBMS_NAME | string | Имя сервера базы данных, к которому вы подключены. Для серверов DB2 это комбинация `DB2`, за которой следует операционная система, в которой работает сервер базы данных.
DBMS_VER | string | Версия сервера базы данных в виде строки "MM.mm.uuuu", где MM - это мажорная версия, mm - это минорная версия, а uuuu - это патч-версия. Например, "08.02.0001" означает мажорную версию 8, минорную версию 2 и патч-версию 1.
DB_CODEPAGE | int | Кодовая страница базы данных, к которой вы подключены.
DB_NAME | string | Имя базы данных, к которой вы подключены.
DFT_ISOLATION | string | Уровень изоляции транзакции по умолчанию, поддерживаемый сервером: UR Незавершённое чтение: изменения сразу видны всем параллельным транзакциям. CS Стабильность курсора: строка, прочитанная одной транзакцией, может быть изменена и зафиксирована второй параллельной транзакцией. RS Стабильность чтения: транзакция может добавлять или удалять строки, соответствующие условию поиска или ожидающей транзакции. RR Повторяющееся чтение: данные, на которые влияет ожидающая транзакция, недоступны для других транзакций. NC Без фиксации: любые изменения видны в конце успешной операции. Явные коммиты и откаты недопустимы.
IDENTIFIER_QUOTE_CHAR | string | Символ, используемый для обозначения идентификатора.
INST_NAME | string | Экземпляр на сервере базы данных, содержащий базу данных.
ISOLATION_OPTION | array | Массив параметров изоляции, поддерживаемых сервером базы данных. Параметры изоляции описаны в свойстве DFT_ISOLATION.
KEYWORDS | array | Массив ключевых слов, зарезервированных сервером базы данных.
LIKE_ESCAPE_CLAUSE | bool | `true`, если сервер базы данных поддерживает использование подстановочных знаков `%` и `_`. `false`, если сервер базы данных не поддерживает эти подстановочные знаки.
MAX_COL_NAME_LEN | int | Максимальная длина имени столбца, поддерживаемая сервером базы данных, выраженная в байтах.
MAX_IDENTIFIER_LEN | int | Максимальная длина SQL-идентификатора, поддерживаемая сервером базы данных, выраженная в символах.
MAX_INDEX_SIZE | int | Максимальный размер столбцов, объединённых в индекс, поддерживаемый сервером базы данных, выраженный в байтах.
MAX_PROC_NAME_LEN | int | Максимальная длина имени процедуры, поддерживаемая сервером базы данных, выраженная в байтах.
MAX_ROW_SIZE | int | Максимальная длина строки в таблице базы данных, поддерживаемая сервером базы данных, выраженная в байтах.
MAX_SCHEMA_NAME_LEN | int | Максимальная длина имени схемы, поддерживаемая сервером базы данных, выраженная в байтах.
MAX_STATEMENT_LEN | int | Максимальная длина SQL-оператора, поддерживаемая сервером базы данных, выраженная в байтах.
MAX_TABLE_NAME_LEN | int | Максимальная длина имени таблицы, поддерживаемая сервером базы данных, выраженная в байтах.
NON_NULLABLE_COLUMNS | bool | `true`, если сервер базы данных поддерживает столбцы, которые можно определить как NOT NULL, `false`, если сервер базы данных не поддерживает столбцы, определённые как NOT NULL.
PROCEDURES | bool | `true`, если сервер базы данных поддерживает использование оператора CALL для вызова хранимых процедур, `false`, если сервер базы данных не поддерживает оператор CALL.
SPECIAL_CHARS | string | Строка, содержащая все символы, кроме a-Z, 0-9 и подчёркивания, которые можно использовать в имени идентификатора.
SQL_CONFORMANCE | string | Уровень соответствия спецификации ANSI/ISO SQL-92, предлагаемый сервером базы данных: ENTRY Соответствие начальному уровню SQL-92. FIPS127 Переходное соответствие FIPS-127-2. FULL Полное соответствие стандарту SQL-92. INTERMEDIATE Соответствие среднему уровню SQL-92.

### Список параметров

`connection`
  Задаёт активное соединение клиента DB2.

### Возвращаемые значения

Возвращает объект в случае успешного вызова функции, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования db2_server_info()

Чтобы получить информацию о сервере, вы должны передать действительный ресурс подключения к базе данных в db2_server_info().

    <?php

    $conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

    $server = db2_server_info( $conn );

    if ($server) {
        echo "DBMS_NAME: ";                 var_dump( $server->DBMS_NAME );
        echo "DBMS_VER: ";                  var_dump( $server->DBMS_VER );
        echo "DB_CODEPAGE: ";               var_dump( $server->DB_CODEPAGE );
        echo "DB_NAME: ";                   var_dump( $server->DB_NAME );
        echo "INST_NAME: ";                 var_dump( $server->INST_NAME );
        echo "SPECIAL_CHARS: ";             var_dump( $server->SPECIAL_CHARS );
        echo "KEYWORDS: ";                  var_dump( sizeof($server->KEYWORDS) );
        echo "DFT_ISOLATION: ";             var_dump( $server->DFT_ISOLATION );
        echo "ISOLATION_OPTION: ";
        $il = '';
        foreach( $server->ISOLATION_OPTION as $opt )
        {
           $il .= $opt." ";
        }
        var_dump( $il );
        echo "SQL_CONFORMANCE: ";           var_dump( $server->SQL_CONFORMANCE );
        echo "PROCEDURES: ";                var_dump( $server->PROCEDURES );
        echo "IDENTIFIER_QUOTE_CHAR: ";     var_dump( $server->IDENTIFIER_QUOTE_CHAR );
        echo "LIKE_ESCAPE_CLAUSE: ";        var_dump( $server->LIKE_ESCAPE_CLAUSE );
        echo "MAX_COL_NAME_LEN: ";          var_dump( $server->MAX_COL_NAME_LEN );
        echo "MAX_ROW_SIZE: ";              var_dump( $server->MAX_ROW_SIZE );
        echo "MAX_IDENTIFIER_LEN: ";        var_dump( $server->MAX_IDENTIFIER_LEN );
        echo "MAX_INDEX_SIZE: ";            var_dump( $server->MAX_INDEX_SIZE );
        echo "MAX_PROC_NAME_LEN: ";         var_dump( $server->MAX_PROC_NAME_LEN );
        echo "MAX_SCHEMA_NAME_LEN: ";       var_dump( $server->MAX_SCHEMA_NAME_LEN );
        echo "MAX_STATEMENT_LEN: ";         var_dump( $server->MAX_STATEMENT_LEN );
        echo "MAX_TABLE_NAME_LEN: ";        var_dump( $server->MAX_TABLE_NAME_LEN );
        echo "NON_NULLABLE_COLUMNS: ";      var_dump( $server->NON_NULLABLE_COLUMNS );

        db2_close($conn);
    }
    ?>

Результат выполнения приведённого примера:

    DBMS_NAME: string(9) "DB2/LINUX"
    DBMS_VER: string(10) "08.02.0000"
    DB_CODEPAGE: int(1208)
    DB_NAME: string(6) "SAMPLE"
    INST_NAME: string(8) "db2inst1"
    SPECIAL_CHARS: string(2) "@#"
    KEYWORDS: int(179)
    DFT_ISOLATION: string(2) "CS"
    ISOLATION_OPTION: string(12) "UR CS RS RR "
    SQL_CONFORMANCE: string(7) "FIPS127"
    PROCEDURES: bool(true)
    IDENTIFIER_QUOTE_CHAR: string(1) """
    LIKE_ESCAPE_CLAUSE: bool(true)
    MAX_COL_NAME_LEN: int(30)
    MAX_ROW_SIZE: int(32677)
    MAX_IDENTIFIER_LEN: int(18)
    MAX_INDEX_SIZE: int(1024)
    MAX_PROC_NAME_LEN: int(128)
    MAX_SCHEMA_NAME_LEN: int(30)
    MAX_STATEMENT_LEN: int(2097152)
    MAX_TABLE_NAME_LEN: int(128)
    NON_NULLABLE_COLUMNS: bool(true)

### Смотрите также

- db2_client_info() - Возвращает объект со свойствами, описывающими клиента DB2

# db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Устанавливает опции для ресурса соединения или ресурса запроса

### Описание

function db2_set_option(resource `$resource`, array `$options`, int `$type`): bool

Функция устанавливает опции для ресурса запроса или ресурса соединения. Нельзя установить опции для ресурсов результирующих наборов.

### Список параметров

`resource`
  Корректный ресурс запроса, который вернула функция db2_prepare() или корректный ресурс соединения, который вернула функция db2_connect() или db2_pconnect().
`options`

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

  `autocommit`
    `DB2_AUTOCOMMIT_ON` — включает режим автофиксации для ресурса соединения. `DB2_AUTOCOMMIT_OFF` — отключает режим автофиксации для ресурса соединения.
  `cursor`
    `DB2_FORWARD_ONLY` — задаёт тип курсора последовательного доступа для ресурса запроса. Это тип курсора по умолчанию, который поддерживается всеми серверами баз данных. `DB2_SCROLLABLE` — задаёт тип прокручиваемого курсора для ресурса запроса. Прокручиваемые курсоры разрешают получать доступ к произвольным строкам результирующего набора, но поддерживаются только базами данных IBM DB2 Universal Database.
  `binmode`
    `DB2_BINARY` — указывает, что функция вернёт двоичные данные как есть. Это эквивалент установки опции конфигурации `ibm_db2.binmode=1` в файле php.ini. `DB2_CONVERT` — указывает, что функция преобразует двоичные данные в шестнадцатеричное представление и вернёт данные в таком виде. Это эквивалент установки опции конфигурации `ibm_db2.binmode=2` в файле php.ini. `DB2_PASSTHRU` — указывает, что функция преобразует двоичные в `null`. Это эквивалент установки опции конфигурации `ibm_db2.binmode=3` в файле php.ini.
  `db2_attr_case`
    `DB2_CASE_LOWER` — определяет, что имена столбцов будут возвращаться в нижнем регистре. `DB2_CASE_UPPER` — определяет, что имена столбцов будут возвращаться в верхнем регистре. `DB2_CASE_NATURAL` — определяет, что имена столбцов будут возвращаться как есть.
  `deferred_prepare`
    `DB2_DEFERRED_PREPARE_ON` - включает отложенную подготовку ресурса запроса. `DB2_DEFERRED_PREPARE_OFF` - выключает отложенную подготовку ресурса запроса.

  Следующие новые опции ОС i5/OS доступны в модуле ibm_db2 1.5.1 и более поздних версиях. Эти опции применяются, только если PHP и модуль ibm_db2 запускаются на системах i5.

  `i5_fetch_only`
    `DB2_I5_FETCH_ON` — курсоры доступны только для чтения и не могут использоваться для позиционирования при операциях DELETE или UPDATE. Это значение по умолчанию, только если для переменной окружения `SQL_ATTR_FOR_FETCH_ONLY` не установили значение `SQL_FALSE`. `DB2_I5_FETCH_OFF` — курсоры можно использовать для позиционирования при операциях DELETE или UPDATE.

  Следующие новые опции доступны в модуле ibm_db2 1.8.0 и более поздних версиях.

  `rowcount`
    `DB2_ROWCOUNT_PREFETCH_ON` — клиент может запросить полное количество строк перед извлечением, что означает, что функция db2_num_rows() вернёт количество выбранных строк, даже если используется курсор `ROLLFORWARD_ONLY`. `DB2_ROWCOUNT_PREFETCH_OFF` — клиент не может запросить полное количество строк перед извлечением.

  Следующие новые опции доступны в модуле ibm_db2 1.7.0 и более поздних версиях.

  `trusted_user`
    Чтобы переключить пользователя в статус доверенного пользователя, указывают идентификатор (строку) доверенного пользователя как значение этого параметра. Эту опцию можно установить только для ресурса соединения. Чтобы использовать эту опцию, требуется включить доверенный контекст на ресурсе подключения.
  `trusted_password`
    Пароль (строка), который соответствует идентификатору пользователя, который задали в опции trusted_user.

  Следующие новые опции доступны в модуле ibm_db2 1.6.0 и более поздних версиях. Эти опции предоставляют полезную информацию отслеживания, доступ к которой можно получить функцией db2_get_option() во время выполнения.

  > Замечание: При установке значений для каждой опции отдельные серверы смогут обработать не всё значение и обрежут его. Чтобы гарантировать правильное преобразование данных каждой опции при передаче на хост-систему, указывают только символы A-Z, 0-9, подчёркивание(_) и точку (.).

  `userid`

    `SQL_ATTR_INFO_USERID` — указатель на строку, которая заканчивается символом null-байта и используется для распознавания клиентского идентификатора пользователя, который передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

    > Замечание: БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 16 символов. Этот идентификатор пользователя не следует путать с идентификатором пользователя для аутентификации, он предназначен только для идентификации и не используется для авторизации.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` — указатель на строку, которая заканчивается символом null-байта и используется для идентификации учётной строки, которая передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

    > Замечание: БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 200 символов.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` — указатель на строку, которая заканчивается символом null-байта и используется для идентификации имени клиентского приложения, которое передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

    > Замечание: БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 32 символов.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` — указатель на строку, которая заканчивается символом null-байта и используется для идентификации имени рабочей станции, которое передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

    > Замечание: БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 18 символов.

`type`
  Целочисленное значение, которое указывает тип ресурса, который передали в функцию. Тип ресурса и это значение должны совпадать. `1` — ресурс соединения передали в функцию. Передача в качестве значения целого числа, которое не равно `1`, указывает, что в функцию передали ресурс запроса.

В следующей таблице указывается совместимость параметров с доступными типами ресурсов:

Матрица ресурс-параметр
Ключ | Значение | Тип ресурса
--- | --- | ---
|  | Соединение | Запрос | Результирующий набор
autocommit | `DB2_AUTOCOMMIT_ON` | X | - | -
autocommit | `DB2_AUTOCOMMIT_OFF` | X | - | -
cursor | `DB2_SCROLLABLE` | - | X | -
cursor | `DB2_FORWARD_ONLY` | - | X | -
binmode | `DB2_BINARY` | X | X | -
binmode | `DB2_CONVERT` | X | X | -
binmode | `DB2_PASSTHRU` | X | X | -
db2_attr_case | `DB2_CASE_LOWER` | X | X | -
db2_attr_case | `DB2_CASE_UPPER` | X | X | -
db2_attr_case | `DB2_CASE_NATURAL` | X | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_ON` | - | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_OFF` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_ON` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_OFF` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_OFF` | - | X | -
trusted_user | `<USER NAME> (String)` | X | - | -
trusted_password | `<PASSWORD> (String)` | X | - | -
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример установки одного параметра для ресурса соединения

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array('autocommit' => DB2_AUTOCOMMIT_ON);

    /* Вызываем функцию */
    $result = db2_set_option($conn, $options, 1);

    /* Проверяем, все ли опции установились */
    if($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Options Set Successfully

Пример #2 Пример установки набора параметров для ресурса соединения

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'autocommit' => DB2_AUTOCOMMIT_OFF,
        'binmode' => DB2_PASSTHRU,
        'db2_attr_case' => DB2_CASE_UPPER,
        'cursor' => DB2_SCROLLABLE
    );

    /* Вызываем функцию */
    $result = db2_set_option($conn, $options, 1);

    /* Проверяем, все ли опции установились */
    if ($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Options Set Successfully

Пример #3 Пример установки набора параметров с одним некорректным ключом

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'autocommit' => DB2_AUTOCOMMIT_OFF,
        'MY_INVALID_KEY' => DB2_PASSTHRU,
        'db2_attr_case' => DB2_CASE_UPPER,
        'cursor' => DB2_SCROLLABLE
    );

    /* Вызываем функцию */
    $result = db2_set_option($conn, $options, 1);

    /* Проверяем, все ли опции установились */
    if ($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Could Not Set Options

Пример #4 Пример установки набора параметров с одним некорректным значением

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'autocommit' => DB2_AUTOCOMMIT_OFF,
        'binmode' => 'INVALID_VALUE',
        'db2_attr_case' => DB2_CASE_UPPER,
        'cursor' => DB2_SCROLLABLE
    );

    /* Вызываем функцию */
    $result = db2_set_option($conn, $options, 1);

    /* Проверяем, все ли опции установились */
    if ($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Could Not Set Options

Пример #5 Пример установки набора параметров с ресурсом соединения и неправильным типом

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'autocommit' => DB2_AUTOCOMMIT_OFF,
        'binmode' => DB2_PASSTHRU,
        'db2_attr_case' => DB2_CASE_UPPER,
        'cursor' => DB2_SCROLLABLE
    );

    /* Вызываем функцию */
    $result = db2_set_option($conn, $options, 2);

    /* Проверяем, все ли опции установились */
    if ($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Could Not Set Options

Пример #6 Пример установки набора параметров с неправильным ресурсом

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'autocommit' => DB2_AUTOCOMMIT_OFF,
        'binmode' => DB2_PASSTHRU,
        'db2_attr_case' => DB2_CASE_UPPER,
        'cursor' => DB2_SCROLLABLE
    );

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

    /* Вызываем функцию */
    $result = db2_set_option($stmt, $options, 1);

    /* Проверяем, все ли опции установились */
    if ($result) {
        echo 'Options Set Successfully';
    } else {
        echo 'Could Not Set Options';
    }

    ?>

Результат выполнения приведённого примера:

    Could Not Set Options

Пример #7 Пример объединения опций

    <?php

    /* Параметры соединения с базой данных */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Строка соединения */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Получаем ресурс соединения */
    $conn = db2_connect($conn_string, '', '');

    /* Создаём ассоциативный массив опций */
    $options = array(
        'db2_attr_case' => DB2_CASE_LOWER,
        'cursor' => DB2_SCROLLABLE
    );

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

    /* Вызываем функцию */
    $option_result = db2_set_option($stmt, $options, 2);
    $result = db2_execute($stmt, array('000130', '000140'));

    /* Получаем строку 2 перед строкой 1. Перематываемый курсор! */
    print_r(db2_fetch_assoc($stmt, 2));
    print '<br /><br />';
    print_r(db2_fetch_assoc($stmt, 1));

    ?>

Результат выполнения приведённого примера:

    Array
    (
        [empno] => 000140
        [firstnme] => HEATHER
        [midinit] => A
        [lastname] => NICHOLLS
        [workdept] => C01
        [phoneno] => 1793
        [hiredate] => 1976-12-15
        [job] => ANALYST
        [edlevel] => 18
        [sex] => F
        [birthdate] => 1946-01-19
        [salary] => 28420.00
        [bonus] => 600.00
        [comm] => 2274.00
    )

    Array
    (
        [empno] => 000130
        [firstnme] => DELORES
        [midinit] => M
        [lastname] => QUINTANA
        [workdept] => C01
        [phoneno] => 4578
        [hiredate] => 1971-07-28
        [job] => ANALYST
        [edlevel] => 16
        [sex] => F
        [birthdate] => 1925-09-15
        [salary] => 23800.00
        [bonus] => 500.00
        [comm] => 1904.00
    )

Пример #8 Пример курсора ОС i5/OS только для чтения

    <?php
    $conn = db2_connect("", "", "", array("i5_lib" => "nobody"));
    $stmt = db2_prepare($conn, 'select * from names where first = ?');
    $name = "first2";

    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);

    $options = array("i5_fetch_only" => DB2_I5_FETCH_ON);

    db2_set_option($stmt, $options, 0);

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            echo "{$row[0]} {$row[1]}";
        }
    }

    ?>

Результат выполнения приведённого примера:

    first2 last2

### Смотрите также

- db2_connect() - Возвращает соединение с базой данных
- db2_pconnect() - Возвращает постоянное соединение с базой данных
- db2_exec() - Выполняет SQL-запрос напрямую
- db2_prepare() - Подготавливает SQL-запрос к выполнению
- db2_cursor_type() - Возвращает тип курсора, который используется в ресурсе оператора

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы

### Описание

function db2_special_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$table_name`,
int `$scope`
): resource

Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы.
`table_name`
  Название таблицы.
`scope`

  Целочисленное значение, представляющее минимальную продолжительность, в течение которой действителен уникальный идентификатор строки. Это может быть одно из следующих значений: values:

  Значение | Константа SQL | Описание
  --- | --- | ---
  0 | SQL_SCOPE_CURROW | Идентификатор строки действителен только тогда, когда курсор находится на строке.
  1 | SQL_SCOPE_TRANSACTION | Идентификатор строки действителен на протяжении всей транзакции.
  2 | SQL_SCOPE_SESSION | Идентификатор строки действителен в течение всего времени соединения.

### Возвращаемые значения

Возвращает ресурс оператора с набором результатов, содержащим строки с уникальной информацией идентификатора строки таблицы. Строки состоят из следующих столбцов: following columns:

Название столбца | Описание
--- | ---
SCOPE |
Значение | Констант SQL | Описание
--- | --- | ---
0 | SQL_SCOPE_CURROW | Идентификатор строки действителен только тогда, когда курсор находится на строке.
1 | SQL_SCOPE_TRANSACTION | Идентификатор строки действителен на протяжении всей транзакции.
2 | SQL_SCOPE_SESSION | Идентификатор строки действителен в течение всего времени соединения.
COLUMN_NAME | Имя уникального столбца.
DATA_TYPE | Тип данных SQL столбца.
TYPE_NAME | Символьное строковое представление типа данных SQL столбца.
COLUMN_SIZE | Целочисленное значение, представляющее размер столбца.
BUFFER_LENGTH | Максимальное количество байтов, необходимое для хранения данных из этого столбца.
DECIMAL_DIGITS | Масштаб столбца или `null`, если масштаб не применим.
NUM_PREC_RADIX | Целочисленное значение либо `10` (представляющее точный числовой тип данных), либо `2` (представляющее приблизительный числовой тип данных), либо `null` (представляющий тип данных, для которого основание системы счисления не применимо).
PSEUDO_COLUMN | Всегда возвращает 1.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — Возвращает набор результатов, содержащий индекс и статистику таблицы

### Описание

function db2_statistics(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`,
bool `$unique`
): resource

Возвращает набор результатов, содержащий индекс и статистику таблицы.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающей на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая целевую таблицу. Если параметр равен `null`, статистика и индексы возвращаются для схемы текущего пользователя.
`table_name`
  Название таблицы.
`unique`
  Если у параметра `unique` значение `true`, возвращается информация для всех индексов в таблице. В противном случае возвращается информация только об уникальных индексах в таблице.

### Возвращаемые значения

Возвращает ресурс оператора с набором результатов, содержащим строки, описывающие статистику и индексы для таблиц базы данных, соответствующих указанным параметрам. Строки состоят из следующих столбцов:

Название столбца | Описание
--- | ---
TABLE_CAT | Каталог, содержащий таблицу. Значение `null`, если в этой таблице нет каталогов.
TABLE_SCHEM | Название схемы, содержащей таблицу.
TABLE_NAME | Название таблицы.
NON_UNIQUE | Целочисленное значение, указывающее, запрещает ли индекс уникальные значения или строка представляет статистику самой таблицы:
Возвращаемое значение | Тип параметра
--- | ---
0 (SQL_FALSE) | Индекс допускает повторяющиеся значения.
1 (SQL_TRUE) | Значения индекса должны быть уникальными.
`null` | Строка представляет собой статистическую информацию для самой таблицы.
INDEX_QUALIFIER | Строковое значение, представляющее квалификатор, который необходимо добавить к INDEX_NAME, чтобы полностью определить индекс.
INDEX_NAME | Строка, представляющая имя индекса.
TYPE | Целочисленное значение, представляющее тип информации, содержащейся в этой строке набора результатов:
Возвращаемое значение | Тип параметра
--- | ---
0 (SQL_TABLE_STAT) | Строка содержит статистику о самой таблице.
1 (SQL_INDEX_CLUSTERED) | Строка содержит информацию о кластеризованном индексе.
2 (SQL_INDEX_HASH) | Строка содержит информацию о хешированном индексе.
3 (SQL_INDEX_OTHER) | Строка содержит информацию о типе индекса, который не кластеризован и не хеширован.
ORDINAL_POSITION | Позиция столбца (начинается от 1) в индексе. `null`, если строка содержит статистическую информацию о самой таблице.
COLUMN_NAME | Название столбца (начинается от 1) в индексе. `null`, если строка содержит статистическую информацию о самой таблице.
ASC_OR_DESC | `A`, если столбец отсортирован в порядке возрастания, `D`, если столбец отсортирован в порядке убывания, `null`, если строка содержит статистическую информацию о самой таблице.
CARDINALITY | Если строка содержит информацию об индексе, этот столбец содержит целочисленное значение, представляющее количество уникальных значений в индексе. Если строка содержит информацию о самой таблице, этот столбец содержит целочисленное значение, представляющее количество строк в таблице.
PAGES | Если строка содержит информацию об индексе, этот столбец содержит целочисленное значение, представляющее количество страниц, используемых для хранения индекса. Если строка содержит информацию о самой таблице, этот столбец содержит целочисленное значение, представляющее количество страниц, используемых для хранения таблицы.
FILTER_CONDITION | Всегда возвращает `null`.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором

### Описание

function db2_stmt_error(?resource `$stmt` = `null`): string

Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором.

Если вы не передадите ресурс оператора в качестве аргумента в db2_stmt_error(), драйвер вернёт значение SQLSTATE, связанное с последней попыткой вернуть ресурс оператора, например, из db2_prepare() или db2_exec().

Чтобы узнать, что означает значение SQLSTATE, вы можете ввести следующую команду в командной строке процессора DB2: `db2 '? `sqlstate-value`'`. Вы также можете вызвать db2_stmt_errormsg(), чтобы получить явное сообщение об ошибке и соответствующее значение SQLCODE.

### Список параметров

`stmt`
  Допустимый ресурс оператора.

### Возвращаемые значения

Возвращает строку, содержащую значение SQLSTATE.

### Смотрите также

- db2_conn_error() - Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения
- db2_conn_errormsg() - Возвращает последнее сообщение об ошибке подключения и значение SQLCODE
- db2_stmt_errormsg() - Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения

### Описание

function db2_stmt_errormsg(?resource `$stmt` = `null`): string

Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения.

Если вы не передаёте ресурс выражения в качестве аргумента в db2_stmt_errormsg(), драйвер возвращает сообщение об ошибке, связанное с последней попыткой вернуть ресурс оператора, например, из db2_prepare() или db2_exec().

### Список параметров

`stmt`
  Допустимый ресурс выражения.

### Возвращаемые значения

Возвращает строку, содержащую сообщение об ошибке и значение SQLCODE последней ошибки, возникшей при выдаче SQL-выражения.

### Смотрите также

- db2_conn_error() - Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения
- db2_conn_errormsg() - Возвращает последнее сообщение об ошибке подключения и значение SQLCODE
- db2_stmt_error() - Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором

# db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных

### Описание

function db2_table_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`
): resource

Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`table_name`
  Название таблицы. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.

### Возвращаемые значения

Возвращает ресурс выражения с набором результатов, содержащим строки, описывающие права доступа для таблиц, которые соответствуют указанным параметрам. Строки состоят из следующих столбцов:

Название столбца | Описание
--- | ---
TABLE_CAT | Каталог, содержащий таблицу или `null`, если в этой таблице нет каталогов.
TABLE_SCHEM | Имя схемы, содержащей таблицу.
TABLE_NAME | Название таблицы.
GRANTOR | Идентификатор авторизации пользователя, предоставившего права доступа.
GRANTEE | Идентификатор авторизации пользователя, которому были предоставлены права доступа.
PRIVILEGE | Предоставляемые права доступа. Может быть один из вариантов: ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT или UPDATE.
IS_GRANTABLE | Строковое значение «YES» или «NO», указывающее, может ли получатель предоставлять права доступа другим пользователям.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_tables() - Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

### Описание

function db2_tables(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$table_type` = `null`
): resource

Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных.

### Список параметров

`connection`
  Допустимое соединение с базой данных IBM DB2, Cloudscape или Apache Derby.
`qualifier`
  Квалификатор для баз данных DB2, работающих на серверах OS/390 или z/OS. Для других баз данных передайте `null` или пустую строку.
`schema`
  Схема, содержащая таблицы. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`table_name`
  Название таблицы. Параметр принимает шаблон поиска, содержащий `_` и `%` в качестве подстановочных знаков.
`table_type`
  Список идентификаторов типов таблиц, разделённых запятыми. Чтобы соответствовать всем типам таблиц, передайте `null` или пустую строку. К допустимым идентификаторам типа таблицы относятся: ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW, и VIEW.

### Возвращаемые значения

Возвращает ресурс выражения с набором результатов, содержащим строки, описывающие таблицы, соответствующие указанным параметрам. Строки состоят из следующих столбцов:

Название столбца | Описание
--- | ---
TABLE_CAT | Каталог, содержащий таблицу или `null`, если в этой таблице нет каталогов.
TABLE_SCHEM | Имя схемы, содержащей таблицу.
TABLE_NAME | Название таблицы.
TABLE_TYPE | Идентификатор типа таблицы.
REMARKS | Описание таблицы.

### Смотрите также

- db2_column_privileges() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns() - Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_foreign_keys() - Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_primary_keys() - Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns() - Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures() - Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_special_columns() - Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics() - Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_table_privileges() - Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных

## Содержание

- db2_autocommit — Возвращает или устанавливает режим автоподтверждения транзакций для соединения
- db2_bind_param — Связывает переменную PHP с параметром SQL-выражения
- db2_client_info — Возвращает объект со свойствами, описывающими клиента DB2
- db2_close — Закрывает соединение с базой данных
- db2_column_privileges — Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
- db2_columns — Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
- db2_commit — Подтверждает транзакцию
- db2_conn_error — Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения
- db2_conn_errormsg — Возвращает последнее сообщение об ошибке подключения и значение SQLCODE
- db2_connect — Возвращает соединение с базой данных
- db2_cursor_type — Возвращает тип курсора, который используется в ресурсе оператора
- db2_escape_string — Экранирует отдельные символы
- db2_exec — Выполняет SQL-запрос напрямую
- db2_execute — Выполняет подготовленный SQL-запрос
- db2_fetch_array — Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
- db2_fetch_assoc — Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
- db2_fetch_both — Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
- db2_fetch_object — Возвращает объект со свойствами, представляющими столбцы в выбранной строке
- db2_fetch_row — Устанавливает указатель набора результатов на следующую строку или запрошенную строку
- db2_field_display_size — Возвращает максимальное количество байтов, необходимое для отображения столбца
- db2_field_name — Возвращает имя столбца в наборе результатов
- db2_field_num — Возвращает позицию указанного столбца в наборе результатов
- db2_field_precision — Возвращает точность указанного столбца в наборе результатов
- db2_field_scale — Возвращает масштаб указанного столбца в наборе результатов
- db2_field_type — Возвращает тип данных указанного столбца в наборе результатов
- db2_field_width — Возвращает ширину текущего значения указанного столбца в наборе результатов
- db2_foreign_keys — Возвращает набор результатов, в котором перечислены внешние ключи таблицы
- db2_free_result — Освобождает ресурсы, связанные с набором результатов
- db2_free_stmt — Освобождает ресурсы, связанные с указанным ресурсом выражения
- db2_get_option — Извлекает значение параметра для ресурса оператора или ресурса соединения
- db2_last_insert_id — Возвращает автоматически сгенерированный идентификатор последнего запроса на добавление, успешно выполненного в этом соединении
- db2_lob_read — Получает определённый пользователем размер LOB-файлов при каждом вызове
- db2_next_result — Запрашивает следующий набор результатов из хранимой процедуры
- db2_num_fields — Возвращает количество полей в результирующем наборе
- db2_num_rows — Возвращает количество строк, затронутых SQL-запросом
- db2_pclose — Закрывает постоянное соединение с базой данных
- db2_pconnect — Возвращает постоянное соединение с базой данных
- db2_prepare — Подготавливает SQL-запрос к выполнению
- db2_primary_keys — Возвращает набор результатов, содержащий первичные ключи таблицы
- db2_procedure_columns — Возвращает набор результатов со списком параметров хранимой процедуры
- db2_procedures — Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
- db2_result — Возвращает один столбец из строки в наборе результатов
- db2_rollback — Откатывает транзакцию
- db2_server_info — Возвращает объект со свойствами, описывающими сервер базы данных DB2
- db2_set_option — Устанавливает опции для ресурса соединения или ресурса запроса
- db2_special_columns — Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
- db2_statistics — Возвращает набор результатов, содержащий индекс и статистику таблицы
- db2_stmt_error — Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором
- db2_stmt_errormsg — Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения
- db2_table_privileges — Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
- db2_tables — Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Функции IBM DB2
  - db2_autocommit — Возвращает или устанавливает режим автоподтверждения транзакций для соединения
  - db2_bind_param — Связывает переменную PHP с параметром SQL-выражения
  - db2_client_info — Возвращает объект со свойствами, описывающими клиента DB2
  - db2_close — Закрывает соединение с базой данных
  - db2_column_privileges — Возвращает результирующий набор, перечисляющий столбцы и связанные с ним привилегии для таблицы
  - db2_columns — Возвращает результирующий набор, перечисляющий столбцы и связанные с ними метаданные для таблицы
  - db2_commit — Подтверждает транзакцию
  - db2_conn_error — Возвращает строку, содержащую значение SQLSTATE, возвращённое последней попыткой подключения
  - db2_conn_errormsg — Возвращает последнее сообщение об ошибке подключения и значение SQLCODE
  - db2_connect — Возвращает соединение с базой данных
  - db2_cursor_type — Возвращает тип курсора, который используется в ресурсе оператора
  - db2_escape_string — Экранирует отдельные символы
  - db2_exec — Выполняет SQL-запрос напрямую
  - db2_execute — Выполняет подготовленный SQL-запрос
  - db2_fetch_array — Возвращает массив, индексированный по положению столбца, представляющий строку в наборе результатов
  - db2_fetch_assoc — Возвращает массив, индексированный по имени столбца, представляющий строку в наборе результатов
  - db2_fetch_both — Возвращает массив, индексированный как по имени столбца, так и по позиции, представляющий строку в наборе результатов
  - db2_fetch_object — Возвращает объект со свойствами, представляющими столбцы в выбранной строке
  - db2_fetch_row — Устанавливает указатель набора результатов на следующую строку или запрошенную строку
  - db2_field_display_size — Возвращает максимальное количество байтов, необходимое для отображения столбца
  - db2_field_name — Возвращает имя столбца в наборе результатов
  - db2_field_num — Возвращает позицию указанного столбца в наборе результатов
  - db2_field_precision — Возвращает точность указанного столбца в наборе результатов
  - db2_field_scale — Возвращает масштаб указанного столбца в наборе результатов
  - db2_field_type — Возвращает тип данных указанного столбца в наборе результатов
  - db2_field_width — Возвращает ширину текущего значения указанного столбца в наборе результатов
  - db2_foreign_keys — Возвращает набор результатов, в котором перечислены внешние ключи таблицы
  - db2_free_result — Освобождает ресурсы, связанные с набором результатов
  - db2_free_stmt — Освобождает ресурсы, связанные с указанным ресурсом выражения
  - db2_get_option — Извлекает значение параметра для ресурса оператора или ресурса соединения
  - db2_last_insert_id — Возвращает автоматически сгенерированный идентификатор последнего запроса на добавление, успешно выполненного в этом соединении
  - db2_lob_read — Получает определённый пользователем размер LOB-файлов при каждом вызове
  - db2_next_result — Запрашивает следующий набор результатов из хранимой процедуры
  - db2_num_fields — Возвращает количество полей в результирующем наборе
  - db2_num_rows — Возвращает количество строк, затронутых SQL-запросом
  - db2_pclose — Закрывает постоянное соединение с базой данных
  - db2_pconnect — Возвращает постоянное соединение с базой данных
  - db2_prepare — Подготавливает SQL-запрос к выполнению
  - db2_primary_keys — Возвращает набор результатов, содержащий первичные ключи таблицы
  - db2_procedure_columns — Возвращает набор результатов со списком параметров хранимой процедуры
  - db2_procedures — Возвращает набор результатов, в котором перечислены хранимые процедуры, зарегистрированные в базе данных
  - db2_result — Возвращает один столбец из строки в наборе результатов
  - db2_rollback — Откатывает транзакцию
  - db2_server_info — Возвращает объект со свойствами, описывающими сервер базы данных DB2
  - db2_set_option — Устанавливает опции для ресурса соединения или ресурса запроса
  - db2_special_columns — Возвращает набор результатов, в котором перечислены столбцы с уникальным идентификатором строки таблицы
  - db2_statistics — Возвращает набор результатов, содержащий индекс и статистику таблицы
  - db2_stmt_error — Возвращает строку, содержащую SQLSTATE, возвращённую SQL-оператором
  - db2_stmt_errormsg — Возвращает строку, содержащую последнее сообщение об ошибке SQL-выражения
  - db2_table_privileges — Возвращает набор результатов, в котором перечислены таблицы и связанные с ними права доступа к базе данных
  - db2_tables — Возвращает набор результатов, в котором перечислены таблицы и связанные метаданные в базе данных

# Модуль MongoDB

Этот модуль разработан на основе библиотек » libmongoc и » libbson. Он предоставляет минимальное API для ключевого функционала драйвера: команды, запросы, записи, управление соединением и сериализация BSON.

Самодельные библиотеки PHP, требующие этот модуль, могут предоставлять высокоуровневые API, такие как: сборщики запросов, методы-помощники для индивидуальных команд и GridFS. Разработчики приложений должны рассмотреть вопрос об использовании этого модуля совместно с » PHP-библиотекой модуля MongoDB, которая реализует те же высокоуровневые API драйвера MongoDB, как и для других языков. Такое разделение задач позволяет модулю сосредоточиться на главных задачах, которые перед ним стоят — повышение производительности.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Начиная с версии 1.21.0 для работы модуля требуется PHP 8.1 или выше. Предыдущие версии модуля обеспечивают совместимость со старыми версиями PHP.

Модулю нужны библиотеки » libbson и » libmongoc, и по умолчанию модуль будет использовать встроенные версии библиотек. Также можно использовать системные библиотеки, как описывает документация по сборке из исходного кода.

Модуль при работе через библиотеку libmongoc необязательно зависит от библиотеки TLS (например, OpenSSL) и будет использовать её, если она доступна. Если процессу сборки не удаётся найти библиотеку TLS, пользователи должны проверить, что соответствующий пакет разработки (например, `libssl-dev`) и » pkg-config установлены. Процесс обнаружения и настройки библиотек TLS более подробно описан в документации по сборке из исходного кода.

» Cyrus SASL — необязательная зависимость для поддержки аутентификации Kerberos, которая будет использоваться, если она доступна.

> Замечание: Из-за потенциальных проблем представления 64-разрядных целых чисел на 32-разрядных платформах, пользователям рекомендуется использовать 64-разрядную среду. При использовании 32-разрядной платформы помните, что любое 64-разрядное целое число, прочитанное из базы данных, будет возвращено как экземпляр MongoDB\BSON\Int64 вместо целочисленного типа PHP.

## Установка

## Установка PHP-модуля MongoDB через репозиторий PECL

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/mongodb

Пользователи Linux, Unix и macOS запускают следующую команду для установки модуля:

    $ sudo pecl install mongodb

На системах с несколькими установленными версиями PHP (например для macOS: установка по умолчанию, Homebrew и » XAMPP) у каждой версии PHP будет своя команда pecl и файл (или файлы) php.ini. Кроме того, каждому PHP-окружению наподобие CLI или web разрешается использовать отдельные файлы php.ini.

Начиная с версии модуля 1.17.0 PECL будет запрашивать разные настройки `configure`. Чтобы установить модуль с параметрами по умолчанию в неинтерактивном скрипте, команду `yes` с вводом пустой строки присоединяют через символ вертикальной черты к команде `pecl install`:

    $ yes '' | sudo pecl install mongodb

Полный список поддерживаемых параметров `configure` доступен в файле `package.xml`, который включили в пакет PECL. Чтобы установить модуль со специфичными параметрами `configure` в неинтерактивном сценарии, указывают параметр `--configureoptions` для команды `pecl install`:

    $ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

По умолчанию установка модуля через PECL использует встроенные версии модулей: » libbson, » libmongoc, » libmongocrypt и попытается сконфигурировать их автоматически.

> Замечание: Когда процесс установки не находит библиотеку SSL, проверяют, что установили пакеты для разработки наподобие `libssl-dev` и пакет » pkg-config. Проводят ручную установку, если это не помогает.

И наконец, добавляют следующую строку в файл php.ini для каждого окружения, в котором будет работать модуль:

    extension=mongodb.so

## Установка PHP-модуля MongoDB в операционную систему macOS через менеджер пакетов Homebrew

Начиная с » Homebrew 1.5.0 пакет » Homebrew/php tap объявили устаревшим, а формулы для отдельных модулей PHP удалили. Пользователям macOS рекомендуют устанавливать драйвер через формулу » php и запускать предоставленную PHP, установленным через менеджер пакетов Homebrew, команду pecl, как рассказывает стандартная инструкция по установке из репозитория PECL.

## Установка PHP-модуля MongoDB в операционную систему Windows

Предварительно скомпилированные исполняемые файлы прикрепляются к » выпускам проекта на GitHub. Архивы публикуются для разных комбинаций версии PHP, потоковой безопасности (TS или NTS) и архитектуры (x86 или x64). Определите правильный архив для PHP-окружения и извлеките файл php_mongodb.dll в директорию с модулями (по умолчанию "ext").

Добавьте следующую строку в файл php.ini для каждого окружения, в котором будет работать модуль:

    extension=php_mongo.dll

Неправильный выбор двоичного файла вызовет ошибку при попытке загрузить DLL-модуль во время выполнения:

    PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Убедитесь, что DLL-файл, который скачали, соответствует следующим свойствам среды выполнения PHP:

- Версия PHP (`PHP_VERSION`)
- Потоковая безопасность (`PHP_ZTS`)
- Архитектура (`PHP_INT_SIZE`)

Просмотр этих свойств доступен в выводе функции phpinfo(). Дважды проверьте, что вывод функции phpinfo() соответствует окружению, если в систему установили несколько версий PHP.

> Замечание: Дополнительные DLL-зависимости для пользователей Windows
> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libsasl.dll

## Сборка PHP-драйвера MongoDB из исходного кода

Разработчики и пользователи, которые заинтересованы в последних исправлениях ошибок, компилируют модуль из последнего исходного кода » на сайте GitHub. Запустите следующие команды, чтобы клонировать и собрать проект:

    $ git clone https://github.com/mongodb/mongo-php-driver.git
    $ cd mongo-php-driver
    $ git submodule update --init
    $ phpize
    $ ./configure
    $ make all
    $ sudo make install

В системах с несколькими установленными версиями PHP (например, macOS: установка по умолчанию, Homebrew, » XAMPP) у каждой версии PHP будет своя команда phpize и файл (или файлы) php.ini. Кроме того, каждое окружение PHP (например, CLI, web) может использовать отдельные файлы php.ini.

По умолчанию модуль использует встроенные версии библиотек » libbson, » libmongoc и » libmongocrypt и попытается настроить библиотеки автоматически. Библиотеки доступны модулю через передачу параметра `--with-mongodb-system-libs=yes` команде `configure`, если эти библиотеки уже установили в систему.

Полный список параметров команды `configure` получают через запуск команды: configure --help.

При работе со встроенными версиями библиотек libmongoc и libmongocrypt, модуль также попытается выбрать SSL-библиотеку в соответствии с параметром `--with-mongodb-ssl` команды `configure`. Начиная с версии модуля 1.17.0 по умолчанию предпочтение отдаётся библиотеке OpenSSL. Предыдущие версии драйвера на системах с macOS по умолчанию выбирали Secure Transport, а на остальных платформах — OpenSSL.

> Замечание: Потребуется проверить, установили ли пакеты для разработки наподобие `libssl-dev` и пакет » pkg-config, если процесс установки не найдёт SSL-библиотеку. Система часто содержит набор версий библиотеки OpenSSL, когда пакетами на macOS управляют через утилиту Homebrew. Дополнительный путь, по которому программа `pkg-config` будет искать файлы, указывают в переменной среды `PKG_CONFIG_PATH`, чтобы выбрать правильную версию библиотеки OpenSSL.

На последнем, финальном шаге, команда make install выведет путь, по которому собрали модуль mongodb.so. Например, вот так:

    Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Убедитесь, что директива extension_dir файла php.ini указывает на каталог, в котором лежит модуль mongodb.so. Значение директивы проверяют вот так:

    $ php -i | grep extension_dir
      extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                       /usr/lib/php/extensions/debug-non-zts-20220829

Значение директивы extension_dir изменяют в файле php.ini или просто перемещают файл mongodb.so в правильную директорию, если директории отличаются.

И наконец, добавьте следующую строку в файл php.ini для каждого окружения, в котором планируется использовать модуль:

    extension=mongodb.so

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки mongodb
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

Краткое разъяснение конфигурационных директив.

`mongodb.debug` string
  Этот параметр можно использовать для включения или отключения ведения журнала отладки на уровне трассировки в модуле (и libmongoc). Укажите пустую строку, `"0"`, `"off"`, `"no"` или `"false"`, чтобы отключить ведение журнала. Укажите `"stderr"` или `"stdout"`, чтобы вести журнал в `stderr` или `stdout`, соответственно. Укажите `"1"`, `"on"`, `"yes"` или `"true"` для ведения журнала в новый временный файл в системном временном каталоге по умолчанию (т.е. sys_get_temp_dir()). Укажите любую другую строку для ведения журнала в новый временный файл в этом каталоге. Если каталог не может быть использован, вместо него будет использоваться системный временный каталог по умолчанию.

  > Замечание: Обратите внимание, что журнал отладки может содержать конфиденциальную информацию, такую как учётные данные на сервере MongoDB и полные документы, записанные или прочитанные с сервера. Пожалуйста, просмотрите все журналы отладки, прежде чем делиться ими с другими людьми.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`MONGODB_VERSION` (string)
  Номер версии модуля в стиле x.y.z
`MONGODB_STABILITY` (string)
  Уровень стабильности (alpha/beta/stable)

# Обучающие материалы

## Содержание

- Работа библиотеки PHP с драйвером MongoDB (PHPLIB)
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

В данном разделе вы найдёте некоторое количество обучающих материалов по использованию драйвера MongoDB для PHP.

## Работа библиотеки PHP с драйвером MongoDB (PHPLIB)

После первоначальной настройки модуля продолжится объяснение того, как начать работу с соответствующей пользовательской библиотекой для написания первого проекта.

## Установка библиотеки PHP через Composer

Последнее, что необходимо установить перед тем, как начать писать приложение, — это библиотека PHP.

Библиотеку будем устанавливать через пакетный менеджер » Composer. Инструкции по установке Composer на разные платформы опубликованы на его сайте.

Библиотеку устанавливают так:

    $ composer require mongodb/mongodb

Будет выведено что-то вроде:

    ./composer.json has been created
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
      - Installing mongodb/mongodb (1.0.0)
        Downloading: 100%

    Writing lock file
    Generating autoload files

Composer создаст несколько файлов: `composer.json`, `composer.lock` и директорию `vendor`, содержащую саму библиотеку и другие зависимости, которые потребуются в проекте.

## Работа с библиотекой PHP

Кроме управления зависимостями, Composer также содержит автозагрузчик классов для этих зависимостей. Необходимо убедиться, что этот автозагрузчик включён в начало скрипта или в код начальной загрузки приложения:

    <?php
    // Этот путь должен указывать на автозагрузчик Composer
    require 'vendor/autoload.php';

После этого можно использовать библиотеку как описано » в документации.

Если ранее приходилось работать с драйвером MongoDB в других языках, API библиотеки будет выглядеть знакомым. Он содержит класс » Client для соединения с MongoDB, класс » Database для операций уровня базы данных (например, команды, управление коллекциями) и класс » Collection для операций уровня коллекций (например, операций » CRUD, управление индексами).

Например, вот как вставить документ в коллекцию beers базы данных demo:

    <?php
    require 'vendor/autoload.php'; // подключаем автозагрузчик классов Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    echo "Идентификатор вставленного документа '{$result->getInsertedId()}'";
    ?>

Поскольку вставленный документ не содержал поля `_id`, модуль сгенерирует объект MongoDB\BSON\ObjectId, чтобы сервера использовал его как `_id`. Это значение также становится доступно вызывающей стороне через результирующий объект, который возвращается методом `insertOne`.

После вставки можно запросить только что вставленные данные. Для этого вызывают метод `find`, который возвращает итерируемый курсор:

    <?php

    require 'vendor/autoload.php'; // Подключаем автозагрузчик классов Composer

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->find(['name' => 'Hinterland', 'brewery' => 'BrewDog']);

    foreach ($result as $entry) {
        echo $entry['_id'], ': ', $entry['name'], "\n";
    }

    ?>

Хотя примеры не всегда добавляют очевидности, но BSON-документы и BSON-массивы по умолчанию не сериализуются как специальные классы в библиотеке. Эти классы расширяют класс ArrayObject для удобства и реализуют интерфейсы модуля MongoDB\BSON\Serializable и MongoDB\BSON\Unserializable, чтобы гарантировать, что значения сохраняют тип при сериализации обратно в BSON. Это помогает избежать предостережения в устаревшем модуле `mongo`, в котором массивы могли превращаться в документы и наоборот. Дополнительную информацию о преобразовании значений между PHP и BSON даёт спецификация Сохранение данных.

## Мониторинг производительности приложения (Application Performance Monitoring, или APM)

Модуль содержит API-интерфейс подписчика события, который разрешает приложениям отслеживать команды и внутреннюю активность, которая относится к » Спецификации обнаружения и мониторинга серверов. Это руководство продемонстрирует мониторинг команд через интерфейс MongoDB\Driver\Monitoring\CommandSubscriber.

Интерфейс MongoDB\Driver\Monitoring\CommandSubscriber определяет три метода: `commandStarted`, `commandSucceeded` и `commandFailed`. Каждый из них принимает один параметр `event` класса, соответствующего нужному событию. К примеру, `commandSucceeded` принимает аргумент `$event` класса MongoDB\Driver\Monitoring\CommandSucceededEvent.

Руководство реализует подписчика, который создаст список профилировок каждого запроса и среднего времени, которое заняли запросы.

## Класс-подписчик Scaffolding

Начнём с шаблона для подписчика:

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void {}

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void {}

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void {}
    }

    ?>

## Регистрация подписчика

Как только объект подписчика создали, подписчика необходимо зарегистрировать в системе мониторинга модуля. Глобально подписчика регистрируют методом MongoDB\Driver\Monitoring\addSubscriber(), а для конкретного объекта класса Manager — методом MongoDB\Driver\Manager::addSubscriber().

    <?php

    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    ?>

## Реализуем логику

Теперь займёмся реализацией логики класа подписчика. Для сопоставления двух событий, относящихся к успешно выполненной команды (commandStarted and commandSucceeded), каждый объект события предоставляет поле `requestId`.

Для записи среднего времени выполнения запроса мы начнём с отслеживания команды `find` в событии commandStarted. Мы будем добавлять элемент в массив `pendingCommands` с индексом соответствующим `requestId` и значением, соответствующим запросу.

Когда мы получим соответствующее событие commandSucceeded с соответствующим `requestId`, мы добавим время выполнения (из `durationMicros`) к общему времени и увеличим счётчик операций.

Если мы получим событие commandFailed, мы просто удалим соответствующую запись из `pendingCommands`.

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        private $pendingCommands = [];
        private $queryShapeStats = [];

        /* Создаёт форму запроса из аргумента фильтра. Учитываются
         * только поля верхнего уровня. */
        private function createQueryShape(array $filter)
        {
            return json_encode(array_keys($filter));
        }

        public function commandStarted(\MongoDB\Driver\Monitoring\CommandStartedEvent $event): void
        {
            if ('find' === $event->getCommandName()) {
                $queryShape = $this->createQueryShape((array) $event->getCommand()->filter);
                $this->pendingCommands[$event->getRequestId()] = $queryShape;
            }
        }

        public function commandSucceeded(\MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void
        {
            $requestId = $event->getRequestId();
            if (array_key_exists($requestId, $this->pendingCommands)) {
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
                unset($this->pendingCommands[$requestId]);
            }
        }

        public function commandFailed(\MongoDB\Driver\Monitoring\CommandFailedEvent $event): void
        {
            if (array_key_exists($event->getRequestId(), $this->pendingCommands)) {
                unset($this->pendingCommands[$event->getRequestId()]);
            }
        }

        public function __destruct()
        {
            foreach ($this->queryShapeStats as $shape => $stats) {
                echo "Shape: ", $shape, " (", $stats['count'], ")\n  ",
                $stats['duration'] / $stats['count'], "µs\n\n";
            }
        }
    }

    $m = new \MongoDB\Driver\Manager('mongodb://localhost:27016');

    /* Добавляем подписчика */
    \MongoDB\Driver\Monitoring\addSubscriber(new QueryTimeCollector());

    /* Запускаем пачку запросов */
    $query = new \MongoDB\Driver\Query([
        'region_slug' => 'scotland-highlands', 'age' => ['$gte' => 20]
    ]);
    $cursor = $m->executeQuery('dramio.whisky', $query);

    $query = new \MongoDB\Driver\Query([
        'region_slug' => 'scotland-lowlands', 'age' => ['$gte' => 15]
    ]);
    $cursor = $m->executeQuery('dramio.whisky', $query);

    $query = new \MongoDB\Driver\Query(['region_slug' => 'scotland-lowlands']);
    $cursor = $m->executeQuery('dramio.whisky', $query);

    ?>

# Обзор архитектуры драйвера и её особенностей

## Содержание

- Архитектура
- Соединения
- Сохранение данных

## Обзор архитектуры

Раздел объясняет, как разные части PHP-драйвера сочетаются друг с другом, от базовых системных библиотек, через PHP-модули и до PHP-библиотек на самом верху.

Наверху стека расположена » библиотека PHP, которая распространяется в виде » пакета Composer. Эта библиотека предоставит API, согласованный с другими » драйверами MongoDB, и реализует междрайверные » спецификации. Хотя модуль можно использовать напрямую, библиотека даёт минимальные накладные расходы и должна быть общей зависимостью для большей части приложений, построенных с MongoDB.

На уровень ниже библиотеки располагается PHP-модуль, который распространяется через репозиторий » PECL. Модуль образует связующую прослойку между PHP и системными библиотеками (» libmongoc, » libbson и » libmongocrypt). Этот публичный API предлагает только самую базовую функциональность:

- Управление соединением
- BSON кодирование и декодирование
- Сериализация документа объекта (для поддержки библиотек ODM)
- Выполнение команд, запросы и запись операций
- Обработка курсоров для команд и результатов запроса

Исходный код драйвера и проекты JIRA
Проект | GitHub | JIRA
--- | --- | ---
PHP библиотека | » mongodb/mongo-php-library | » PHPLIB
PHP-модуль | » mongodb/mongo-php-driver | » PHPC

## Обработка и сохранение соединения

> Замечание: На платформах Unix модуль чувствителен к сценариям, которые используют системный вызов fork() без последующего вызова exec(). Пользователям не рекомендуется переиспользовать экземпляр класса MongoDB\Driver\Manager в дочернем процессе. child process.

## Сохранение соединения и топологии (версия PHP начиная с 1.2.0)

Каждая версия модуля начиная с 1.2.0 сохраняет клиентский объект » libmongoc в рабочем процессе PHP, что позволяет ему повторно использовать соединения с базой данных, состояния аутентификации и информацию о топологии в нескольких запросах.

Когда вызывается метод MongoDB\Driver\Manager::__construct(), из его аргументов создаётся хеш (т. е. строка URI и параметры массива). Модуль попытается найти ранее сохранённый клиентский объект » libmongoc для этого хеша. Если существующий клиент не может быть найден для хеша, будет создан новый клиент и сохранён для будущего использования. Это поведение можно выключить через параметр драйвера `"disableClientPersistence"`.

Каждый клиент содержит свои собственные подключения к базе данных и представление топологии сервера (например, автономный, набор реплик, кластер сегментов). Сохраняя клиент между PHP-запросами, модуль может переиспользовать установленные подключения к базе данных и устранять необходимость » обнаружения топологии сервера при каждом запросе.

Рассмотрим следующий пример:

    <?php

    $managers = [
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
        new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
    ];

    foreach ($managers as $manager) {
        $manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
    }

    ?>

Первые два объекта Manager будут использовать один и тот же клиент » libmongoc, поскольку их аргументы конструктора идентичны. Третий и четвёртый объекты будут использовать каждый свой клиент. Всего будет создано три клиента, и процесс PHP, выполняющий этот скрипт, откроет два соединения с адресом `127.0.0.1` и одно соединение с каждым из адресов: `rs1.example.com` и `rs2.example.com`. Если драйвер обнаруживает дополнительных членов набора реплик после выполнения команд `hello`, он также открывает дополнительные подключения к этим серверам.

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

## Сохранение сокетов (версии PHP до 1.2.0)

Версии модуля до 1.2.0 используют API-интерфейс PHP-потоков для подключений к базам данных через внутренний API-интерфейс библиотеки » libmongoc, чтобы назначить пользовательские обработчики для связи с сокетами; однако новый клиент libmongoc создаётся для каждого менеджера MongoDB\Driver\Manager. В результате модуль сохраняет отдельные соединения с базой данных, но не информацию о состоянии аутентификации или топологии. Поэтому модулю приходится выдавать команды в начале каждого запроса, чтобы проверить подлинность и » обнаружить топологию сервера.

Соединения с базой данных сохраняются как хеш хоста, порта и строки URI-идентификатора сервера, которую передавали в конструктор менеджера MongoDB\Driver\Manager. Параметры массива конструктора не включаются в этот хеш.

> Замечание: Версии модуля >= 1.1.8 and < 1.2.0 не сохраняют сокеты для SSL-соединений. Смотрите » PHPC-720 для получения дополнительной информации.

Несмотря на недостатки, которые связаны с сохранением SSL-соединений и информацией о топологии, эта версия модуля поддерживает все параметры SSL-контекста, поскольку использует API-интерфейс потоков PHP.

## Сериализация и десериализация PHP-переменных в модуле MongoDB

В документе обсуждается, как составные структуры наподобие документов, массивов и объектов преобразовываются между значениями формата BSON и PHP-значениями.

## Сериализация в BSON

## Массивы

Если массив представляет собой упакованный массив — то есть пустой массив или ключи начинаются с 0 и идут последовательно без пробелов: BSON-массив.

Если массив не упакован — то есть содержит ассоциативные (строковые) ключи, ключи не начинаются с 0 или содержат пробелы: BSON-объект

Документ верхнего уровня (корневой) всегда сериализуется как BSON-документ.

## Примеры

Эти PHP-массивы сериализуются как BSON-массив:

    [8, 5, 2, 3] => [8, 5, 2, 3]
    [0 => 4, 1 => 9] => [4, 9]

Эти PHP-массивы сериализуются как BSON-документ:

    [0 => 1, 2 => 8, 3 => 12] => {"0": 1, "2": 8, "3": 12}
    ["foo" => 42] => {"foo": 42}
    [1 => 9, 0 => 10] => {"1": 9, "0": 10}

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

## Объекты

Если объект принадлежит типу stdClass, он сериализуется как BSON-документ.

Если объект — поддерживаемый класс, который реализует интерфейс MongoDB\BSON\Type, используется логика сериализации BSON для этого конкретного типа. Экземпляры с типом MongoDB\BSON\Type (исключая тип MongoDB\BSON\Serializable) можно сериализовать только как значение поля документа. Попытка сериализовать такой объект как корневой документ выбросит исключение MongoDB\Driver\Exception\UnexpectedValueException.

Если объект принадлежит неизвестному классу, который реализует интерфейс MongoDB\BSON\Type, выбрасывается исключение MongoDB\Driver\Exception\UnexpectedValueException.

Если объект принадлежит какому-либо другому классу без реализации какого-либо специального интерфейса, он сериализуется как BSON-документ. Остаются только открытые (public) свойства, а защищённые (protected) и закрытые (private) свойства игнорируются.

Если объект принадлежит к классу, который реализует интерфейс MongoDB\BSON\Serializable, вызывают метод MongoDB\BSON\Serializable::bsonSerialize() и сериализуют массив или stdClass, которые возвращает метод, как BSON-документ или как BSON-массив. Тип BSON определят следующие условия:

1. Корневые документы требуется сериализовать как BSON-документ.
2. Объекты с типом MongoDB\BSON\Persistable требуется сериализовать как BSON-документы.
3. Если метод MongoDB\BSON\Serializable::bsonSerialize() возвращает упакованный массив, его сериализуют как BSON-массив.
4. Если метод MongoDB\BSON\Serializable::bsonSerialize() возвращает неупакованный массив или объект stdClass, его сериализуют как BSON-документ.
5. Если метод MongoDB\BSON\Serializable::bsonSerialize() не вернул массив или объект stdClass, выбрасывается исключение MongoDB\Driver\Exception\UnexpectedValueException.

Если объект принадлежит классу, который реализует интерфейс MongoDB\BSON\Persistable (что подразумевает реализацию метода MongoDB\BSON\Serializable), свойства остаются по аналогии с предыдущими абзацами, но также добавляется дополнительное свойство __pclass в виде Binary-значения с подтипом `0x80` и данными, которые содержат полное имя класса объекта, который сериализуется.

Свойство __pclass добавляется в массив или объект, который возвращает метод MongoDB\BSON\Serializable::bsonSerialize(), что означает, что оно перезапишет любой ключ или свойство __pclass в значении, которое возвращает метод MongoDB\BSON\Serializable::bsonSerialize(). Если требуется избежать такого поведения и установить собственное значение __pclass, вместо реализации интерфейса MongoDB\BSON\Persistable следует напрямую реализовать интерфейс MongoDB\BSON\Serializable.

## Примеры

    <?php

    class stdClass
    {
        public $foo = 42;
    } // => {"foo": 42}

    class MyClass
    {
        public $foo = 42;
        protected $prot = 'вино';
        private $fpr = 'сыр';
    } // => {"foo": 42}

    class AnotherClass1 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;
        protected $prot = 'вино';
        private $fpr = 'сыр';

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "вино"}

    class AnotherClass2 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;

        public function bsonSerialize(): self
        {
            return $this;
        }
    } // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

    class AnotherClass3 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    /**
     * Вложенные сериализуемые классы
     */

    class AnotherClass4 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "2": "bar"}

    class ContainerClass1 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass4();
        }

        function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "2": "bar"}}

    class AnotherClass5 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return array_values($this->elements);
        }
    } // => {"0": "foo", "1": "bar"} as a root class
      //    ["foo", "bar"] as a nested value

    class ContainerClass2 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass5();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": ["foo", "bar"]}

    class AnotherClass6 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        function bsonSerialize(): object
        {
            return (object) $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    class ContainerClass3 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass6();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "1": "bar"}}

    class UpperClass implements MongoDB\BSON\Persistable
    {
        public $foo = 42;
        protected $prot = 'вино';
        private $fpr = 'сыр';

        private $data;

        public function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "вино", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

    ?>

## Десериализация из BSON

Внимание

Документы BSON технически могут содержать повторяющиеся ключи, поскольку документы хранятся в виде списка пар ключ-значение; однако приложениям следует воздерживаться от создания документов с дубликатами ключей, поскольку поведение сервера и драйвера может быть неопределённым. Поскольку объекты и массивы PHP не могут иметь повторяющихся ключей, данные также могут быть потеряны при декодировании документа BSON с повторяющимися ключами.

Устаревший модуль `mongo` десериализовывал BSON-документы и BSON-массивы в PHP-массивы. Хотя с PHP-массивами удобно работать, такое поведение было проблематичным, поскольку разные BSON-типы могли десериализоваться до одного и того же PHP-значения (например, `{"0": "foo"}` и `["foo"]`), что делало невозможным определение оригинального BSON-типа. По умолчанию модуль `mongodb` решает эту проблему и гарантирует, что BSON-массивы преобразуются в PHP-массивы, а BSON-документы в PHP-объекты.

Для составных типов существует три типа данных:

root
  относится только к BSON-документу верхнего уровня
document
  относится только к встроенным BSON-документам
array
  относится к BSON-массивам

Помимо трёх групповых типов, также можно настроить определённые поля в документе для сопоставления с типами данных, как указывает следующий фрагмент кода. В качестве примера, следующая карта типов позволяет сопоставить каждый встроенный документ в массиве `«addresses»` с классом Address, а каждое поле `«city»` в этих документах с встроенным адресом с классом City:

    [
        'fieldPaths' => [
            'addresses.$' => 'MyProject\Address',
            'addresses.$.city' => 'MyProject\City',
        ],
    ]

Каждый из этих трёх типов данных, а также сопоставления конкретных полей можно сопоставить с различными типами PHP. Возможные значения сопоставления:

не указано или NULL (по умолчанию)

  - BSON-массив будет десериализован как PHP-массив (array).
  - BSON-документ (корневой или встроенный) без свойства __pclass [1]

    Свойство __pclass считается существующим, только если существует свойство с таким именем, и оно представляет собой Binary-значение, а подтип Binary значения равен 0x80. Если какое-либо из этих трёх условий не выполняется, свойство __pclass не существует и должно рассматриваться как любое другое обычное свойство.

    становится PHP-объектом stdClass, причём каждый ключ BSON-документа устанавливается как открытое свойство объекта stdClass.
  - BSON-документ (корневой или встроенный) со свойством __pclass [1] становится PHP-объектом имени класса, как это определяет свойство __pclass. Если именованный класс реализует интерфейс MMongoDB\BSON\Persistable, то свойства BSON-документа, включая свойство __pclass, отправляются как ассоциативный массив в метод MongoDB\BSON\Unserializable::bsonUnserialize(), чтобы инициализировать свойства объекта. Если именованный класс не существует или не реализует интерфейс MongoDB\BSON\Persistable, будет использоваться объект stdClass, и каждый ключ BSON-документа (включая свойство __pclass) будет установлен как открытое свойство объекта stdClass. Функциональность свойства __pclass зависит от того, представляет ли собой свойство часть извлечённого документа БД MongoDB. Если при запросе документов используется проекция, необходимо включить в проекцию поле __pclass, чтобы эта функциональность работала.
`«array»`
  Превращает BSON-массив или BSON-документ в PHP-массив. Специальной обработки свойства __pclass [1] не будет, но его можно установить как элемент в возвращаемом массиве, если он содержался в BSON-документе.
`«object»` или `«stdClass»`
  Превращает BSON-массив или BSON-документ в объект stdClass. Специальной обработки свойства __pclass [1] не будет, но его можно установить как открытое свойство в возвращаемом объекте, если оно присутствовало в BSON-документе.
`«bson»`
  Превращает BSON-массив в объект MongoDB\BSON\PackedArray, а BSON-документ в объект MongoDB\BSON\Document, независимо от того, есть ли у BSON-документа свойство __pclass [1].

  > Замечание: Значение `bson` доступно только для трёх корневых типов, но не в отображениях для конкретных полей.

любая другая строка
  Определяет имя класса, который должен десериализовать BSON-массив или BSON-объект. Для BSON-объектов, которые содержат свойства __pclass, этот класс будет приоритетным. Если именованный класс не существует, не представляет собой конкретный класс (то есть это абстрактный класс или интерфейс) или не реализует интерфейс MongoDB\BSON\Unserializable, выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException. Если BSON-объект содержит свойство __pclass и этот класс существует и реализует интерфейс MongoDB\BSON\Persistable, он заменит класс, представленный в карте типов. Свойства BSON-документа, включая свойство __pclass, если оно существует, отправляются как ассоциативный массив в метод MongoDB\BSON\Unserializable::bsonUnserialize(), чтобы инициализировать свойства объекта.

## TypeMaps

Функции настройки TypeMaps можно установить методом MongoDB\Driver\Cursor::setTypeMap() для объекта MongoDB\Driver\Cursor или аргумента `$typeMap` в методах MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP() и MongoDB\BSON\PackedArray::toPHP(). Каждый из трёх классов (root, document, и array) можно задать индивидуально, в дополнение к типам полей.

Если значение на карте равно NULL, это означает то же, что и значение по умолчанию для этого элемента.

## Примеры

В этих примерах используются следующие классы:

MyClass
  не реализует интерфейсы
YourClass
  реализует интерфейс MongoDB\BSON\Unserializable
OurClass
  реализует интерфейс MongoDB\BSON\Persistable
TheirClass
  расширяет класс OurClass

Метод MongoDB\BSON\Unserializable::bsonUnserialize() классов YourClass, OurClass, OurClass выполняет итерацию по массиву и устанавливает свойства без изменений. Метод также устанавливает для свойства `$unserialized` значение `true`:

    <?php

    function bsonUnserialize(array $map)
    {
        foreach ($map as $k => $value) {
            $this->$k = $value;
        }
        $this->unserialized = true;
    }

    ?>

    /* typemap: [] (все значения по умолчанию) */
    {"foo": "yes", "bar" : false}
      -> stdClass {$foo => 'yes', $bar => false}

    {"foo": "no", "array" : [5, 6]}
      -> stdClass {$foo => 'no', $array => [5, 6]}

    {"foo": "no", "obj" : {"embedded" : 3.14}}
      -> stdClass {$foo => 'no', $obj => stdClass {$embedded => 3.14}}

    {"foo": "yes", "__pclass": "MyClass"}
      -> stdClass {$foo => 'yes', $__pclass => 'MyClass'}

    {"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "MyClass"}}
      -> stdClass {$foo => 'yes', $__pclass => Binary(0x80, 'MyClass')}

    {"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "YourClass")}
      -> stdClass {$foo => 'yes', $__pclass => Binary(0x80, 'YourClass')}

    {"foo": "yes", "__pclass": {"$type" : "80", "$binary" : "OurClass")}
      -> OurClass {$foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true}

    {"foo": "yes", "__pclass": {"$type" : "44", "$binary" : "YourClass")}
      -> stdClass {$foo => 'yes', $__pclass => Binary(0x44, 'YourClass')}

    /* typemap: ["root" => "MissingClass"] */
    {"foo": "yes"}
      -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

    /* typemap: ["root" => "MyClass"] */
    {"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MyClass"}}
      -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

    /* typemap: ["root" => "MongoDB\BSON\Unserializable"] */
    {"foo": "yes"}
      -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

    /* typemap: ["root" => "YourClass"] */
    {"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MongoDB\BSON\Unserializable"}}
      -> YourClass {$foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true}

    /* typemap: ["root" => "YourClass"] */
    {"foo": "yes", "__pclass" : {"$type": "80", "$binary": "MyClass"}}
      -> YourClass {$foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true}

    /* typemap: ["root" => "YourClass"] */
    {"foo": "yes", "__pclass" : {"$type": "80", "$binary": "OurClass"}}
      -> OurClass {$foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true}

    /* typemap: ["root" => "YourClass"] */
    {"foo": "yes", "__pclass" : {"$type": "80", "$binary": "TheirClass"}}
      -> TheirClass {$foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true}

    /* typemap: ["root" => "OurClass"] */
    { foo: "yes", "__pclass" : {"$type": "80", "$binary": "TheirClass"}}
      -> TheirClass {$foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true}

    /* typemap: ['root' => 'YourClass'] */
    {foo: "yes", "__pclass": {"$type": "80", "$binary": "YourClass"}}
      -> YourClass {$foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true}

    /* typemap: ['root' => 'array', 'document' => 'array'] */
    {"foo": "yes", "bar": false}
      -> ["foo" => "yes", "bar" => false]

    {"foo": "no", "array": [5, 6]}
      -> ["foo" => "no", "array" => [5, 6]]

    {"foo": "no", "obj": {"embedded": 3.14}}
      -> ["foo" => "no", "obj" => ["embedded => 3.14]]

    {"foo": "yes", "__pclass": "MyClass"}
      -> ["foo" => "yes", "__pclass" => "MyClass"]

    {"foo": "yes", "__pclass": {"$type": "80", "$binary": "MyClass"}}
      -> ["foo" => "yes", "__pclass" => Binary(0x80, "MyClass")]

    {"foo": "yes", "__pclass": {"$type": "80", "$binary": "OurClass"}}
      -> ["foo" => "yes", "__pclass" => Binary(0x80, "OurClass")]

    /* typemap: ['root' => 'object', 'document' => 'object'] */
    {"foo": "yes", "__pclass": {"$type": "80", "$binary": "MyClass"}}
      -> stdClass {$foo => "yes", "__pclass" => Binary(0x80, "MyClass")}

# Безопасность

## Содержание

- Атака с помощью инъекций в запросе
- Атака с помощью инъекций в скриптах

## Атака с помощью инъекций в запросе

Если вы передаёте параметры `$_GET` (или `$_POST`) своим запросам, убедитесь, что они сначала приводятся к строкам. Пользователи могут вставлять ассоциативные массивы в запросы GET и POST, которые затем могут стать нежелательными $-запросами.

Довольно безобидный пример. Предположим, вы ищете информацию о пользователе по запросу http://www.example.com?username=bob. Ваше приложение создаёт запрос `$q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ])`.

Кто-то может подорвать это, получив http://www.example.com?username[$ne]=foo, который PHP волшебным образом превратит в ассоциативный массив, превратив ваш запрос в `$q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] )`, который вернёт всех пользователей, не имеющих имени "foo" (вероятно, всех ваших пользователей).

От этой атаки достаточно легко защититься: убедитесь, что параметры $_GET и $_POST соответствуют ожидаемому типу, прежде чем отправлять их в базу данных. PHP имеет функцию filter_var(), чтобы помочь с этим.

Обратите внимание, что этот тип атаки может использоваться с любым взаимодействием с базой данных, которое находит документ, включая команды update, upserts, delete и findAndModify.

Смотрите » основную документацию для получения дополнительной информации о проблемах SQL инъекций в MongoDB.

## Атака с помощью инъекций в скриптах

Если вы используете JavaScript, убедитесь, что все переменные, которые пересекают границу PHP-JavaScript, передаются в поле `scope` MongoDB\BSON\Javascript, а не интерполируются в строку JavaScript. Это может возникнуть при использовании предложений `$where` в запросах, командах mapReduce и group, а также в любое другое время, когда вы можете передать JavaScript в базу данных.

Например, предположим, что у нас есть некоторый JavaScript, чтобы приветствовать пользователя в журналах базы данных. Мы могли бы сделать:

    <?php
    $m = new MongoDB\Driver\Manager;

    // Не делайте так!!!
    $username = $_GET['field'];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Привет, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Однако что, если злоумышленник передаст какой-то JavaScript?

    <?php
    $m = new MongoDB\Driver\Manager;

    // Не делайте так!!!
    $username = $_GET['field'];
    // $username is set to "'); db.users.drop(); print('"

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Привет, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Теперь MongoDB выполнит строку JavaScript `"print('Привет, '); db.users.drop(); print('!');"`. Эту атаку легко избежать: используйте `args` для передачи переменных из PHP в JavaScript:

    <?php
    $m = new MongoDB\Driver\Manager;

    $_GET['field'] = 'derick';
    $args = [ $_GET['field'] ];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "function greet(username) { print('Привет, ' + username + '!'); }",
        'args' => $args,
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Это добавляет аргумент в область JavaScript, которая используется в качестве аргумента для функции `greet`. Теперь, если кто-то попытается отправить вредоносный код, MongoDB безвредно напечатает `Привет, '); db.dropDatabase(); print('!`.

Использование аргументов помогает предотвратить выполнение вредоносного ввода базой данных. Тем не менее, вы должны убедиться, что ваш код не перевернётся и всё равно выполнит ввод! Лучше всего избегать выполнения любого JavaScript на сервере.

Настоятельно рекомендуется избегать предложения » $where clause с запросами, так как это существенно влияет на производительность. По возможности используйте либо обычные операторы запросов, либо » Aggregation Framework.

В качестве альтернативы » MapReduce, использующей JavaScript, рассмотрите возможность использования » Aggregation Framework. В отличие от Map/Reduce, он использует идиоматический язык для построения запросов, без необходимости писать и использовать более медленный подход JavaScript, который требуется для Map/Reduce.

Команда » eval устарела с MongoDB 3.0, и её также следует избегать.

# Классы модуля MongoDB

## Содержание

- MongoDB\Driver\Manager
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# Класс MongoDB\Driver\Manager

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\Manager — основная точка входа в модуль. Класс отвечает за поддержание соединений с БД MongoDB (будь то автономный сервер, набор реплик или распределённый кластер).

При инициализации класса Manager не происходит подключение к серверу MongoDB. Это означает, что экземпляр класса MongoDB\Driver\Manager всегда можно создать, даже если серверы MongoDB не работают.

Любая запись или запрос будут выбрасывать исключение соединения, поскольку соединения создаются «лениво» (по требованию). Сервер MongoDB также может быть недоступен в течение всего времени выполнения скрипта. Поэтому важно, чтобы каждое действие с объектом класса Manager оборачивались в блок try/catch.

## Обзор класса

final class MongoDB\Driver\Manager {
/* Методы */
final public function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function startSession(?array `$options` = `null`): MongoDB\Driver\Session
}

## Примеры

Пример #1 Простой пример использования MongoDB\Driver\Manager::__construct()

Выводит различную информацию о MongoDB\Driver\Manager с помощью функции var_dump(). Это может быть полезно для отладки, чтобы посмотреть как драйвер видит настройку MongoDB и какие опции используются.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager);

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\Manager)#1 (2) {
      ["uri"]=>
      string(26) "mongodb://127.0.0.1:27017/"
      ["cluster"]=>
      array(0) {
      }
    }

# MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Регистрирует подписчика на событие мониторинга в данном объекте Manager

### Описание

final public function MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Регистрирует подписчика на событие мониторинга в данном объекте Manager. Подписчик будет уведомлен обо всех событиях для этого объекта Manager.

> Замечание: Если `subscriber` уже зарегистрирован в данном объекте Manager, эта функция будет недоступна. Если `subscriber` также зарегистрирован глобально, он всё равно будет получать уведомление только один раз о каждом событии для этого объекта Manager.

### Список параметров

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Подписчик событий мониторинга, который должен быть зарегистрирован в данном объекте Manager.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если `subscriber` является MongoDB\Driver\Monitoring\LogSubscriber, поскольку регистраторы могут быть зарегистрированы только глобально.

### Смотрите также

- MongoDB\Driver\Manager::removeSubscriber() - Отменяет регистрацию подписчика на событие мониторинга в данном объекте Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Создаёт нового MongoDB-менеджера

### Описание

final public function MongoDB\Driver\Manager::__construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)

Метод создаёт новый объект MongoDB\Driver\Manager с заданными параметрами.

> Замечание: В » спецификации по обнаружению и мониторингу сервера, этот конструктор не выполняет ввода-вывода. Соединения будут инициализироваться по требованию, когда выполняется первая операция.

> Замечание: При передаче любых URI-опций, которые связаны с SSL или TLS, через строку подключения или параметр `uriOptions`, модуль неявно включает TLS при соединениях. Чтобы предотвратить это, либо явно отключают опцию `tls`, либо не передают никаких TLS-опций.

> Замечание: На платформах Unix модуль чувствителен к сценариям, которые используют системный вызов fork() без последующего вызова exec(). Пользователям не рекомендуется переиспользовать экземпляр класса MongoDB\Driver\Manager в дочернем процессе. child process.

### Список параметров

`uri`

  URI-адрес подключения » mongodb://:

      mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

  Параметр примет значение по умолчанию `"mongodb://127.0.0.1:27017"`, если аргумент не передали.

  Подробнее о поддерживаемых URI-параметрах рассказывает раздел » Параметры строки подключения в руководстве MongoDB. » Параметры пула подключения не поддерживаются, поскольку модуль не реализует пулы подключений.

  `uri` — это URL, поэтому любые специальные символы в его компонентах должны закодированы в соответствии » RFC 3986. Это особенно актуально для имени пользователя и пароля, которые часто могут содержать специальные символы, такие как `@`, `:`, или `%`. При подключении через доменный сокет Unix, путь сокета может содержать специальные символы, например слеши, которые необходимо закодировать. Функция rawurlencode() может использоваться для кодирования составных частей URI-адреса.

  Компонент `defaultAuthDb` может использоваться для указания имени базы данных, связанной с учётными данными пользователя; однако параметр URI `authSource` будет иметь приоритет, если он указан. Если ни `defaultAuthDb`, ни `authSource` не указаны, база данных `admin` будет использоваться по умолчанию. Компонент `defaultAuthDb` не имеет смысла при отсутствии учётных данных пользователя.

`uriOptions`

  Дополнительные » параметры строки подключения, которые будут перезаписывать любые параметры с тем же именем в параметре `uri`.

  uriOptions
  Название опции | Тип | Описание
  --- | --- | ---
  appname | string | В MongoDB 3.4+ появилась возможность добавлять аннотации к соединениям с метаданными, предоставляемыми подключающимся клиентом. Эти метаданные включаются в журналы логирования сервера при установлении соединения, а также записываются в журналы медленных запросов, если включено профилирование базы данных. Эта опция может использоваться для указания имени приложения, которое будет включено в метаданные. Значение не может превышать 128 символов.
  authMechanism | string | Механизм аутентификации, который MongoDB будет использовать для аутентификации соединения. Для просмотра дополнительных сведений и списка поддерживаемых значений, смотрите раздел » Параметры аутентификации в руководстве MongoDB.
  authMechanismProperties | array | Свойства для выбранного механизма аутентификации. Для просмотра дополнительных сведений и списка поддерживаемых значений, смотрите раздел » Спецификация аутентификации драйвера. Замечание: Если не указана в строке URI-адреса, эта опция представляется в виде массива пар ключ-значение. Ключи и значения в этом массиве должны быть строками.
  authSource | string | Имя базы данных, связанное с учётными данными пользователя. По умолчанию используется компонент базы данных из URI-адреса соединения или база данных `admin`, если оба не указаны. Для механизмов аутентификации, которые делегируют хранение учётных данных другим службам (например, GSSAPI), значение должно быть `"$external"`.
  compressors | string | Приоритетный список разделённых запятыми компрессоров, которые требуется использовать клиенту. Сообщения сжаты, только если клиент и сервер совместно используют любые компрессоры, а компрессор, используемый в каждом направлении, будет зависеть от индивидуальной конфигурации сервера или драйвера. Дополнительную информацию даёт страница » Спецификация компрессии драйвера.
  connectTimeoutMS | int | Время ожидания в миллисекундах при попытке соединения. Значение по умолчанию равно 10 000 миллисекунд.
  directConnection | bool | Параметр управляет поведением при обнаружении набора реплик, если в строке подключения указали только один хост. По умолчанию предоставление одного члена в строке подключения устанавливается прямое подключение или обнаруживается дополнительное количество членов в зависимости от того, указали ли URI-параметр `"replicaSet"`. Укажите `false` для принудительного обнаружения, если опустили параметр `"replicaSet"`, или укажите `true`, чтобы форсировать прямое соединение, если параметр `"replicaSet"` указали.
  enableOverloadRetargeting | bool | Если установлено в `true`, форсирует выбор сервера после ошибки `SystemOverloadedError`. По умолчанию `false`.
  heartbeatFrequencyMS | int | Задаёт интервал в миллисекундах между проверками драйвера топологии MongoDB, которые отсчитываются с конца предыдущей проверки до начала следующей. Значение по умолчанию равно 60 000 миллисекунд. Согласно » Спецификации по обнаружению и мониторингу сервера, нельзя указывать значение меньше 500 миллисекунд.
  journal | bool | Соответствует параметру гарантий записи `journal`. Если `true`, для записи будет требоваться подтверждение от MongoDB, что операция была записана в журнал. Подробнее смотрите MongoDB\Driver\WriteConcern.
  loadBalanced | bool | Указывает, подключается ли драйвер к кластеру MongoDB через балансировщик нагрузки. Если `true`, драйвер может подключаться только к одному узлу (указанному либо строкой подключения, либо поиском SRV), параметр URI `"directConnection"` не может быть `true` и опция URI `"replicaSet"` должна быть опущена. По умолчанию `false`.
  localThresholdMS | int | Размер в миллисекундах окна задержки для выбора среди нескольких подходящих экземпляров MongoDB при разрешении предпочтения чтения. По умолчанию — 15 миллисекунд.
  maxAdaptiveRetries | int | Опция используется для изменения максимального числа повторов при возникновении ошибки `SystemOverloadedError`. Значение должно быть положительным целым; по умолчанию `2`.
  maxStalenessSeconds | int | Соответствует параметру предпочтения чтения `"maxStalenessSeconds"`. Указывает в секундах, насколько устаревшим может быть вторичный узел в наборе реплик, прежде чем клиент перестанет его использовать для операций чтения. По умолчанию не задано максимальное отставание репликации (staleness) и клиенты не будут учитывать отставание вторичного узла при выборе направления операции чтения. Подробнее об этом рассказано в описании класса MongoDB\Driver\ReadPreference. Если указана, максимальное отставание должно быть 32-битным целым числом, большим или равным `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` (т. е. 90 секунд).
  password | string | Пароль для аутентификации пользователя. Эта опция полезна, если пароль содержит специальные символы, которые в противном случае должны были закодированы для URI-адреса подключения.
  readConcernLevel | string | Соответствует параметру гарантий чтения `level` Определяет уровень изоляции чтения. Подробнее смотрите MongoDB\Driver\ReadConcern.
  readPreference | string | Соответствует параметру предпочтениям чтения `mode` По умолчанию — `"primary"`. Подробнее смотрите MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Соответствует параметру предпочтениям чтения `tagSets`. Наборы тегов позволяют настраивать операции чтения для определённых членов набора реплики. Подробнее смотрите MongoDB\Driver\ReadPreference. Замечание: Если в строке URI не указано, этот параметр представляется как как массив, соответствующий формату, ожидаемому MongoDB\Driver\ReadPreference::__construct().
  replicaSet | string | Задаёт имя набора реплики.
  retryReads | bool | Указывает, должен ли драйвер автоматически повторять определённые операции чтения, которые не выполняются из-за временных сетевых ошибок или выборов набора реплик. Требуется MongoDB 3.6+. По умолчанию `true`. Смотрите » Спецификацию по Retryable Reads для получения дополнительной информации.
  retryWrites | bool | Указывает, должен ли драйвер автоматически повторять определённые операции записи, которые не выполняются из-за временных сетевых ошибок или выборов набора реплик. Требуется MongoDB 3.6+. По умолчанию `true`. Смотрите » Retryable Writes в руководстве MongoDB для получения дополнительной информации.
  serverSelectionTimeoutMS | int | Указывает как долго в миллисекунд блокировать выбор сервера перед выбросом исключения. По умолчанию — 30 000 миллисекунд.
  serverSelectionTryOnce | bool | Со значением `true` сообщает драйверу сканировать развёртывание MongoDB только один раз после неудачной попытки выбора сервера, а затем или выбрать сервер, или создать ошибку. Со значением `false` драйвер блокирует выбор и выполняет поиск сервера до истечения времени, которое указали в параметре `"serverSelectionTimeoutMS"`. Значение по умолчанию равно `true`.
  socketCheckIntervalMS | int | Если сокет не использовался в последнее время, драйвер должен проверить с помощью команды `hello`, прежде чем использовать его для любой операции. По умолчанию — 5 000 миллисекунд.
  socketTimeoutMS | int | Время в миллисекундах, чтобы попытаться отправить или получить в сокет до истечения времени. По умолчанию — 300 000 миллисекунд (т. е. 5 минут).
  srvMaxHosts | int | Максимальное количество результатов SRV для случайного выбора при первоначальном заполнении посевного списка или, во время опроса SRV, при добавлении новых узлов к топологии. По умолчанию `0` (т. е. без максимума).
  srvServiceName | string | Имя службы, используемое для поиска SRV в начальном списке DNS seedlist обнаружения и опроса SRV. По умолчанию `"mongodb"`.
  tls | bool | Со значением `true` инициирует соединение с TLS/SSL. Значение по умолчанию равно `false`.
  tlsAllowInvalidCertificates | bool | Указывает драйверу, выдавать ли ошибку, если TLS-сертификат сервера недействителен. Значение по умолчанию равно `false`. Внимание Отключение проверки сертификата создаёт уязвимость.
  tlsAllowInvalidHostnames | bool | Указывает, должен ли драйвер выдавать ошибку при несоответствии имени хоста сервера и имени хоста, указанного в сертификате TLS. По умолчанию `false`. Внимание Отключение проверки сертификата создаёт уязвимость. Разрешение недопустимых имён хоста может привести к атаке типа » "человек посередине" (man-in-the-middle).
  tlsCAFile | string | Путь к файлу с одним или несколькими центрами сертификации, которые следует считать доверенными при установлении соединения TLS. По умолчанию будет использоваться хранилище системных сертификатов.
  tlsCertificateKeyFile | string | Путь к файлу сертификата клиента или файлу закрытого ключа клиента; в случае, если они оба необходимы, файлы должны быть объединены.
  tlsCertificateKeyFilePassword | string | Пароль для расшифровки закрытого ключа клиента (т. е. параметра URI `"tlsCertificateKeyFile"`), который будет использоваться для соединений TLS.
  tlsDisableCertificateRevocationCheck | bool | Если `true`, драйвер не будет пытаться проверить статус отзыва сертификата (например, OCSP, CRL). По умолчанию `false`.
  tlsDisableOCSPEndpointCheck | bool | Если `true`, драйвер не будет пытаться связаться с конечной точкой ответа OCSP, если это необходимо (то есть ответ OCSP не сшивается). По умолчанию `false`.
  tlsInsecure | bool | Ослабьте ограничения TLS в максимально возможной степени. При значении `true` этот параметр имеет тот же эффект, что и указание значения `true` для обоих параметров URI `"tlsAllowInvalidCertificates"` и `"tlsAllowInvalidHostnames"`. По умолчанию `false`. Внимание Отключение проверки сертификата создаёт уязвимость. Разрешение недопустимых имён хоста может привести к атаке типа » "человек посередине" (man-in-the-middle).
  username | string | Имя пользователя для аутентификации. Эта опция полезна, если имя пользователя содержит специальные символы, которые в противном случае должны были быть закодированы в URL для URI-адреса подключения.
  w | int|string | Соответствует параметру гарантий записи `w`. Подробнее смотрите MongoDB\Driver\WriteConcern.
  wTimeoutMS | int|string | Соответствует параметру гарантий записи `wtimeout`. Указывает срок в миллисекундах для гарантии записи. Подробнее смотрите MongoDB\Driver\WriteConcern. Если указан, `wTimeoutMS` должен быть 32-битным целым числом со знаком, большим или равным нулю.
  zlibCompressionLevel | int | Указывает уровень сжатия для использования zlib. Эта опция ничего не делает, если `zlib` не включён в URL опции `"compressors"`. Смотрите » Спецификация компрессии драйвера для получения дополнительной информации.

`driverOptions`

  driverOptions
  Опция | Тип | Описание
  --- | --- | ---
  autoEncryption | array | Предоставляет опции для включения автоматического шифрования на уровне поля на стороне клиента. Список опций описан в таблице ниже. Замечание: Автоматическое шифрование — функция только для Enterprise версии, которая применяется только к операциям над коллекцией. Автоматическое шифрование не поддерживается для операций над базой данных или представлением, а операции, которые не обходятся, приведут к ошибке (смотрите » libmongocrypt: Список разрешений на автоматическое шифрование). Чтобы обойти автоматическое шифрование для всех операций, установите `bypassAutoEncryption` в значение `true`. Автоматическое шифрование требует, чтобы у аутентифицированного пользователя была привилегия » listCollections. Явное шифрование/дешифрование и автоматическая расшифровка — это функция Community версии. Драйвер все ещё может автоматически расшифровывать, если у опции `bypassAutoEncryption` установлено значение `true`.
  ca_dir | string | Путь к корректно захешированному каталогу сертификатов. По умолчанию будет использоваться хранилище системных сертификатов.
  crl_file | string | Путь к файлу списка аннулированных сертификатов.
  disableClientPersistence | bool | Со значением `true` менеджер будет использовать новый клиент библиотеки libmongoc, который не будет сохраняться или использоваться другими объектами Manager. Когда этот объект Manager освободится, его клиент уничтожится, а все соединения закроются. Значение по умолчанию равно `false`. Замечание: Отключение сохранения клиента обычно не рекомендуется.
  driver | array | Позволяет библиотеке более высокого уровня добавлять свои метаданные к рукопожатию сервера. По умолчанию модуль отправляет своё имя, версию и платформу (то есть PHP-версию) при рукопожатии. Для ключей `name`, `version` и `platform` этого массива можно указать строки, которые метод добавит к полям документа рукопожатия. Замечание: Информация о рукопожатии ограничена 512 байтами. Модуль обрежет данные рукопожатия, чтобы соответствовать этой 512-байтовой строке. Библиотекам более высокого уровня рекомендуется сохранять свои метаданные краткими.
  serverApi | MongoDB\Driver\ServerApi | Опция обновляет версию API-интерфейса сервера для менеджера. Без опции API-версия не объявляется.

  Опции, поддерживаемые автоматическим шифрованием с помощью `autoEncryption`:

  autoEncryption
  Опция | Тип | Описание
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Менеджер маршрутизации запросов ключей данных в отдельный кластер MongoDB. По умолчанию метод выбирает текущий менеджер и кластер.
  keyVaultNamespace | string | Полное пространство имён (например, `"databaseName.collectionName"`), обозначающее коллекцию, которая содержит все ключи данных, используемые для шифрования и дешифрования. Обязательный параметр.
  kmsProviders | array | Документ, содержащий конфигурацию для одного или нескольких провайдеров KMS, которые используются для шифрования ключей данных. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"local"`, и, по крайней мере, один из них должен быть указан. Если для `"aws"`, `"azure"` или `"gcp"` указан пустой документ, драйвер попытается сконфигурировать провайдера, используя » Автоматические учётные данные. Формат для `"aws"` выглядит следующим образом:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Формат для `"azure"` выглядит следующим образом:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // По умолчанию "login.microsoftonline.com"

      }
  Формат для `"gcp"` выглядит следующим образом:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // По умолчанию "oauth2.googleapis.com"

      }
  Формат для `"kmip"` выглядит следующим образом:
      kmip: {
          endpoint: <string>
      }
  Формат для `"local"` выглядит следующим образом:
      local: {
          // 96-байтовый главный ключ, используемый для шифрования/дешифрования ключей данных
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Документ, содержащий конфигурацию TLS для одного или нескольких KMS провайдеров. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"kmip"`. Все провайдеры поддерживают следующие опции:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }
  schemaMap | array|object | Карта пространств имён коллекции в локальную схему JSON. Используется для настройки автоматического шифрования. Дополнительную информацию смотрите в » Правилах автоматического шифрования в руководстве по MongoDB. Ошибкой является указание коллекции как в `schemaMap`, так и в `encryptedFieldsMap`. Замечание: Добавление `schemaMap` обеспечивает большую безопасность, чем использование схем JSON, полученных с сервера. Это защищает от вредоносного сервера, рекламирующего ложную схему JSON, которая может заставить клиента отправлять незашифрованные данные, которые должны быть зашифрованы. Замечание: Схемы, поставляемые в `schemaMap`, применяются только для настройки автоматического шифрования на стороне клиента. Другие правила проверки в схеме JSON не будут применяться драйвером и приведут к ошибке.
  bypassAutoEncryption | bool | Если `true`, `mongocryptd` не будет появляться автоматически. Используется для отключения автоматического шифрования. По умолчанию `false`.
  bypassQueryAnalysis | bool | Если `true`, автоматический анализ исходящих команд будет отключён и `mongocryptd` не будет появляться автоматически. Это позволяет использовать явное шифрование для запроса индексированных полей без необходимости использования лицензированной корпоративной библиотеки `crypt_shared` или процесса `mongocryptd`. По умолчанию установлено значение `false`.
  encryptedFieldsMap | array|object | Карта пространств имён коллекции в документе `encryptedFields`. Используется для настройки шифрования с возможностью запроса. Смотрите » Шифрование полей и возможность запросов в руководстве по MongoDB для получения дополнительной информации. Ошибкой является указание коллекции как в `encryptedFieldsMap`, так и в `schemaMap`. Замечание: Указание `encryptedFieldsMap` обеспечивает большую безопасность, чем полагаться на `encryptedFields`, полученные от сервера. Это защищает от злонамеренного сервера, рекламирующего ложные `encryptedFields`.
  extraOptions | array | `extraOptions` относится к процессу `mongocryptd`. Поддерживаются следующие параметры: `mongocryptdURI` (string): URI для подключения к существующему процессу `mongocryptd`. По умолчанию `"mongodb://localhost:27020"`. `mongocryptdBypassSpawn` (bool): Если `true`, предотвращает создание драйвером `mongocryptd`. По умолчанию `false`. `mongocryptdSpawnPath` (string): Абсолютный путь для поиска двоичного файла `mongocryptd`. По умолчанию это пустая строка, использующая системные пути. `mongocryptdSpawnArgs` (array): Массив строковых аргументов для передачи в `mongocryptd` при создании. По умолчанию `["--idleShutdownTimeoutSecs=60"]`. `cryptSharedLibPath` (string): Абсолютный путь к библиотеке общего доступа `crypt_shared`. По умолчанию — пустая строка и использует системные пути. `cryptSharedLibRequired` (bool): Если `true`, требует, чтобы драйвер загружал `crypt_shared`. По умолчанию `false`. Смотрите » Руководство по шифрованию на стороне клиента, чтобы получить больше информации.

  > Замечание: Автоматическое шифрование — это только корпоративная функция, которая применяется только к операциям над коллекцией. Автоматическое шифрование не поддерживается для операций с базой данных или представлением, операции, которые не получится обойти, приведут к ошибке. Чтобы обойти автоматическое шифрование для всех операций, установите `bypassAutoEncryption=true` в `autoEncryption`. Для получения дополнительной информации о разрешённых операциях смотрите » Руководство по шифрованию на стороне клиента.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неверном формате `uri` выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Удалили URI-параметр `"canonicalizeHostname"`. Вместо него указывают свойство URI-параметра `"authMechanismProperties"` — `"CANONICALIZE_HOST_NAME"`. Удалили URI-параметр `"gssapiServiceName"`. Вместо него указывают свойство URI-параметра `"authMechanismProperties"` — `"SERVICE_NAME"`. Удалили URI-параметр `"safe"` URI. Вместо него указывают URI-параметры `"w"` и `"wTimeoutMS"`. Удалили URI-параметр `"ssl"`. Вместо него указывают URI-параметр `"tls"`. Удалили драйверный параметр `"allow_invalid_hostname"`. Вместо него указывают URI-параметр `"tlsAllowInvalidHostnames"`. Удалили драйверный параметр `"ca_file"`. Вместо него указывают URI-параметр `"tlsCAFile"`. Удалили драйверный параметр `"context"`. Параметры контекста устарели в пользу URI-параметров, которые связаны с TLS. Удалили драйверный параметр `"pem_file"`. Вместо него указывают URI-параметр `"tlsCertificateKeyFile"`. Удалили драйверный параметр `"pem_pwd"`. Вместо него указывают URI-параметр `"tlsCertificateKeyFilePassword"`. Удалили драйверный параметр `"weak_cert_validation"`. Вместо него указывают URI-параметр `"tlsAllowInvalidCertificates"`.
PECL-модуль mongodb 1.16.0 | Провайдер AWS KMS для шифрования на стороне клиента теперь принимает параметр `"sessionToken"`, который можно использовать для аутентификации с временными учётными данными AWS. Добавили `"tlsDisableOCSPEndpointCheck"` в поле `"tlsOptions"` поля `"autoEncryption"` опции драйвера. Драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные, если для KMS-провайдеров `"azure"` или `"gcp"` указали пустой документ.
PECL-модуль mongodb 1.15.0 | Драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные, если для KMS-провайдера `"aws"` указали пустой документ.
PECL-модуль mongodb 1.14.0 | Добавили опции автоматического шифрования `"bypassQueryAnalysis"` и `"encryptedFieldsMap"`. Дополнительные опции, относящиеся к `crypt_shared`, теперь поддерживаются в опции автоматического шифрования `"extraOptions"`. option.
PECL-модуль mongodb 1.13.0 | Добавили URI-параметры `"srvMaxHosts"` и `"srvServiceName"`.
PECL-модуль mongodb 1.12.0 | KMIP теперь поддерживается как KMS-провайдер для шифрования на стороне клиента и настраивается через поле `"kmsProviders"` параметра драйвера `"autoEncryption"`. Кроме того, параметры TLS для KMS-провайдеров теперь настраиваются в поле `"tlsOptions"` параметра драйвера `"autoEncryption"`.
PECL-модуль mongodb 1.11.0 | Добавили URI-параметр `"loadBalanced"`.
PECL-модуль mongodb 1.10.0 | Добавили драйверный параметр `"disableClientPersistence"`. Azure и GCP теперь поддерживаются как поставщик KMS для шифрования на стороне клиента и могут быть настроены в поле `"kmsProviders"` параметра драйвера `"autoEncryption"`. Строки в кодировке Base64 теперь принимаются как альтернатива MongoDB\BSON\Binary для параметров внутри `"kmsProviders"`.
PECL-модуль mongodb 1.8.0 | Добавили URI-параметры `"directConnection"`, `"tlsDisableCertificateRevocationCheck"` и `"tlsDisableOCSPEndpointCheck"`. Добавили драйверный параметр `"driver"`.
PECL-модуль mongodb 1.7.0 | Добавили драйверный параметр `"autoEncryption"`. Указание любой опции SSL или TLS в параметре `driverOptions` теперь неявно включает TLS, как это делается для соответствующих URI-параметров.
PECL-модуль mongodb 1.6.0 | Добавили URI-параметры `"retryReads"`, `"tls"`, `"tlsAllowInvalidCertificates"`, `"tlsAllowInvalidHostnames"`, `"tlsCAFile"`, `"tlsCertificateKeyFile"`, `"tlsCertificateKeyFilePassword"` и `"tlsInsecure"`. Значение URI-параметра `"retryWrites"` теперь по умолчанию равно `true`. Передача URI-опции SSL или TLS через строку подключения или параметр `uriOptions` теперь неявно включает TLS, при условии, если значения `ssl` или `tls` не равны `false`. TSL не включается неявно для любых опций в параметре `driverOptions`, как в предыдущих версиях.
PECL-модуль mongodb 1.5.0 | Параметр `"wtimeoutMS"` теперь всегда проверяется и применяется к гарантии записи. Раньше параметр игнорировался, если значение параметра `"w"` оказывалось <= 1, поскольку время ожидания применяется только к репликации.
PECL-модуль mongodb 1.4.0 | Добавили URI-параметры `"compressors"`, `"retryWrites"` и `"zlibCompressionLevel"`.
PECL-модуль mongodb 1.3.0 | В аргументе `uriOptions` появились опции `"authMechanism"` и `"authMechanismProperties"`. Раньше эти опции поддерживались только в аргументе `uri`.
PECL-модуль mongodb 1.2.0 | Аргумент `uri` по умолчанию теперь равен `"mongodb://127.0.0.1/"`. Порт по умолчанию не изменился — `27017`. Добавили URI-параметр `"appname"`. Добавили драйверные параметры `"allow_invalid_hostname"`, `"ca_file"`, `"ca_dir"`, `"clr_file"`, `"pem_file"`, `"pem_pwd"` и `"weak_cert_validation"`. API-интерфейс PHP-потоков больше не задействуется для соединения с сокетом. Значение URI-параметра `connectTimeoutMS` по умолчанию теперь равно 10 секундам вместо значения опции default_socket_timeout, как было в предыдущих версиях. Кроме того, модуль больше не поддерживает параметры SSL-контекста через параметр драйвера `context`.
PECL-модуль mongodb 1.1.0 | Аргумент `uri` стал необязательным и по умолчанию равен `"mongodb://localhost:27017/"`.

### Примеры

Пример #1 Примеры работы метода MongoDB\Driver\Manager::__construct()

Подключение к автономному узлу MongoDB:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

    ?>

Подключение к автономному узлу СУБД MongoDB через доменный сокет Unix. Путь сокета допускает специальные символы наподобие слешей, которые требуется закодировать функцией rawurlencode().

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

    ?>

Подключение к набору реплик:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    ?>

Подключение к сегментированному кластеру (т. е. одну или нескольким экземплярам mongos):

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

    ?>

Подключение к MongoDB с учётными данными аутентификации для конкретного пользователя и базы данных:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

    ?>

Подключение к MongoDB с учётными данными аутентификации для конкретного пользователя и базы данных, где имя пользователя или пароль содержат специальные символы (например, `@`, `:`, `%`). В следующем примере, строка с паролем `myp@ss:w%rd` была вручную экранирована; однако rawurlencode() может использоваться для экранирования URI-компонентов, которые могут содержать специальные символы.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

    ?>

Подключение к MongoDB с аутентификацией X509:

    <?php

    $manager = new MongoDB\Driver\Manager(
        "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
        [],
        [
            "pem_file" => "/path/to/client.pem",
        ]
    );
    ?>

### Смотрите также

- Обработка подключения и сохранение
- » Формат строки соединения MongoDB

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Создание нового объекта ClientEncryption

### Описание

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Создаёт новый объект MongoDB\Driver\ClientEncryption с заданными параметрами.

### Список параметров

`options`

  options
  Параметр | Тип | Описание
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Менеджер маршрутизации запросов ключей данных в отдельный кластер MongoDB. По умолчанию метод выбирает текущий менеджер и кластер.
  keyVaultNamespace | string | Полное пространство имён (например, `"databaseName.collectionName"`), обозначающее коллекцию, которая содержит все ключи данных, используемые для шифрования и дешифрования. Обязательный параметр.
  kmsProviders | array | Документ, содержащий конфигурацию для одного или нескольких провайдеров KMS, которые используются для шифрования ключей данных. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"local"`, и, по крайней мере, один из них должен быть указан. Если для `"aws"`, `"azure"` или `"gcp"` указан пустой документ, драйвер попытается сконфигурировать провайдера, используя » Автоматические учётные данные. Формат для `"aws"` выглядит следующим образом:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Формат для `"azure"` выглядит следующим образом:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // По умолчанию "login.microsoftonline.com"

      }
  Формат для `"gcp"` выглядит следующим образом:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // По умолчанию "oauth2.googleapis.com"

      }
  Формат для `"kmip"` выглядит следующим образом:
      kmip: {
          endpoint: <string>
      }
  Формат для `"local"` выглядит следующим образом:
      local: {
          // 96-байтовый главный ключ, используемый для шифрования/дешифрования ключей данных
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Документ, содержащий конфигурацию TLS для одного или нескольких KMS провайдеров. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"kmip"`. Все провайдеры поддерживают следующие опции:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Возвращаемые значения

Возвращает новый экземпляр MongoDB\Driver\ClientEncryption.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException если модуль был скомпилирован без поддержки libmongocrypt

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.16.0 | Провайдер AWS KMS для шифрования на стороне клиента теперь принимает параметр `"sessionToken"`, который можно использовать для аутентификации с временными учётными данными AWS. Для опции `"tlsOptions"` добавлена настройка `"tlsDisableOCSPEndpointCheck"`. Если для KMS-провайдеров `"azure"` или `"gcp"` указан пустой документ, драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные.
PECL mongodb 1.15.0 | Если для KMS-провайдера `"aws"` указан пустой документ, драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные.
PECL mongodb 1.12.0 | KMIP теперь поддерживается в качестве KMS провайдера для шифрования на стороне клиента и может быть настроен с помощью параметра `"kmsProviders"`. Добавлен параметр `"tlsOptions"`.
PECL mongodb 1.10.0 | Azure и GCP теперь поддерживаются в качестве поставщиков KMS для шифрования на стороне клиента и могут быть настроены в поле `"kmsProviders"` параметра драйвера `"autoEncryption"`. Строки в кодировке Base64 теперь принимаются в качестве альтернативы MongoDB\BSON\Binary для параметров внутри `"kmsProviders"`.

### Смотрите также

- MongoDB\Driver\ClientEncryption::__construct() - Создаёт новый объект ClientEncryption
- Страница в руководстве по MongoDB: » Явное (ручное) шифрование на уровне поля на стороне клиента

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Выполняет операции записи

### Описание

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Метод выполняет одну или несколько операций записи на основном сервере.

Объект класса MongoDB\Driver\BulkWrite создают с одной или несколькими операциями записи: обновления, удаления или вставки. Драйвер попытается отправить операции одного и того же типа на сервер с минимальным количества запросов, чтобы сократить обращения к серверу.

Значение по умолчанию для опции `"writeConcern"` автоматически определяется на основе активной транзакции или URI-идентификатора соединения, если транзакция не содержит значения. На активную транзакцию указывает опция `"session"`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`bulk` (MongoDB\Driver\BulkWrite)
  Записи для выполнения.
`опции`

  options
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

### Возвращаемые значения

Метод возвращает экземпляр класса MongoDB\Driver\WriteResult, если выполнился успешно.

### Ошибки

- При отсутствии какой-либо операции записи в параметр `bulk`, метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Если параметр `bulk` уже выполнился, метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException. Объекты MongoDB\Driver\BulkWrite нельзя выполнить несколько раз.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При ошибке записи метод выбрасывает исключение MongoDB\Driver\Exception\BulkWriteException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При возникновении других ошибок, метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\WriteConcern.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\WriteConcern как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"session"` указать вместе с неподтверждаемым уровнем записи.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\WriteConcern.
PECL-модуль mongodb 1.3.0 | Метод теперь выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит операций записи. Раньше выбрасывалось исключение MongoDB\Driver\Exception\BulkWriteException.

### Примеры

Пример #1 Пример записи методом MongoDB\Driver\Manager::executeBulkWrite()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Количество вставленных документов: %d\n", $result->getInsertedCount());
    printf("Количество документов для обновления: %d\n", $result->getMatchedCount());
    printf("Количество обновлённых документов: %d\n", $result->getModifiedCount());
    printf("Количество операций upsert: %d\n", $result->getUpsertedCount());
    printf("Количество удалённых документов: %d\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* При невозможности выполнить требование WriteConcern */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf(
            "%s (%d): %s\n",
            $writeConcernError->getMessage(),
            $writeConcernError->getCode(),
            var_export($writeConcernError->getInfo(), true)
        );
    }

    /* При невозможности записи */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Операция#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }

    ?>

Вывод приведённого примера будет похож на:

    Количество вставленных документов: 3
    Количество документов для обновления: 1
    Количество обновлённых документов: 1
    Количество операций upsert: 2
    Количество удалённых документов: 1
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

### Смотрите также

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Выполняет операции записи на сервере

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Выполняет операции записи через команду bulkWrite

### Описание

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Метод выполняет одну или несколько операций записи на первичном сервере через команду » bulkWrite, которая появилась в MongoDB 8.0.

Объект класса MongoDB\Driver\BulkWriteCommand создают с одной или несколькими операциями записи: вставки, обновления или удаления. Каждую операцию записи возможно нацелить на разные коллекции.

Значение по умолчанию для опции `"writeConcern"` автоматически определяется на основе активной транзакции или URI-идентификатора соединения, если транзакция не содержит значения. На активную транзакцию указывает опция `"session"`.

### Список параметров

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Одна или несколько операций записи для выполнения.
`options`

  Опции
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

### Возвращаемые значения

Метод возвращает объект класса MongoDB\Driver\BulkWriteCommandResult, если выполнился успешно.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит ни одной операции записи.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если операции в параметре `bulk` уже выполнились. Объекты MongoDB\Driver\BulkWriteCommand невозможно выполнить многократно.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\BulkWriteCommandException при ошибках записи наподобие сбоя команды, ошибки записи или ошибки подтверждения записи.
- При других ошибках метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Примеры

Пример #1 Пример смешанных операций записи

Смешанные операции записи наподобие вставки, обновления или удаления отправляются на сервер одной командой » bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    // Удалить документы из обеих коллекций
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Вставить документы в две коллекции
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Обновить документ в столбце "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Количество операций вставки документов: %d\n", $result->getInsertedCount());
    printf("Количество операций обновления документов: %d\n", $result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    Количество операций вставки документов: 3
    Количество операций обновления документов: 1

Пример #2 Пример упорядоченных операций записи, которые вызывают ошибку

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Количество операций вставки документов: %d\n", $result->getInsertedCount());

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Количество операций вставки документов: 2

### Смотрите также

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Выполняет операции записи на текущем сервере командой bulkWrite

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Выполняет команду базы данных

### Описание

final public function MongoDB\Driver\Manager::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выбирает сервер в соответствии с опцией `readPreference` и выполняет команду на этом сервере.

Метод не применяет особую логику к команде. Значения по умолчанию для опций `readPreference`, `readConcern` и `writeConcern` метод получит из активной транзакции (указывает опция `session`). Для выбора сервера метод использует основное предпочтение чтения, если активной транзакции нет.

Метод не получает значения по умолчанию из URI-идентификатора соединения. Поэтому пользователям рекомендуют использовать методы команд чтения и (или) записи, если это возможно.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При других ошибках наподобие неправильной команды метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\ReadPreference как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"session"` указать вместе с неподтверждаемым уровнем записи.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\ReadPreference.

### Примеры

Пример #1 Пример выполнения команды базы данных методом MongoDB\Driver\Manager::executeCommand() с командой, которая возвращает одиночный документ

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $command = new MongoDB\Driver\Command(['ping' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* Команда ping возвращает одиночный результат, поэтому мы должны получить доступ к
     * первому результату в курсор. */
    $response = $cursor->toArray()[0];

    var_dump($response);

    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["ok"]=>
      float(1)
    }

Пример #2 Пример поведения метода MongoDB\Driver\Manager::executeCommand() с командой, которая возвращает курсор

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1, 'y' => 'foo']);
    $bulk->insert(['x' => 2, 'y' => 'bar']);
    $bulk->insert(['x' => 3, 'y' => 'bar']);
    $manager->executeBulkWrite('db.collection', $bulk);

    $command = new MongoDB\Driver\Command([
        'aggregate' => 'collection',
        'pipeline' => [
            ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
        ],
        'cursor' => new stdClass,
    ]);
    $cursor = $manager->executeCommand('db', $command);

    /* Команда aggragete опционально может вернуть результаты в курсоре вместо
     * одиночного документа. В таком случае мы можем перебирать на курсоре для
     * непосредственного доступа к результатам. */
    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Результат выполнения приведённого примера:

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

Пример #3 Ограничение времени выполнения запроса

Опция `"maxTimeMS"` класса MongoDB\Driver\Query ограничивает время выполнения запроса. Обратите внимание, что этот срок применяется на стороне сервера и не учитывает задержки сети. Дополнительную информацию дает страница » Завершение выполнения операций в руководстве MongoDB.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $command = new MongoDB\Driver\Command([
        'count' => 'collection',
        'query' => ['x' => ['$gt' => 1]],
        'maxTimeMS' => 1000,
    ]);

    $cursor = $manager->executeCommand('db', $command);

    var_dump($cursor->toArray()[0]);

    ?>

Метод выбросит исключение MongoDB\Driver\Exception\ExecutionTimeoutException, если запрос не завершится через секунду после начала выполнения на сервере.

### Примечания

> Замечание: Вызывающий код берёт на себя ответственность за гарантию выполнения команды `command` на вторичном узле, если используется вторичный сервер из опции `readPreference`. Драйвер не выполняет проверку.

> Замечание: Этот метод — не метод по умолчанию, чтобы получить предпочтения чтения из URI-адреса подключения MongoDB. Приложениям, которым требуется это поведение, доступен вызов метода MongoDB\Driver\Manager::executeReadCommand().

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeReadCommand() - Выполняет команду базы данных, которая читает
- MongoDB\Driver\Manager::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет
- MongoDB\Driver\Manager::executeWriteCommand() - Выполняет команду базы данных, которая пишет
- MongoDB\Driver\Server::executeCommand() - Выполняет команду базы данных на сервере

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Выполняет запрос к базе данных

### Описание

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выбирает сервер в соответствии с опцией `readPreference` и выполняет запрос на этом сервере.

Значения по умолчанию для опциии `"readPreference"` и Query-опции `"readConcern"` метод получит из активной транзакции, за которой следует URI-идентификатор соединения. Активную транзакцию обозначает опция `session`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`query` (MongoDB\Driver\Query)
  Запрос для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При других ошибках наподобие неправильных операторах запроса метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\ReadPreference как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\ReadPreference.

### Примеры

Пример #1 Пример выполнения запроса к базе данных методом MongoDB\Driver\Manager::executeQuery()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'projection' => ['_id' => 0],
        'sort' => ['x' => -1],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Результат выполнения приведённого примера:

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

Пример #2 Ограничение времени выполнения запроса

Опция `maxTimeMS` класса MongoDB\Driver\Query ограничивает время выполнения запроса. Обратите внимание, что этот срок применяется на стороне сервера и не учитывает задержки сети. Дополнительную информацию даёт страница » Завершение выполнения операций в руководстве СУБД MongoDB.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'maxTimeMS' => 1000,
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Метод выбросит исключение MongoDB\Driver\Exception\ExecutionTimeoutException, если запрос не завершится через секунду после начала выполнения на сервере.

### Смотрите также

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Server::executeQuery() - Выполняет запрос к базе данных на сервере

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Выполняет команду базы данных, которая читает

### Описание

final public function MongoDB\Driver\Manager::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выбирает сервер в соответствии с опцией `readPreference` и выполняет команду на сервере.

Этот метод будет применять логику, специфичную для команд, которые читают (например, » distinct). Значения по умолчанию для параметров `"readPreference"` и `readConcern` метод получит из активной транзакции (обозначена параметром `session`), за которой следует URI-идентификатор соединения.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException для других ошибок (например, неверной команды).

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных
- MongoDB\Driver\Manager::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет
- MongoDB\Driver\Manager::executeWriteCommand() - Выполняет команду базы данных, которая пишет
- MongoDB\Driver\Server::executeReadCommand() - Выполняет команду базы данных, которая читает на сервере

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Выполняет команду базы данных, которая читает и пишет

### Описание

final public function MongoDB\Driver\Manager::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на основном сервере.

Этот метод будет применять логику, специфичную для команд, которые читают и пишут (например, » aggregate). Значения по умолчанию для параметров `readConcern` и `writeConcern` метод получит из активной транзакции (обозначена параметром `session`), за которой следует URI-идентификатор соединения.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException для других ошибок (например, неверной команды).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `session` используется в сочетании с неподтверждённой записью.

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных
- MongoDB\Driver\Manager::executeReadCommand() - Выполняет команду базы данных, которая читает
- MongoDB\Driver\Manager::executeWriteCommand() - Выполняет команду базы данных, которая пишет
- MongoDB\Driver\Server::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет на сервере

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Выполняет команду базы данных, которая пишет

### Описание

final public function MongoDB\Driver\Manager::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на основном сервере.

Этот метод будет применять логику, специфичную для команд, которые пишут (например, » drop). Значение по умолчанию для параметра `"writeConcern"` метод получит из активной транзакции (обозначена параметром `session`), за которым следует URI-идентификатор соединения.

> Замечание: Метод не предназначен для выполнения запросов » insert, » update, или » delete команд. Пользователям рекомендуется пользоваться методом MongoDB\Driver\Manager::executeBulkWrite() для этих операций.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException для других ошибок (например, неверной команды).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `session` используется в сочетании с неподтверждённой записью.

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных
- MongoDB\Driver\Manager::executeReadCommand() - Выполняет команду базы данных, которая читает
- MongoDB\Driver\Manager::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет
- MongoDB\Driver\Server::executeWriteCommand() - Выполняет команду базы данных, которая пишет на сервере

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Возвращает опцию автоматического шифрования encryptedFieldsMap для Manager

### Описание

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Возвращает параметр `encryptedFieldsMap` автоматического шифрования для Manager, если он указан.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Параметр `encryptedFieldsMap` автоматического шифрования для Manager или `null`, если он не был указан.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Manager::__construct() - Создаёт нового MongoDB-менеджера

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Возвращает ReadConcern для Manager

### Описание

final public function MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Возвращает MongoDB\Driver\ReadConcern для Manager, полученный из его URI-опций. Это гарантия чтения по умолчанию для запросов и команд, выполняемых в Manager.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

MongoDB\Driver\ReadConcern для Manager.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Manager::getReadConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
    var_dump($manager->getReadConcern());

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### Смотрите также

- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Manager::__construct() - Создаёт нового MongoDB-менеджера

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Возвращает ReadPreference для Manager

### Описание

final public function MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Метод возвращает экземпляр класса MongoDB\Driver\ReadPreference для объекта Manager, который метод получил из URI-опций диспетчера. Это предпочтение чтения по умолчанию для запросов и команд, которые выполняются в диспетчере Manager.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает экземпляр класса MongoDB\Driver\ReadPreference для диспетчера Manager.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Manager::getReadPreference()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadPreference());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
    var_dump($manager->getReadPreference());

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\ReadPreference)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(18) "secondaryPreferred"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#3 (2) {
          ["dc"]=>
          string(2) "ny"
          ["rack"]=>
          string(1) "1"
        }
        [1]=>
        object(stdClass)#4 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [2]=>
        object(stdClass)#5 (0) {
        }
      }
    }

### Смотрите также

- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::__construct() - Создаёт нового MongoDB-менеджера

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Возвращает серверы, к которым подключён менеджер

### Описание

final public function MongoDB\Driver\Manager::getServers(): array

Возвращает массив (array) экземпляров MongoDB\Driver\Server, к которым подключён текущий менеджер.

> Замечание: Поскольку драйвер подключается к базе данных лениво, этот метод может возвращать пустой массив (array), если он вызывается перед выполнением операции в MongoDB\Driver\Manager.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив (array) экземпляров MongoDB\Driver\Server, к которым подключён менеджер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Manager::getServers()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    /* Из-за того, что драйвер подключается к серверу лениво, вызов Manager::getServers()
     * первоначально может вернуть пустой массив. */
    var_dump($manager->getServers());

    $command = new MongoDB\Driver\Command(['ping' => 1]);
    $manager->executeCommand('db', $command);

    var_dump($manager->getServers());

    ?>

Вывод приведённого примера будет похож на:

    array(0) {
    }
    array(1) {
      [0]=>
      object(MongoDB\Driver\Server)#3 (10) {
        ["host"]=>
        string(9) "localhost"
        ["port"]=>
        int(27017)
        ["type"]=>
        int(1)
        ["is_primary"]=>
        bool(false)
        ["is_secondary"]=>
        bool(false)
        ["is_arbiter"]=>
        bool(false)
        ["is_hidden"]=>
        bool(false)
        ["is_passive"]=>
        bool(false)
        ["last_hello_response"]=>
        array(8) {
          ["isWritablePrimary"]=>
          bool(true)
          ["maxBsonObjectSize"]=>
          int(16777216)
          ["maxMessageSizeBytes"]=>
          int(48000000)
          ["maxWriteBatchSize"]=>
          int(1000)
          ["localTime"]=>
          object(MongoDB\BSON\UTCDateTime)#4 (1) {
            ["milliseconds"]=>
            int(1447267964517)
          }
          ["maxWireVersion"]=>
          int(3)
          ["minWireVersion"]=>
          int(0)
          ["ok"]=>
          float(1)
        }
        ["round_trip_time"]=>
        int(554)
      }
    }

### Смотрите также

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::selectServer() - Выбрать сервер, соответствующий предпочтениям чтения

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Возвращает WriteConcern для Manager

### Описание

final public function MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Возвращает MongoDB\Driver\WriteConcern для Manager, полученный из его URI-опций. Это гарантия записи по умолчанию для запросов и команд, выполняемых в Manager.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

MongoDB\Driver\WriteConcern для Manager.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Manager::getWriteConcern()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getWriteConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
    var_dump($manager->getWriteConcern());

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### Смотрите также

- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::__construct() - Создаёт нового MongoDB-менеджера

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Отменяет регистрацию подписчика на событие мониторинга в данном объекте Manager

### Описание

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Отменяет регистрацию подписчика на событие мониторинга в данном объекте Manager.

> Замечание: Если `subscriber` ещё не зарегистрирован в данном объекте Manager, функция отработает без результата.

### Список параметров

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Подписчик на событие мониторинга, которому необходимо отменить регистрацию в данном объекте Manager.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\removeSubscriber() - Отменяет глобальную регистрацию подписчика на событие мониторинга
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Выбрать сервер, соответствующий предпочтениям чтения

### Описание

final public function MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server

Выбирает MongoDB\Driver\Server, соответствующий `readPreference`. Если параметр `readPreference` равен `null` или опущен, по умолчанию будет выбран первичный сервер. Это можно использовать для предварительного выбора сервера, чтобы выполнить проверку версии перед выполнением операции.

> Замечание: В отличие от MongoDB\Driver\Manager::getServers(), этот метод будет инициализировать подключение к базе данных и при необходимости выполнять обнаружение сервера. Подробнее смотрите. » Спецификацию выбора сервера.

### Список параметров

`readPreference` (MongoDB\Driver\ReadPreference)
  Предпочтение чтения используется для выбора сервера. Если `null` или опущен, по умолчанию будет выбран первичный сервер.

### Возвращаемые значения

Возвращает MongoDB\Driver\Server, соответствующий предпочтению чтения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При невозможности найти сервер, соответствующий предпочтению чтения, выбрасывает исключение MongoDB\Driver\Exception\RuntimeException

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.11.0 | Параметр `readPreference` теперь необязателен. Если указано значение `null` или опущен, по умолчанию будет выбран первичный сервер.

### Смотрите также

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::getServers() - Возвращает серверы, к которым подключён менеджер
- » Спецификация выбора сервера

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Запускает новый клиентский сеанс для использования с этим клиентом

### Описание

final public function MongoDB\Driver\Manager::startSession(?array `$options` = `null`): MongoDB\Driver\Session

Создаёт MongoDB\Driver\Session для указанных параметров. Сеанс затем может быть указан при выполнении команд, запросов и операций записи.

> Замечание: MongoDB\Driver\Session может использоваться только с MongoDB\Driver\Manager, из которого он был создан.

### Список параметров

`options`

  options
  Опция | Тип | Описание | По умолчанию
  --- | --- | --- | ---
  causalConsistency | bool | Настраивает причинную согласованность в сеансе. Если `true`, каждая операция в сеансе будет причинно упорядочена после предыдущей операции чтения или записи. Установите на `false`, чтобы отключить причинную согласованность. Смотрите » Причинную согласованность в руководстве MongoDB для получения дополнительной информации. | `true`
  defaultTransactionOptions | array | Параметры по умолчанию для применения к вновь создаваемым транзакциям. Эти параметры используются, если они не переопределяются, когда транзакция запускается с различным значением для каждого параметра.
  options
  Опция | Тип | Описание
  --- | --- | ---
  maxCommitTimeMS | integer | Максимальный период времени в миллисекундах, в течение которого выполняется одна команда `commitTransaction`. Опция принимает `maxCommitTimeMS` 32-разрядное целое число со знаком, которое больше или равно нулю.
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.
  Эта опция доступна в MongoDB 4.0+. | `[]`
  snapshot | bool | Опция настраивает чтение моментальных снимков в сессии. Если `true`, временная метка будет получена из первой поддерживаемой операции чтения в сессии (т.е. `find`, `aggregate` или unsharded `distinct`). Последующие операции чтения в рамках сессии будут затем использовать уровень гарантии чтения `"snapshot"` для чтения данных, подтверждённых большинством, из этой временной метки. Установите значение `false` для отключения чтения моментальных снимков. Для чтения моментальных снимков требуется MongoDB 5.0+, и их нельзя использовать с причинно-согласованной связью, транзакциями или операциями записи. Если `"snapshot"` равен `true`, `"causalConsistency"` по умолчанию будет `false`. Смотрите » гарантию чтения "snapshot" в руководстве MongoDB для получения дополнительной информации. | `false`

### Возвращаемые значения

Возвращает MongoDB\Driver\Session.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException если опции `"causalConsistency"` и `"snapshot"` равны `true`.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException если сеанс не может быть создан (например, libmongoc не поддерживает шифрование).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.11.0 | Добавлен параметр `"snapshot"`.
PECL mongodb 1.6.0 | Параметр `"maxCommitTimeMS"` добавлен в `"defaultTransactionOptions"`.
PECL mongodb 1.5.0 | Добавлена опция `"defaultTransactionOptions"`.

### Смотрите также

- MongoDB\Driver\Session
- » Причинная согласованность в руководстве MongoDB

## Содержание

- MongoDB\Driver\Manager::addSubscriber — Регистрирует подписчика на событие мониторинга в данном объекте Manager
- MongoDB\Driver\Manager::__construct — Создаёт нового MongoDB-менеджера
- MongoDB\Driver\Manager::createClientEncryption — Создание нового объекта ClientEncryption
- MongoDB\Driver\Manager::executeBulkWrite — Выполняет операции записи
- MongoDB\Driver\Manager::executeBulkWriteCommand — Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\Manager::executeCommand — Выполняет команду базы данных
- MongoDB\Driver\Manager::executeQuery — Выполняет запрос к базе данных
- MongoDB\Driver\Manager::executeReadCommand — Выполняет команду базы данных, которая читает
- MongoDB\Driver\Manager::executeReadWriteCommand — Выполняет команду базы данных, которая читает и пишет
- MongoDB\Driver\Manager::executeWriteCommand — Выполняет команду базы данных, которая пишет
- MongoDB\Driver\Manager::getEncryptedFieldsMap — Возвращает опцию автоматического шифрования encryptedFieldsMap для Manager
- MongoDB\Driver\Manager::getReadConcern — Возвращает ReadConcern для Manager
- MongoDB\Driver\Manager::getReadPreference — Возвращает ReadPreference для Manager
- MongoDB\Driver\Manager::getServers — Возвращает серверы, к которым подключён менеджер
- MongoDB\Driver\Manager::getWriteConcern — Возвращает WriteConcern для Manager
- MongoDB\Driver\Manager::removeSubscriber — Отменяет регистрацию подписчика на событие мониторинга в данном объекте Manager
- MongoDB\Driver\Manager::selectServer — Выбрать сервер, соответствующий предпочтениям чтения
- MongoDB\Driver\Manager::startSession — Запускает новый клиентский сеанс для использования с этим клиентом

# Класс MongoDB\Driver\Command

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\Command — объект значения, который представляет команду базы данных.

Чтобы предоставить Помощников команд (Command Helpers) требуется сформировать объект команды MongoDB\Driver\Command.

## Обзор класса

final class MongoDB\Driver\Command {
/* Методы */
final public function __construct(array|object `$document`, ?array `$commandOptions` = `null`)
}

## Примеры

Пример #1 Пример составления команды MongoDB\Driver\Command для предоставления помощника по созданию коллекций

    <?php

    class CreateCollection
    {
        protected $cmd = array();

        function __construct($collectionName)
        {
            $this->cmd["create"] = (string) $collectionName;
        }

        function setCappedCollection($maxBytes, $maxDocuments = false)
        {
            $this->cmd["capped"] = true;
            $this->cmd["size"]   = (int) $maxBytes;

            if ($maxDocuments) {
                $this->cmd["max"] = (int) $maxDocuments;
            }
        }

        function usePowerOf2Sizes($bool)
        {
            if ($bool) {
                $this->cmd["flags"] = 1;
            } else {
                $this->cmd["flags"] = 0;
            }
        }

        function setFlags($flags)
        {
            $this->cmd["flags"] = (int) $flags;
        }

        function getCommand()
        {
            return new MongoDB\Driver\Command($this->cmd);
        }

        function getCollectionName()
        {
            return $this->cmd["create"];
        }
    }

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $createCollection = new CreateCollection("cappedCollection");
    $createCollection->setCappedCollection(64 * 1024);

    try {
        $command = $createCollection->getCommand();
        $cursor = $manager->executeCommand("databaseName", $command);
        $response = $cursor->toArray()[0];
        var_dump($response);

        $collstats = ["collstats" => $createCollection->getCollectionName()];
        $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
        $response = $cursor->toArray()[0];
        var_dump($response);
    } catch (MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\Driver\Command)#3 (1) {
      ["command"]=>
      array(3) {
        ["create"]=>
        string(16) "cappedCollection"
        ["capped"]=>
        bool(true)
        ["size"]=>
        int(65536)
      }
    }
    array(1) {
      ["ok"]=>
      float(1)
    }
    array(16) {
      ["ns"]=>
      string(29) "databaseName.cappedCollection"
      ["count"]=>
      int(0)
      ["size"]=>
      int(0)
      ["numExtents"]=>
      int(1)
      ["storageSize"]=>
      int(65536)
      ["nindexes"]=>
      int(1)
      ["lastExtentSize"]=>
      float(65536)
      ["paddingFactor"]=>
      float(1)
      ["paddingFactorNote"]=>
      string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
      ["userFlags"]=>
      int(0)
      ["capped"]=>
      bool(true)
      ["max"]=>
      int(9223372036854775807)
      ["maxSize"]=>
      int(65536)
      ["totalIndexSize"]=>
      int(8176)
      ["indexSizes"]=>
      object(stdClass)#4 (1) {
        ["_id_"]=>
        int(8176)
      }
      ["ok"]=>
      float(1)
    }

# MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Создаёт новый объект Command

### Описание

final public function MongoDB\Driver\Command::__construct(array|object `$document`, ?array `$commandOptions` = `null`)

Создаёт новый объект класса MongoDB\Driver\Command, который является неизменяемым значением, представляющим команду базы данных. Эту команду впоследствии можно запустить с помощью MongoDB\Driver\Manager::executeCommand().

Полный документ команды, включающий её имя и прочие опции,, должен быть задан в параметре `document`. Параметр `commandOptions` используется только для определения опций запуска команды и результирующий MongoDB\Driver\Cursor.

### Список параметров

`document`
  Полный документ команды, который будет передан серверу.
`commandOptions`

  > Замечание: Не используйте этот параметр для указания опций, описанных в руководстве по командам MongoDB. Этот параметр можно использовать только для опций перечисленных ниже.

  commandOptions
  Опция | Тип | Описание
  --- | --- | ---
  maxAwaitTimeMS | int | Положительное целое число, определяющие ограничение времени в миллисекундах, на которое сервер может блокировать операцию getMore, если данные отсутствуют. Эта опция может использоваться только совместно с командами, возвращающими хвостовые (tailable) курсоры. (например » Change Streams).

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.4.0 | Добавлен второй аргумент `commandOptions`, позволяющий определить опцию `"maxAwaitTimeMS"`.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Command::__construct()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(array("buildinfo" => 1));

    try {
        $cursor = $manager->executeCommand("admin", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Вывод приведённого примера будет похож на:

    array(13) {
      ["version"]=>
      string(14) "2.8.0-rc2-pre-"
      ["gitVersion"]=>
      string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
      ["OpenSSLVersion"]=>
      string(25) "OpenSSL 1.0.1f 6 Jan 2014"
      ["sysInfo"]=>
      string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
      ["loaderFlags"]=>
      string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
      ["compilerFlags"]=>
      string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
      ["allocator"]=>
      string(8) "tcmalloc"
      ["versionArray"]=>
      array(4) {
        [0]=>
        int(2)
        [1]=>
        int(8)
        [2]=>
        int(0)
        [3]=>
        int(-8)
      }
      ["javascriptEngine"]=>
      string(2) "V8"
      ["bits"]=>
      int(64)
      ["debug"]=>
      bool(false)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["ok"]=>
      float(1)
    }

Пример #2 Пример использования MongoDB\Driver\Command::__construct()

Команды также могут принимать опции, как часть нормальной структуры, которую вы создаёте и отправляете на сервер. К примеру, с большинством команд можно передавать опцию `maxTimeMS` для ограничения времени их выполнения.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(
        array(
            "distinct" => "beer",
            "key" => "beer_name",
            "maxTimeMS" => 10,
        )
    );

    try {
        $cursor = $manager->executeCommand("beerdb", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Вывод приведённого примера будет похож на:

operation exceeded time limit

### Смотрите также

- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных
- MongoDB\Driver\Cursor

## Содержание

- MongoDB\Driver\Command::__construct — Создаёт новый объект Command

# Класс MongoDB\Driver\Query

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\Query - это объект значения, представляющий запрос базы данных.

## Обзор класса

final class MongoDB\Driver\Query {
/* Методы */
final public function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Создаёт новый запрос

### Описание

final public function MongoDB\Driver\Query::__construct(array|object `$filter`, ?array `$queryOptions` = `null`)

Метод создаёт новый объект MongoDB\Driver\Query — неизменяемый объект значения, который представляет запрос к базе данных. После этого запрос готов к выполнению методом MongoDB\Driver\Manager::executeQuery().

### Список параметров

`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`queryOptions`

  queryOptions
  Опция | Тип | Описание
  --- | --- | ---
  allowDiskUse | bool | Разрешает БД MongoDB при обработке операции блочной сортировки хранить на диске временные файлы с данными, размер которых превышает 100-мегабайтный предел системной памяти.
  allowPartialResults | bool | Для запросов к шардированной коллекции вместо выдачи ошибки возвращает из процесса mongos частичные результаты, если отдельные шарды недоступны. Драйвер откатится к считыванию устаревшей опции `"partial"`, если эту опцию не указали.
  awaitData | bool | Опцию указывают совместно с опцией `"tailable"`, чтобы вместо возврата данных временно заблокировать операцию getMore для курсора, если курсор в конце данных. По истечении времени ожидания запрос возвращается в стандартном режиме.
  batchSize | int | Устанавливает количество документов для возврата в первом пакете. Значение по умолчанию равно 101. Размер пакета 0 означает, что курсор установится, но документы не вернутся в первом пакете. В версиях MongoDB до 3.2, в которых запросы работают по устаревшему проводному протоколу OP_QUERY, размер пакета со значением 1 закроет курсор независимо от количества совпадающих документов.
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  comment | mixed | Добавляет произвольный комментарий, который помогает отслеживать операцию через профилировщик базы данных, данные, которые выводит метод CurrentOp, и журналы. Комментарий добавляют в виде допустимого для MongoDB 4.4+ BSON-типа. Предыдущие версии сервера поддерживают только строковые значения. Драйвер откатится к считыванию устаревшего модификатора `"$comment"`, если эту опцию не указали.
  exhaust | bool | Настраивает запрос на потоковую передачу данных клиенту на полную мощность в нескольких «дополнительных» пакетах при условии, что клиент прочитает все данные, которые запросил. Опция уменьшает задержку, когда извлекается много данных и известно, что требуется извлечь все данные. Примечание: клиенту требуется прочитать все данные или закрыть соединение. Опция не поддерживается командой find в MongoDB 3.2+ и заставит драйвер использовать устаревшую версию проводного протокола (то есть OP_QUERY).
  explain | bool | Со значением `true` курсор MongoDB\Driver\Cursor, который вернёт команда или запрос, будет содержать один документ, который описывает план запроса: процесс и индексы, которые БД использует, чтобы вернуть запрос. Драйвер откатится к считыванию устаревшего модификатора `"$explain"`, если эту опцию не указали. Команда find в БД MongoDB 3.2+ не поддерживает эту опцию, опцию учитывает только устаревшая версия проводного протокола — с кодом операции OP_QUERY в заголовке сообщения. В БД MongoDB 3.0+ вместо этой опции пользуются командой » explain.
  hint | string|array|object | Устанавливает спецификацию индекса. Значение опции указывают либо как название индекса в виде строки, либо как шаблон ключа индекса. С этой опцией система запросов будет рассматривать только планы запроса с подсказкой индекса. Драйвер откатится к считыванию устаревшей опции `"hint"`, если эту опцию не указали.
  let | array|object | Карта имён и значений параметров. Значения должны быть константами или закрытыми выражениями, которые не ссылаются на поля документа. К параметрам можно обращаться как к переменным в контексте агрегированного выражения (например, `$$var`). Опция доступна в MongoDB 5.0+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  limit | int | Параметр устанавливает максимальное количество документов для возврата. По умолчанию ограничений нет, если опцию не указали. Значение 0 — то же, что отмена ограничения.
  max | array|object | Устанавливает эксклюзивную верхнюю границу для конкретного индекса. Драйвер откатится к считыванию устаревшего модификатора `"$max"`, если эту опцию не указали.
  maxAwaitTimeMS | int | Принимает положительное целое число, которое устанавливает ограничение времени в миллисекундах, в течение которого серверу разрешается заблокировать операцию getMore при недоступности данных. Опцию указывают только в сочетании с опциями `"tailable"` и `"awaitData"`.
  maxTimeMS | int | Совокупный лимит времени в миллисекундах для операций обработки на курсоре. БД MongoDB прерывает операцию в ближайшей следующей точке прерывания. Драйвер откатится к считыванию устаревшего модификатора `"$maxTimeMS"`, если эту опцию не указали.
  min | array|object | Инклюзивная нижняя граница для конкретного индекса. Драйвер откатится к считыванию устаревшего модификатора `"$min"`, если эту опцию не указали.
  noCursorTimeout | bool | Запрещает серверу синхронизировать незанятые курсоры после периода бездействия, который составляет 10 минут.
  projection | array|object | » Спецификация проекции, которая помогает определить, какие поля включать в документы, которые возвращает БД. В проекцию включают поле __pclass, если при работе с функциями ODM требуется десериализовать документы в их исходный PHP-класс. Десериализация будет работать только с этим полем, а без него модуль по умолчанию вернёт объект класса stdClass.
  readConcern | MongoDB\Driver\ReadConcern | Определяет уровень изоляции для операций чтения. По умолчанию модуль использует ограничения считывания из URI-идентификатора подключения к БД MongoDB. Эта опция доступна в MongoDB 3.2+ и выбросит исключение во время выполнения, если опцию указали для более старой версии сервера.
  returnKey | bool | Со значением `true` опция возвращает в результирующих документах только индексные ключи. Значением по умолчанию равно `false`. Документы, которые вернёт БД, будут пустыми, если для опции указали значение `true`, а команда find не использует индекс. Драйвер откатится к считыванию устаревшего модификатора `"$returnKey"`, если эту опцию не указали.
  showRecordId | bool | Определяет, возвращать ли идентификатор записи для каждого документа. Со значением `true` опция добавляет поле `"$recordId"` верхнего уровня к документам, которые возвращает БД. Драйвер откатится к считыванию устаревшего модификатора `"$showDiskLoc"`, если эту опцию не указали.
  singleBatch | bool | Определяет, закрывать ли курсор после первого пакета. Значение по умолчанию равно `false`.
  skip | int | Определяет количество документов, которое требуется пропустить. Значение по умолчанию равно 0.
  sort | array|object | Спецификация сортировки для упорядочения результатов. Драйвер откатится к считыванию устаревшего модификатора `"$orderby"`, если эту опцию не указали.
  tailable | bool | Возвращает хвостовой курсор для ограниченной коллекции.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 2.0.0 | Параметр `"partial"` удалили. Вместо него указывают параметр `"allowPartialResults"`. Параметр `"maxScan"` удалили. Поддержку параметра удалили в MongoDB 4.2. Параметр `"modifiers"` удалили. Параметр указывали для устаревших модификаторов запроса, которые устарели. Параметр `"oplogReplay"` удалили. Параметр игнорировали СУБД MongoDB 4.4 и новее. Параметр `"snapshot"` удалили. Поддержку параметра удалили в MongoDB 4.0. Отрицательное значение в параметре `"limit"` больше не интерпретируется как значение `true` для параметра `"singleBatch"`. Одну часть результатов получают путём объединения положительного значения в параметре `"limit"` с параметром `"singleBatch"`.
PECL-модуль mongodb 1.14.0 | Добавили опцию `"let"`. Опция `"comment"` теперь принимает любой тип.
PECL-модуль mongodb 1.8.0 | Добавили опцию `"allowDiskUse"`. Опция `"oplogReplay"` устарела.
PECL-модуль mongodb 1.5.0 | Опции `"maxScan"` и `"snapshot"` устарели.
PECL-модуль mongodb 1.3.0 | Добавили опцию `"maxAwaitTimeMS"`.
PECL-модуль mongodb 1.2.0 | Добавили опции `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"` и `"snapshot"`. Опцию `"partial"` переименовали в `"allowPartialResults"`. В целях обратной совместимости опция `"partial"` по-прежнему будет считываться, если опцию `"allowPartialResults"` не указали. Удалили устаревший параметр `"secondaryOk"`. Для запросов, которые работают по устаревшему проводному протоколу OP_QUERY, драйвер по мере необходимости установит бит `secondaryOk` по правилам » Спецификации выбора сервера.
PECL-модуль mongodb 1.1.0 | Добавили опцию `"readConcern"`.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Query::__construct()

    <?php

    /* Выбераем только документы автора "bjori" с количеством просмотров, которое равно или превышает 100 */
    $filter = [
        'author' => 'bjori',
        'views' => [
            '$gte' => 100,
        ],
    ];

    $options = [
        /* Возвращаем только следующие поля в соответствующих документах */
        'projection' => [
            'title' => 1,
            'article' => 1,
        ],
        /* Возвращаем документы в порядке убывания просмотров */
        'sort' => [
            'views' => -1
        ],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

### Смотрите также

- MongoDB\Driver\Manager::executeQuery() - Выполняет запрос к базе данных
- MongoDB\Driver\Cursor

## Содержание

- MongoDB\Driver\Query::__construct — Создаёт новый запрос

# Класс MongoDB\Driver\BulkWrite

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\BulkWrite собирает одну или несколько операций записи, которые должны быть отправлены на сервер. После добавления любого количества операций вставки, обновления или удаления, коллекция может быть выполнена с помощью MongoDB\Driver\Manager::executeBulkWrite().

Операции записи могут быть отсортированы (по умолчанию) или не отсортированы. Отсортированные операции записи отправляются на сервер в указанном порядке для последовательного выполнения. В случае возникновения ошибки записи, любые оставшиеся операции будут прерваны. Неотсортированные операции отправляются на сервер в произвольном порядке, где они могут выполняться параллельно. Сообщения об ошибках, которые возникают, будут отправлены после выполнения всех операций.

## Обзор класса

final class MongoDB\Driver\BulkWrite implements Countable {
/* Методы */
public function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$document`): mixed
public function update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void
}

## Примеры

Пример #1 Смешанные операции группируются по типу

Смешанные операции записи (т.е. добавления, обновления или удаления) будут собраны в типизированные команды записи, которые в последовательном порядке будут отправлены на сервер.

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->insert(['_id' => 3, 'x' => 3]);
    $bulk->delete(['x' => 1]);

    ?>

В результате будут выполнены четыре команды записи (т.е. обращений). Поскольку операции отсортированы, третья вставка не может быть отправлена до тех пор, пока не будет выполнено предыдущее обновление.

Пример #2 Отсортированные операции записи, вызывающие ошибку

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3, 'hello' => 'world']);
    $bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
    $bulk->insert(['_id' => 4, 'hello' => 'pluto']);
    $bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 5]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Убедиться, что гарантия записи не может быть выполнена
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Проверить, не выполнялись ли какие-либо операции записи
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Другая ошибка: %s\n", $e->getMessage());
        exit;
    }

    printf("Добавлено %d документ(ов)\n", $result->getInsertedCount());
    printf("Обновлено %d документ(ов)\n", $result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Добавлено 4 документ(ов)
    Обновлено 2 документ(ов)

Если гарантия записи не может быть выполнена, результат вышеприведённого примера будет что-то вроде этого:

    waiting for replication timed out (64): array (
      'wtimeout' => true,
    )
    Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
    Inserted 4 document(s)
    Updated  2 document(s)

Если мы выполним пример выше, но разрешим неотсортированные записи:

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    /* ... */

    ?>

Результат выполнения приведённого примера:

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
    Inserted 5 document(s)
    Updated  2 document(s)

## Смотрите также

- MongoDB\Driver\Manager::executeBulkWrite()
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Создаёт новый объект BulkWrite

### Описание

public function MongoDB\Driver\BulkWrite::__construct(?array `$options` = `null`)

Создаёт новый MongoDB\Driver\BulkWrite, который является изменяемым объектом, к которому могут быть добавлены одна и несколько операций записи. Операции записи могут быть выполнены с помощью MongoDB\Driver\Manager::executeBulkWrite().

### Список параметров

`options` (array)

  options
  Опция | Тип | Описание | Значение по умолчанию
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Если `true`, позволяет выполнять операции вставки или обновления, чтобы обойти проверку уровня документа. Этот параметр доступен в MongoDB 3.2+ и игнорируется в более старых версиях сервера, которые не поддерживают проверку уровня сервера. | `false`
  comment | mixed | Произвольный комментарий, помогающий отследить операцию с помощью профилировщика базы данных, вывода CurrentOp и журналов. Опция доступна в MongoDB 4.4+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  let | array|object | Карта имён и значений параметров. Значения должны быть константами или закрытыми выражениями, которые не ссылаются на поля документа. К параметрам можно обращаться как к переменным в контексте агрегированного выражения (например, `$$var`). Опция доступна в MongoDB 5.0+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  ordered | bool | Отсортированные операции (`true`) выполняется последовательно на сервере MongoDB, тогда как неотсортированные операции (`false`) отправляются на сервере в произвольном порядке и могут выполняться параллельно. | `true`

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.14.0 | Добавлены опции `"comment"` и `"let"`.
PECL mongodb 1.1.0 | Добавлена опция `"bypassDocumentValidation"`.

### Примеры

Пример #1 Пример использования MongoDB\Driver\BulkWrite::__construct()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(
        ['x' => 2],
        ['$set' => ['x' => 1]],
        ['limit' => 1, 'upsert' => false]
    );
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->update(
        ['_id' => 3],
        ['$set' => ['x' => 3]],
        ['limit' => 1, 'upsert' => true]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(1);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Проверяем обеспечение гарантии записи
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Проверяем, если какие-либо операции записи не были выполнены
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Другая ошибка: %s\n", $e->getMessage());
        exit;
    }

    printf("Добавлено %d документ(ов)\n", $result->getInsertedCount());
    printf("Обновлено  %d документ(ов)\n", $result->getModifiedCount());
    printf("Слито %d документ(ов)\n", $result->getUpsertedCount());
    printf("Удалено  %d документ(ов)\n", $result->getDeletedCount());

    ?>

Результат выполнения приведённого примера:

    Добавлено 2 документ(ов)
    Обновлено 1 документ(ов)
    Слито 1 документ(ов)
    Удалено  1 документ(ов)

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Подсчитывает количество операций записи в порции

### Описание

public function MongoDB\Driver\BulkWrite::count(): int

Возвращает количество операций записи, добавленных в объект MongoDB\Driver\BulkWrite.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество операций записи, добавленных в объект MongoDB\Driver\BulkWrite.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.2.0 | Возвращает количество операций записи, добавленных в объект MongoDB\Driver\BulkWrite. В более ранних версиях возвращалось предполагаемое количество обращений клиента к серверу, необходимых для выполнения всех операций записи.

### Примеры

Пример #1 Пример использования MongoDB\Driver\BulkWrite::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->delete(['x' => 1]);

    var_dump(count($bulk));

    ?>

Результат выполнения приведённого примера:

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Добавление операции удаления в порцию

### Описание

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Добавляет операцию удаления в объект MongoDB\Driver\BulkWrite.

### Список параметров

`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`deleteOptions`

  deleteOptions
  Опция | Тип | Описание | Значение по умолчанию
  --- | --- | --- | ---
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Индекс спецификации. Укажите либо имя индекса в виде строки, либо шаблон ключа индекса. Если указано, то система запросов будет рассматривать планы только с использованием индекса подсказок. Опция доступна с MongoDB 4.4+ и приведёт к исключению во время выполнения, если она указан для более старой версии сервера.
  limit | bool | Удалить все подходящие документа (`false`) или только первый найденный документ (`true`) | `false`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.8.0 | Добавлена опция `"hint"`.
PECL mongodb 1.2.0 | Добавлена опция `"collation"`.

### Примеры

Пример #1 Пример использования MongoDB\Driver\BulkWrite::delete()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->delete(['x' => 2], ['limit' => 0]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Добавить операцию вставки в порцию

### Описание

public function MongoDB\Driver\BulkWrite::insert(array|object `$document`): mixed

Добавляем операцию вставки в MongoDB\Driver\BulkWrite.

### Список параметров

`document` (array|object)
  Документ для вставки.

### Возвращаемые значения

Возвращает `_id` добавленного документа. Если в `document` не был задан `_id`, будет возвращён MongoDB\BSON\ObjectId, сгенерированный для вставки.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.3.0 | Всегда возвращается `_id` для добавленного документа. Ранее метод возвращал значение только в случае если MongoDB\BSON\ObjectId был создан.

### Примеры

Пример #1 Пример использования MongoDB\Driver\BulkWrite::insert()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    var_dump($id1, $id2, $id3);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Добавить операцию обновления в порцию

### Описание

public function MongoDB\Driver\BulkWrite::update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void

Добавляет операцию обновления в MongoDB\Driver\BulkWrite.

### Список параметров

`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`newObj` (array|object)
  Документ, содержащий операторы обновления (например, `$set`), заменяющий документ (например, только выражения `field:value`) или » конвейер агрегации.
`updateOptions`

  updateOptions
  Опция | Тип | Описание | Значение по умолчанию
  --- | --- | --- | ---
  arrayFilters | array | Массив документов фильтров, который определяет, какие элементы массива будут изменены для операции обновления в поле массива. Смотрите » Указывайте arrayFilters для операций обновления массива в руководстве MongoDB для получения дополнительной информации. Опция доступна с MongoDB 3.6+ и приведёт к исключению во время выполнения, если она указан для более старой версии сервера.
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Индекс спецификации. Укажите либо имя индекса в виде строки, либо шаблон ключа индекса. Если указано, то система запросов будет рассматривать планы только с использованием индекса подсказок. Опция доступна с MongoDB 4.4+ и приведёт к исключению во время выполнения, если она указан для более старой версии сервера.
  multi | bool | Обновить только первый найденный документ, если `false` или все подходящие документы при `true`. Эта опция не может быть `true`, когда `newObj` - заменяющий документ. | `false`
  sort | array|object | Укажите, какой документ будет обновлён в результате операции, если запрос соответствует нескольким документам. Будет обновлён первый документ, соответствующий порядку сортировки. Параметр не может быть использован, если значение `"multi"` равно `true`. Опция доступна в MongoDB 8.0+ и приведёт к исключению во время выполнения, если будет указана для более старой версии сервера.
  upsert | bool | Если `filter` не соответствует существующему документу, будет вставлен новый документ. Документ будет создан из `newObj`, если он заменяющий документ (т.е. отсутствуют операторы обновления); в противном случае операторы в `newObj` будут применяться к `filter` для создания нового документа. | `false`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.21.0 | Добавлена опция `"sort"`.
PECL mongodb 1.7.0 | Добавлена опция `"hint"`.
PECL mongodb 1.6.0 | Параметр `newObj` теперь принимает конвейер агрегации. Требуется MongoDB 4.2+, для более старой версии сервера выбросит исключение во время выполнения.
PECL mongodb 1.5.0 | Использование опции `"arrayFilters"` приведёт к исключению во время выполнения, если она не поддерживается сервером. Раньше не выбрасывалось исключение, и этот параметр, возможно, был проигнорирован.
PECL mongodb 1.4.0 | Добавлена опция `"arrayFilters"`.
PECL mongodb 1.2.0 | Добавлена опция `"collation"`.

### Примеры

Пример #1 Пример использования MongoDB\Driver\BulkWrite::update()

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->update(
        ['x' => 2],
        ['$set' => ['y' => 3]],
        ['multi' => false, 'upsert' => false]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи
- MongoDB\Driver\WriteResult

## Содержание

- MongoDB\Driver\BulkWrite::__construct — Создаёт новый объект BulkWrite
- MongoDB\Driver\BulkWrite::count — Подсчитывает количество операций записи в порции
- MongoDB\Driver\BulkWrite::delete — Добавление операции удаления в порцию
- MongoDB\Driver\BulkWrite::insert — Добавить операцию вставки в порцию
- MongoDB\Driver\BulkWrite::update — Добавить операцию обновления в порцию

# Класс MongoDB\Driver\BulkWriteCommand

(mongodb >=2.1.0)

## Введение

Класс MongoDB\Driver\BulkWriteCommand собирает одну или набор операций записи, которые требуется отправить на сервер командой » bulkWrite, которая появилась в MongoDB 8.0. После добавления произвольного количества операций вставки, обновления и удаления команда готова к выполнению методом MongoDB\Driver\Manager::executeBulkWriteCommand().

В отличие от класса MongoDB\Driver\BulkWrite, в котором каждую операцию записи требуется нацелить на ту же коллекцию, каждая операция записи внутри объекта MongoDB\Driver\BulkWriteCommand умеет нацеливаться на другую коллекцию.

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

## Обзор класса

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* Методы */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## Примеры

Пример #1 Смешанные операции записи

Смешанные операции записи наподобие вставок, обновлений или удалений отправляются на сервер одной командой » bulkWrite.

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    // Удалить документы из обоих коллекций
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Вставить документы в две коллекции
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Обновить документ в столбце "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Количество операций вставки документов: %d\n", $result->getInsertedCount());
    printf("Количество операций обновления документов: %d\n", $result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    Количество операций вставки документов: 3
    Количество операций обновления документов: 1

Пример #2 Упорядоченные операции записи, при которых возникает ошибка

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Количество операций вставки документов: %d\n", $result->getInsertedCount());

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Количество операций вставки документов: 2

## Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Создаёт новый объект BulkWriteCommand

### Описание

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Метод создаёт новый объект класса MongoDB\Driver\BulkWriteCommand для выполнения множественных операций вставки, обновления и удаления на наборе коллекций в одном запросе через команду » bulkWrite, которая появилась в MongoDB 8.0. Тогда как класс MongoDB\Driver\BulkWrite поддерживается всеми версиями серверов, но ограничивается одной коллекцией.

После добавления операций записи объект выполняют методом MongoDB\Driver\Manager::executeBulkWriteCommand().

### Список параметров

`options` (array)

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  bypassDocumentValidation | bool | Со значением `true` разрешает операции вставки и обновления для обхода проверки на уровне документа. | `false`
  comment | mixed | Произвольный комментарий, который помогает отслеживать операцию в профилировщике базы данных, выводе команды currentOp и логах.
  let | array|object | Карта имён и значений параметров. Значения должны быть константами или закрытыми выражениями, которые не ссылаются на поля документа. К параметрам можно обращаться как к переменным в контексте агрегированного выражения (например, `$$var`). Опция доступна в MongoDB 5.0+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  ordered | bool | Требуется ли выполнять операции текущей массовой записи в порядке добавления. Со значением `false` выполнение операций записи продолжится, если возникнет ошибка отдельной записи. Со значением `true` выполнение операции записи прекратится, если возникнет ошибка отдельной записи. | `true`
  verboseResults | bool | Требуется ли включать подробные результаты о каждой успешной операции в данные, которые возвращает класс MongoDB\Driver\BulkWriteCommandResult. | `false`

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример создания методом MongoDB\Driver\BulkWriteCommand::__construct() команды для множественных операций записи

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    // Удаление документов из обоих коллекций
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Вставка документов в две коллекции
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Обновление документа в столбце "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Количество операций вставки документов: %d\n", $result->getInsertedCount());
    printf("Количество операций обновления документов: %d\n", $result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    Количество операций вставки документов: 3
    Количество операций обновления документов: 1

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Подсчитывает количество операций записи в команде BulkWriteCommand

### Описание

public function MongoDB\Driver\BulkWriteCommand::count(): int

Метод возвращает количество операций записи, которые добавили в объект MongoDB\Driver\BulkWriteCommand.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество операций записи, которые добавили в объект MongoDB\Driver\BulkWriteCommand.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример подсчёта количества операций записи методом MongoDB\Driver\BulkWriteCommand::count()

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

Результат выполнения приведённого примера:

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Добавляет операцию deleteMany

### Описание

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Метод добавляет операцию deleteMany в объект MongoDB\Driver\BulkWriteCommand. Операция удалит из коллекции, которую определяет пространство имён `namespace`, каждый документ, который соответствует фильтру `filter`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`options`

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Спецификация индекса. Опция указывает либо название индекса в виде строки, либо шаблон ключа индекса. При установке значения система запросов ограничит поиск только теми планами, которые выполняют сканирование через заданный индекс.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции удаления методом MongoDB\Driver\BulkWriteCommand::deleteMany()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Смотрите также

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Добавляет операцию deleteOne
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Добавляет операцию deleteOne

### Описание

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Метод добавляет операцию deleteOne в объект MongoDB\Driver\BulkWriteCommand. Операция удалит из коллекции, которую определяет пространство имён `namespace`, первый документ, который соответствует фильтру `filter`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`options`

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Спецификация индекса. Опция указывает либо название индекса в виде строки, либо шаблон ключа индекса. При установке значения система запросов ограничит поиск только теми планами, которые выполняют сканирование через заданный индекс.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции удаления методом MongoDB\Driver\BulkWriteCommand::deleteOne()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Смотрите также

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Добавляет операцию deleteMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Добавляет операцию insertOne

### Описание

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Метод добавляет операцию insertOne в объект MongoDB\Driver\BulkWriteCommand. Операция вставит документ в коллекцию, которую определят пространство имён `namespace`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`document` (array|object)
  Документ для вставки.

### Возвращаемые значения

Метод возвращает `_id` документа, который вставила операция. Метод вернёт объект MongoDB\BSON\ObjectId, который модуль автоматически генерирует при вставке, если документ `document` не содержит поля `_id`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции вставки методом MongoDB\Driver\BulkWriteCommand::insertOne()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Добавляет операцию replaceOne

### Описание

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Метод добавляет операцию replaceOne в объект MongoDB\Driver\BulkWriteCommand. Операция заменит в коллекции, которую определяет пространство имён `namespace`, первый документ, который соответствует фильтру `filter`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`replacement` (array|object)
  Документ для замены.
`options`

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Спецификация индекса. Опция указывает либо название индекса в виде строки, либо шаблон ключа индекса. При установке значения система запросов ограничит поиск только теми планами, которые выполняют сканирование через заданный индекс.
  sort | array|object | Указывает, какой документ заменяет операция, если запрос соответствует набору документов. Операция заменит первый документ, который соответствует порядку сортировки.
  upsert | bool | Операция вставляет один документ, если фильтр `filter` не соответствует существующему документу. Документ создаётся из значения параметра `replacement`. | `false`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции замены методом MongoDB\Driver\BulkWriteCommand::replaceOne()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Смотрите также

- MongoDB\Driver\BulkWriteCommand::updateOne() - Добавляет операцию updateOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Добавляет операцию updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Добавляет операцию updateMany

### Описание

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Метод добавляет операцию updateMany в объект MongoDB\Driver\BulkWriteCommand. Операция обновит в коллекции, которую определяет пространство имён `namespace`, каждый документ, который соответствует фильтру `filter`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`update` (array|object)
  Документ, который содержит либо операторы обновления наподобие `$set`, либо » конвейер агрегации.
`options`

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  arrayFilters | array | Массив документов, каждый из которых содержит условия фильтрации. Документы определяют, какие элементы массива требуется изменить при обновлении поля массива. Подробнее об этом рассказывает страница руководства MongoDB » Определение фильтра arrayFilters для операций обновления массива.
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Спецификация индекса. Опция указывает либо название индекса в виде строки, либо шаблон ключа индекса. При установке значения система запросов ограничит поиск только теми планами, которые выполняют сканирование через заданный индекс.
  upsert | bool | Операция вставляет один документ, если фильтр `filter` не соответствует существующему документу. Документ создаётся путём применения операторов из параметра `update` к значениям полей в фильтре `filter`. | `false`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции обновления методом MongoDB\Driver\BulkWriteCommand::updateMany()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Смотрите также

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Добавляет операцию replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Добавляет операцию updateOne

### Описание

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Метод добавляет операцию updateOne в объект MongoDB\Driver\BulkWriteCommand. Операция обновит в коллекции, которую определяет пространство имён `namespace`, первый документ, который соответствует фильтру `filter`.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`update` (array|object)
  Документ, который содержит либо операторы обновления наподобие `$set`, либо » конвейер агрегации.
`options`

  Опции
  Опция | Тип | Описание | Стандартное значение
  --- | --- | --- | ---
  arrayFilters | array | Массив документов, каждый из которых содержит условия фильтрации. Документы определяют, какие элементы массива требуется изменить при обновлении поля массива. Подробнее об этом рассказывает страница руководства MongoDB » Определение фильтра arrayFilters для операций обновления массива.
  collation | array|object | » Сопоставление позволяет пользователям указывать специфичные для конкретного языка правила для сравнения строк, такие как реакцию на регистр букв и надстрочные знаки. Если задали сопоставление, то поле `"locale"` также обязательно. Описание полей смотрите в разделе » Сопоставление. Если сопоставление не задали явно, но у коллекции определили сопоставление по умолчанию, то будет выбрано оно. Если нет ни того ни того, то MongoDB будет использовать простое бинарное сравнение строк. Эта опция доступна в MongoDB 3.4+ и, если будет использована для более старых версий, вызовет исключение во время исполнения.
  hint | string|array|object | Спецификация индекса. Опция указывает либо название индекса в виде строки, либо шаблон ключа индекса. При установке значения система запросов ограничит поиск только теми планами, которые выполняют сканирование через заданный индекс.
  sort | array|object | Указывает, какой документ обновит операция, если запросу соответствует больше одного документа. Операция обновит первый документ, который соответствует порядку сортировки.
  upsert | bool | Операция вставляет один документ, если фильтр `filter` не соответствует существующему документу. Документ создаётся путём применения операторов из параметра `update` к значениям полей в фильтре `filter`. | `false`

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример добавления операции обновления методом MongoDB\Driver\BulkWriteCommand::updateOne()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Смотрите также

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Добавляет операцию replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany() - Добавляет операцию updateMany
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\BulkWriteCommandResult

## Содержание

- MongoDB\Driver\BulkWriteCommand::__construct — Создаёт новый объект BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Подсчитывает количество операций записи в команде BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Добавляет операцию deleteMany
- MongoDB\Driver\BulkWriteCommand::deleteOne — Добавляет операцию deleteOne
- MongoDB\Driver\BulkWriteCommand::insertOne — Добавляет операцию insertOne
- MongoDB\Driver\BulkWriteCommand::replaceOne — Добавляет операцию replaceOne
- MongoDB\Driver\BulkWriteCommand::updateMany — Добавляет операцию updateMany
- MongoDB\Driver\BulkWriteCommand::updateOne — Добавляет операцию updateOne

# Класс MongoDB\Driver\Session

(mongodb >=1.4.0)

## Введение

Класс MongoDB\Driver\Session представляет клиентский сеанс и возвращается методом MongoDB\Driver\Manager::startSession(). Команды, запросы и операции записи могут затем быть связаны с сеансом.

## Обзор класса

final class MongoDB\Driver\Session {
/* Константы */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* Методы */
final public function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): boolean
final public function startTransaction(?array `$options` = `null`): void
}

## Предопределённые константы

`MongoDB\Driver\Session::TRANSACTION_NONE`
  Нет транзакции в процессе.
`MongoDB\Driver\Session::TRANSACTION_STARTING`
  Транзакция была начата, но на сервер не было отправлено ни одной операции.
`MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS`
  Транзакция в процессе.
`MongoDB\Driver\Session::TRANSACTION_COMMITTED`
  Транзакция была зафиксирована.
`MongoDB\Driver\Session::TRANSACTION_ABORTED`
  Транзакция была прервана.

# MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Прерывает транзакцию

### Описание

final public function MongoDB\Driver\Session::abortTransaction(): void

Завершает многодокументную транзакцию и откатывает любые изменения данных, сделанные операциями внутри транзакции. То есть транзакция заканчивается без сохранения каких-либо изменений, внесённых операциями в транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выдаёт исключение MongoDB\Driver\Exception\RuntimeException, если транзакция не может быть прервана (например, транзакция не была начата).

### Смотрите также

- MongoDB\Driver\Manager::startSession() - Запускает новый клиентский сеанс для использования с этим клиентом
- MongoDB\Driver\Session::commitTransaction() - Фиксирует транзакцию
- MongoDB\Driver\Session::startTransaction() - Запускает транзакцию

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Увеличивает время кластера для сеанса

### Описание

final public function MongoDB\Driver\Session::advanceClusterTime(array|object `$clusterTime`): void

Увеличивает время кластера для сеанса. Если время кластера меньше или равно текущему времени кластера сеанса, функция не будет работать.

Используя этот метод в сочетании с MongoDB\Driver\Session::advanceOperationTime() для копирования кластера и времени операций из другого сеанса, вы можете убедиться, что операции в этом сеансе причинно соответствуют последней операции в другом сеансе.

### Список параметров

`clusterTime`
  Время кластера - это документ, содержащий логическую метку времени и сигнатуру сервера. Как правило, это значение будет получено путём вызова MongoDB\Driver\Session::getClusterTime() для другого объекта сеанса.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::advanceOperationTime() - Увеличивает время операции для сеанса
- MongoDB\Driver\Session::getClusterTime() - Возвращает время кластера для этого сеанса

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Увеличивает время операции для сеанса

### Описание

final public function MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void

Увеличивает время операции для сеанса. Если время операции меньше или равно текущему времени сеанса, функция не будет работать.

Используя этот метод в сочетании с MongoDB\Driver\Session::advanceClusterTime() для копирования операции и времени кластеризации из другого сеанса, вы можете гарантировать, что операции в этом сеансе причинно согласуются с последней операцией в другом сеансе.

### Список параметров

`operationTime`
  Время операции является логической отметкой времени. Как правило, это значение будет получено путём вызова MongoDB\Driver\Session::getOperationTime() для другого объекта сеанса.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::advanceClusterTime() - Увеличивает время кластера для сеанса
- MongoDB\Driver\Session::getClusterTime() - Возвращает время кластера для этого сеанса

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Фиксирует транзакцию

### Описание

final public function MongoDB\Driver\Session::commitTransaction(): void

Метод сохраняет изменения, которые внесли операции в многодокументную транзакцию, и завершает транзакцию. До фиксации каждое изменение, которое вносит транзакция в данные, останется невидимым за пределами транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\CommandException, если серверу не удалось зафиксировать транзакцию (например, из-за конфликтов, проблем с сетью). Попытка повтора всей транзакции будет безопасной, если исключение MongoDB\Driver\Exception\CommandException::getResultDocument() содержит элемент `"errorLabels"`, и этот массив содержит значение `"TransientTransactionError"` или `"UnknownTransactionCommitResult"`. В более новых версиях модуля вместо этого лучше вызвать метод MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() для проверки этой ситуации.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если транзакцию невозможно зафиксировать (например, транзакцию не запустили).

### Смотрите также

- MongoDB\Driver\Manager::startSession() - Запускает новый клиентский сеанс для использования с этим клиентом
- MongoDB\Driver\Session::abortTransaction() - Прерывает транзакцию
- MongoDB\Driver\Session::startTransaction() - Запускает транзакцию
- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Возвращает информацию о том, связана ли метка ошибки с исключением

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Создаёт новый сеанс (не используется)

### Описание

final private function MongoDB\Driver\Session::__construct()

MongoDB\Driver\Session объекты возвращаются MongoDB\Driver\Manager::startSession() и не могут быть созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\Driver\Manager::startSession() - Запускает новый клиентский сеанс для использования с этим клиентом

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Завершает сеанс

### Описание

final public function MongoDB\Driver\Session::endSession(): void

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

> Замечание: Сессии также закрыты во время сбора мусора. Не должно быть необходимости вызывать этот метод при нормальных обстоятельствах.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Manager::startSession() - Запускает новый клиентский сеанс для использования с этим клиентом
- MongoDB\Driver\Session::abortTransaction() - Прерывает транзакцию
- MongoDB\Driver\Session::commitTransaction() - Фиксирует транзакцию
- MongoDB\Driver\Session::startTransaction() - Запускает транзакцию

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Возвращает время кластера для этого сеанса

### Описание

final public function MongoDB\Driver\Session::getClusterTime(): ?object

Возвращает время кластера для этого сеанса. Если сеанс не использовался для какой-либо операции и MongoDB\Driver\Session::advanceClusterTime() не был вызван, время кластера будет равно `null`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает время кластера для этого сеанса или `null`, если у сеанса нет времени кластера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::advanceClusterTime() - Увеличивает время кластера для сеанса

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Возвращает логический идентификатор сеанса для этого сеанса

### Описание

final public function MongoDB\Driver\Session::getLogicalSessionId(): object

Возвращает логический идентификатор сеанса для этого сеанса, который может использоваться для идентификации операций сеанса на сервере.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает логический идентификатор сеанса для этого сеанса.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Возвращает время операции для этого сеанса

### Описание

final public function MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Возвращает время операции для этого сеанса. Если сеанс не использовался ни для какой операции, и MongoDB\Driver\Session::advanceOperationTime() не был вызван, время операции будет равно `null`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает время операции для этого сеанса или `null`, если у сеанса нет времени операции.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::advanceOperationTime() - Увеличивает время операции для сеанса

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Возвращает сервер к которому привязана текущая сессия

### Описание

final public function MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Возвращает MongoDB\Driver\Server, к которому привязана текущая сессия. Если сессия не привязана к серверу, то будет возвращён `null`.

Привязка сессии в основном используется для шардированных транзакций, так как все команды должны идти на один и тот же экземпляр mongos. Этот метод предназначен для использования в библиотеках, построенных поверх модуля, чтобы можно было закрепить сервер, а не выбирать сервер для каждой следующей команды.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает MongoDB\Driver\Server к которому прикреплена сессия. Или `null`, если сессия не прикреплена ни к какому серверу.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Возвращает настройки текущей транзакции

### Описание

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Возвращает настройки текущей транзакции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив, содержащий настройки текущей транзакции, либо `null`, если транзакция не стартована.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::getTransactionState() - Возвращает статус транзакции для текущей сессии

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Возвращает статус транзакции для текущей сессии

### Описание

final public function MongoDB\Driver\Session::getTransactionState(): string

Возвращает статус транзакции для текущей сессии.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает статус транзакции для текущей сессии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::isInTransaction() - Определяет, происходит ли в данный момент многодокументная транзакция
- MongoDB\Driver\Session::getTransactionOptions() - Возвращает настройки текущей транзакции

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Возвращает, была ли сессия помечена как грязная

### Описание

final public function MongoDB\Driver\Session::isDirty(): bool

Возвращает, была ли сессия помечена как грязная (т.е. была ли она использована с командой, которая столкнулась с сетевой ошибкой).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает, была ли сессия помечена как грязная.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Определяет, происходит ли в данный момент многодокументная транзакция

### Описание

final public function MongoDB\Driver\Session::isInTransaction(): boolean

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Session::getTransactionState() - Возвращает статус транзакции для текущей сессии

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Запускает транзакцию

### Описание

final public function MongoDB\Driver\Session::startTransaction(?array `$options` = `null`): void

Запускает многодокументную транзакцию, связанную с сеансом. В любой момент времени вы можете иметь не более одной открытой транзакции для сеанса. После запуска транзакции объект сеанса должен быть передан каждой операции с помощью опции `"session"` (например, MongoDB\Driver\Manager::executeBulkWrite()), чтобы связать эту операцию с транзакцией.

Транзакции могут быть зафиксированы через MongoDB\Driver\Session::commitTransaction() и прерваны с помощью MongoDB\Driver\Session::abortTransaction(). Транзакции также автоматически прерываются, когда сеанс закрывается из сборки мусора или явно вызывается MongoDB\Driver\Session::endSession().

### Список параметров

`options`
  Параметры могут быть переданы в качестве аргумента этому методу. Каждый элемент в этом массиве опций переопределяет соответствующую опцию из опции `"defaultTransactionOptions"`, если она установлена при запуске сеанса с MongoDB\Driver\Manager::startSession().

  options
  Опция | Тип | Описание
  --- | --- | ---
  maxCommitTimeMS | integer | Максимальный период времени в миллисекундах, в течение которого выполняется одна команда `commitTransaction`. Опция принимает `maxCommitTimeMS` 32-разрядное целое число со знаком, которое больше или равно нулю.
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выдаёт исключение MongoDB\Driver\Exception\CommandException, если транзакция не может быть запущена из-за проблемы на стороне сервера (например, не удалось получить блокировку).
- Выдаёт исключение MongoDB\Driver\Exception\RuntimeException, если транзакция не может быть запущена (например, транзакция уже была запущена).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.6.0 | Добавлен параметр `"maxCommitTimeMS"`.

### Смотрите также

- MongoDB\Driver\Manager::startSession() - Запускает новый клиентский сеанс для использования с этим клиентом
- MongoDB\Driver\Session::commitTransaction() - Фиксирует транзакцию
- MongoDB\Driver\Session::abortTransaction() - Прерывает транзакцию

## Содержание

- MongoDB\Driver\Session::abortTransaction — Прерывает транзакцию
- MongoDB\Driver\Session::advanceClusterTime — Увеличивает время кластера для сеанса
- MongoDB\Driver\Session::advanceOperationTime — Увеличивает время операции для сеанса
- MongoDB\Driver\Session::commitTransaction — Фиксирует транзакцию
- MongoDB\Driver\Session::__construct — Создаёт новый сеанс (не используется)
- MongoDB\Driver\Session::endSession — Завершает сеанс
- MongoDB\Driver\Session::getClusterTime — Возвращает время кластера для этого сеанса
- MongoDB\Driver\Session::getLogicalSessionId — Возвращает логический идентификатор сеанса для этого сеанса
- MongoDB\Driver\Session::getOperationTime — Возвращает время операции для этого сеанса
- MongoDB\Driver\Session::getServer — Возвращает сервер к которому привязана текущая сессия
- MongoDB\Driver\Session::getTransactionOptions — Возвращает настройки текущей транзакции
- MongoDB\Driver\Session::getTransactionState — Возвращает статус транзакции для текущей сессии
- MongoDB\Driver\Session::isDirty — Возвращает, была ли сессия помечена как грязная
- MongoDB\Driver\Session::isInTransaction — Определяет, происходит ли в данный момент многодокументная транзакция
- MongoDB\Driver\Session::startTransaction — Запускает транзакцию

# Класс MongoDB\Driver\ClientEncryption

(mongodb >=1.7.0)

## Введение

Класс MongoDB\Driver\ClientEncryption обрабатывает создание ключей данных для шифрования на стороне клиента, а также ручное шифрование и расшифровку значений

## Обзор класса

final class MongoDB\Driver\ClientEncryption {
/* Константы */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* Методы */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object
}

## Предопределённые константы

`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  Указывает алгоритм для » детерминированного шифрования, который подходит для выполнения запросов.
`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  Указывает алгоритм для » рандомизированного шифрования.
`MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  Указывает алгоритм для проиндексированной зашифрованной полезной нагрузки, который может использоваться с доступным для запросов шифрованием. Чтобы вставить или запросить индексированные зашифрованные полезные данные, менеджер MongoDB\Driver\Manager необходимо настроить с опцией драйвера `autoEncryption`. Для опции автоматического шифрования `bypassQueryAnalysis` разрешается устанавливать значение `true`. Параметру автоматического шифрования `bypassAutoEncryption` требуется установить значение `false`.
`MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  Указывает алгоритм для непроиндексированной зашифрованной полезной нагрузки.
`MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  Указывает алгоритм для диапазона зашифрованной полезной нагрузки, который можно использовать с доступным для запросов шифрованием. Чтобы запросить диапазон зашифрованных полезных данных, менеджер MongoDB\Driver\Manager требуется настроить с опцией драйвера `autoEncryption`. Для опции автоматического шифрования `bypassQueryAnalysis` разрешается устанавливать значение `true`. Параметру автоматического шифрования `bypassAutoEncryption` требуется установить значение `false`.

  > Замечание: Модуль пока не поддерживает запросы диапазона для BSON-полей с типом Decimal128.

`MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  Указывает тип запроса равенства, который используется в сочетании с опцией `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`.
`MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`
  Указывает тип запроса диапазона, который используется в сочетании с опцией `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Удалили константы `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` и `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL-модуль mongodb 1.20.0 | Добавили опции `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE` и `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`. Опции `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` и `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW` устарели.
PECL-модуль mongodb 1.16.0 | Добавили константы `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` и `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL-модуль mongodb 1.14.0 | Добавили опции `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`, `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`, и `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`.

## Смотрите также

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Добавляет альтернативное имя к документу с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Добавляет параметр `keyAltName` в набор альтернативных имён для документа с ключом с заданным UUID `keyId`.

### Список параметров

`keyId`
  Экземпляр MongoDB\BSON\Binary с подтипом 4 (UUID), идентифицирующий документ с ключом.
`keyAltName`

  Альтернативное имя для добавления в документ с ключом.

### Возвращаемые значения

Возвращает предыдущую версию документа с ключом или `null`, если ни один документ не был найден.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

### Смотрите также

- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Получает документ с ключом по альтернативному имени
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Удаляет альтернативное имя из документа с ключом

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Создаёт новый объект ClientEncryption

### Описание

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Создаёт новый объект MongoDB\Driver\ClientEncryption с указанными опциями.

### Список параметров

`options`

  Опции
  Опция | Тип | Описание
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Менеджер, используемый для маршрутизации запросов ключей данных. Опция является обязательной (в отличие от функции MongoDB\Driver\Manager::createClientEncryption()).
  keyVaultNamespace | string | Полное пространство имён (например, `"databaseName.collectionName"`), обозначающее коллекцию, которая содержит все ключи данных, используемые для шифрования и дешифрования. Обязательный параметр.
  kmsProviders | array | Документ, содержащий конфигурацию для одного или нескольких провайдеров KMS, которые используются для шифрования ключей данных. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"local"`, и, по крайней мере, один из них должен быть указан. Если для `"aws"`, `"azure"` или `"gcp"` указан пустой документ, драйвер попытается сконфигурировать провайдера, используя » Автоматические учётные данные. Формат для `"aws"` выглядит следующим образом:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Формат для `"azure"` выглядит следующим образом:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // По умолчанию "login.microsoftonline.com"

      }
  Формат для `"gcp"` выглядит следующим образом:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // По умолчанию "oauth2.googleapis.com"

      }
  Формат для `"kmip"` выглядит следующим образом:
      kmip: {
          endpoint: <string>
      }
  Формат для `"local"` выглядит следующим образом:
      local: {
          // 96-байтовый главный ключ, используемый для шифрования/дешифрования ключей данных
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Документ, содержащий конфигурацию TLS для одного или нескольких KMS провайдеров. Поддерживаются провайдеры `"aws"`, `"azure"`, `"gcp"` и `"kmip"`. Все провайдеры поддерживают следующие опции:
      <provider>: {
          tlsCaFile: <optional string>,
          tlsCertificateKeyFile: <optional string>,
          tlsCertificateKeyFilePassword: <optional string>,
          tlsDisableOCSPEndpointCheck: <optional bool>
      }

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если модуль был скомпилирован без поддержки libmongocrypt.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.16.0 | Провайдер AWS KMS для шифрования на стороне клиента теперь принимает параметр `"sessionToken"`, который можно указывать для аутентификации с временными учётными данными AWS. Добавлена поддержка поля `"tlsDisableOCSPEndpointCheck"` в опции `"tlsOptions"`. Если для KMS-провайдеров `"azure"` или `"gcp"` указан пустой документ, драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные.
PECL mongodb 1.15.0 | Если для KMS-провайдера `"aws"` указан пустой документ, драйвер попытается сконфигурировать провайдера, заполнив » Автоматические учётные данные.

### Смотрите также

- MongoDB\Driver\Manager::createClientEncryption() - Создание нового объекта ClientEncryption
- » Явное (ручное) шифрование уровня полей на стороне клиента в руководстве по MongoDB

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Создаёт документ с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

Создаёт новый документ с ключом шифрования и кладёт его в коллекцию хранилища ключей.

### Список параметров

`kmsProvider`
  Провайдер KMS (`"local"`, `"aws"`), который будет использоваться для шифрования нового ключа данных.
`options`

  Опции
  Опция | Тип | Описание
  --- | --- | ---
  masterKey | array | Документ masterKey определяет специфический для KMS ключ, используемый для шифрования нового ключа данных. Параметр обязателен, если параметр `kmsProvider` не является `"local"`.
  Параметры провайдера `"aws"`
  Параметр | Тип | Описание
  --- | --- | ---
  region | Строка | Обязательный.
  key | Строка | Обязательный. Имя ресурса Amazon (ARN) для главного ключа клиента AWS (CMK).
  endpoint | Строка | Необязательный. Альтернативный идентификатор хоста для отправки запросов KMS. Может содержать номер порта.
  Параметры провайдера `"azure"`
  Параметр | Тип | Описание
  --- | --- | ---
  keyVaultEndpoint | Строка | Обязательный. Хост с необязательным портом (например, "example.vault.azure.net").
  keyName | Строка | Обязательный.
  keyVersion | Строка | Необязательный. Определённая версия именованного ключа. По умолчанию — первичная версия ключа.
  Параметры провайдера `"gcp"`
  Параметр | Тип | Описание
  --- | --- | ---
  projectId | Строка | Обязательный.
  location | Строка | Обязательный.
  keyRing | Строка | Обязательный.
  keyName | Строка | Обязательный.
  keyVersion | Строка | Необязательный. Определённая версия именованного ключа. По умолчанию — первичная версия ключа.
  endpoint | Строка | Необязательный. Хост с дополнительным портом. По умолчанию "cloudkms.googleapis.com"..
  Параметры провайдера `"kmip"`
  Параметр | Тип | Описание
  --- | --- | ---
  keyId | Строка | Необязательный. Уникальный идентификатор 96-байтового управляемого объекта секретных данных протокола KMIP. При пропуске параметра драйвер создаёт случайный 96-байтовый управляемый объект секретных данных протокола KMIP.
  endpoint | Строка | Необязательный. Хост с дополнительным портом.
  delegated | bool | Необязательный. Установка значения `true` передаёт управление расшифровкой ключа KMIP-серверу.
  keyAltNames | array | Опциональный список альтернативных имён использующихся для ссылки на ключ. Если ключ создан с использованием альтернативных имён, то при шифровании можно ссылаться на уникальное альтернативное имя вместо `_id`.
  keyMaterial | MongoDB\BSON\Binary | Необязательное 96-байтовое значение для использования в качестве материала пользовательского ключа для создаваемого ключа данных. Если задан keyMaterial, то используется пользовательский материал ключа для шифрования и расшифровки данных. В противном случае материал ключа для нового ключа данных генерируется из криптографически защищённого случайного устройства.

### Возвращаемые значения

Возвращает идентификатор нового ключа в виде объекта MongoDB\BSON\Binary с подтипом 4 (UUID).

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения других ошибок.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.20.0 | Добавлена опция `"delegated"` к параметрам masterKey поставщика KMIP.
PECL mongodb 1.15.0 | Добавлена опция `"keyMaterial"`.
PECL mongodb 1.10.0 | В качестве поставщиков KMS для шифрования на стороне клиента теперь поддерживаются Azure и GCP.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Расшифровывает данные

### Описание

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Метод расшифровывает значение.

### Список параметров

`value`
  Объект класса MongoDB\BSON\Binary с подтипом 6, который содержит зашифрованные данные.

### Возвращаемые значения

Метод возвращает расшифрованные данные в том виде, в котором данные передали в метод MongoDB\Driver\ClientEncryption::encrypt().

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\EncryptionException, если в процессе дешифровки возникла ошибка.

### Смотрите также

- MongoDB\Driver\ClientEncryption::encrypt() - Шифрует данные

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Удаляет документ с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary `$keyId`): object

Удаляет документ с ключом с заданным UUID `keyId` из коллекции хранилища ключей.

### Список параметров

`keyId`
  Экземпляр MongoDB\BSON\Binary с подтипом 4 (UUID), идентифицирующий документ с ключом.

### Возвращаемые значения

Возвращает результат внутренней операции `deleteOne` над коллекцией хранилища ключей.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Шифрует данные

### Описание

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Метод шифрует данные.

### Список параметров

`value`
  Значение для шифрования. Метод шифрует любые значения, которые вставляются в БД MongoDB.
`options`

  Encryption options
  Опция | Тип | Описание
  --- | --- | ---
  algorithm | string | Алгоритм шифрования, который будет использоваться. Опция обязательна. Укажите одну из следующих констант ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | Коэффициент конкуренции для оценки запросов с индексированными зашифрованными полезными нагрузками. Опция применяется и может быть указана только тогда, когда опция `algorithm` равна `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` или `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Идентифицирует документ коллекции хранилища ключей по `keyAltName`. Опция является взаимоисключающей с `keyId` и требуется ровно один.
  keyId | MongoDB\BSON\Binary | Идентифицирует ключ данных по `_id`. Значением является UUID (двоичный подтип 4). Опция является взаимоисключающей с `keyAltName` и требуется ровно один.
  queryType | string | Тип запроса для оценки запросов с индексированными, зашифрованными полезными нагрузками. Укажите одну из следующих констант ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Опция применяется и может быть указана только тогда, когда опция `algorithm` равна `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` или `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Опции индекса для шифруемого поля с поддержкой запросов «range». Параметры, которые приводят следующие абзацы, должны соответствовать значениям, которые установили в параметре `encryptedFields` целевой коллекции. Для BSON-полей с типом double и decimal128 требуется либо установить все опции `min`, `max` и `precision`, либо все отключить.
  Опции индекса диапазона
  Опция | Тип | Описание
  --- | --- | ---
  min | mixed | Обязательна, если опцию `precision` установили. Минимальное BSON-значение в диапазоне.
  max | mixed | Обязательна, если опцию `precision` установили. Максимальное BSON-значение в диапазоне.
  sparsity | int | Необязательна. Опция принимает положительное 64-битное целое число.
  precision | int | Небязательна. Опция принимает положительное 32-битное целое число, которое указывает точность для явного шифрования. Опцию устанавливают только для BSON-полей с типом double или decimal128.
  trimFactor | int | Необязательна. Положительное 32-битное целое число.

### Возвращаемые значения

Метод возвращает зашифрованные данные в виде объекта MongoDB\BSON\Binary с подтипом 6.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\EncryptionException, если при шифровании возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 1.20.0 | В список опций параметра шифрования rangeOpts добавили опцию индекса диапазона `"trimFactor"`. Опция диапазона `"sparsity"` теперь необязательна.
PECL-модуль mongodb 1.16.0 | В список параметров шифрования добавили параметр `"rangeOpts"`.
PECL-модуль mongodb 1.14.0 | В список параметров шифрования добавили параметры `"contentionFactor"` и `"queryType"`.

### Смотрите также

- MongoDB\Driver\ClientEncryption::decrypt() - Расшифровывает данные
- MongoDB\Driver\ClientEncryption::encryptExpression() - Шифрует совпадение или агрегированное выражение

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Шифрует совпадение или агрегированное выражение

### Описание

final public function MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Метод шифрует совпадение или агрегированное выражение для запроса индекса диапазона.

Для выполнения запроса с зашифрованным диапазоном полезной нагрузки драйвер MongoDB\Driver\Manager конфигурируют с опцией `"autoEncryption"`. Опция `"bypassQueryAnalysis"` автоматического шифрования принимает значение `true`. Для опции автоматического шифрования `"bypassAutoEncryption"` устанавливают значение `false`.

> Замечание: Модуль пока не поддерживает запросы диапазонов для BSON-полей с типом Decimal128.

### Список параметров

`expr`
  Соответствие или агрегированное выражение, которое требуется зашифровать. В выражениях указывают хотя бы один оператор из списка: `$gt`, `$gte`, `$lt` или `$lte`. Оператор верхнего уровня `$and` необходим, даже если используется только один оператор сравнения. Пример поддерживаемого выражения соответствия (применяется для запросов и этапа агрегации `$match`) выглядит следующим образом:

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  Пример поддерживаемого агрегированного выражения выглядит следующим образом:

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Encryption options
  Опция | Тип | Описание
  --- | --- | ---
  algorithm | string | Алгоритм шифрования, который будет использоваться. Опция обязательна. Укажите одну из следующих констант ClientEncryption: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | Коэффициент конкуренции для оценки запросов с индексированными зашифрованными полезными нагрузками. Опция применяется и может быть указана только тогда, когда опция `algorithm` равна `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` или `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Идентифицирует документ коллекции хранилища ключей по `keyAltName`. Опция является взаимоисключающей с `keyId` и требуется ровно один.
  keyId | MongoDB\BSON\Binary | Идентифицирует ключ данных по `_id`. Значением является UUID (двоичный подтип 4). Опция является взаимоисключающей с `keyAltName` и требуется ровно один.
  queryType | string | Тип запроса для оценки запросов с индексированными, зашифрованными полезными нагрузками. Укажите одну из следующих констант ClientEncryption: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` Опция применяется и может быть указана только тогда, когда опция `algorithm` равна `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` или `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Опции индекса для шифруемого поля с поддержкой запросов «range». Параметры, которые приводят следующие абзацы, должны соответствовать значениям, которые установили в параметре `encryptedFields` целевой коллекции. Для BSON-полей с типом double и decimal128 требуется либо установить все опции `min`, `max` и `precision`, либо все отключить.
  Опции индекса диапазона
  Опция | Тип | Описание
  --- | --- | ---
  min | mixed | Обязательна, если опцию `precision` установили. Минимальное BSON-значение в диапазоне.
  max | mixed | Обязательна, если опцию `precision` установили. Максимальное BSON-значение в диапазоне.
  sparsity | int | Необязательна. Опция принимает положительное 64-битное целое число.
  precision | int | Небязательна. Опция принимает положительное 32-битное целое число, которое указывает точность для явного шифрования. Опцию устанавливают только для BSON-полей с типом double или decimal128.
  trimFactor | int | Необязательна. Положительное 32-битное целое число.

### Возвращаемые значения

Метод возвращает зашифрованное выражение в виде объекта.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\EncryptionException, если возникла ошибка при шифровании выражения.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 1.20.0 | В список опций параметра шифрования rangeOpts добавили опцию индекса диапазона `"trimFactor"`. Опция диапазона `"sparsity"` теперь необязательна.

### Смотрите также

- MongoDB\Driver\Manager::__construct() - Создаёт нового MongoDB-менеджера
- MongoDB\Driver\ClientEncryption::encrypt() - Шифрует данные

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Получает документ с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary `$keyId`): ?object

Находит единственный документ с ключом в коллекции хранилища ключей с заданным UUID `keyId`.

### Список параметров

`keyId`
  Экземпляр MongoDB\BSON\Binary с подтипом 4 (UUID), идентифицирующий документ с ключом.

### Возвращаемые значения

Возвращает документ с ключом или `null`, если ни один документ не совпал.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Получает документ с ключом по альтернативному имени

### Описание

final public function MongoDB\Driver\ClientEncryption::getKeyByAltName(string `$keyAltName`): ?object

Находит единственный документ с ключом в коллекции хранилища ключей с заданным альтернативным именем `keyAltName`.

### Список параметров

`keyAltName`
  Альтернативное имя документа с ключом.

### Возвращаемые значения

Возвращает документ с ключом или `null`, если ни один документ не совпал.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

### Смотрите также

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Добавляет альтернативное имя к документу с ключом
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Удаляет альтернативное имя из документа с ключом

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Получает все документы с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Находит все документы с ключом в коллекции хранилища ключей.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Удаляет альтернативное имя из документа с ключом

### Описание

final public function MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Удаляет параметр `keyAltName` из набора альтернативных имён для документа с ключом с заданным UUID `keyId`.

### Список параметров

`keyId`
  Экземпляр MongoDB\BSON\Binary с подтипом 4 (UUID), идентифицирующий документ с ключом.
`keyAltName`
  Альтернативное имя для удаления из документа с ключом.

### Возвращаемые значения

Возвращает предыдущую версию документа с ключом или `null`, если ни один документ не совпадает.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

### Смотрите также

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Добавляет альтернативное имя к документу с ключом
- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Получает документ с ключом по альтернативному имени

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Переворачивает ключи данных

### Описание

final public function MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object

Переворачивает (т.е. расшифровывает и заново шифрует) ноль или более ключей данных в коллекции хранилища ключей, которые соответствуют заданному фильтру (`filter`).

Если опция `"provider"` не указана, совпадающие ключи данных будут повторно зашифрованы с помощью текущего поставщика KMS. В противном случае совпадающие ключи данных будут зашифрованы заново в соответствии с указанными опциями `"provider"` и `"masterKey"`.

### Список параметров

`filter` (array|object)
  » Предикат запроса. Пустой предикат совпадёт со всеми элементами коллекции.

  > Замечание: СУБД MongoDB при оценке критериев запроса сравнивает типы и значения по внутренним » правилам сравнения BSON-типов, которые не совпадают с правилами сравнения и жонглирования типами в PHP. При сопоставлении специального BSON-типа в запросе требуется передать объект BSON-класса, который соответствует типу BSON-значения, поэтому для сопоставления с BSON-типом » ObjectId указывают объект класса MongoDB\BSON\ObjectId.

`options`

  Параметры RewrapManyDataKey
  Параметр | Тип | Описание
  --- | --- | ---
  provider | string | KMS-провайдер (например, `"local"`, `"aws"`), который будет использоваться для повторного шифрования совпавших ключей данных. Если провайдер KMS не указан, то совпадающие ключи данных будут повторно зашифрованы с помощью текущего провайдера KMS.
  masterKey | array | Параметр masterKey определяет специфический для KMS ключ, используемый для шифрования нового ключа данных. Параметр не должен указываться без параметра `"provider"`. Параметр необходим, если указан `"provider"`, а не `"local"`.
  Параметры провайдера `"aws"`
  Параметр | Тип | Описание
  --- | --- | ---
  region | Строка | Обязательный.
  key | Строка | Обязательный. Имя ресурса Amazon (ARN) для главного ключа клиента AWS (CMK).
  endpoint | Строка | Необязательный. Альтернативный идентификатор хоста для отправки запросов KMS. Может содержать номер порта.
  Параметры провайдера `"azure"`
  Параметр | Тип | Описание
  --- | --- | ---
  keyVaultEndpoint | Строка | Обязательный. Хост с необязательным портом (например, "example.vault.azure.net").
  keyName | Строка | Обязательный.
  keyVersion | Строка | Необязательный. Определённая версия именованного ключа. По умолчанию — первичная версия ключа.
  Параметры провайдера `"gcp"`
  Параметр | Тип | Описание
  --- | --- | ---
  projectId | Строка | Обязательный.
  location | Строка | Обязательный.
  keyRing | Строка | Обязательный.
  keyName | Строка | Обязательный.
  keyVersion | Строка | Необязательный. Определённая версия именованного ключа. По умолчанию — первичная версия ключа.
  endpoint | Строка | Необязательный. Хост с дополнительным портом. По умолчанию "cloudkms.googleapis.com"..
  Параметры провайдера `"kmip"`
  Параметр | Тип | Описание
  --- | --- | ---
  keyId | Строка | Необязательный. Уникальный идентификатор 96-байтового управляемого объекта секретных данных протокола KMIP. При пропуске параметра драйвер создаёт случайный 96-байтовый управляемый объект секретных данных протокола KMIP.
  endpoint | Строка | Необязательный. Хост с дополнительным портом.
  delegated | bool | Необязательный. Установка значения `true` передаёт управление расшифровкой ключа KMIP-серверу.

### Возвращаемые значения

Возвращает объект, у которого будет необязательное свойство `bulkWriteResult`, содержащее результат внутренней операции `bulkWrite` в виде объекта. Если ни один ключ данных не соответствует фильтру или запись не была признана, свойство `bulkWriteResult` будет равно `null`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Выбрасывает исключение MongoDB\Driver\Exception\EncryptionException, если при расшифровке или повторном шифровании ключа данных произошла ошибка.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException в случае возникновения прочих ошибок.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.20.0 | Добавлена опция `"delegated"` к параметрам masterKey поставщика KMIP.

## Содержание

- MongoDB\Driver\ClientEncryption::addKeyAltName — Добавляет альтернативное имя к документу с ключом
- MongoDB\Driver\ClientEncryption::__construct — Создаёт новый объект ClientEncryption
- MongoDB\Driver\ClientEncryption::createDataKey — Создаёт документ с ключом
- MongoDB\Driver\ClientEncryption::decrypt — Расшифровывает данные
- MongoDB\Driver\ClientEncryption::deleteKey — Удаляет документ с ключом
- MongoDB\Driver\ClientEncryption::encrypt — Шифрует данные
- MongoDB\Driver\ClientEncryption::encryptExpression — Шифрует совпадение или агрегированное выражение
- MongoDB\Driver\ClientEncryption::getKey — Получает документ с ключом
- MongoDB\Driver\ClientEncryption::getKeyByAltName — Получает документ с ключом по альтернативному имени
- MongoDB\Driver\ClientEncryption::getKeys — Получает все документы с ключом
- MongoDB\Driver\ClientEncryption::removeKeyAltName — Удаляет альтернативное имя из документа с ключом
- MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Переворачивает ключи данных

# Класс MongoDB\Driver\ServerApi

(mongodb >=1.10.0)

## Введение

## Обзор класса

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* Константы */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* Методы */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## Предопределённые константы

`MongoDB\Driver\ServerApi::V1`
  Server API версия 1.

## Примеры

Пример #1 Пример объявления версии API в диспетчере

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* Команда buildInfo возвращает единственный документ результата, поэтому нам нужно получить доступ
     * к первому результату в курсоре. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

Результат выполнения приведённого примера:

    4.9.0-alpha7-49-gb968ca0

Пример #2 Пример объявления строгой версии API для менеджера

В следующем примере устанавливается флаг `strict`, который сообщает серверу отклонить любую команду, которая — не часть объявленной версии API. Это приводит к ошибке при выполнении команды buildInfo.

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1, true);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* Команда buildInfo возвращает единственный документ результата, поэтому нам нужно получить доступ
     * к первому результату в курсоре. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

Результат выполнения приведённого примера:

    Provided apiStrict:true, but the command buildInfo is not in API Version 1

# MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Возвращает объект для сериализации BSON

### Описание

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект для сериализации ServerApi как BSON.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Создаёт новый экземпляр ServerApi

### Описание

final public function MongoDB\Driver\ServerApi::__construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)

Создаёт новый экземпляр MongoDB\Driver\ServerApi экземпляр, используемый для объявления версии API при создании MongoDB\Driver\Manager.

### Список параметров

`version`
  Версия API сервера. Поддерживаемые версии API представлены в виде констант в MongoDB\Driver\ServerApi. Единственной поддерживаемой версией API является `MongoDB\Driver\ServerApi::V1`.
`strict`
  Если у параметра `strict` установлено значение `true`, сервер будет выдавать ошибку для любой команды, которая не является частью указанной версии API. Если значение не указано, используется значение по умолчанию (`false`).
`deprecationErrors`
  Если у параметра `deprecationErrors` установлено значение `true`, сервер будет выдавать ошибку при использовании команды, которая устарела в указанной версии API. Если значение не задано, используется значение по умолчанию (`false`).

## Содержание

- MongoDB\Driver\ServerApi::bsonSerialize — Возвращает объект для сериализации BSON
- MongoDB\Driver\ServerApi::__construct — Создаёт новый экземпляр ServerApi

# Класс MongoDB\Driver\WriteConcern

(mongodb >=1.0.0)

## Введение

Объект класса MongoDB\Driver\WriteConcern описывает уровень подтверждения, который объект запросил у БД MongoDB для операций записи в автономный демон `mongod`, наборы реплик или шардированные кластеры. В шардированных кластерах экземпляры маршрутизаторов запроса `mongos` передадут уровень подтверждения записи — на шарды.

## Обзор класса

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* Константы */
const string MAJORITY = "majority";
/* Свойства */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* Методы */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## Свойства

w
  Значение write concern (целое число узлов, строка `"majority"` или имя пользовательского тега write concern) или `null`, если не задано.
j
  Определяет, должны ли операции записи быть зафиксированы в журнале до подтверждения, или `null`, если не указано.
wtimeout
  Время ожидания подтверждения write concern в миллисекундах. Значение `0` означает ожидание без ограничения по времени.

## Предопределённые константы

`MongoDB\Driver\WriteConcern::MAJORITY`

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

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.
PECL-модуль mongodb 1.7.0 | Реализовали интерфейс Serializable.
PECL-модуль mongodb 1.2.0 | Реализовали интерфейс MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Возвращает объект для BSON-сериализации

### Описание

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект для сериализации объекта WriteConcern в формате BSON.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример сериализации методом MongoDB\Driver\WriteConcern::bsonSerialize() объекта с гарантией записи большей частью узлов

    <?php

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

Пример #2 Пример сериализации методом MongoDB\Driver\WriteConcern::bsonSerialize() объекта со временем ожидания и журналом

    <?php

    $wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ
- » Справочная информация об уровнях подтверждения записи

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Создаёт новый объект WriteConcern

### Описание

final public function MongoDB\Driver\WriteConcern::__construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)

Метод создаёт новый уровень подтверждения записи MongoDB\Driver\WriteConcern как неизменяемый объект значения.

### Список параметров

`w`

  Уровень подтверждения записи
  Значение | Описание
  --- | ---
  1 | Запрашивает подтверждение распространения операции записи в автономный демон `mongod` или на первичный узел в наборе реплик. Это уровень подтверждения записи по умолчанию для БД MongoDB.
  0 | Не требует подтверждение операции записи. Однако возвращает приложению информацию об исключениях сокета и сетевых ошибках.
  <целое число больше 1> | Числа, которые превышают 1, допустимы только для наборов реплик, чтобы запросить подтверждение записи от первичного узла набора, и такого количества вторичных узлов, которые в сумме с первичным удовлетворят заданному количеству.
  `MongoDB\Driver\WriteConcern::MAJORITY` | Запрашивает подтверждение распространения операции записи на большинство голосующих узлов, включая первичный, и записались в журнал на диске для этих узлов. До MongoDB 3.0 это относилось к большинству членов набора реплик, а не только к узлам голосования.
  string | Строковое значение интерпретируется как набор тегов. С таким значением параметра метод запрашивает подтверждение распространения операции записи на членов пользовательского уровня подтверждения записи, который определили в настройках набора реплик и для которого указали набор тегов, которые предварительно закрепили за узлами набора реплик.

`wtimeout`
  Сколько ждать ответа от вторичных узлов в миллисекундах перед тем, как выдать ошибку. Параметр `wtimeout` заставляет операции записи возвращаться с ошибкой WriteConcernError после заданного времени ожидания, даже если уровень подтверждения записи, который запросили, в конечном счёте завершится без ошибки. После возврата этих операций записи БД MongoDB не отменяет удачные изменения данных, которые выполнила до превышения ограничения времени ожидания `wtimeout` уровнем подтверждения записи. Значение параметра `wtimeout` указывают как 64-битное целое число со знаком, которое больше или равно нулю.

  Время ожидания уровня подтверждения записи
  Значение | Описание
  --- | ---
  0 | Блокировать на неопределенный срок. Это значение по умолчанию.
  <целое число больше 0> | Количество миллисекунд ожидания возврата.

`journal`
  Включает ожидание записи данных в журнал на диске процессом mongod.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если значение параметра `w` недопустимо, или если значение времени ожидания `wtimeout` отрицательно или выходит за пределы 32-битного целого числа со знаком.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 1.7.0 | Параметр `wTimeout` теперь принимает 64-битные значения.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\WriteConcern::__construct()

    <?php

    /* Запрос подтверждения записи от большинства узлов набора реплик */
    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

    /* Запрос подтверждения записи от узла, для которого настроили пользовательский уровень подтверждения
        записи, который в настройках набора реплик назвали "MultipleDC" и для которого указали набор тегов */
    $wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

    ?>

### Смотрите также

- » Справочная информация об уровнях подтверждения записи

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Возвращает опцию "journal" WriteConcern

### Описание

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает опцию "journal" WriteConcern.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcern::getJournal()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, true);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, false);
    var_dump($wc->getJournal());

    ?>

Результат выполнения приведённого примера:

    NULL
    bool(true)
    bool(false)

### Смотрите также

- » Руководство по гарантии записи

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Возвращает опцию "w" WriteConcern

### Описание

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает опцию "w" WriteConcern.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcern::getW()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getW());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->getW());

    ?>

Результат выполнения приведённого примера:

    int(1)
    string(8) "majority"

### Смотрите также

- » Руководство по гарантии записи

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Возвращает опцию "wtimeout" WriteConcern

### Описание

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает опцию "wtimeout" WriteConcern.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.7.0 | В 32-разрядных системах метод всегда будет усекать значение `wTimeout`, если оно выходит за пределы 32-битного диапазона. В этом случае будет выдано предупреждение.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcern::getWtimeout()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getWtimeout());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
    var_dump($wc->getWtimeout());

    ?>

Результат выполнения приведённого примера:

    int(0)
    int(3000)

### Смотрите также

- » Руководство по гарантии записи

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Проверяет, установили ли для уровня подтверждения записи значение по умолчанию

### Описание

final public function MongoDB\Driver\WriteConcern::isDefault(): bool

Метод проверяет, установили ли для уровня подтверждения записи значение по умолчанию — т. е. не указали значение параметра. Задача метода — при совместной работе с методом диспетчера драйвера MongoDB\Driver\Manager::getWriteConcern() определить, создали ли объект диспетчера драйвера без параметров уровня подтверждения записи.

Драйвер не будет включать уровень подтверждения записи по умолчанию в свои операции записи наподобие метода MongoDB\Driver\Manager::executeBulkWrite()), чтобы разрешить серверу применять свои настройки по умолчанию, которые, возможно, » изменили. Библиотеки, которые обращаются к уровню подтверждения записи диспетчера драйвера, вызывают этот метод, чтобы гарантировать, что уровни подтверждения записи сохранили значения по умолчанию, чтобы включить уровень подтверждения записи в свои команды записи.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает `true`, если для уровня подтверждения записи установили значение по умолчанию, иначе возвращает `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример проверки значения уровня подтверждения записи методом MongoDB\Driver\WriteConcern::isDefault()

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- MongoDB\Driver\Manager::getWriteConcern() - Возвращает WriteConcern для Manager
- » Изменение значения по умолчанию уровня подтверждения записи в руководстве MongoDB
- » Справочная информация об уровнях подтверждения записи

## Содержание

- MongoDB\Driver\WriteConcern::bsonSerialize — Возвращает объект для BSON-сериализации
- MongoDB\Driver\WriteConcern::__construct — Создаёт новый объект WriteConcern
- MongoDB\Driver\WriteConcern::getJournal — Возвращает опцию "journal" WriteConcern
- MongoDB\Driver\WriteConcern::getW — Возвращает опцию "w" WriteConcern
- MongoDB\Driver\WriteConcern::getWtimeout — Возвращает опцию "wtimeout" WriteConcern
- MongoDB\Driver\WriteConcern::isDefault — Проверяет, установили ли для уровня подтверждения записи значение по умолчанию

# Класс MongoDB\Driver\ReadPreference

(mongodb >=1.0.0)

## Введение

## Обзор класса

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* Свойства */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* Константы */
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* Методы */
final public function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## Свойства

mode
  Режим read preference в виде строки (например, `"primary"`, `"secondary"`).
tags
  Список наборов тегов, который использует read preference, или `null`, если наборы тегов не указаны.
maxStalenessSeconds
  Максимальное отставание (staleness) в секундах для операций чтения или `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, если максимальное отставание не указано.
hedge
  Документ, который задаёт параметры hedge для read preference, или `null`, если параметры hedge не указаны.
  Внимание

  Свойство устарело, поскольку hedged reads устарели в MongoDB 8.0.

## Предопределённые константы

`MongoDB\Driver\ReadPreference::PRIMARY`

  Каждую операцию чтения из текущей реплики установили первичными. Это предпочтение чтения по умолчанию для СУБД MongoDB.

`MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`

  В большей части случаев операции считываются из первичного узла, но если узел недоступен, операции считываются со вторичных узлов.

`MongoDB\Driver\ReadPreference::SECONDARY`

  Каждая операция считывается из вторичных узлов набора реплик.

`MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`

  В большей части случаев операции считываются из вторичных узлов, но если узлы недоступны, операции считываются с первичного.

`MongoDB\Driver\ReadPreference::NEAREST`

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

`MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`

  Значение по умолчанию для параметра `"maxStalenessSeconds"` чтобы указать на ограничение на максимальное запаздывание (staleness), что означает, что драйвер не будет учитывать задержку вторичных узлов при выборе направления для операции чтения.

`MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`

  Минимальное значение для параметра `"maxStalenessSeconds"` равно 90 секундам. Драйвер оценивает запаздывание (staleness) вторичных узлов, периодически проверяя последнюю дату записи каждого члена набора реплик. Поскольку эти проверки нечастые, оценка запаздывания грубая. Поэтому драйвер не обеспечивает максимальную величину запаздывания меньше 90 секунд.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.
PECL-модуль mongodb 2.0.0 | Удалили константы `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED` и `MongoDB\Driver\ReadPreference::RP_NEAREST`. Метод getMode() тоже удалили.
PECL-модуль mongodb 1.20.0 | Константы `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED` и `MongoDB\Driver\ReadPreference::RP_NEAREST` устарели.
PECL-модуль mongodb 1.7.0 | Добавили константы `MongoDB\Driver\ReadPreference::PRIMARY`, `MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::SECONDARY`, `MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED` и `MongoDB\Driver\ReadPreference::NEAREST`. Класс теперь реализует интерфейс Serializable.
PECL-модуль mongodb 1.2.0 | Добавили константы `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` и `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Класс теперь реализует интерфейс MongoDB\BSON\Serializable.

# MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Возвращает объект для BSON-сериализации

### Описание

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект для сериализации объекта ReadPreference в формате BSON.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример сериализации методом MongoDB\Driver\ReadPreference::bsonSerialize() объекта с первичным предпочтением чтения

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

Пример #2 Пример сериализации методом MongoDB\Driver\ReadPreference::bsonSerialize() объекта с вторичным предпочтением чтения и наборами тегов

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#1 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [1]=>
        object(stdClass)#5 (2) {
          ["dc"]=>
          string(2) "sf"
          ["use"]=>
          string(9) "reporting"
        }
        [2]=>
        object(stdClass)#4 (0) {
        }
      }
    }

    { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

Пример #3 Пример использования MongoDB\Driver\ReadPreference::bsonSerialize() с вторичным предпочтением чтения и максимальным staleness

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ
- » Справочная информация по предпочтению чтения

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Создаёт новый объект предпочтения чтения ReadPreference

### Описание

final public function MongoDB\Driver\ReadPreference::__construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Метод создаёт новый объект MongoDB\Driver\ReadPreference — неизменяемый объект значения.

### Список параметров

`mode`

  Режим предпочтения чтения
  Значение | Описание
  --- | ---
  `"primary"` | Операции считываются из текущего первичного узла набора реплик. Это предпочтение чтения по умолчанию для БД MongoDB.
  `"primaryPreferred"` | В большей части случаев операции считываются из первичного узла, но если узел недоступен, операции считываются из вторичных узлов.
  `"secondary"` | Операции считываются из вторичных узлов набора реплик.
  `"secondaryPreferred"` | В большей части случаев операции считываются из вторичных членов, но если вторичные члены недоступны, операции считываются из первичного узла.
  `"nearest"` | Операции считываются из члена набора реплик с наименьшей задержкой сети, независимо от типа члена.

`tagSets`
  Наборы тегов разрешают нацеливать операции чтения на конкретных членов набора реплик. Аргумент формируют как массив ассоциативных массивов, каждый из которых содержит ноль или больше пар ключ-значение. Для операции чтения драйвер выбирает сервер, в конфигурации которого узел содержит каждый тег набора — ассоциативного массива пар ключей и значений. Драйвер выполнит попытку со следующими наборами, если не получилось выбрать узел. Пустой набор тегов `array()` совпадёт с любым узлом, его передают как запасной вариант. Теги несовместимы с режимом `"primary"`, и по ним сервер чаще выбирает только вторичного члена набора для операции чтения. Между тем, при сочетании режима `"nearest"` с набором тегов драйвер выбирает члена с наименьшей задержкой в сети. Тогда членом, которого выберет драйвер, окажется первичный или вторичный узел.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  hedge | object|array | Определяет, использовать ли » хеджированные считывания , которые БД MongoDB 4.4+ поддерживают для шардированных запросов. Хеджированные считывания с сервера доступны для непервичных предпочтений чтения и включаются по умолчанию в режиме `"nearest"`. Через эту опцию явно разрешают серверу считывание с хеджированием для непервичных предпочтений чтения путём установки аргумента `['enabled' => true]` или явно запрещают серверу чтения с хеджированием для предпочтения чтения в режиме `"nearest"` путём установки аргумента `['enabled' => false]`.
  maxStalenessSeconds | int | Определяет максимальное отставание репликации (англ. staleness) для чтения из вторичных узлов. Когда по оценке клиента отставания репликации вторичных узлов превышает это значение, драйвер прекращает использовать отставание для операций чтения. Максимальное значение отставания репликации указывают как 32-битное целое число со знаком, которое больше или равно значению константы `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Значение по умолчанию для опции равно значению константы `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`. При таком значении драйвер не будет учитывать отставания репликаций вторичных узлов при выборе направления для операции чтения. Опция несовместима с режимом `"primary"`. Со значением максимального отставания репликации умеют работать только экземпляры MongoDB с БД MongoDB 3.4+ в развёртывании. Метод выбросит исключение во время выполнения, если версия сервера хотя бы одного экземпляра MongoDB в развёртывании старее.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException при недопустимом значении аргумента `mode`.
- Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если аргумент `tagSets` передали для предпочтения чтения первичного узла или аргумент неправильно сформировали — передали не массив из нуля или больше документов.
- Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"maxStalenessSeconds"` передали для предпочтения чтения первичного узла или указали значение за пределами диапазона.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Передача значения с типом int в аргументе `mode` больше не поддерживается.
PECL-модуль mongodb 1.20.0 | Передача целых чисел (int) в аргументе `mode` УСТАРЕЛА.
PECL-модуль mongodb 1.8.0 | Добававили опцию `"hedge"`.
PECL-модуль mongodb 1.3.0 | Параметр `mode` теперь принимает строковое значение, которое соответствует URI-опции `"readPreference"` метода MongoDB\Driver\Manager::__construct().
PECL-модуль mongodb 1.2.0 | Добавили в сигнатуру метода третий параметр — `options`, который поддерживает опцию `"maxStalenessSeconds"`.

### Примеры

Пример #1 Пример создания нового объекта ReadPreference методом MongoDB\Driver\ReadPreference::__construct()

    <?php

    /* Предпочитать вторичный узел, но в случае отказа отступить к первичному */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

    /* Предпочитать узел в Нью-Йоркском центре обработки данных с минимальной задержкой */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

    /* Требуется дополнительный узел, задержка репликации которого в пределах двух минут от основного */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Явно разрешить серверу хеджированные считывания */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### Смотрите также

- » Руководство по предпочтению чтения

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Возвращает опцию "hedge" объекта ReadPreference

### Описание

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает опцию "hedge" объекта ReadPreference.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- » Документация к Read Preference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Возвращает опцию "maxStalenessSeconds" объекта ReadPreference

### Описание

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает значение опции "maxStalenessSeconds" объекта ReadPreference. Метод вернёт значение константы `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, если максимальное значение отставания репликации (англ. staleness) не указали.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример возврата опции методом MongoDB\Driver\ReadPreference::getMaxStalenessSeconds()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

Результат выполнения приведённого примера:

    int(-1)
    int(-1)
    int(90)
    int(1000)

### Смотрите также

- » Руководство по предпочтению чтения

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Возвращает опцию "mode" объекта ReadPreference

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\Driver\ReadPreference::getModeString().

### Описание

final public function MongoDB\Driver\ReadPreference::getMode(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает параметр "mode" ReadPreference

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Метод удалили.

### Примеры

Пример #1 Пример возврата опции методом MongoDB\Driver\ReadPreference::getMode()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getMode());

    ?>

Результат выполнения приведённого примера:

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### Смотрите также

- MongoDB\Driver\ReadPreference::getModeString() - Возвращает опцию "mode" объекта ReadPreference в виде строки
- » Документация к Read Preference

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Возвращает опцию "mode" объекта ReadPreference в виде строки

### Описание

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает опцию "mode" объекта ReadPreference в виде строки.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример возврата опции методом MongoDB\Driver\ReadPreference::getModeString()

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getModeString());

    ?>

Результат выполнения приведённого примера:

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### Смотрите также

- MongoDB\Driver\ReadPreference::getMode() - Возвращает опцию "mode" объекта ReadPreference
- » Документация к Read Preference

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Возвращает опцию "tagSets" объекта ReadPreference

### Описание

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает опцию "tagSets" объекта ReadPreference.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример возврата опции методом MongoDB\Driver\ReadPreference::getTagSets()

    <?php

    $mode = MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED;

    /* Null и пустой массив говорят, что нет предпочтений в наборе тегов */
    $rp = new MongoDB\Driver\ReadPreference($mode, null);
    var_dump($rp->getTagSets());

    $rp = new MongoDB\Driver\ReadPreference($mode, []);
    var_dump($rp->getTagSets());

    /* Выбрать узел в Нью-Йорке, но вернуться к любому доступному резервному узлу */
    $rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
    var_dump($rp->getTagSets());

    /* Выбрать узел в Нью-Йорке, за которым следует узел в Сан-Франциско,
       который пометили для использования в отчётах, и, наконец, вернуться к любому доступному резервному узлу */
    $rp = new MongoDB\Driver\ReadPreference($mode, [
        ['dc' => 'ny'],
        ['dc' => 'sf', 'use' => 'reporting'],
        [],
    ]);
    var_dump($rp->getTagSets());

    ?>

Результат выполнения приведённого примера:

    array(0) {
    }
    array(0) {
    }
    array(2) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(0) {
      }
    }
    array(3) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(2) {
        ["dc"]=>
        string(2) "sf"
        ["use"]=>
        string(9) "reporting"
      }
      [2]=>
      array(0) {
      }
    }

### Смотрите также

- » Справочная информация по предпочтению чтения

## Содержание

- MongoDB\Driver\ReadPreference::bsonSerialize — Возвращает объект для BSON-сериализации
- MongoDB\Driver\ReadPreference::__construct — Создаёт новый объект предпочтения чтения ReadPreference
- MongoDB\Driver\ReadPreference::getHedge — Возвращает опцию "hedge" объекта ReadPreference
- MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Возвращает опцию "maxStalenessSeconds" объекта ReadPreference
- MongoDB\Driver\ReadPreference::getMode — Возвращает опцию "mode" объекта ReadPreference
- MongoDB\Driver\ReadPreference::getModeString — Возвращает опцию "mode" объекта ReadPreference в виде строки
- MongoDB\Driver\ReadPreference::getTagSets — Возвращает опцию "tagSets" объекта ReadPreference

# Класс MongoDB\Driver\ReadConcern

(mongodb >=1.1.0)

## Введение

Класс MongoDB\Driver\ReadConcern контролирует уровень изоляции для операций чтения для наборов реплик и сегментов наборов реплик. Эта опция требует БД MongoDB 3.2 или новее.

## Обзор класса

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* Свойства */
public readonly ?string $level;
/* Константы */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* Методы */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## Свойства

level
  Уровень read concern. `null`, если уровень не указан.

## Предопределённые константы

`MongoDB\Driver\ReadConcern::AVAILABLE`

  По умолчанию для чтения на вторичных узлах, когда опции `afterClusterTime` и `level` не указали.

  Запрос возвращает самые последние данные экземпляра. Не гарантирует, что данные были записаны большинству членов набора реплик (то есть могут быть откаты).

  Для неохраняемых коллекций (включая коллекции в автономном развёртывании или развёртывании набора реплик), `"local"` и `"available"` гарантии чтения ведут себя одинаково.

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

`MongoDB\Driver\ReadConcern::LINEARIZABLE`

  Запрос возвращает данные, которые отражают все успешные записи, выпущенные с гарантиями записи `"majority"` и подтверждённые до начала операции чтения. Для наборов реплик, которые выполняются с параметром `writeConcernMajorityJournalDefault`, установленным в значение `true`, линеаризуемые гарантии чтения возвращают данные, которые никогда не будут откатываться.

  Если для `writeConcernMajorityJournalDefault` задано значение `false`, MongoDB не будет ожидать, что `w: "majority"` записей будет устойчивым, прежде чем подтвердить записи. Таким образом, операции записи `"majority"` могут откатываться в случае потери члена набора реплик.

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

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

  Подсказка

  Всегда используйте `maxTimeMS` с линеаризуемыми гарантиями чтения, если большинство элементов, несущих данные, недоступно. `maxTimeMS` гарантирует, что операция не блокируется бесконечно, и вместо этого гарантирует, что операция возвращает ошибку, если проблема чтения не может быть выполнена.

  Для линеаризуемых гарантий чтения требуется MongoDB 3.4.

`MongoDB\Driver\ReadConcern::LOCAL`

  По умолчанию для чтения по первичному, если `level` не указан, и для чтения по вторичному, если `level` не указан, но задано `afterClusterTime`.

  Запрос возвращает самые последние данные экземпляра. Не гарантирует, что данные были записаны большинству членов набора реплик (то есть могут быть откаты).

`MongoDB\Driver\ReadConcern::MAJORITY`

  Запрос возвращает самые последние данные экземпляра, которые были признаны записанными большинству членов в наборе реплик.

  Чтобы использовать уровень гарантий чтения `"majority"`, наборы реплик должны использовать механизм хранения WiredTiger и протокол выбора версии 1.

`MongoDB\Driver\ReadConcern::SNAPSHOT`

  Гарантия чтения `"snapshot"` доступна для транзакций с несколькими документами, а начиная с MongoDB 5.0 также доступна для некоторых операций чтения не только для транзакций с несколькими документами.

  Если транзакция не является частью причинно-согласованного сессии, после фиксации транзакции с проблемой записи `"majority"`, операции транзакции гарантированно прочитают из моментального снимка зафиксированных большинством данных.

  Если транзакция является частью причинно-согласованной сессии, при фиксации транзакции с проблемой записи `"majority"`, операции транзакции гарантированно считывают из моментального снимка данные, подтверждённые большинством, что обеспечивает причинную согласованность с операций, непосредственно предшествующей началу транзакции.

  Вне транзакций с несколькими документами, проблема чтения `"snapshot"` доступна на первичных и вторичных серверах для следующих операций чтения: `find`, `aggregate` и `distinct` (для необработанных коллекций). Все остальные команды чтения запрещают `"snapshot"`.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.
PECL mongodb 1.11.0 | Добавлена константа `MongoDB\Driver\ReadConcern::SNAPSHOT`.
PECL mongodb 1.7.0 | Реализует Serializable.
PECL mongodb 1.4.0 | Добавлена константа `MongoDB\Driver\ReadConcern::AVAILABLE`.
PECL mongodb 1.2.0 | Добавлена константа `MongoDB\Driver\ReadConcern::LINEARIZABLE`. Реализует MongoDB\BSON\Serializable.

## Смотрите также

- » Справка по гарантиям чтения

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Возвращает объект для сериализации BSON

### Описание

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект для сериализации объекта ReadConcern в формате BSON.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\ReadConcern::bsonSerialize() с пустыми гарантиями чтения

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (0) {
    }

    { }

Пример #2 Пример использования MongoDB\Driver\ReadConcern::bsonSerialize() с локальными гарантиями чтения

    <?php

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ
- » Справка по гарантиям чтения

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Создаёт новый ReadConcern

### Описание

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Создаёт новый MongoDB\Driver\ReadConcern, который является объектом неизменяемого значения.

### Список параметров

`level`
  » Уровень гарантий чтения. Вы можете использовать, но не ограничиваясь этим, одну из констант класса.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\ReadConcern::__construct()

    <?php

    /* Неуказанный уровень изоляции чтения (использует поведение сервера по умолчанию) */
    $rc = new MongoDB\Driver\ReadConcern();

    /* Запрашиваем изоляцию чтения от одного узла набора реплик */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

    /* Запрашиваем изоляцию чтения от большинства узлов набора реплик */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

    ?>

### Смотрите также

- » Справка по гарантиям чтения

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Возвращает опцию "level" ReadConcern

### Описание

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает опцию "level" ReadConcern.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\ReadConcern::getLevel()

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->getLevel());

    ?>

Результат выполнения приведённого примера:

    NULL
    string(5) "local"
    string(8) "majority"

### Смотрите также

- » Справка по гарантиям чтения

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Проверяет, является ли гарантией чтения по умолчанию

### Описание

final public function MongoDB\Driver\ReadConcern::isDefault(): bool

Возвращает, является ли это гарантией чтения по умолчанию (т.е. параметры не указаны). Этот метод в первую очередь предназначен для использования в сочетании с MongoDB\Driver\Manager::getReadConcern(), чтобы определить, был ли построен Manager без каких-либо гарантий чтения.

Драйвер не будет включать в себя гарантии чтения по умолчанию в своих операциях чтения (например, MongoDB\Driver\Manager::executeQuery()), чтобы сервер мог применять свои собственные значения по умолчанию. Библиотеки, которые обращаются к гарантиям чтения Manager, чтобы включить его в свои собственные команды чтения, должны использовать этот метод, чтобы гарантировать, что гарантии чтения по умолчанию остаются неустановленными.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если это гарантии чтения по умолчанию, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\ReadConcern::isDefault()

    <?php

    $rc = new MongoDB\Driver\ReadConcern(null);
    var_dump($rc->isDefault());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- MongoDB\Driver\Manager::getReadConcern() - Возвращает ReadConcern для Manager
- » Справка по гарантиям чтения

## Содержание

- MongoDB\Driver\ReadConcern::bsonSerialize — Возвращает объект для сериализации BSON
- MongoDB\Driver\ReadConcern::__construct — Создаёт новый ReadConcern
- MongoDB\Driver\ReadConcern::getLevel — Возвращает опцию "level" ReadConcern
- MongoDB\Driver\ReadConcern::isDefault — Проверяет, является ли гарантией чтения по умолчанию

# Класс MongoDB\Driver\Cursor

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\Cursor содержит результаты команды MongoDB command или запроса и может быть возвращён MongoDB\Driver\Manager::executeCommand() или MongoDB\Driver\Manager::executeQuery() соответственно.

## Обзор класса

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* Методы */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function valid(): bool
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 1.9.0 | Класс теперь реализует интерфейс Iterator.
PECL-модуль mongodb 1.6.0 | Класс теперь реализует интерфейс MongoDB\Driver\CursorInterface, который наследует Traversable.

## Примеры

Пример #1 Reading a result set

Методы MongoDB\Driver\Manager::executeCommand() и MongoDB\Driver\Manager::executeQuery() возвращают результаты в виде объекта MongoDB\Driver\Cursor.

Поскольку класс MongoDB\Driver\Cursor реализует интерфейс Traversable, программистам доступна итерация по набору результата конструкцией `foreach`.

    <?php

    $manager = new MongoDB\Driver\Manager();

    /* Вставить определённые документы, чтобы наш запрос вернул результаты */
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
    $bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
    $manager->executeBulkWrite("test.asteroids", $bulkWrite);

    /* Запрос на получение всех элементов в коллекции */
    $query = new MongoDB\Driver\Query( [] );

    /* Запрос коллекции "asteroids" базы данных "test" */
    $cursor = $manager->executeQuery("test.asteroids", $query);

    /* Теперь $cursor содержит объект, обёрнутый вокруг набора с результатом. Используйте
     * foreach() для итеации по всему результату */
    foreach ($cursor as $document) {
        print_r($document);
    }

    ?>

Вывод приведённого примера будет похож на:

    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc2
            )

        [name] => Ceres
        [size] => 946
        [distance] => 2.766
    )
    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc3
            )

        [name] => Vesta
        [size] => 525
        [distance] => 2.362
    )

Пример #2 Чтение набора результатов для хвостового курсора

» Хвостовые курсоры — особый тип курсора СУБД MongoDB, который разрешает клиенту читать отдельные результаты, а затем ждать, пока не появятся дополнительные документы. Эти курсоры часто используются с » Capped Collections и » Change Streams.

Хотя стандартные курсоры возможно перебрать конструкцией `foreach` один раз, этот подход не сработает с хвостовыми курсорами. Цикл останавливается по достижении конца начального набора результатов, когда хвостовой курсор перебирают конструкцией `foreach`. Попытка продолжить итерацию курсора со вторым `foreach` выбросить исключение, поскольку PHP пытается перемотать курсор. Подобно объектам результатов в других драйверах баз данных, курсоры в СУБД MongoDB поддерживают только продвижение вперёд, поэтому их нельзя перемотать.

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

Продемонстрируем хвостовой курсор в действии, для этого напишем два скрипта: «производитель» (producer) и «потребитель» (consumer). Скрипт продюсера создаст новую capped-коллекцию командой » create и начнёт вставку нового документа в эту коллекцию каждую секунду.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $manager->executeCommand('test', new MongoDB\Driver\Command([
        'create' => 'asteroids',
        'capped' => true,
        'size' => 1048576,
    ]));

    while (true) {
        $bulkWrite = new MongoDB\Driver\BulkWrite;
        $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
        $manager->executeBulkWrite('test.asteroids', $bulkWrite);

        sleep(1);
    }

    ?>

Пока скрипт продюсера (producer) запущен, выполняют второй пользовательский скрипт для чтения вставленных документов с помощью хвостового (tailable) курсора, обозначенного параметрами `tailable` и `awaitData` в методе MongoDB\Driver\Query::__construct().

    <?php

    $manager = new MongoDB\Driver\Manager;

    $query = new MongoDB\Driver\Query([], [
        'tailable' => true,
        'awaitData' => true,
    ]);

    $cursor = $manager->executeQuery('test.asteroids', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();

    while (true) {
        if ($iterator->valid()) {
            $document = $iterator->current();
            printf("Пользовательский документ создан: %s\n", $document->createdAt);
        }

        $iterator->next();
    }

    ?>

Пользовательский скрипт начнёт с быстрой печати всех доступных документов в заблокированной коллекции, как если бы коллекцию перебирали конструкцией `foreach`; но при достижении конца начального набора результатов перебор не завершится. Поскольку курсор хвостовой, вызов метода IteratorIterator::valid() будет блокировать и ждать дополнительных результатов. Метод IteratorIterator::valid() также используется для проверки наличия на каждом этапе данных, доступных для чтения.

> Замечание: В этом примере используется опция запроса `awaitData`, чтобы проинструктировать сервер блокировать в течение короткого периода (например, одну секунду) в конце набора результатов перед возвратом ответа драйверу. Это используется для предотвращения агрессивного опроса (polling) сервера при отсутствии результатов. Параметр `maxAwaitTimeMS` может использоваться в сочетании с `tailable` и `awaitData`, чтобы указать время, которое сервер должен блокировать, когда он достигнет конца набора результатов.

## Ошибки

При итерации по объекту курсора BSON-данные преобразовываются в PHP-переменные. Эта итерация иногда вызывает следующие исключения:

- Выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если невозможно создать класс на карте типов или класс не реализует интерфейс MongoDB\BSON\Unserializable.
- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если во входных данных передали больше одного BSON-документа. Возможные причины включают, но не ограничиваются недопустимым BSON-форматом, лишними данными или неожиданной ошибкой » libbson.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Создаёт новый объект Cursor (не используется)

### Описание

final private function MongoDB\Driver\Cursor::__construct()

Объекты MongoDB\Driver\Cursor возвращаются в результате выполнения команды или запроса и не могут быть созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных
- MongoDB\Driver\Manager::executeQuery() - Выполняет запрос к базе данных
- MongoDB\Driver\Server::executeCommand() - Выполняет команду базы данных на сервере
- MongoDB\Driver\Server::executeQuery() - Выполняет запрос к базе данных на сервере

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Возвращает текущий элемент

### Описание

public function MongoDB\Driver\Cursor::current(): array|object|null

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает текущий документ в виде массива или объекта, в зависимости от настроек курсора. Если итерация не была начата, либо текущая позиция не корректна, будет возвращён `null`.

### Смотрите также

- Iterator::current() - Возврат текущего элемента

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Возвращает идентификатор текущего курсора

### Описание

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Метод возвращает идентификатор текущего курсора. На сервере каждому курсору присваивается уникальный идентификатор.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор текущего курсора. Метод вернёт идентификатор как объект MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Тип значения возврата изменили на MongoDB\BSON\Int64. Параметр `asInt64` удалили.
PECL-модуль mongodb 1.20.0 | Возврат объекта MongoDB\Driver\CursorId устарел. Добавили параметр `asInt64`, чтобы упростить переход на будущие версии. Идентификатор вернётся как объект MongoDB\BSON\Int64, если для параметра `asInt64` установили значение `true`.

### Примеры

Пример #1 Пример получения идентификатора курсора методом MongoDB\Driver\Cursor::getId()

    <?php

    /** Пример добавляет набор документов в коллекцию и указывает
     * меньший batchSize, чтобы гарантировать, что первый пакет содержит только
     * подмножество результатов, а курсор остаётся открытым на сервере
     */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite();
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getId(true));

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### Смотрите также

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Возвращает сервер, связанный с курсором

### Описание

final public function MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Возвращает MongoDB\Driver\Server, связанный с курсором. Это сервер, который выполнил MongoDB\Driver\Query или MongoDB\Driver\Command.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает MongoDB\Driver\Server, связанный с курсором.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Cursor::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getServer());

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\Server)#5 (10) {
      ["host"]=>
      string(9) "localhost"
      ["port"]=>
      int(27017)
      ["type"]=>
      int(1)
      ["is_primary"]=>
      bool(false)
      ["is_secondary"]=>
      bool(false)
      ["is_arbiter"]=>
      bool(false)
      ["is_hidden"]=>
      bool(false)
      ["is_passive"]=>
      bool(false)
      ["last_hello_response"]=>
      array(8) {
        ["isWritablePrimary"]=>
        bool(true)
        ["maxBsonObjectSize"]=>
        int(16777216)
        ["maxMessageSizeBytes"]=>
        int(48000000)
        ["maxWriteBatchSize"]=>
        int(1000)
        ["localTime"]=>
        object(MongoDB\BSON\UTCDateTime)#6 (1) {
          ["milliseconds"]=>
          int(1446505367907)
        }
        ["maxWireVersion"]=>
        int(3)
        ["minWireVersion"]=>
        int(0)
        ["ok"]=>
        float(1)
      }
      ["round_trip_time"]=>
      int(584)
    }

### Смотрите также

- MongoDB\Driver\Server

# MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Проверяет, исчерпан ли курсор или может содержать дополнительные результаты

### Описание

final public function MongoDB\Driver\Cursor::isDead(): bool

Проверяет, нет ли у курсора дополнительных результатов. Этот метод аналогичен методу » cursor.isExhausted() в оболочке MongoDB и в первую очередь полезен при выполнении итерации » хвостовых курсоров.

Курсор не имеет дополнительных результатов и считается "мёртвым", если выполняется одно из следующих условий:

- Текущий пакет был полностью повторён и идентификатор курсора равен нулю (то есть » getMore не может быть выполнен).
- Произошла ошибка при итерации курсора.
- Курсор достиг своего установленного предела.

Преднамеренно не всегда возможно определить, имеет ли курсор дополнительные результаты. Случаи, когда курсор может иметь больше доступных данных, следующие:

- В текущем пакете есть дополнительные документы, которые буферизируются на стороне клиента. Итерация извлечёт документ из локального буфера.
- В текущем пакете нет дополнительных документов (то есть локального буфера), но идентификатор курсора не равен нулю. Итерация будет запрашивать больше документов с сервера с помощью операции » getMore, которая может возвращать или не возвращать дополнительные результаты и/или указывать, что курсор был закрыт на сервере, возвращая ноль для его идентификатора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если курсор не содержит никаких дополнительных результатов и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Cursor::isDead()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- » Хвостовые курсоры в руководстве MongoDB
- » cursor.isExhausted() в руководстве MongoDB

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Возвращает индекс текущего результата в курсоре

### Описание

public function MongoDB\Driver\Cursor::key(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Числовой индекс текущего результата в курсоре.

### Смотрите также

- Iterator::key() - Возвращает ключ текущего элемента

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Перемещает курсор на следующий результат

### Описание

public function MongoDB\Driver\Cursor::next(): void

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Сдвигает текущую позицию к следующему результату в курсоре.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.

### Смотрите также

- Iterator::next() - Переходит к следующему элементу

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Перемещает курсор к первому результату

### Описание

public function MongoDB\Driver\Cursor::rewind(): void

Если курсор продвинулся дальше своей первой позиции, то его переместить к первому результату уже не получится.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`null`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Бросает исключение MongoDB\Driver\Exception\LogicException если метод был вызван после продвижения курсора дальше своей первой позиции.

### Смотрите также

- Iterator::rewind() - Возвращает итератор на первый элемент

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Устанавливает карту типа для десериализации BSON

### Описание

final public function MongoDB\Driver\Cursor::setTypeMap(array `$typemap`): void

Устанавливает конфигурацию карты типов, которая будет использоваться при десериализации результатов BSON в значения PHP.

### Список параметров

`typeMap` (array)
  Конфигурация карты типов.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

При итерации по курсору может выбрасываться следующие исключения из-за неправильной конфигурации карты типов:

- Выбрасывает MongoDB\Driver\Exception\InvalidArgumentException, если класс на карте типов не может быть создан или не реализует MongoDB\BSON\Unserializable.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Cursor::setTypeMap()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $id = $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query(['_id' => $id]);
    $cursor = $manager->executeQuery('db.collection', $query);
    $cursor->setTypeMap(['root' => 'array']);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### Смотрите также

- Сохранение данных

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Возвращает массив, содержащий все результаты курсора

### Описание

final public function MongoDB\Driver\Cursor::toArray(): array

Итерирует курсор и возвращает его результаты в виде массива. MongoDB\Driver\Cursor::setTypeMap() может использоваться для управления тем, как документы десериализованы в значение PHP.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив (array), содержащий все результаты курсора.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Cursor::toArray()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query([]);
    $cursor = $manager->executeQuery('db.collection', $query);

    var_dump($cursor->toArray());

    ?>

Вывод приведённого примера будет похож на:

    array(3) {
      [0]=>
      object(stdClass)#6 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#5 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf61"
        }
        ["x"]=>
        int(1)
      }
      [1]=>
      object(stdClass)#8 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#7 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf62"
        }
        ["x"]=>
        int(2)
      }
      [2]=>
      object(stdClass)#10 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#9 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf63"
        }
        ["x"]=>
        int(3)
      }
    }

### Смотрите также

- MongoDB\Driver\Cursor::setTypeMap() - Устанавливает карту типа для десериализации BSON

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Проверяет, корректна ли текущая позиция курсора

### Описание

public function MongoDB\Driver\Cursor::valid(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если позиция корректна и `false`, если нет.

### Смотрите также

- Iterator::valid() - Проверяет корректность текущей позиции

## Содержание

- MongoDB\Driver\Cursor::__construct — Создаёт новый объект Cursor (не используется)
- MongoDB\Driver\Cursor::current — Возвращает текущий элемент
- MongoDB\Driver\Cursor::getId — Возвращает идентификатор текущего курсора
- MongoDB\Driver\Cursor::getServer — Возвращает сервер, связанный с курсором
- MongoDB\Driver\Cursor::isDead — Проверяет, исчерпан ли курсор или может содержать дополнительные результаты
- MongoDB\Driver\Cursor::key — Возвращает индекс текущего результата в курсоре
- MongoDB\Driver\Cursor::next — Перемещает курсор на следующий результат
- MongoDB\Driver\Cursor::rewind — Перемещает курсор к первому результату
- MongoDB\Driver\Cursor::setTypeMap — Устанавливает карту типа для десериализации BSON
- MongoDB\Driver\Cursor::toArray — Возвращает массив, содержащий все результаты курсора
- MongoDB\Driver\Cursor::valid — Проверяет, корректна ли текущая позиция курсора

# Класс MongoDB\Driver\CursorId

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\CursorID — объект значения, который представляет идентификатор курсора. Экземпляры класса возвращает метод MongoDB\Driver\Cursor::getId().

Внимание

Класс УСТАРЕЛ с версии модуля 1.20.0, а в версии 2.0 класс удалили. В приложениях требуется обновить метод MongoDB\Driver\Cursor::getId(), чтобы вместо объектов этого класса метод возвращал объекты класса MongoDB\BSON\Int64.

## Обзор класса

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* Методы */
final private function __construct()
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс удалили.
PECL-модуль mongodb 1.20.0 | Класс устарел и его удалят в версии 2.0.
PECL mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.7.0 | Класс теперь реализует интерфейс Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Создаёт новый объект CursorId (не используется)

### Описание

final private function MongoDB\Driver\CursorId::__construct()

Объекты MongoDB\Driver\CursorId возвращаются из MongoDB\Driver\Cursor::getId() и не могут созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\Driver\Cursor::getId() - Возвращает идентификатор текущего курсора

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — Строковое представление идентификатора курсора

### Описание

final public function MongoDB\Driver\CursorId::__toString(): string

Возвращает идентификатор курсора в виде строки (string).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор курсора в виде строки (string).

### Примеры

Пример #1 Пример использования MongoDB\Driver\CursorId::__toString()

    <?php

    /* В этом примере мы добавляем документы в коллекцию и указываем
     * меньший batchSize, чтобы гарантировать, что первая порция содержит только подмножество
     * наших результатов и курсор остаётся открытым на сервере. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump((string) $cursor->getId());

    ?>

Вывод приведённого примера будет похож на:

    string(11) "98061641158"

### Смотрите также

- MongoDB\Driver\Cursor::getId() - Возвращает идентификатор текущего курсора

## Содержание

- MongoDB\Driver\CursorId::__construct — Создаёт новый объект CursorId (не используется)
- MongoDB\Driver\CursorId::__toString — Строковое представление идентификатора курсора

# Интерфейс MongoDB\Driver\CursorInterface

(mongodb >=1.6.0)

## Введение

Интерфейс, реализованный MongoDB\Driver\Cursor, но также может использоваться в качестве параметра, возвращаемого значения или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\Driver\CursorInterface implements Iterator {
/* Методы */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Интерфейс теперь расширяет интерфейс Iterator. Типы значений возврата, которые прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Возвращает идентификатор текущего курсора

### Описание

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Метод возвращает идентификатор текущего курсора. На сервере каждому курсору присваивается уникальный идентификатор.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает уникальный идентификатор текущего курсора.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 1.20.0 | В предварительный тип значения, которое возвращает метод, добавили тип MongoDB\BSON\Int64. Тип MongoDB\Driver\CursorId удалят из типа возврата в версии 2.0.

### Смотрите также

- MongoDB\Driver\Cursor::getId() - Возвращает идентификатор текущего курсора
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Возвращает сервер, с которым связан курсор

### Описание

abstract public function MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Возвращает MongoDB\Driver\Server связанный с курсором. Это тот сервер, на котором запущены MongoDB\Driver\Query или MongoDB\Driver\Command.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает MongoDB\Driver\Server связанный с курсором.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Cursor::getServer() - Возвращает сервер, связанный с курсором
- MongoDB\Driver\Server

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Проверить, можно ли ещё получить из курсора результаты

### Описание

abstract public function MongoDB\Driver\CursorInterface::isDead(): bool

Проверяет, можно ли попытаться получить из курсора результаты. Изначально курсор находится в статусе "жив"(alive), но в следующих случаях может перейти в статус "мёртв"(dead):

- При очередной вычитке не хвостового курсора не был возвращён документ
- Произошла ошибка
- Курсор прочитал последний батч до завершения
- Курсор достиг предустановленного лимита

Это в первую очередь полезно при работе с хвостовыми курсорами.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если запросить очередной результат не получится или `false`, если он ещё "жив".

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Cursor::isDead() - Проверяет, исчерпан ли курсор или может содержать дополнительные результаты

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Задать сопоставление типов для десериализации BSON

### Описание

abstract public function MongoDB\Driver\CursorInterface::setTypeMap(array `$typemap`): void

Задать сопоставление типов для использования при десериализации результатов BSON в значения PHP.

### Список параметров

`typeMap` (array)
  Конфигурация карты типов.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Cursor::setTypeMap() - Устанавливает карту типа для десериализации BSON
- Сохранение данных

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Вернуть все результаты для данного курсора в виде массива

### Описание

abstract public function MongoDB\Driver\CursorInterface::toArray(): array

Итерирует курсор и возвращает результаты в виде массива. Для контроля десериализации в типы PHP можно использовать MongoDB\Driver\CursorInterface::setTypeMap().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив, содержащий все результаты курсора.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Cursor::toArray() - Возвращает массив, содержащий все результаты курсора
- MongoDB\Driver\CursorInterface::setTypeMap() - Задать сопоставление типов для десериализации BSON

## Содержание

- MongoDB\Driver\CursorInterface::getId — Возвращает идентификатор текущего курсора
- MongoDB\Driver\CursorInterface::getServer — Возвращает сервер, с которым связан курсор
- MongoDB\Driver\CursorInterface::isDead — Проверить, можно ли ещё получить из курсора результаты
- MongoDB\Driver\CursorInterface::setTypeMap — Задать сопоставление типов для десериализации BSON
- MongoDB\Driver\CursorInterface::toArray — Вернуть все результаты для данного курсора в виде массива

# Класс MongoDB\Driver\Server

(mongodb >=1.0.0)

## Введение

## Обзор класса

final class MongoDB\Driver\Server {
/* Константы */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* Методы */
final private function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function isSecondary(): bool
}

## Предопределённые константы

`MongoDB\Driver\Server::TYPE_UNKNOWN`

  Неизвестный тип сервера, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_STANDALONE`

  Автономный тип сервера, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_MONGOS`

  Тип сервера Mongos, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY`

  Тип набора реплик возможного основного сервера, который возвращает метод MongoDB\Driver\Server::getType().

  Сервер может быть идентифицирован как возможный основной, если он ещё не был проверен, но другой член набора реплик думает, что он основной.

`MongoDB\Driver\Server::TYPE_RS_PRIMARY`

  Тип набора реплик основного сервера, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_RS_SECONDARY`

  Тип набора реплик вторичного сервера, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_RS_ARBITER`

  Тип набора реплик арбитра сервера, который возвращает метод MongoDB\Driver\Server::getType().

`MongoDB\Driver\Server::TYPE_RS_OTHER`

  Другой тип набора реплик сервера, который возвращает метод MongoDB\Driver\Server::getType().

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

`MongoDB\Driver\Server::TYPE_RS_GHOST`

  Призрачный тип набора реплик, который возвращает метод MongoDB\Driver\Server::getType().

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

`MongoDB\Driver\Server::TYPE_LOAD_BALANCER`

  Тип сервера балансировщика нагрузки, который возвращает метод MongoDB\Driver\Server::getType().

## Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.11.0 | Добавлена константа `MongoDB\Driver\Server::TYPE_LOAD_BALANCER`.

# MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Создаёт новый Server (не используется)

### Описание

final private function MongoDB\Driver\Server::__construct()

Объекты MongoDB\Driver\Server создаются внутри MongoDB\Driver\Manager, когда соединение с базой данных установлено и могут быть возвращены MongoDB\Driver\Manager::getServers() и MongoDB\Driver\Manager::selectServer().

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\Driver\Manager::getServers() - Возвращает серверы, к которым подключён менеджер
- MongoDB\Driver\Manager::selectServer() - Выбрать сервер, соответствующий предпочтениям чтения

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Выполняет операции записи на сервере

### Описание

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Метод выполняет одну или несколько операций записи на первичном сервере.

Объект MongoDB\Driver\BulkWrite создают с одной или набором операций записи разного типа, например обновления, удаления и вставки. Драйвер попытается отправить операции одного типа на сервер как можно меньшим количеством запросов, чтобы сократить обращения к серверу.

Значение по умолчанию для параметра `writeConcern` метод получит из активной транзакции (указывает параметр `session`), за которой следует URI-идентификатор соединения.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`bulk` (MongoDB\Driver\BulkWrite)
  Записи для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

### Возвращаемые значения

Метод возвращает экземпляр класса MongoDB\Driver\WriteResult, если выполнился успешно.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит операций записи.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если уже выполнил операции параметра `bulk`. Объекты MongoDB\Driver\BulkWrite нельзя выполнять многократно.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При ошибке записи метод выбрасывает исключение MongoDB\Driver\Exception\BulkWriteException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При других ошибках метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\WriteConcern.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\WriteConcern как опции параметра `options` устарела, а в версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"session"` указать вместе с неподтверждаемым уровнем записи.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.3.0 | Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит операций записи. Раньше метод выбрасывал исключение MongoDB\Driver\Exception\BulkWriteException.

### Примечания

> Замечание: Ответственность вызывающего кода заключается в том, что сервер в состоянии выполнять операцию записи. Например, выполнение операции записи на вторичном узле (исключая «локальную» базу данных) завершится неудачей.

### Смотрите также

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Выполняет операции записи на текущем сервере командой bulkWrite

### Описание

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Метод выполняет одну или несколько операций записи на текущем сервере командой » bulkWrite, которая появилась в MongoDB 8.0.

Объект класса MongoDB\Driver\BulkWriteCommand создают с одной или несколькими операциями записи: вставки, обновления или удаления. Каждую операцию записи возможно нацелить на разные коллекции.

Значение по умолчанию для опции `"writeConcern"` автоматически определяется на основе активной транзакции или URI-идентификатора соединения, если транзакция не содержит значения. На активную транзакцию указывает опция `"session"`.

### Список параметров

`bulk` (MongoDB\Driver\BulkWriteCommand)
  Одна или несколько операций записи для выполнения.
`options`

  Опции
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

### Возвращаемые значения

Метод возвращает объект класса MongoDB\Driver\BulkWriteCommandResult, если выполнился успешно.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если параметр `bulk` не содержит ни одной операции записи.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если операции в параметре `bulk` уже выполнились. Объекты MongoDB\Driver\BulkWriteCommand невозможно выполнить многократно.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\BulkWriteCommandException при ошибках записи наподобие сбоя команды, ошибки записи или ошибки подтверждения записи.
- При других ошибках метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Смотрите также

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Выполняет команду базы данных на сервере

### Описание

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на сервере.

Этот метод не применяет специальной логики к команде. Значения по умолчанию для параметров `readPreference`, `readConcern` и `writeConcern` метод получит из активной транзакции, которую обозначает параметр `session`. Если активной транзакции нет, для выбора сервера будет использоваться основное предпочтение чтения.

Метод не получает значения по умолчанию из URI-идентификатора соединения. Поэтому пользователям рекомендуют по возможности использовать конкретные методы команд чтения и (или) записи.

> Замечание: Опция `"readPreference"` не управляет сервером, на который драйвер отправляет операцию; опция выполняется только на этом объекте сервера. Вместо этого опцию указывают при выполнении операции на вторичном узле (из соединения с набором реплик, а не на автономном) или на узле mongos, чтобы гарантировать, что драйвер устанавливает правильный протокол передачи данных или добавляет предпочтение чтения к операции.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При других ошибках наподобие неправильной команды или выдачи команды записи на вторичное устройство метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\ReadPreference как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опцию `"session"` указать вместе с неподтверждаемым уровнем записи.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\ReadPreference.

### Примечания

> Замечание: Ответственность вызывающего кода заключается в том, что сервер в состоянии выполнять операцию записи. Например, выполнение операции записи на вторичном узле (исключая «локальную» базу данных) завершится неудачей.

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeReadCommand() - Выполняет команду базы данных, которая читает на сервере
- MongoDB\Driver\Server::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет на сервере
- MongoDB\Driver\Server::executeWriteCommand() - Выполняет команду базы данных, которая пишет на сервере
- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Выполняет запрос к базе данных на сервере

### Описание

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет запрос на сервере.

Значения по умолчанию для опциии `"readPreference"` и Query-опции `"readConcern"` метод получит из активной транзакции, за которой следует URI-идентификатор соединения. Активную транзакцию обозначает опция `session`.

> Замечание: Опция `"readPreference"` не управляет сервером, на который драйвер отправляет операцию; опция выполняется только на этом объекте сервера. Вместо этого опцию указывают при выполнении операции на вторичном узле (из соединения с набором реплик, а не на автономном) или на узле mongos, чтобы гарантировать, что драйвер устанавливает правильный протокол передачи данных или добавляет предпочтение чтения к операции.

### Список параметров

`namespace` (string)
  Полностью определённое имя (т. е. `"databaseName.collectionName"`).
`query` (MongoDB\Driver\Query)
  Запрос для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- При других ошибках наподобие недопустимых операторов запроса метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `options` больше не принимает объекты MongoDB\Driver\ReadPreference.
PECL-модуль mongodb 1.21.0 | Передача объекта MongoDB\Driver\ReadPreference как опции параметра `options` устарела, а с версии 2.0 передачу объекта запретят.
PECL-модуль mongodb 1.4.0 | Третий параметр `options` стал массивом опций, но в целях обратной совместимости пока ещё принимает объект MongoDB\Driver\ReadPreference.

### Смотрите также

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::executeQuery() - Выполняет запрос к базе данных

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Выполняет команду базы данных, которая читает на сервере

### Описание

final public function MongoDB\Driver\Server::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на сервере независимо от параметра `readPreference`.

Метод будет применять логику, специфичную для команд, которые читают (например, » distinct). Значения по умолчанию для параметров `readPreference` и `readConcern` метод получит из активной транзакции (указывает параметр `session`), за которой следует URI-идентификатор соединения.

> Замечание: Опция `"readPreference"` не управляет сервером, на который драйвер отправляет операцию; опция выполняется только на этом объекте сервера. Вместо этого опцию указывают при выполнении операции на вторичном узле (из соединения с набором реплик, а не на автономном) или на узле mongos, чтобы гарантировать, что драйвер устанавливает правильный протокол передачи данных или добавляет предпочтение чтения к операции.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  readPreference | MongoDB\Driver\ReadPreference | Предпочтение чтения, используемая для выбора сервера для выполнения операции.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывет исключение MongoDB\Driver\Exception\RuntimeException на другие ошибки (например, неверную команду).

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Выполняет команду базы данных на сервере
- MongoDB\Driver\Server::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет на сервере
- MongoDB\Driver\Server::executeWriteCommand() - Выполняет команду базы данных, которая пишет на сервере
- MongoDB\Driver\Manager::executeReadCommand() - Выполняет команду базы данных, которая читает

# MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Выполняет команду базы данных, которая читает и пишет на сервере

### Описание

final public function MongoDB\Driver\Server::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на сервере.

Этот метод будет применять логику, специфичную для команд, которые читают и пишут (например » aggregate). Значения по умолчанию для параметров `readConcern` `writeConcern` метод получит из активной транзакции (указывает параметр `session`), за которой следует URI-идентификатор соединения.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Гарантия чтения для применения к операции. Эта опция доступна в MongoDB 3.2+ и приведёт к исключению во время выполнения, если указана для более старой версии сервера.
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выдаёт исключение MongoDB\Driver\Exception\RuntimeException на другие ошибки (например, неверную команду).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.4.4 | Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `session` используется в сочетании с неподтверждённой записью.

### Примечания

> Замечание: Ответственность вызывающего кода заключается в том, что сервер в состоянии выполнять операцию записи. Например, выполнение операции записи на вторичном узле (исключая «локальную» базу данных) завершится неудачей.

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Выполняет команду базы данных на сервере
- MongoDB\Driver\Server::executeReadCommand() - Выполняет команду базы данных, которая читает на сервере
- MongoDB\Driver\Server::executeWriteCommand() - Выполняет команду базы данных, которая пишет на сервере
- MongoDB\Driver\Manager::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Выполняет команду базы данных, которая пишет на сервере

### Описание

final public function MongoDB\Driver\Server::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Метод выполняет команду на сервере.

Метод будет применять логику, специфичную для команд, которые пишут (например, » drop). Значение по умолчанию для параметра `writeConcern` метод получит из активной транзакции (указывает параметр `session`), за которой следует URI-идентификатор соединения.

> Замечание: Метод не предназначен для выполнения запросов » insert, » update, или » delete команд. Пользователям рекомендуется пользоваться методом MongoDB\Driver\Server::executeBulkWrite() для этих операций.

### Список параметров

`db` (string)
  Название базы данных, в которой запускается команда.
`command` (MongoDB\Driver\Command)
  Команда для выполнения.
`options`

  options
  Опция | Тип | Описание
  --- | --- | ---
  session | MongoDB\Driver\Session | Сессия для связывания с операцией.
  writeConcern | MongoDB\Driver\WriteConcern | Гарантия записи для применения к операции.

  Внимание

  С парметром `"session"` и при незавершённых транзакциях нельзя указать параметр `"readConcern"` или `"writeConcern"`. Это выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException. Вместо этого две этих опции устанавливают методом MongoDB\Driver\Session::startTransaction(), когда создают транзакцию.

### Возвращаемые значения

Метод возвращает курсор MongoDB\Driver\Cursor, если выполнился успешно.

### Ошибки

- Выбрасывается исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана с соответствующей транзакцией в сочетании с опцией `"readConcern"` или `"writeConcern"`.
- Выбрасывается MongoDB\Driver\Exception\InvalidArgumentException, если опция `"session"` указана в сочетании с неподтверждённой гарантией записи.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При неудачном соединении с сервером (кроме ошибок аутентификации) метод выбрасывает исключение MongoDB\Driver\Exception\ConnectionException.
- При неудачной аутентификации метод выбрасывает исключение MongoDB\Driver\Exception\AuthenticationException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException на другие ошибки (например, неверную команду).

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.4.4 | Метод выбросит исключение MongoDB\Driver\Exception\InvalidArgumentException, если опция `session` используется в сочетании с неподтверждённой записью.

### Примечания

> Замечание: Ответственность вызывающего кода заключается в том, что сервер в состоянии выполнять операцию записи. Например, выполнение операции записи на вторичном узле (исключая «локальную» базу данных) завершится неудачей.

### Смотрите также

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Выполняет команду базы данных на сервере
- MongoDB\Driver\Server::executeReadCommand() - Выполняет команду базы данных, которая читает на сервере
- MongoDB\Driver\Server::executeReadWriteCommand() - Выполняет команду базы данных, которая читает и пишет на сервере
- MongoDB\Driver\Manager::executeWriteCommand() - Выполняет команду базы данных, которая пишет

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Server::getHost(): string

Метод возвращает имя хоста сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Server::getHost()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

Результат выполнения приведённого примера:

    string(9) "localhost"

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер
- MongoDB\Driver\ServerDescription::getHost() - Возвращает имя хоста сервера

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Возвращает массив информации, описывающий сервер

### Описание

final public function MongoDB\Driver\Server::getInfo(): array

Возвращает массив информации, описывающий сервер. Этот массив получен из последнего ответа команды » hello, полученного с помощью » мониторинга сервера.

> Замечание: Когда драйвер подключён к балансировщику нагрузки, метод вернёт ответ на команду » hello от резервного сервера при первоначальном подтверждении соединения. Это отличается от других методов (например, MongoDB\Driver\Server::getType()), которые возвращают информацию о самом балансировщике нагрузки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив информации, описывающий сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\Server::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

    $rp = new MongoDB\Driver\ReadPreference('primary');
    $server = $manager->selectServer($rp);

    var_dump($server->getInfo());

    ?>

Вывод приведённого примера будет похож на:

    array(23) {
      ["helloOk"]=>
      bool(true)
      ["topologyVersion"]=>
      array(2) {
        ["processId"]=>
        object(MongoDB\BSON\ObjectId)#4 (1) {
          ["oid"]=>
          string(24) "617b6d696a3a89d2f77e6df0"
        }
        ["counter"]=>
        int(6)
      }
      ["hosts"]=>
      array(1) {
        [0]=>
        string(15) "localhost:27017"
      }
      ["setName"]=>
      string(3) "rs0"
      ["setVersion"]=>
      int(1)
      ["ismaster"]=>
      bool(true)
      ["secondary"]=>
      bool(false)
      ["primary"]=>
      string(15) "localhost:27017"
      ["me"]=>
      string(15) "localhost:27017"
      ["electionId"]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "7fffffff0000000000000001"
      }
      ["lastWrite"]=>
      array(4) {
        ["opTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#6 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["lastWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#7 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
        ["majorityOpTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#8 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["majorityWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#9 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
      }
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(100000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#10 (1) {
        ["milliseconds"]=>
        string(13) "1635478992136"
      }
      ["logicalSessionTimeoutMinutes"]=>
      int(30)
      ["connectionId"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["maxWireVersion"]=>
      int(13)
      ["readOnly"]=>
      bool(false)
      ["ok"]=>
      float(1)
      ["$clusterTime"]=>
      array(2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#11 (2) {
          ["increment"]=>
          string(1) "1"
          ["timestamp"]=>
          string(10) "1635478989"
        }
        ["signature"]=>
        array(2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#12 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          int(0)
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#13 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
    }

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.11.0 | Когда драйвер подключён к подсистеме балансировки нагрузки, метод возвращает ответ на команду `hello` вспомогательного сервера при первоначальном подтверждении соединения.

### Смотрите также

- MongoDB\Driver\ServerDescription::getHelloResponse() - Возвращает последний ответ сервера "hello"
- Команда » hello в руководстве MongoDB
- » Руководство по обнаружению и мониторингу серверов

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Возвращает задержку сервера в миллисекундах

### Описание

final public function MongoDB\Driver\Server::getLatency(): ?integer

Метод возвращает задержку сервера в миллисекундах. » Время прохождения команды `hello`, которое измерил клиент.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает задержку сервера в миллисекундах или `null`, если клиент не измерил задержку (например, клиент подключён к балансировщику нагрузки).

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.11.0 | Метод вернёт `null`, если задержку не измерили. В предыдущих версиях при каждом вызове возвращалось целое число, а неустановленное значение иногда отображалось как `-1`.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Server::getLatency()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

Вывод приведённого примера будет похож на:

    int(592)

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер
- MongoDB\Driver\ServerDescription::getRoundTripTime() - Возвращает время обхода сервера в миллисекундах
- » Спецификация обнаружения и мониторинга сервера

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Возвращает порт, который слушает сервер

### Описание

final public function MongoDB\Driver\Server::getPort(): int

Метод возвращает порт, который слушает сервер.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает порт, который слушает сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Server::getPort()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

Результат выполнения приведённого примера:

    int(27017)

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер
- MongoDB\Driver\ServerDescription::getPort() - Возвращает порт, на котором прослушивается данный сервер

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Возвращает ServerDescription сервера

### Описание

final public function MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Возвращает MongoDB\Driver\ServerDescription сервера. Это неизменяемый объект значения, который будет описывать сервер во время вызова метода.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает MongoDB\Driver\ServerDescription сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Возвращает массив тегов, описывающих сервер в наборе реплик

### Описание

final public function MongoDB\Driver\Server::getTags(): array

Возвращает array » тегов, используемых для описания этого сервера в наборе реплик. Массив будет содержать ноль или более пар string ключей и значений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает array тегов, используемых для описания сервера в наборе реплик.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Возвращает целое число, обозначающее тип этого сервера

### Описание

final public function MongoDB\Driver\Server::getType(): int

Возвращает int, обозначающее тип этого сервера. Значение будет соответствовать константе MongoDB\Driver\Server.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает int, обозначающее тип этого сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер
- MongoDB\Driver\ServerDescription::getType() - Возвращает строку, обозначающую тип данного сервера

# MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Проверяет, является ли сервер членом-арбитром в наборе реплик

### Описание

final public function MongoDB\Driver\Server::isArbiter(): bool

Возвращает, является ли этот сервер » членом-арбитром набора реплик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если этот сервер является членом-арбитром набора реплик, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

# MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Проверяет, является ли сервер скрытым членом набора реплик

### Описание

final public function MongoDB\Driver\Server::isHidden(): bool

Возвращает, является ли этот сервер » скрытым членом набора реплик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если этот сервер является скрытым членом набора реплик, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

# MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Проверяет, является ли сервер пассивным членом набора реплик

### Описание

final public function MongoDB\Driver\Server::isPassive(): bool

Возвращает, является ли этот сервер » пассивным членом набора реплик (то есть его приоритет равен `0`).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если этот сервер является пассивным членом набора реплик, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

# MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Проверяет, является ли сервер основным членом набора реплик

### Описание

final public function MongoDB\Driver\Server::isPrimary(): bool

Возвращает, является ли этот сервер » основным членом набора реплик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если этот сервер является основным членом набора реплик, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

# MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Проверяет, является ли этот сервер второстепенным членом набора реплик

### Описание

final public function MongoDB\Driver\Server::isSecondary(): bool

Возвращает, является ли этот сервер » второстепенным членом набора реплик.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если этот сервер является второстепенным членом набора реплик, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер

## Содержание

- MongoDB\Driver\Server::__construct — Создаёт новый Server (не используется)
- MongoDB\Driver\Server::executeBulkWrite — Выполняет операции записи на сервере
- MongoDB\Driver\Server::executeBulkWriteCommand — Выполняет операции записи на текущем сервере командой bulkWrite
- MongoDB\Driver\Server::executeCommand — Выполняет команду базы данных на сервере
- MongoDB\Driver\Server::executeQuery — Выполняет запрос к базе данных на сервере
- MongoDB\Driver\Server::executeReadCommand — Выполняет команду базы данных, которая читает на сервере
- MongoDB\Driver\Server::executeReadWriteCommand — Выполняет команду базы данных, которая читает и пишет на сервере
- MongoDB\Driver\Server::executeWriteCommand — Выполняет команду базы данных, которая пишет на сервере
- MongoDB\Driver\Server::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Server::getInfo — Возвращает массив информации, описывающий сервер
- MongoDB\Driver\Server::getLatency — Возвращает задержку сервера в миллисекундах
- MongoDB\Driver\Server::getPort — Возвращает порт, который слушает сервер
- MongoDB\Driver\Server::getServerDescription — Возвращает ServerDescription сервера
- MongoDB\Driver\Server::getTags — Возвращает массив тегов, описывающих сервер в наборе реплик
- MongoDB\Driver\Server::getType — Возвращает целое число, обозначающее тип этого сервера
- MongoDB\Driver\Server::isArbiter — Проверяет, является ли сервер членом-арбитром в наборе реплик
- MongoDB\Driver\Server::isHidden — Проверяет, является ли сервер скрытым членом набора реплик
- MongoDB\Driver\Server::isPassive — Проверяет, является ли сервер пассивным членом набора реплик
- MongoDB\Driver\Server::isPrimary — Проверяет, является ли сервер основным членом набора реплик
- MongoDB\Driver\Server::isSecondary — Проверяет, является ли этот сервер второстепенным членом набора реплик

# Класс MongoDB\Driver\ServerDescription

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\ServerDescription — объект значения, который представляет сервер, к которому подключён драйвер. Экземпляры класса возвращаются методами MongoDB\Driver\Server::getServerDescription() и MongoDB\Driver\Monitoring\ServerChangedEvent.

## Обзор класса

final class MongoDB\Driver\ServerDescription {
/* Константы */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* Методы */
final public function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function getType(): string
}

## Предопределённые константы

`MongoDB\Driver\ServerDescription::TYPE_UNKNOWN`
  Неизвестный тип сервера, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_STANDALONE`
  Тип автономного сервера, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_MONGOS`
  Тип сервера Mongos, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY`
  Набор реплик возможного типа первичного сервера, который возвращает метод MongoDB\Driver\ServerDescription::getType(). Сервер может быть определён как возможный первичный, если он ещё не был проверен, но другая память набора реплик считает его первичным.
`MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY`
  Тип первичного сервера набора реплик, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY`
  Тип вторичного сервера набора реплик, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER`
  Тип сервера арбитража набора реплик, который возвращает метод MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_OTHER`
  Набор реплик другого типа сервера, который возвращает метод MongoDB\Driver\ServerDescription::getType(). Такие серверы могут быть скрыты, запускаться или восстанавливаться. Их нельзя запросить, но их списки хостов полезны для обнаружения текущей конфигурации набора реплик.
`MongoDB\Driver\ServerDescription::TYPE_RS_GHOST`

  Тип сервера-призрака набора реплик, который возвращает метод MongoDB\Driver\ServerDescription::getType().

  Серверы могут быть определены как таковые по крайней мере в трёх ситуациях: кратковременно во время запуска сервера; в неинициализированном наборе реплик; или когда сервер избегается (т. е. удаляется из конфигурации набора реплик). Они не могут быть запрошены, и их список хостов не может быть использован для обнаружения текущей конфигурации набора реплик; однако клиент может следить за этим сервером в надежде, что он перейдёт в более полезное состояние.
`MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER`
  Тип сервера балансировщика нагрузки, который возвращает метод MongoDB\Driver\ServerDescription::getType().

# MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Возвращает последний ответ сервера "hello"

### Описание

final public function MongoDB\Driver\ServerDescription::getHelloResponse(): array

Возвращает массив информации, описывающей сервер. Этот массив формируется из самого последнего (на момент создания MongoDB\Driver\ServerDescription) ответа команды » hello ответ команды, полученный с помощью » мониторинга сервера.

> Замечание: Если драйвер подключён к балансировщику нагрузки, метод вернёт пустой массив, так как балансировщики нагрузки не отслеживаются. В отличие от MongoDB\Driver\Server::getInfo(), которая возвращает ответ команды » hello от начального рукопожатия соединения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив информации, описывающей сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getInfo() - Возвращает массив информации, описывающий сервер
- Команда » hello в руководстве по MongoDB
- » Спецификация обнаружения и мониторинга серверов

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\ServerDescription::getHost(): string

Возвращает имя хоста сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getHost() - Возвращает имя хоста сервера

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Возвращает время последнего обновления сервера в микросекундах

### Описание

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Возвращает время последнего обновления сервера в микросекундах.

> Замечание: Возвращаемое значение представляет собой монотонную метку времени, которая начинается в произвольной точке. Как таковое, оно подходит только для сравнения с другими возвращаемыми значениями из функции MongoDB\Driver\ServerDescription::getLastUpdateTime().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает время последнего обновления сервера в микросекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Возвращает порт, на котором прослушивается данный сервер

### Описание

final public function MongoDB\Driver\ServerDescription::getPort(): int

Возвращает порт, на котором прослушивается данный сервер.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается данный сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getPort() - Возвращает порт, который слушает сервер

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Возвращает время обхода сервера в миллисекундах

### Описание

final public function MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Возвращает время обхода сервера в миллисекундах. Это измерение продолжительности команды » hello.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает время обхода сервера в миллисекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getLatency() - Возвращает задержку сервера в миллисекундах

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Возвращает строку, обозначающую тип данного сервера

### Описание

final public function MongoDB\Driver\ServerDescription::getType(): string

Возвращает строку (string), обозначающую тип данного сервера. Значение будет соотноситься с константой MongoDB\Driver\ServerDescription.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку (string), обозначающую тип данного сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Server::getType() - Возвращает целое число, обозначающее тип этого сервера

## Содержание

- MongoDB\Driver\ServerDescription::getHelloResponse — Возвращает последний ответ сервера "hello"
- MongoDB\Driver\ServerDescription::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\ServerDescription::getLastUpdateTime — Возвращает время последнего обновления сервера в микросекундах
- MongoDB\Driver\ServerDescription::getPort — Возвращает порт, на котором прослушивается данный сервер
- MongoDB\Driver\ServerDescription::getRoundTripTime — Возвращает время обхода сервера в миллисекундах
- MongoDB\Driver\ServerDescription::getType — Возвращает строку, обозначающую тип данного сервера

# Класс MongoDB\Driver\TopologyDescription

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\TopologyDescription — объект значения, который представляет топологию, к которой подключён драйвер. Экземпляры класса возвращаются методами класса MongoDB\Driver\Monitoring\TopologyChangedEvent.

## Обзор класса

final class MongoDB\Driver\TopologyDescription {
/* Константы */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* Методы */
final public function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function hasWritableServer(): bool
}

## Предопределённые константы

`MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN`
  Неизвестный тип топологии, который возвращает метод MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SINGLE`
  Одиночный сервер (т. е. прямое соединение), который возвращает метод MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SHARDED`
  Разделяемый кластер, который возвращает метод MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY`
  Набор реплик без первичного сервера, который возвращает метод MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY`
  Набор реплик с первичным сервером, который возвращает метод MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED`
  Сбалансированная по нагрузке топология, которую возвращает метод MongoDB\Driver\TopologyDescription::getType().

# MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Возвращает серверы в топологии

### Описание

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Возвращает массив объектов MongoDB\Driver\ServerDescription, соответствующих известным серверам в топологии.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив объектов MongoDB\Driver\ServerDescription, соответствующих известным серверам в топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Возвращает строку, обозначающую тип топологии

### Описание

final public function MongoDB\Driver\TopologyDescription::getType(): string

Возвращает строку (string), обозначающую тип топологии. Значение будет соотноситься с константой MongoDB\Driver\TopologyDescription.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку (string), обозначающую тип топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Возвращает, есть ли в топологии сервер, доступный для чтения

### Описание

final public function MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool

Возвращает, есть ли в топологии сервер, доступный для чтения, или, если указан параметр `readPreference`, сервер, соответствующий указанному предпочтению чтения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает, есть ли в топологии сервер, доступный для чтения, или, если указан параметр `readPreference`, сервер, соответствующий указанному предпочтению чтения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Возвращает, есть ли в топологии сервер, доступный для записи

### Описание

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Возвращает, есть ли в топологии сервер, доступный для записи.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает, есть ли в топологии сервер, доступный для записи.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\TopologyDescription::getServers — Возвращает серверы в топологии
- MongoDB\Driver\TopologyDescription::getType — Возвращает строку, обозначающую тип топологии
- MongoDB\Driver\TopologyDescription::hasReadableServer — Возвращает, есть ли в топологии сервер, доступный для чтения
- MongoDB\Driver\TopologyDescription::hasWritableServer — Возвращает, есть ли в топологии сервер, доступный для записи

# Класс MongoDB\Driver\WriteConcernError

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\WriteConcernError инкапсулирует информацию об ошибке записи и может быть возвращён MongoDB\Driver\WriteResult::getWriteConcernError().

## Обзор класса

final class MongoDB\Driver\WriteConcernError {
/* Свойства */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* Методы */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Свойства

message
  Сообщение об ошибке.
code
  Код ошибки.
info
  Дополнительная информация об ошибке или `null`, если недоступна.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Возвращает код ошибки WriteConcernError

### Описание

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код ошибки WriteConcernError.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcernError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

Вывод приведённого примера будет похож на:

    int(64)

### Смотрите также

- » Справка по гарантиям записи

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Возвращает документ метаданных для WriteConcernError

### Описание

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ метаданных для WriteConcernError или `null`, если нет метаданных.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcernError::getInfo()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### Смотрите также

- » Справка по гарантиям записи

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Возвращает сообщение об ошибке WriteConcernError

### Описание

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сообщение об ошибке WriteConcernError.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteConcernError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

Вывод приведённого примера будет похож на:

    string(33) "waiting for replication timed out"

### Смотрите также

- » Справка по гарантиям записи

## Содержание

- MongoDB\Driver\WriteConcernError::getCode — Возвращает код ошибки WriteConcernError
- MongoDB\Driver\WriteConcernError::getInfo — Возвращает документ метаданных для WriteConcernError
- MongoDB\Driver\WriteConcernError::getMessage — Возвращает сообщение об ошибке WriteConcernError

# Класс MongoDB\Driver\WriteError

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\WriteError инкапсулирует информацию об ошибке записи и может быть возвращён как элемент массива из MongoDB\Driver\WriteResult::getWriteErrors().

## Обзор класса

final class MongoDB\Driver\WriteError {
/* Свойства */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* Методы */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Свойства

message
  Сообщение об ошибке.
code
  Код ошибки.
index
  Индекс операции записи внутри MongoDB\Driver\BulkWrite, которая вызвала ошибку.
info
  Дополнительная информация об ошибке или `null`, если недоступна.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Возвращает код ошибки WriteError

### Описание

final public function MongoDB\Driver\WriteError::getCode(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код ошибки WriteError.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteError::getCode()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
    }

    ?>

Вывод приведённого примера будет похож на:

    int(11000)

# MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Возвращает индекс записи, соответствующей этому WriteError

### Описание

final public function MongoDB\Driver\WriteError::getIndex(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает индекс записи (из MongoDB\Driver\BulkWrite), соответствующий текущему WriteError.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteError::getIndex()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
    }

    ?>

Вывод приведённого примера будет похож на:

    int(1)

### Смотрите также

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Возвращает документ метаданных для WriteError

### Описание

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ метаданных для WriteError, либо `null`, если метаданные недоступны.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Возвращает сообщение об ошибке WriteError

### Описание

final public function MongoDB\Driver\WriteError::getMessage(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сообщение об ошибке WriteError.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteError::getMessage()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
    }

    ?>

Вывод приведённого примера будет похож на:

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## Содержание

- MongoDB\Driver\WriteError::getCode — Возвращает код ошибки WriteError
- MongoDB\Driver\WriteError::getIndex — Возвращает индекс записи, соответствующей этому WriteError
- MongoDB\Driver\WriteError::getInfo — Возвращает документ метаданных для WriteError
- MongoDB\Driver\WriteError::getMessage — Возвращает сообщение об ошибке WriteError

# Класс MongoDB\Driver\WriteResult

(mongodb >=1.0.0)

## Введение

Класс MongoDB\Driver\WriteResult инкапсулирует информацию о выполненном MongoDB\Driver\BulkWrite и может быть возвращён MongoDB\Driver\Manager::executeBulkWrite().

## Обзор класса

final class MongoDB\Driver\WriteResult {
/* Свойства */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* Методы */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## Свойства

insertedCount
  Количество вставленных документов (без upsert) или `null`, если write concern не запросил подтверждение.
matchedCount
  Количество документов, найденных операциями обновления и замены, или `null`, если write concern не запросил подтверждение.
modifiedCount
  Количество документов, изменённых операциями обновления и замены, или `null`, если write concern не запросил подтверждение или если сервер не сообщил эту информацию.
deletedCount
  Количество удалённых документов или `null`, если write concern не запросил подтверждение.
upsertedCount
  Количество upsert-документов или `null`, если write concern не запросил подтверждение.
server
  Сервер, который выполнил bulk-операцию записи.
upsertedIds
  Массив значений `_id` для upsert-документов. Ключи массива соответствуют индексу операции записи из MongoDB\Driver\BulkWrite.
writeErrors
  Массив объектов MongoDB\Driver\WriteError для всех ошибок записи, которые возникли при выполнении.
writeConcernError
  Объект MongoDB\Driver\WriteConcernError, если возникла ошибка write concern, или `null`, если ошибки не было.
writeConcern
  Объект MongoDB\Driver\WriteConcern, который использовался для bulk-операции записи, или `null`, если недоступен.
errorReplies
  Массив документов ответа об ошибке, который вернул сервер.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Возвращает количество удалённых документов

### Описание

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество удалённых документов.

### Ошибки

- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | При вызове для записи без подтверждения метод вместо возврата значения `null` теперь выбрасывает исключение.

### Примеры

Пример #1 Пример получения количества удалённых документов методом MongoDB\Driver\WriteResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getDeletedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Возвращает количество вставленных документов без учёта операций upsert

### Описание

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество вставленных документов без учёта операций upsert.

### Ошибки

- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | При вызове для записи без подтверждения метод вместо возврата значения `null` теперь выбрасывает исключение.

### Примеры

Пример #1 Пример получения количества вставленных документов методом MongoDB\Driver\WriteResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getInsertedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Возвращает количество документов, которые сервер выбрал для обновления

### Описание

final public function MongoDB\Driver\WriteResult::getMatchedCount(): int

Количество совпадений иногда превышает значение, которое возвращает метод MongoDB\Driver\WriteResult::getModifiedCount(), если операция обновления не изменяет документ, например, устанавливает значение поля равным текущему значению.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество документов, которые СУБД выбрала для обновления.

### Ошибки

- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | При вызове для записи без подтверждения метод вместо возврата значения `null` теперь выбрасывает исключение.

### Примеры

Пример #1 Пример получения количества обновляемых документов методом MongoDB\Driver\WriteResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWrite();
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getMatchedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\WriteResult::getModifiedCount() - Возвращает количество существующих обновлённых документов
- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Возвращает количество существующих обновлённых документов

### Описание

final public function MongoDB\Driver\WriteResult::getModifiedCount(): int

При операциях обновления, которые не изменяют документ, наподобие установки значения поля в его текущее значение изменённое число иногда становится меньше, чем значение, которое возвращает метод MongoDB\Driver\WriteResult::getMatchedCount().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество существующих обновлённых документов.

### Ошибки

- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | При вызове для записи без подтверждения метод вместо возврата значения `null` теперь выбрасывает исключение.

### Примеры

Пример #1 Пример получения количества существующих обновлённых документов методом MongoDB\Driver\WriteResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\WriteResult::getMatchedCount() - Возвращает количество документов, которые сервер выбрал для обновления
- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Возвращает сервер, который связан с этим результатом записи

### Описание

final public function MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Метод возвращает объект MongoDB\Driver\Server, который связан с этим результатом записи. Это сервер, который выполнил операции, которые собрал объект MongoDB\Driver\BulkWrite.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект MongoDB\Driver\Server, который связан с этим результатом записи.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\WriteResult::getServer()

    <?php

    $manager = new MongoDB\Driver\Manager();
    $server = $manager->selectServer();

    $bulk = new MongoDB\Driver\BulkWrite();
    $bulk->insert(['x' => 1]);

    $result = $server->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getServer() == $server);

    ?>

Результат выполнения приведённого примера:

    bool(true)

### Смотрите также

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Возвращает количество документов, вставленных операцией upsert

### Описание

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество документов, вставленных операцией upsert.

### Ошибки

- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | При вызове для записи без подтверждения метод вместо возврата значения `null` теперь выбрасывает исключение.

### Примеры

Пример #1 Пример получения количества документов, вставленных операцией upsert, методом MongoDB\Driver\WriteResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedCount());

    ?>

Результат выполнения приведённого примера:

    int(2)

### Смотрите также

- MongoDB\Driver\WriteResult::getUpsertedIds() - Возвращает массив идентификаторов для объединённых документов
- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Возвращает массив идентификаторов для объединённых документов

### Описание

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив идентификаторов (т.е. значения полей `"_id"`) для объединённых документов. Ключи массива будут соответствовать индексу операции записи (из MongoDB\Driver\BulkWrite), ответственной за слияние.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteResult::getUpsertedIds()

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedIds());

    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### Смотрите также

- MongoDB\Driver\WriteResult::getUpsertedCount() - Возвращает количество документов, вставленных операцией upsert
- MongoDB\Driver\WriteResult::isAcknowledged() - Возвращает, была ли запись подтверждена

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Возвращает любую ошибку гарантий записи, которая произошла

### Описание

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает MongoDB\Driver\WriteConcernError, если во время операции записи произошла ошибка гарантий записи, и `null` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteResult::getWriteConcernError()

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError());
    }

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\Driver\WriteConcernError)#6 (3) {
      ["message"]=>
      string(33) "waiting for replication timed out"
      ["code"]=>
      int(64)
      ["info"]=>
      object(stdClass)#7 (1) {
        ["wtimeout"]=>
        bool(true)
      }
    }

### Смотрите также

- MongoDB\Driver\WriteConcern
- » Справка по гарантиям записи

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Возвращает любые ошибки записи, которые произошли

### Описание

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив объектов MongoDB\Driver\WriteError для любых ошибок записи, обнаруженных во время операции записи. Массив будет пустым, если ошибок не произошло.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteResult::getWriteErrors() с одной ошибкой

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* По умолчанию массовые операции записи выполняются последовательно по порядку
     * и выполнение прекращается после первой ошибки.
     */
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
    }

Пример #2 Пример использования MongoDB\Driver\WriteResult::getWriteErrors() с несколькими ошибками

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* Параметр "ordered" может использоваться для продолжения
     * выполнения массовых операций записи после первой ошибки.
     */
    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
      [1]=>
      object(MongoDB\Driver\WriteError)#6 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(5)
        ["info"]=>
        NULL
      }
    }

### Смотрите также

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Возвращает, была ли запись подтверждена

### Описание

final public function MongoDB\Driver\WriteResult::isAcknowledged(): bool

Если запись подтверждена, другие поля будут доступны в объекте MongoDB\Driver\WriteResult.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если запись была подтверждена, и `false` в противном случае.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\Driver\WriteResult::isAcknowledged() с подтверждёнными гарантиями записи

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

Результат выполнения приведённого примера:

    bool(true)

Пример #2 Пример использования MongoDB\Driver\WriteResult::isAcknowledged() с неподтверждёнными гарантиями записи

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk, new MongoDB\Driver\WriteConcern(0));

    var_dump($result->isAcknowledged());

    ?>

Результат выполнения приведённого примера:

    bool(false)

### Смотрите также

- MongoDB\Driver\WriteConcern
- » Справка по гарантиям записи

## Содержание

- MongoDB\Driver\WriteResult::getDeletedCount — Возвращает количество удалённых документов
- MongoDB\Driver\WriteResult::getInsertedCount — Возвращает количество вставленных документов без учёта операций upsert
- MongoDB\Driver\WriteResult::getMatchedCount — Возвращает количество документов, которые сервер выбрал для обновления
- MongoDB\Driver\WriteResult::getModifiedCount — Возвращает количество существующих обновлённых документов
- MongoDB\Driver\WriteResult::getServer — Возвращает сервер, который связан с этим результатом записи
- MongoDB\Driver\WriteResult::getUpsertedCount — Возвращает количество документов, вставленных операцией upsert
- MongoDB\Driver\WriteResult::getUpsertedIds — Возвращает массив идентификаторов для объединённых документов
- MongoDB\Driver\WriteResult::getWriteConcernError — Возвращает любую ошибку гарантий записи, которая произошла
- MongoDB\Driver\WriteResult::getWriteErrors — Возвращает любые ошибки записи, которые произошли
- MongoDB\Driver\WriteResult::isAcknowledged — Возвращает, была ли запись подтверждена

# Класс MongoDB\Driver\BulkWriteCommandResult

(mongodb >=2.1.0)

## Введение

Класс MongoDB\Driver\BulkWriteCommandResult инкапсулирует информацию о выполненной команде MongoDB\Driver\BulkWriteCommand. Объекты класса возвращает метод MongoDB\Driver\Manager::executeBulkWriteCommand().

## Обзор класса

final class MongoDB\Driver\BulkWriteCommandResult {
/* Методы */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Возвращает количество удалённых документов

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает общее количество документов, удалённых всеми операциями.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения количества удалённых документов методом MongoDB\Driver\BulkWriteCommandResult::getDeletedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

Результат выполнения приведённого примера:

    int(3)

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Возвращает подробную информацию о результатах успешных операций удаления
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Возвращает подробную информацию о результатах успешных операций удаления

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает документ, который содержит результаты каждой успешной операции удаления, или `null`, если подробные результаты не запрашивались. Ключи документа соответствуют индексу операции записи из объекта MongoDB\Driver\BulkWriteCommand.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения подробных результатов об операциях удаления методом MongoDB\Driver\BulkWriteCommandResult::getDeleteResults()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Возвращает количество удалённых документов
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Возвращает количество вставленных документов

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает общее количество документов, вставленных всеми операциями за исключением операций upsert.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения количества вставленных документов методом MongoDB\Driver\BulkWriteCommandResult::getInsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Возвращает подробную информацию о результатах успешных операций вставки
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Возвращает подробную информацию о результатах успешных операций вставки

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Значение `insertedId` в каждом результате соответствует значению, которое метод MongoDB\Driver\BulkWriteCommand::insertOne() возвращает после добавления конкретной операции вставки, включая значения полей `_id`, которые модуль автоматически генерирует при вставке документов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает документ, который содержит результаты каждой успешной операции вставки, или `null`, если подробные результаты не запрашивались. Ключи документа соответствуют индексу операции записи из объекта MongoDB\Driver\BulkWriteCommand.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения подробных результатов об операциях вставки методом MongoDB\Driver\BulkWriteCommandResult::getInsertResults()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Возвращает количество вставленных документов
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи
- MongoDB\Driver\BulkWriteCommand::insertOne() - Добавляет операцию insertOne

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Возвращает количество документов, которые сервер выбрал для обновления

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(): int

Количество совпадений иногда превышает значение, которое возвращает метод MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(), если операция обновления не изменяет документ, например, устанавливает значение поля равным текущему значению.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает общее количество документов, которые СУБД выбрала для обновления после обработки всех операций обновления.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения количества обновляемых документов методом MongoDB\Driver\BulkWriteCommandResult::getMatchedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Возвращает количество обновлённых документов
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Возвращает подробную информацию о результатах успешных операций обновления
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Возвращает количество обновлённых документов

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(): int

Количество изменений иногда оказывается меньше значения, которое возвращает метод MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(), если операция обновления не изменяет документ, например, устанавливает значение поля равным текущему значению.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает общее количество документов, обновлённых всеми операциями.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения количества обновлённых документов методом MongoDB\Driver\BulkWriteCommandResult::getModifiedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Возвращает количество документов, которые сервер выбрал для обновления
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Возвращает подробную информацию о результатах успешных операций обновления
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Возвращает подробную информацию о результатах успешных операций обновления

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает документ, который содержит результаты каждой успешной операции обновления, или `null`, если подробные результаты не запрашивались. Ключи документа соответствуют индексу операции записи из объекта MongoDB\Driver\BulkWriteCommand.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения подробных результатов об операциях обновления методом MongoDB\Driver\BulkWriteCommandResult::getUpdateResults()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Возвращает количество документов, которые сервер выбрал для обновления
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Возвращает количество обновлённых документов
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Возвращает количество документов, которые вставила операция upsert
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Возвращает количество документов, которые вставила операция upsert

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает общее количество документов, которые вставили все операции upsert.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- При записи без подтверждения метод выбрасывает исключение MongoDB\Driver\Exception\LogicException.

### Примеры

Пример #1 Пример получения количества вставок документов операциями upsert методом MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

Результат выполнения приведённого примера:

    int(2)

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Возвращает подробную информацию о результатах успешных операций обновления
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Возвращает информацию о подтверждении записи

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Возвращает информацию о подтверждении записи

### Описание

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

Другие поля в объекте MongoDB\Driver\BulkWriteCommandResult становятся доступными только после подтверждения записи.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает `true`, если СУБД подтвердила запись, иначе возвращает `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример получения информации о подтверждении записи методом MongoDB\Driver\BulkWriteCommandResult::isAcknowledged()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

Результат выполнения приведённого примера:

    bool(true)

Пример #2 Пример работы метода MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() в режиме записи без подтверждения

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

Результат выполнения приведённого примера:

    bool(false)

### Смотрите также

- MongoDB\Driver\WriteConcern
- » О гарантиях записи

## Содержание

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Возвращает количество удалённых документов
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Возвращает подробную информацию о результатах успешных операций удаления
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Возвращает количество вставленных документов
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Возвращает подробную информацию о результатах успешных операций вставки
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Возвращает количество документов, которые сервер выбрал для обновления
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Возвращает количество обновлённых документов
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Возвращает подробную информацию о результатах успешных операций обновления
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Возвращает количество документов, которые вставила операция upsert
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Возвращает информацию о подтверждении записи

# Классы и функции модуля MongoDB для работы с форматом BSON

## Содержание

- Функции
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDateTime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# Функции

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Возвращает BSON-представление JSON-значения

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::fromJSON().

### Описание

function MongoDB\BSON\fromJSON(string `$json`): string

Метод преобразовывает строку в формате » Extended JSON в её представление в формате BSON.

### Список параметров

`json` (string)
  Значение JSON для преобразования.

### Возвращаемые значения

Метод возвращает сериализованный BSON-документ в виде двоичной строки.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если JSON-значение невозможно преобразовать в формат BSON, например, из-за синтаксической ошибки.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.

### Примеры

Пример #1 Пример преобразования JSON-значения в BSON-формат методом MongoDB\BSON\fromJSON()

    <?php

    $json = '{"_id": {"$oid": "563143b280d2387c91807965"}}';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

Результат выполнения приведённого примера:

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### Смотрите также

- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\toJSON() - Возвращает Legacy Extended JSON-представление BSON-значения
- » Формат MongoDB Extended JSON
- » BSON-типы БД MongoDB

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Возвращает BSON-представление PHP-значения

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::fromPHP().

### Описание

function MongoDB\BSON\fromPHP(array|object `$value`): string

Метод сериализует массив или объект PHP (например, документ) в его представление в формате » BSON. Возвращённая двоичная строка будет описывать BSON-документ.

### Список параметров

`value` (array|object)
  Значение PHP для сериализации.

### Возвращаемые значения

Метод возвращает сериализованный документ BSON в виде двоичной строки.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если значение PHP невозможно преобразовать в формат BSON. Возможные причины включают, но не ограничиваются столкновением с неожиданным экземпляром MongoDB\BSON\Type или MongoDB\BSON\Serializable::bsonSerialize(), который не возвращает массив (array) или объект stdClass.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.

### Примеры

Пример #1 Пример сериализации PHP-значения в BSON-представление методом MongoDB\BSON\fromPHP()

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

Результат выполнения приведённого примера:

    0e00000010666f6f000100000000

### Смотрите также

- MongoDB\BSON\Document::fromPHP() - Создаёт новый экземпляр документа из PHP-данных
- MongoDB\BSON\toPHP() - Возвращает PHP-представление BSON-значения
- » BSON-типы БД MongoDB
- Сохранение данных

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Возвращает Canonical Extended JSON-представление BSON-значения

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::toCanonicalExtendedJSON().

### Описание

function MongoDB\BSON\toCanonicalExtendedJSON(string `$bson`): string

Метод преобразовывает BSON-строку в представление » в каноническом расширенном JSON-формате. В каноническом формате в ущерб краткости вывода отдают преимущество точности типов. В каноническом формате создают данные вывода, которым доступно преобразование обратно в BSON-формат без потери информации о типе, например, числовые типы останутся дифференцированными.

### Список параметров

`bson` (string)
  Значение BSON для преобразования.

### Возвращаемые значения

Метод возвращает JSON-значение, в которое преобразовал BSON-значение.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если во входных данных передали больше одного BSON-документа. Возможные причины включают, но не ограничиваются недопустимым BSON-форматом, лишними данными или неожиданной ошибкой » libbson.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.

### Примеры

Пример #1 Пример преобразования BSON-значения в представление в формате Canonical Extended JSON методом MongoDB\BSON\toCanonicalExtendedJSON()

    <?php

    $documents = [
        ['null' => null],
        ['boolean' => true],
        ['string' => 'foo'],
        ['int32' => 123],
        ['int64' => 4294967295],
        ['double' => 1.0],
        ['nan' => NAN],
        ['pos_inf' => INF],
        ['neg_inf' => -INF],
        ['array' => ['foo', 'bar']],
        ['document' => ['foo' => 'bar']],
        ['oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1')],
        ['dec128' => new MongoDB\BSON\Decimal128('1234.5678')],
        ['binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC)],
        ['date' => new MongoDB\BSON\UTCDateTime(1445990400000)],
        ['timestamp' => new MongoDB\BSON\Timestamp(1234, 5678)],
        ['regex' => new MongoDB\BSON\Regex('pattern', 'i')],
        ['code' => new MongoDB\BSON\Javascript(
            'function() {
                return 1;
            }'
        )],
        ['code_ws' => new MongoDB\BSON\Javascript(
            'function() {
                return a;
            }',
            ['a' => 1]
        )],
        ['minkey' => new MongoDB\BSON\MinKey],
        ['maxkey' => new MongoDB\BSON\MaxKey],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
    }

    ?>

Результат выполнения приведённого примера:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Смотрите также

- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-документа
- MongoDB\BSON\fromJSON() - Возвращает BSON-представление JSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Спецификация формата Extended JSON
- » BSON-типы БД MongoDB

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Возвращает Legacy Extended JSON-представление BSON-значения

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::toCanonicalExtendedJSON() или MongoDB\BSON\Document::toRelaxedExtendedJSON().

### Описание

function MongoDB\BSON\toJSON(string `$bson`): string

Метод преобразовывает в BSON-строку её представление в формате » Legacy Extended JSON.

> Замечание: BSON-данные представляют в ряде JSON-форматов. Метод реализует «строгий режим», который определяется форматом » MongoDB Extended JSON, который заменили каноническими — реализовали в методе MongoDB\BSON\toCanonicalExtendedJSON() — и упрощёнными — в методе MongoDB\BSON\toRelaxedExtendedJSON() — форматами, которые определили » в спецификации Extended JSON.

Внимание

Формат » JSON не поддерживает нечисло `NAN` и бесконечность `INF`, а формат Legacy Extended JSON базы данных MongoDB не определяет альтернативное представление для этих значений (библиотека » libbson выведет литералы `nan` и `inf`, которые иногда не распознаются, в допустимом JSON-формате). При работе с BSON-форматом, который иногда содержит бесконечные числа, вызывают метод MongoDB\BSON\toCanonicalExtendedJSON() или MongoDB\BSON\toRelaxedExtendedJSON().

### Список параметров

`bson` (string)
  Значение BSON для преобразования.

### Возвращаемые значения

Метод возвращает JSON-значение, в которое преобразовал BSON-значение.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если во входных данных передали больше одного BSON-документа. Возможные причины включают, но не ограничиваются недопустимым BSON-форматом, лишними данными или неожиданной ошибкой » libbson.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.

### Примеры

Пример #1 Пример преобразования BSON-значения в Legacy Extended JSON-представление методом MongoDB\BSON\toJSON()

    <?php

    $documents = [
        ['null' => null],
        ['boolean' => true],
        ['string' => 'foo'],
        ['int32' => 123],
        ['int64' => 4294967295],
        ['double' => 1.0],
        ['nan' => NAN],
        ['pos_inf' => INF],
        ['neg_inf' => -INF],
        ['array' => ['foo', 'bar']],
        ['document' => ['foo' => 'bar']],
        ['oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1')],
        ['dec128' => new MongoDB\BSON\Decimal128('1234.5678')],
        ['binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC)],
        ['date' => new MongoDB\BSON\UTCDateTime(1445990400000)],
        ['timestamp' => new MongoDB\BSON\Timestamp(1234, 5678)],
        ['regex' => new MongoDB\BSON\Regex('pattern', 'i')],
        ['code' => new MongoDB\BSON\Javascript(
            'function() {
                return 1;
            }'
        )],
        ['code_ws' => new MongoDB\BSON\Javascript(
            'function() {
                return a;
            }',
            ['a' => 1]
        )],
        ['minkey' => new MongoDB\BSON\MinKey],
        ['maxkey' => new MongoDB\BSON\MaxKey],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toJSON($bson), "\n";
    }

    ?>

Результат выполнения приведённого примера:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : nan }
    { "pos_inf" : inf }
    { "neg_inf" : -inf }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
    { "date" : { "$date" : 1445990400000 } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regex" : "pattern", "$options" : "i" } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Смотрите также

- MongoDB\BSON\fromJSON() - Возвращает BSON-представление JSON-значения
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Формат MongoDB Extended JSON
- » BSON-типы БД MongoDB

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Возвращает PHP-представление BSON-значения

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::toPHP().

### Описание

function MongoDB\BSON\toPHP(string `$bson`, array `$typeMap` = array()): array|object

Метод десериализует BSON-документ — двоичную строку — в его PHP-представление. Через параметр `typeMap` управляют PHP-типами, через которые преобразовывают BSON-массивы и BSON-документы (как корневые, так и встроенные).

Внимание

Документы BSON технически могут содержать повторяющиеся ключи, поскольку документы хранятся в виде списка пар ключ-значение; однако приложениям следует воздерживаться от создания документов с дубликатами ключей, поскольку поведение сервера и драйвера может быть неопределённым. Поскольку объекты и массивы PHP не могут иметь повторяющихся ключей, данные также могут быть потеряны при декодировании документа BSON с повторяющимися ключами.

### Список параметров

`bson` (string)
  BSON-значение для десериализации.
`typeMap` (array)
  Конфигурация карты типов.

### Возвращаемые значения

Метод возвращает PHP-значение, которое сгенерировал путём десериализации BSON-документа.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если класс в карте типов невозможно создать или класс не реализует интерфейс MongoDB\BSON\Unserializable.
- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если во входных данных передали больше одного BSON-документа. Возможные причины включают, но не ограничиваются недопустимым BSON-форматом, лишними данными или неожиданной ошибкой » libbson.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.
PECL-модуль mongodb 1.4.0 | Модуль больше не записывает предупреждение в журнал отладки, если входные данные содержат устаревший BSON-тип, который не поддерживается модулем. Вместо этого метод создаст объект, который представляет такой тип.
PECL-модуль mongodb 1.3.2 | Метод больше не выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException если входные данные содержат устаревший BSON-тип, который не поддерживается модулем. Метод проигнорирует такие типы (как и в версиях до 1.3.0), хотя модуль теперь записывает предупреждение в журнал отладки (смотрите описание директивы mongodb.debug).
PECL-модуль mongodb 1.3.0 | Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если входные данные содержат устаревший BSON-тип, который не поддерживается модулем. Раньше модуль игнорировал такие типы.

### Примеры

Пример #1 Пример преобразования BSON-значения в PHP-представление методом MongoDB\BSON\toPHP()

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

Результат выполнения приведённого примера:

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### Смотрите также

- MongoDB\BSON\Document::toPHP() - Возвращает PHP-представление BSON-документа
- MongoDB\BSON\fromPHP() - Возвращает BSON-представление PHP-значения
- » BSON-типы БД MongoDB
- Сохранение данных

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Возвращает представление BSON-значения в слабом расширенном JSON-формате

Внимание

Метод УСТАРЕЛ с модуля версии 1.20.0, а в версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать метод MongoDB\BSON\Document::toRelaxedExtendedJSON().

### Описание

function MongoDB\BSON\toRelaxedExtendedJSON(string `$bson`): string

Метод преобразовывает BSON-строку в представление » в слабом расширенном JSON-формате . В слабом формате в ущерб точности типов отдают преимущество работе с примитивами JSON-типа. В слабом формате создаются данные вывода для API-интерфейсов к веб-сервисам и такие данных проще воспринимать людям.

### Список параметров

`bson` (string)
  Значение BSON для преобразования.

### Возвращаемые значения

Метод возвращает JSON-значение, которое сгенерировал путём преобразования BSON-значения.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если во входных данных передали больше одного BSON-документа. Возможные причины включают, но не ограничиваются недопустимым BSON-форматом, лишними данными или неожиданной ошибкой » libbson.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Функцию удалили.

### Примеры

Пример #1 Пример преобразования BSON-значения в представление в формате Relaxed Extended JSON методом MongoDB\BSON\toRelaxedExtendedJSON()

    <?php

    $documents = [
        ['null' => null],
        ['boolean' => true],
        ['string' => 'foo'],
        ['int32' => 123],
        ['int64' => 4294967295],
        ['double' => 1.0],
        ['nan' => NAN],
        ['pos_inf' => INF],
        ['neg_inf' => -INF],
        ['array' => ['foo', 'bar']],
        ['document' => ['foo' => 'bar']],
        ['oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1')],
        ['dec128' => new MongoDB\BSON\Decimal128('1234.5678')],
        ['binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC)],
        ['date' => new MongoDB\BSON\UTCDateTime(1445990400000)],
        ['timestamp' => new MongoDB\BSON\Timestamp(1234, 5678)],
        ['regex' => new MongoDB\BSON\Regex('pattern', 'i')],
        ['code' => new MongoDB\BSON\Javascript(
            'function() {
                return 1;
            }'
        )],
        ['code_ws' => new MongoDB\BSON\Javascript(
            'function() {
                return a;
            }',
            ['a' => 1]
        )],
        ['minkey' => new MongoDB\BSON\MinKey],
        ['maxkey' => new MongoDB\BSON\MaxKey],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
    }

    ?>

Результат выполнения приведённого примера:

    {"null": null}
    {"boolean": true}
    {"string": "foo"}
    {"int32": 123}
    {"int64": 4294967295}
    {"double": 1.0}
    {"nan": {"$numberDouble": "NaN"}}
    {"pos_inf": {"$numberDouble": "Infinity"}}
    {"neg_inf": {"$numberDouble": "-Infinity"}}
    {"array": ["foo", "bar"]}
    {"document": {"foo": "bar"}}
    {"oid": {"$oid": "56315a7c6118fd1b920270b1"}}
    {"dec128": {"$numberDecimal": "1234.5678"}}
    {"binary": {"$binary": {"base64": "Zm9v", "subType": "00"}}}
    {"date": {"$date": "2015-10-28T00:00:00Z"}}
    {"timestamp": {"$timestamp": {"t": 5678, "i": 1234}}}
    {"regex": {"$regularExpression": {"pattern": "pattern", "options": "i"}}}
    {"code": {"$code": "function() {return 1;}"}}
    {"code_ws": {"$code" : "function() {return a;}", "$scope": {"a": 1}}}
    {"minkey": {"$minKey": 1}}
    {"maxkey": {"$maxKey": 1}}

### Смотрите также

- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Возвращает представление BSON-документа в слабом расширенном JSON-формате
- MongoDB\BSON\fromJSON() - Возвращает BSON-представление JSON-значения
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- » Формат Extended JSON
- » BSON-типы БД MongoDB

## Содержание

- MongoDB\BSON\fromJSON — Возвращает BSON-представление JSON-значения
- MongoDB\BSON\fromPHP — Возвращает BSON-представление PHP-значения
- MongoDB\BSON\toCanonicalExtendedJSON — Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toJSON — Возвращает Legacy Extended JSON-представление BSON-значения
- MongoDB\BSON\toPHP — Возвращает PHP-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON — Возвращает представление BSON-значения в слабом расширенном JSON-формате

# Класс MongoDB\BSON\Document

(mongodb >=1.16.0)

## Введение

Класс представляет BSON-документ. Класс используется при чтении данных в виде необработанного BSON и не может быть модифицирован.

## Обзор класса

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Методы */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.17.0 | Класс теперь реализует интерфейс MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Создаёт новый BSON-документ (не используется)

### Описание

final private function MongoDB\BSON\Document::__construct()

Объекты MongoDB\BSON\Document создаются с помощью статических фабричных методов и не могут быть инициализированы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\BSON\Document::fromPHP() - Создаёт новый экземпляр документа из PHP-данных
- MongoDB\BSON\Document::fromBSON() - Создаёт новый экземпляр документа из BSON-строки
- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- » Типы BSON

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Создаёт новый экземпляр документа из BSON-строки

### Описание

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### Список параметров

`bson` (string)
  Строка, которая содержит документ в BSON-формате.

### Возвращаемые значения

Метод возвращает новый экземпляр класса MongoDB\BSON\Document.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если в параметр `bson` передали недопустимую BSON-строку или аргумент содержит больше одного документа.

### Смотрите также

- MongoDB\BSON\Document::fromPHP() - Создаёт новый экземпляр документа из PHP-данных
- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- » Типы BSON

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Создаёт новый экземпляр документа из JSON-строки

### Описание

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Метод преобразовывает строку » в расширенном JSON-формате в её BSON-представление.

### Список параметров

`json` (string)
  JSON-значение, которое требуется преобразовать.

### Возвращаемые значения

Метод возвращает новый экземпляр класса MongoDB\BSON\Document.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если JSON-значение невозможно преобразовать в BSON-документ, например из-за ошибки синтаксиса.

### Смотрите также

- MongoDB\BSON\Document::fromPHP() - Создаёт новый экземпляр документа из PHP-данных
- MongoDB\BSON\Document::fromBSON() - Создаёт новый экземпляр документа из BSON-строки
- » Формат Extended JSON БД MongoDB
- » Типы BSON

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Создаёт новый экземпляр документа из PHP-данных

### Описание

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### Список параметров

`value` (object|array)
  PHP-объект или массив, в котором содержится документ. При передаче массива с числовыми ключами числовые значения преобразовываются в строки и становятся ключами документа.

### Возвращаемые значения

Метод возвращает новый экземпляр класса MongoDB\BSON\Document.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\Document::fromBSON() - Создаёт новый экземпляр документа из BSON-строки
- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- » Типы BSON

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Возвращает значение ключа в документе

### Описание

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### Список параметров

`key` (string)
  Ключ, который необходимо извлечь из документа.

### Возвращаемые значения

Возвращает значение, связанное с заданным ключом. Если ключ отсутствует в документе, будет выброшено исключение.

> Замечание: Если в BSON-документе встречается значение, закодированное как 64-битное целое число, то возвращаемым значением этого метода будет экземпляр MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если ключ отсутствует в документе.

### Смотрите также

- MongoDB\BSON\Document::has() - Возвращает, присутствует ли ключ в документе
- » Типы BSON

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Возвращает итератор для документа BSON

### Описание

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает экземпляр MongoDB\BSON\Iterator, который может быть использован для итерации по всем ключам в документе.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если итератор BSON не может быть инициализирован.

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Возвращает, присутствует ли ключ в документе

### Описание

final public function MongoDB\BSON\Document::has(string `$key`): bool

### Список параметров

`key` (string)
  Ключ, который необходимо искать в документе.

### Возвращаемые значения

Возвращает `true`, если ключ присутствует в документе, в противном случае возвращает `false` .

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\Document::get() - Возвращает значение ключа в документе
- » Типы BSON

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Проверяет, присутствует ли ключ в документе

### Описание

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### Список параметров

`key`
  Ключ, который нужно искать в документе.

### Возвращаемые значения

Метод возвращает `true`, если ключ присутствует в документе, иначе `false`.

### Смотрите также

- ArrayAccess::offsetExists() - Определяет, существует ли заданное смещение (ключ)
- MongoDB\BSON\Document::has() - Возвращает, присутствует ли ключ в документе

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Возвращает значение ключа в документе

### Описание

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### Список параметров

`key`
  Ключ, который требуется получить из документа.

### Возвращаемые значения

Метод возвращает значение, которое связано с ключом. Если ключа нет в документе, метод выбрасывает исключение.

> Замечание: При обнаружении значения, которое закодировали как 64-битное целое число в BSON-документе, метод вернёт экземпляр класса MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если ключа нет в документе.

### Смотрите также

- ArrayAccess::offsetGet() - Возвращает заданное смещение (ключ)
- MongoDB\BSON\Document::get() - Возвращает значение ключа в документе

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Реализует интерфейс ArrayAccess

### Описание

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Метод устанавливает значение ключа `key` параметру `value`.

### Список параметров

`key`
  Устанавливаемый индекс.
`value`
  Новое значение для параметра `key`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- Метод всегда выбрасывает исключение MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Реализует интерфейс ArrayAccess

### Описание

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Метод удаляет значение по индексу.

### Список параметров

`key`
  Удаляемый индекс.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- Метод всегда выбрасывает исключение MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Возвращает Canonical Extended JSON-представление BSON-документа

### Описание

final public function MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Преобразовывает BSON-документ в его представление » в каноническом расширенном JSON-формате . Канонический формат предпочитает точность типов, за что расплачивается краткостью вывода. В каноническом формате создаётся вывод, который доступен для преобразования обратно в BSON-формат без потери информации о типе, например, числовые типы останутся дифференцированными.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строку, которая содержит представление BSON-документа в формате » Canonical Extended JSON.

### Примеры

Пример #1 Пример преобразования BSON-документа в формат Canonical Extended JSON методом MongoDB\BSON\Document::toCanonicalExtendedJSON()

    <?php

    $documents = [
        ['null' => null],
        ['boolean' => true],
        ['string' => 'foo'],
        ['int32' => 123],
        ['int64' => 4294967295],
        ['double' => 1.0],
        ['nan' => NAN],
        ['pos_inf' => INF],
        ['neg_inf' => -INF],
        ['array' => ['foo', 'bar']],
        ['document' => ['foo' => 'bar']],
        ['oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1')],
        ['dec128' => new MongoDB\BSON\Decimal128('1234.5678')],
        ['binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC)],
        ['date' => new MongoDB\BSON\UTCDateTime(1445990400000)],
        ['timestamp' => new MongoDB\BSON\Timestamp(1234, 5678)],
        ['regex' => new MongoDB\BSON\Regex('pattern', 'i')],
        [
            'code' => new MongoDB\BSON\Javascript(
                'function() {
                    return 1;
                }'
            )
        ],
        [
            'code_ws' => new MongoDB\BSON\Javascript(
                'function() {
                    return a;
                }',
                [
                    'a' => 1
                ]
            )
        ],
        ['minkey' => new MongoDB\BSON\MinKey],
        ['maxkey' => new MongoDB\BSON\MaxKey],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toCanonicalExtendedJSON(), "\n";
    }

    ?>

Результат выполнения приведённого примера:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Смотрите также

- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Возвращает представление BSON-документа в слабом расширенном JSON-формате
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- » Спецификация Extended JSON
- » Типы BSON

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Возвращает PHP-представление BSON-документа

### Описание

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Метод десериализует BSON-документ в его PHP-представление. Через параметр `typeMap` управляют PHP-типами, через которые преобразовывают BSON-массивы и BSON-документы (как корневые, так и встроенные).

Внимание

Документы BSON технически могут содержать повторяющиеся ключи, поскольку документы хранятся в виде списка пар ключ-значение; однако приложениям следует воздерживаться от создания документов с дубликатами ключей, поскольку поведение сервера и драйвера может быть неопределённым. Поскольку объекты и массивы PHP не могут иметь повторяющихся ключей, данные также могут быть потеряны при декодировании документа BSON с повторяющимися ключами.

### Список параметров

`typeMap` (array)
  Конфигурация карты типов.

### Возвращаемые значения

Метод возвращает PHP-значение, которое сгенерировал путём десериализации BSON-документа.

> Замечание: Значением возврата будет экземпляр MongoDB\BSON\Int64, если в BSON-документе встречается значение, которое закодировали как 64-битное целое число.

### Ошибки

- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если класс в карте типов невозможно инициализировать или класс не реализует интерфейс MongoDB\BSON\Unserializable.

### Смотрите также

- MongoDB\BSON\toPHP() - Возвращает PHP-представление BSON-значения
- » BSON-типы БД MongoDB

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Возвращает представление BSON-документа в слабом расширенном JSON-формате

### Описание

final public function MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Метод преобразовывает BSON-документ в представление » в слабом расширенном JSON-формате . В слабом формате создаются данные вывода для API-интерфейсов к веб-сервисам и такие данных проще воспринимать людям.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строку, которая содержит представление BSON-документа в формате » Relaxed Extended JSON .

### Примеры

Пример #1 Пример преобразования BSON-документа в представление в формате Relaxed Extended JSON методом MongoDB\BSON\Document::toRelaxedExtendedJSON()

    <?php

    $documents = [
        ['null' => null],
        ['boolean' => true],
        ['string' => 'foo'],
        ['int32' => 123],
        ['int64' => 4294967295],
        ['double' => 1.0],
        ['nan' => NAN],
        ['pos_inf' => INF],
        ['neg_inf' => -INF],
        ['array' => ['foo', 'bar']],
        ['document' => ['foo' => 'bar']],
        ['oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1')],
        ['dec128' => new MongoDB\BSON\Decimal128('1234.5678')],
        ['binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC)],
        ['date' => new MongoDB\BSON\UTCDateTime(1445990400000)],
        ['timestamp' => new MongoDB\BSON\Timestamp(1234, 5678)],
        ['regex' => new MongoDB\BSON\Regex('pattern', 'i')],
        ['code' => new MongoDB\BSON\Javascript(
            'function() {
                return 1;
            }'
        )],
        ['code_ws' => new MongoDB\BSON\Javascript(
            'function() {
                return a;
            }',
            ['a' => 1]
        )],
        ['minkey' => new MongoDB\BSON\MinKey],
        ['maxkey' => new MongoDB\BSON\MaxKey],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toRelaxedExtendedJSON(), "\n";
    }

    ?>

Результат выполнения приведённого примера:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Смотрите также

- MongoDB\BSON\Document::fromJSON() - Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-документа
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Спецификация Extended JSON
- » Типы BSON

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Возвращает строковое представление данного BSON-документа

### Описание

final public function MongoDB\BSON\Document::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление данного BSON-документа

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\Document::__construct — Создаёт новый BSON-документ (не используется)
- MongoDB\BSON\Document::fromBSON — Создаёт новый экземпляр документа из BSON-строки
- MongoDB\BSON\Document::fromJSON — Создаёт новый экземпляр документа из JSON-строки
- MongoDB\BSON\Document::fromPHP — Создаёт новый экземпляр документа из PHP-данных
- MongoDB\BSON\Document::get — Возвращает значение ключа в документе
- MongoDB\BSON\Document::getIterator — Возвращает итератор для документа BSON
- MongoDB\BSON\Document::has — Возвращает, присутствует ли ключ в документе
- MongoDB\BSON\Document::offsetExists — Проверяет, присутствует ли ключ в документе
- MongoDB\BSON\Document::offsetGet — Возвращает значение ключа в документе
- MongoDB\BSON\Document::offsetSet — Реализует интерфейс ArrayAccess
- MongoDB\BSON\Document::offsetUnset — Реализует интерфейс ArrayAccess
- MongoDB\BSON\Document::toCanonicalExtendedJSON — Возвращает Canonical Extended JSON-представление BSON-документа
- MongoDB\BSON\Document::toPHP — Возвращает PHP-представление BSON-документа
- MongoDB\BSON\Document::toRelaxedExtendedJSON — Возвращает представление BSON-документа в слабом расширенном JSON-формате
- MongoDB\BSON\Document::__toString — Возвращает строковое представление данного BSON-документа

# Класс MongoDB\BSON\PackedArray

(mongodb >=1.16.0)

## Введение

Класс представляет BSON-массив. С классом работают при чтении необработанных двоичных BSON-данных и объект класса нельзя модифицировать.

## Обзор класса

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Методы */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.17.0 | Класс теперь реализует интерфейс MongoDB\BSON\Type.
PECL-модуль mongodb 1.17.0 | Класс MongoDB\BSON\PackedArray нельзя сериализовать в контекстах, в которых ожидается BSON-документ. В предыдущих версиях BSON-массив требовалось преобразовывать в документ.

# MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Создаёт новый массив BSON (не используется)

### Описание

final private function MongoDB\BSON\PackedArray::__construct()

Объекты MongoDB\BSON\PackedArray создаются с помощью статических фабричных методов и не могут быть инициализированы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\BSON\PackedArray::fromPHP() - Создаёт новый экземпляр BSON-массива из PHP-данных
- » Типы BSON

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Создаёт новый экземпляр BSON-массива из JSON-строки

### Описание

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Метод преобразовывает строку » в расширенном JSON-формате в BSON-представление.

### Список параметров

`json` (string)
  JSON-значение, которое требуется преобразовать.

### Возвращаемые значения

Метод возвращает новый экземпляр MongoDB\BSON\PackedArray.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если JSON-значение невозможно преобразовать в BSON-массив, например из-за синтаксической ошибки.

### Примеры

Пример #1 Пример создания нового экземпляра BSON-массива из JSON-строки методом MongoDB\BSON\PackedArray::fromJSON()

    <?php

    $json = '["foo", {"$numberInt": "123"}, {"$numberLong": "4294967295"}, {"$oid": "56315a7c6118fd1b920270b1"}]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### Смотрите также

- MongoDB\BSON\PackedArray::fromPHP() - Создаёт новый экземпляр BSON-массива из PHP-данных
- » Расширенный JSON-формат БД MongoDB
- » BSON-типы

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Создаёт новый экземпляр BSON-массива из PHP-данных

### Описание

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### Список параметров

`value` (array)
  Массив PHP, который требуется преобразовать в BSON-массив. Массив передают в виде списка — с последовательными числовыми ключами, которые начинаются с `0`.

### Возвращаемые значения

Метод возвращает новый экземпляр класса MongoDB\BSON\PackedArray.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException при передаче массива, который отличается от списка, — не содержит последовательные числовые ключи, которые начинаются с `0`.

### Смотрите также

- » BSON-типы

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Возвращает значение индекса массива

### Описание

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### Список параметров

`key` (int)
  Индекс для получения из массива.

### Возвращаемые значения

Метод возвращает значение, которое связано с заданным индексом. Если индекс отсутствует в массиве, метод выбросит исключение.

> Замечание: Если в массиве BSON встречается значение, закодированное как 64-битное целое число, то возвращаемым значением метода будет экземпляр класса MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если индекс отсутствует в массиве.

### Смотрите также

- MongoDB\BSON\PackedArray::has() - Возвращает информацию о том, содержится ли индекс в массиве
- » Типы BSON

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Возвращает итератор для массива BSON

### Описание

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает экземпляр MongoDB\BSON\Iterator, который может быть использован для итерации по всем индексам в массиве.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\UnexpectedValueException, если итератор BSON не может быть инициализирован.

### Смотрите также

- » Типы BSON

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Возвращает информацию о том, содержится ли индекс в массиве

### Описание

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### Список параметров

`index` (int)
  Индекс, который требуется искать в массиве.

### Возвращаемые значения

Метод возвращает `true`, если индекс содержится в массиве, иначе возвращает значение `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\PackedArray::get() - Возвращает значение индекса массива
- » BSON-типы

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Возвращает информацию о том, содержится ли индекс в массиве

### Описание

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### Список параметров

`key`
  Индекс, который требуется искать в массиве.

### Возвращаемые значения

Метод возвращает `true`, если индекс содержится в массиве, иначе возвращает значение `false`.

### Смотрите также

- ArrayAccess::offsetExists() - Определяет, существует ли заданное смещение (ключ)
- MongoDB\BSON\PackedArray::has() - Возвращает информацию о том, содержится ли индекс в массиве

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Возвращает значение индекса в массиве

### Описание

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### Список параметров

`key`
  Индекс, который нужно получить из массива. Поддерживается только тип int.

### Возвращаемые значения

Метод возвращает значение, которое связано с индексом. Если индекс отсутствует в массиве, генерируется исключение.

> Замечание: При обнаружении значения, которое закодировали как 64-битное целое число в BSON-массиве, метод вернёт экземпляр класса MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\RuntimeException, если индекс отсутствует в массиве.

### Смотрите также

- ArrayAccess::offsetGet() - Возвращает заданное смещение (ключ)
- MongoDB\BSON\PackedArray::get() - Возвращает значение индекса массива

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Реализует интерфейс ArrayAccess

### Описание

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Метод устанавливает значение ключа `key` параметру `value`.

### Список параметров

`key`
  Устанавливаемый индекс.
`value`
  Новое значение для параметра `key`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- Метод всегда выбрасывает исключение MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Реализует интерфейс ArrayAccess

### Описание

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Метод удаляет значение по индексу.

### Список параметров

`key`
  Удаляемый индекс.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- Метод всегда выбрасывает исключение MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Возвращает представление BSON-массива в каноническом расширенном JSON-формате

### Описание

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Метод преобразовывает BSON-массив в представление » в каноническом расширенном JSON-формате. В каноническом формате в ущерб краткости вывода отдают преимущество точности типов. В каноническом формате создают данные вывода, которым доступно преобразование обратно в BSON-формат без потери информации о типе, например, числовые типы останутся дифференцированными.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строку, которая содержит представление BSON-массива » в каноническом расширенном JSON-формате.

### Примеры

Пример #1 Пример преобразования BSON-массива в представление в формате Canonical Extended JSON методом MongoDB\BSON\PackedArray::toCanonicalExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

Результат выполнения приведённого примера:

    ["foo", {"$numberInt": "123"}, {"$numberLong": "4294967295"}, {"$oid": "56315a7c6118fd1b920270b1"}]

### Смотрите также

- MongoDB\BSON\PackedArray::fromJSON() - Создаёт новый экземпляр BSON-массива из JSON-строки
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Возвращает представление BSON-массива в слабом расширенном JSON-формате
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- » Спецификация расширенного JSON-формата
- » BSON-типы

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Возвращает PHP-представление массива BSON

### Описание

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### Список параметров

`typeMap` (array)
  Конфигурация карты типов.

### Возвращаемые значения

Декодированное значение PHP.

> Замечание: Если в массиве BSON встречается значение, закодированное как 64-битное целое число, то возвращаемым значением метода будет экземпляр MongoDB\BSON\Int64.

### Ошибки

- Выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если класс в карте типов не может быть инициализирован или не реализует интерфейс MongoDB\BSON\Unserializable.

### Смотрите также

- MongoDB\BSON\toPHP() - Возвращает PHP-представление BSON-значения
- » Типы BSON

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Возвращает представление BSON-массива в слабом расширенном JSON-формате

### Описание

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Метод преобразовывает BSON-массив в представление » в слабом расширенном JSON-формате. В слабом формате в ущерб точности типов отдают преимущество работе с примитивами JSON-типа. В слабом формате создают данные вывода для API-интерфейсов к веб-сервисам и такие данных проще воспринимать людям.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает строку, которая содержит представление BSON-массива в формате » в слабом расширенном JSON-формате .

### Примеры

Пример #1 Пример преобразования BSON-массива в представление в формате Relaxed Extended JSON методом MongoDB\BSON\PackedArray::toRelaxedExtendedJSON()

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

Результат выполнения приведённого примера:

    ["foo", 123, 4294967295, {"$oid": "56315a7c6118fd1b920270b1"}]

### Смотрите также

- MongoDB\BSON\PackedArray::fromJSON() - Создаёт новый экземпляр BSON-массива из JSON-строки
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Возвращает представление BSON-массива в каноническом расширенном JSON-формате
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Спецификация расширенного JSON-формата
- » BSON-типы

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Возвращает строковое представление BSON-массива

### Описание

final public function MongoDB\BSON\PackedArray::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление массива в формате BSON.

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\PackedArray::__construct — Создаёт новый массив BSON (не используется)
- MongoDB\BSON\PackedArray::fromJSON — Создаёт новый экземпляр BSON-массива из JSON-строки
- MongoDB\BSON\PackedArray::fromPHP — Создаёт новый экземпляр BSON-массива из PHP-данных
- MongoDB\BSON\PackedArray::get — Возвращает значение индекса массива
- MongoDB\BSON\PackedArray::getIterator — Возвращает итератор для массива BSON
- MongoDB\BSON\PackedArray::has — Возвращает информацию о том, содержится ли индекс в массиве
- MongoDB\BSON\PackedArray::offsetExists — Возвращает информацию о том, содержится ли индекс в массиве
- MongoDB\BSON\PackedArray::offsetGet — Возвращает значение индекса в массиве
- MongoDB\BSON\PackedArray::offsetSet — Реализует интерфейс ArrayAccess
- MongoDB\BSON\PackedArray::offsetUnset — Реализует интерфейс ArrayAccess
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Возвращает представление BSON-массива в каноническом расширенном JSON-формате
- MongoDB\BSON\PackedArray::toPHP — Возвращает PHP-представление массива BSON
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Возвращает представление BSON-массива в слабом расширенном JSON-формате
- MongoDB\BSON\PackedArray::__toString — Возвращает строковое представление BSON-массива

# Класс MongoDB\BSON\Iterator

(mongodb >=1.16.0)

## Введение

Итератор, используемый для обхода BSON-документа или массива.

## Обзор класса

final class MongoDB\BSON\Iterator implements Iterator {
/* Методы */
final private function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Создаёт новый итератор BSON (не используется)

### Описание

final private function MongoDB\BSON\Iterator::__construct()

Объекты MongoDB\BSON\Iterator создаются путём вызова MongoDB\BSON\Document::getIterator() или MongoDB\BSON\PackedArray::getIterator() и не могут быть инициализированы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- MongoDB\BSON\Document::getIterator() - Возвращает итератор для документа BSON
- MongoDB\BSON\PackedArray::getIterator() - Возвращает итератор для массива BSON
- » Типы BSON

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Возвращает текущий элемент

### Описание

public function MongoDB\BSON\Iterator::current(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает значение текущего элемента.

> Замечание: Если в структуре BSON встречается значение, закодированное как 64-битное целое число, то возвращаемым значением метода будет экземпляр MongoDB\BSON\Int64.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключениеMongoDB\Driver\Exception\LogicException, если итератор не является корректным.

### Смотрите также

- Iterator::current() - Возврат текущего элемента

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Возвращает ключ текущего элемента

### Описание

public function MongoDB\BSON\Iterator::key(): string|int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ключ текущего элемента. При итерации BSON-документа ключом всегда будет строка (string). При итерации массива BSON ключом будет целое число (int).

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\LogicException, если итератор не является корректным.

### Смотрите также

- Iterator::key() - Возвращает ключ текущего элемента

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Продвигает итератор до следующего элемента

### Описание

public function MongoDB\BSON\Iterator::next(): void

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- Iterator::next() - Переходит к следующему элементу

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Перематывает итератор к первому элементу

### Описание

public function MongoDB\BSON\Iterator::rewind(): void

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- Iterator::rewind() - Возвращает итератор на первый элемент

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Проверяет, является ли текущая позиция корректной

### Описание

public function MongoDB\BSON\Iterator::valid(): bool

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если текущая позиция итератора корректная, в противном случае возвращает `false`.

### Смотрите также

- Iterator::valid() - Проверяет корректность текущей позиции

## Содержание

- MongoDB\BSON\Iterator::__construct — Создаёт новый итератор BSON (не используется)
- MongoDB\BSON\Iterator::current — Возвращает текущий элемент
- MongoDB\BSON\Iterator::key — Возвращает ключ текущего элемента
- MongoDB\BSON\Iterator::next — Продвигает итератор до следующего элемента
- MongoDB\BSON\Iterator::rewind — Перематывает итератор к первому элементу
- MongoDB\BSON\Iterator::valid — Проверяет, является ли текущая позиция корректной

# Класс MongoDB\BSON\Binary

(mongodb >=1.0.0)

## Введение

Класс представляет и обрабатывает типы двоичных данных в виде массива байтов для хранения BSON-документа. Бинарные значения хранят подтипы — идентификаторы, которые указывают тип данных в массиве байтов. Подтипы от 0 до 127 предопределили или зарезервировали. Подтипы в диапазоне 128-255 задаются пользователем.

## Обзор класса

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Константы */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* Методы */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## Предопределённые константы

`MongoDB\BSON\Binary::TYPE_GENERIC`
  Бинарные данные общего подтипа.
`MongoDB\BSON\Binary::TYPE_FUNCTION`
  Функция.
`MongoDB\BSON\Binary::TYPE_OLD_BINARY`
  Бинарные данные общего подтипа (константу объявили устаревшей в пользу `MongoDB\BSON\Binary::TYPE_GENERIC`).
`MongoDB\BSON\Binary::TYPE_OLD_UUID`
  Универсальный уникальный идентификатор (константу объявили устаревшей в пользу `MongoDB\BSON\Binary::TYPE_UUID`). Обязательное требование к двоичным данным этого типа в объекте Binary — длина составляет 16 байтов. Исторически другие драйверы кодировали значения этого типа по правилам, которые соответствовали внутренним языковым соглашениям (например, с разным порядком байтов), что делает тип непереносимым. PHP-модуль не применяет обработок для кодирования или декодирования данных этого типа.
`MongoDB\BSON\Binary::TYPE_UUID`
  Универсальный уникальный идентификатор. Обязательное требование к двоичным данным этого типа в объекте Binary — длина составляет 16 байтов и данные закодировали по правилам стандарта » RFC 4122.
`MongoDB\BSON\Binary::TYPE_MD5`
  Хеш в формате MD5. Обязательное требование к двоичным данным этого типа в объекте Binary — длина составляет 16 байтов.
`MongoDB\BSON\Binary::TYPE_ENCRYPTED`
  Зашифрованное значение. Подтип для шифрования на стороне клиента.
`MongoDB\BSON\Binary::TYPE_COLUMN`
  Данные столбца. Подтип для коллекций временны́х рядов.
`MongoDB\BSON\Binary::TYPE_SENSITIVE`
  Конфиденциальные данные. Подтип для конфиденциальных данных, которые по возможности исключают из логирования на стороне сервера.
`MongoDB\BSON\Binary::TYPE_VECTOR`
  Векторные данные. Подтип оптимизирует хранение векторов и ускоряет векторный поиск в MongoDB.
`MongoDB\BSON\Binary::TYPE_USER_DEFINED`
  Пользовательский тип. Типы с 0 по 127 предопределили или зарезервировали, а типы со 128 по 255 предусмотрели для определения в пользовательских целях.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.2.0 | Добавили константу `MongoDB\BSON\Binary::TYPE_VECTOR`, а также функции MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType() и MongoDB\BSON\Binary::toArray().
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.17.0 | Добавили тип `MongoDB\BSON\Binary::TYPE_SENSITIVE`.
PECL-модуль mongodb 1.12.0 | Реализовали интерфейс Stringable для PHP 8.0+. Добавили тип `MongoDB\BSON\Binary::TYPE_COLUMN`.
PECL-модуль mongodb 1.7.0 | Добавили тип `MongoDB\BSON\Binary::TYPE_ENCRYPTED`.
PECL-модуль mongodb 1.3.0 | Реализовали интерфейс MongoDB\BSON\BinaryInterface.
PECL-модуль mongodb 1.2.0 | Реализовали интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Создаёт новый объект с типом данных Binary

### Описание

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### Список параметров

`data` (string)
  Двоичные данные.
`type` (int)
  8-разрядное целое число, которое указывает тип данных. По умолчанию принимает значение `MongoDB\BSON\Binary::TYPE_GENERIC`, если не указали другое.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если в параметр `type` передали значение, которое отличается от беззнакового 8-разрядного целого числа.
- Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если для параметра `type` установили значение `MongoDB\BSON\Binary::TYPE_UUID` или `MongoDB\BSON\Binary::TYPE_OLD_UUID`, а длина `data` не равна 16 байтам.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.15.0 | Параметр `type` по умолчанию принимает значение `MongoDB\BSON\Binary::TYPE_GENERIC`, если не указали другое.
PECL mongodb 1.3.0 | Метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если для параметра `type` установили значение `MongoDB\BSON\Binary::TYPE_UUID` или `MongoDB\BSON\Binary::TYPE_OLD_UUID`, а длина `data` не равна 16 байтам.
PECL mongodb 1.1.3 | Метод выбрасывает исключениеMongoDB\Driver\Exception\InvalidArgumentException, если в параметр `type` передали значение, которое отличается от беззнакового 8-разрядного целого числа.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\Binary::__construct()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Создаёт объект Binary с подтипом `MongoDB\BSON\Binary::SUBTYPE_VECTOR` из массива векторных данных и типа вектора

### Описание

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### Список параметров

`vector` (array)

  Массив значений вектора. Тип значений задаётся параметром `vectorType`:

  - `MongoDB\BSON\VectorType::Float32` — значения float
  - `MongoDB\BSON\VectorType::Int8` — 8-разрядные значения int от `-127` до `128`
  - `MongoDB\BSON\VectorType::PackedBit` — значения bool или 1-разрядные значения int: `0` или `1`
`vectorType` (MongoDB\BSON\VectorType)
  Тип векторных данных.

### Возвращаемые значения

Метод возвращает новый объект Binary с подтипом `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\Binary::toArray() - Возвращает вектор Binary с подтипом MongoDB\BSON\Binary::SUBTYPE_VECTOR в виде массива
- MongoDB\BSON\Binary::getVectorType() - Возвращает тип данных объекта Binary с подтипом вектора
- MongoDB\BSON\VectorType
- » Типы BSON

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Возвращает данные, которые содержит объект типа данных Binary

### Описание

final public function MongoDB\BSON\Binary::getData(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает двоичные данные, которые содержит объект типа данных Binary.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\Binary::getData()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

Результат выполнения приведённого примера:

    string(3) "foo"

### Смотрите также

- » BSON-типы

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Возвращает тип данных, которые содержит объект типа данных Binary

### Описание

final public function MongoDB\BSON\Binary::getType(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает тип двоичных данных, которые содержит объект типа данных Binary.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\Binary::getType()

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

Результат выполнения приведённого примера:

    int(0)

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Возвращает тип данных объекта Binary с подтипом вектора

### Описание

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает тип данных вектора Binary.

### Ошибки

- Метод выбросит исключение MongoDB\Driver\Exception\LogicException, если вектор не принадлежит подтипу `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- » Типы BSON
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Binary.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Возвращает вектор Binary с подтипом `MongoDB\BSON\Binary::SUBTYPE_VECTOR` в виде массива

### Описание

final public function MongoDB\BSON\Binary::toArray(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив с данными вектора.

### Ошибки

- Метод выбросит исключение MongoDB\Driver\Exception\LogicException, если вектор не принадлежит подтипу `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\BSON\Binary::fromVector() - Создаёт объект Binary с подтипом MongoDB\BSON\Binary::SUBTYPE_VECTOR из массива векторных данных и типа вектора
- » Типы BSON

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Возвращает данные, которые содержит объект типа данных Binary

### Описание

final public function MongoDB\BSON\Binary::__toString(): string

Псевдоним метода MongoDB\BSON\Binary::getData().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает двоичные данные, которые содержит объект типа данных Binary.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\Binary::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

Результат выполнения приведённого примера:

    string(3) "foo"

### Смотрите также

- MongoDB\BSON\Binary::getData() - Возвращает данные, которые содержит объект типа данных Binary
- » BSON-типы

## Содержание

- MongoDB\BSON\Binary::__construct — Создаёт новый объект с типом данных Binary
- MongoDB\BSON\Binary::fromVector — Создаёт объект Binary с подтипом MongoDB\BSON\Binary::SUBTYPE_VECTOR из массива векторных данных и типа вектора
- MongoDB\BSON\Binary::getData — Возвращает данные, которые содержит объект типа данных Binary
- MongoDB\BSON\Binary::getType — Возвращает тип данных, которые содержит объект типа данных Binary
- MongoDB\BSON\Binary::getVectorType — Возвращает тип данных объекта Binary с подтипом вектора
- MongoDB\BSON\Binary::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Binary::toArray — Возвращает вектор Binary с подтипом MongoDB\BSON\Binary::SUBTYPE_VECTOR в виде массива
- MongoDB\BSON\Binary::__toString — Возвращает данные, которые содержит объект типа данных Binary

# Перечисление MongoDB\BSON\VectorType

(mongodb >=2.2.0)

## Введение

Перечисление MongoDB\BSON\VectorType указывает тип векторных данных, которые хранятся в объекте MongoDB\BSON\Binary с подтипом `MongoDB\BSON\Binary::TYPE_VECTOR`.

## Обзор перечисления

enum MongoDB\BSON\VectorType
{
case Float32 ; // Каждый элемент в векторе — 32-разрядное число с плавающей точкой.
case Int8 ; // Каждый элемент в векторе — 8-разрядное целочисленное значение.
case PackedBit ; // Каждый элемент в векторе — 1-разрядное значение. При создании векторов этого типа передают значения bool или 1-разрядные значения int: `0` или `1`.
}

# Класс MongoDB\BSON\Decimal128

(mongodb >=1.2.0)

## Введение

Тип BSON для » Decimal128 формата с плавающей точкой, который поддерживает числа до 34 десятичных знаков, или значащих цифр, и диапазон экспонент от -6143 до +6144.

В отличие от типа double BSON, или тип float в PHP, который хранит только приблизительные значения десятичных значений, тип данных decimal хранит точное значение. Например, `MongoDB\BSON\Decimal128('9.99')` содержит точное значение 9.99, где двойное значение 9.99 будет содержать приблизительное значение 9.9900000000000002131628….

> Замечание: MongoDB\BSON\Decimal128 совместим только с MongoDB 3.4+. При попытке использовать тип BSON с более ранними версиями приведёт к ошибке.

## Обзор класса

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\Decimal128Interface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Создаёт новый Decimal128

### Описание

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> Замечание: MongoDB\BSON\Decimal128 совместим только с MongoDB 3.4+. При попытке использовать тип BSON с более ранними версиями приведёт к ошибке.

### Список параметров

`value` (string)
  Десятичная строка.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выдаёт исключение MongoDB\Driver\Exception\InvalidArgumentException, если `value` не является допустимой десятичной строкой.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Decimal128::__construct()

    <?php

    var_dump(new MongoDB\BSON\Decimal128(1234.5678));
    var_dump(new MongoDB\BSON\Decimal128(NAN));
    var_dump(new MongoDB\BSON\Decimal128(INF));

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(9) "1234.5678"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(3) "NaN"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(8) "Infinity"
    }

### Смотрите также

- » Формат с плавающей точкой Decimal128
- » Типы BSON

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Decimal128.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Возвращает строковое представление Decimal128

### Описание

final public function MongoDB\BSON\Decimal128::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Decimal128.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Decimal128::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
    var_dump((string) new MongoDB\BSON\Decimal128(NAN));
    var_dump((string) new MongoDB\BSON\Decimal128(INF));

    ?>

Вывод приведённого примера будет похож на:

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### Смотрите также

- » Формат с плавающей точкой Decimal128
- » Типы BSON

## Содержание

- MongoDB\BSON\Decimal128::__construct — Создаёт новый Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Decimal128::__toString — Возвращает строковое представление Decimal128

# Класс MongoDB\BSON\Javascript

(mongodb >=1.0.0)

## Введение

Класс представляет BSON-тип для JavaScript-кода. Конструктор класс принимает необязательный документ области видимости, который сопоставляет идентификаторы со значениями и определяет область, в которой код должен оцениваться сервером.

> Замечание: С этим BSON-тип часто работают при выполнении команд базы данных, которые принимают Javascript-функцию как параметр, например » mapReduce.

## Обзор класса

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\JavascriptInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Конструктор Javascript

### Описание

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### Список параметров

`code` (string)
  Код Javascript.
`scope` (array|object)
  Контекст Javascript.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Порождает исключение MongoDB\Driver\Exception\InvalidArgumentException если `code` содержит null-байты.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.2.0 | Порождает исключение MongoDB\Driver\Exception\InvalidArgumentException если `code` содержит null-байты. Ранее, в подобном случае, аргумент обрезался про первому встретившемуся null-байту.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Javascript::__construct()

    <?php

    $code = new MongoDB\BSON\Javascript('function() { return 1; }');
    var_dump($code);

    $codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
    var_dump($codews);

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\Javascript)#1 (2) {
      ["javascript"]=>
      string(24) "function() { return 1; }"
      ["scope"]=>
      object(stdClass)#2 (0) {
      }
    }
    object(MongoDB\BSON\Javascript)#2 (2) {
      ["javascript"]=>
      string(26) "function() { return foo; }"
      ["scope"]=>
      object(stdClass)#1 (1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Возвращает код JavaScript

### Описание

final public function MongoDB\BSON\Javascript::getCode(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код JavaScript.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Javascript::getCode()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

Результат выполнения приведённого примера:

    string(33) "function foo(bar) { return bar; }"

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Возвращает область документа JavaScript

### Описание

final public function MongoDB\BSON\Javascript::getScope(): ?object

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает область документа JavaScript или `null` в случае, если области нет.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Javascript::getScope()

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getScope());

    $js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
    var_dump($js->getScope());

    ?>

Результат выполнения приведённого примера:

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Возвращает представление, которое может быть преобразовано в JSON

### Описание

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает данные, которые могут быть сериализованы json_encode() для создания JSON-представления MongoDB\BSON\Javascript.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Расширенный JSON MongoDB

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Возвращает код JavaScript

### Описание

final public function MongoDB\BSON\Javascript::__toString(): string

Псевдоним метода MongoDB\BSON\Javascript::getCode().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код JavaScript.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Javascript::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

Результат выполнения приведённого примера:

    string(33) "function foo(bar) { return bar; }"

### Смотрите также

- MongoDB\BSON\Javascript::getCode() - Возвращает код JavaScript
- » Типы BSON

## Содержание

- MongoDB\BSON\Javascript::__construct — Конструктор Javascript
- MongoDB\BSON\Javascript::getCode — Возвращает код JavaScript
- MongoDB\BSON\Javascript::getScope — Возвращает область документа JavaScript
- MongoDB\BSON\Javascript::jsonSerialize — Возвращает представление, которое может быть преобразовано в JSON
- MongoDB\BSON\Javascript::__toString — Возвращает код JavaScript

# Класс MongoDB\BSON\MaxKey

(mongodb >=1.0.0)

## Введение

Особый BSON-тип, который сравнивается выше остальных возможных значений BSON-элементов.

> Замечание: Это внутренний тип СУБД MongoDB для индексации и шардирования.

## Обзор класса

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Методы */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.3.0 | Класс тепрерь реализует интерфейс MongoDB\BSON\MaxKeyInterface.
PECL-модуль mongodb 1.2.0 | Класс тепрерь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Конструктор MaxKey

### Описание

final public function MongoDB\BSON\MaxKey::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\MaxKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### Смотрите также

- » Типы BSON

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\MaxKey.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

## Содержание

- MongoDB\BSON\MaxKey::__construct — Конструктор MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

# Класс MongoDB\BSON\MinKey

(mongodb >=1.0.0)

## Введение

Особый BSON-тип, который сравнивается ниже остальных возможных значений BSON-элементов.

> Замечание: Это внутренний тип СУБД MongoDB для индексации и шардирования.

## Обзор класса

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Методы */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\MinKeyInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Конструктор MinKey

### Описание

final public function MongoDB\BSON\MinKey::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\MinKey::__construct()

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### Смотрите также

- » Типы BSON

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\MinKey.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

## Содержание

- MongoDB\BSON\MinKey::__construct — Конструктор MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

# Класс MongoDB\BSON\ObjectId

(mongodb >=1.0.0)

## Введение

Класс представляет BSON-данные с типом » ObjectId. Значение состоит из 12 байтов, в которых первые четыре байта — метка времени, которая отражает время, в которое создали объект ObjectId. Подробный состав значения:

- 4-байтовое значение, которое представляет количество секунд, которое прошло с начала эпохи Unix
- 5-байтовое случайное число, которое уникально для машины и процесса
- 3-байтовый счётчик, который начинается со случайного значения

В БД MongoDB для каждого документа, который хранится в коллекции, требуется уникальное поле `_id`, которое играет роль первичного ключа. Модуль автоматически генерирует значение ObjectId для поля `_id`, если во вставленном документе нет поля `_id`.

Идентификаторы ObjectId для поля `_id` дают следующую дополнительную выгоду:

- У метода MongoDB\BSON\ObjectId::getTimestamp() будет доступ ко времени, в которое создали значение ObjectId.
- Сортировка по полю `_id`, которое хранит значения ObjectId, примерно эквивалентна сортировке по времени создания.

## Обзор класса

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс переименовали из `MongoDB\BSON\ObjectID` в `MongoDB\BSON\ObjectId`. Класс теперь реализует интерфейс MongoDB\BSON\ObjectIdInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Создаёт новый ObjectId

### Описание

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### Список параметров

`id` (string)
  24-символьная шестнадцатеричная строка. Если не указано, модуль сгенерирует ObjectId.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Метод выдаёт исключение MongoDB\Driver\Exception\InvalidArgumentException если `id` — не 24-символьная шестнадцатеричная строка.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\ObjectId::__construct()

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### Смотрите также

- » Справка по ObjectId
- » Типы BSON: ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Возвращает метку времени ObjectId

### Описание

final public function MongoDB\BSON\ObjectId::getTimestamp(): int

Компонент метки времени в ObjectId - это его наиболее значимые 32 бита, которые обозначают количество секунд с начала эпохи Unix. Это значение читается, как 32-разрядное целое число без знака с порядком байтов в старшем порядке.

> Замечание: Поскольку целочисленный тип в PHP — знаковый, некоторые значения, которые получают этим методом, на 32-битных платформах могут превратиться в отрицательные целые числа. Чтобы получить строковое представление беззнакового целого, пользуются шаблоном форматирования "%u" функции sprintf().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает метку времени ObjectId.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\ObjectId::getTimestamp()

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

Вывод приведённого примера будет похож на:

    integer(1484854719)
    integer(42)

### Смотрите также

- » Справка по ObjectId
- » Типы BSON: ObjectId

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\ObjectId.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Возвращает шестнадцатеричное представление ObjectId

### Описание

final public function MongoDB\BSON\ObjectId::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает шестнадцатеричное представление ObjectId.

### Примеры

Пример #1 Пример использования MongoDB\BSON\ObjectId::__toString()

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Вывод приведённого примера будет похож на:

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### Смотрите также

- » Справка по ObjectId
- » Типы BSON: ObjectId

## Содержание

- MongoDB\BSON\ObjectId::__construct — Создаёт новый ObjectId
- MongoDB\BSON\ObjectId::getTimestamp — Возвращает метку времени ObjectId
- MongoDB\BSON\ObjectId::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\ObjectId::__toString — Возвращает шестнадцатеричное представление ObjectId

# Класс MongoDB\BSON\Regex

(mongodb >=1.0.0)

## Введение

Класс представляет BSON-тип для шаблона регулярного выражения и дополнительных » флагов.

> Замечание: С этим BSON-типом часто работают при запросах к базе данных. Альтернативно указывают оператор запроса » $regex.

## Обзор класса

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\RegexInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Создаёт новый Regex

### Описание

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### Список параметров

`pattern` (string)
  Шаблон регулярного выражения.

  > Замечание: Шаблон не должен быть заключён в символы-разделители.

`flags` (string)
  » Флаги регулярных выражений. Символы в этом аргументе будут отсортированы в алфавитном порядке.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выдаёт MongoDB\Driver\Exception\InvalidArgumentException, если `pattern` или `flags` содержат нулевые байты.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.2.0 | Аргумент `flags` является необязательным и по умолчанию равен пустой строке. Символы в аргументе `flags` будут отсортированы в алфавитном порядке при построении регулярного выражения. Ранее символы хранились в указанном порядке. Выдаётся MongoDB\Driver\Exception\InvalidArgumentException, если `pattern` или `flags` содержат нулевые байты. Ранее значения были бы обрезаны в первом нулевом байте.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Regex::__construct()

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### Смотрите также

- » Типы BSON
- » Поддерживаемые флаги регулярных выражений

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Возвращает флаги Regex

### Описание

final public function MongoDB\BSON\Regex::getFlags(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает флаги Regex.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Regex::getFlags()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

Вывод приведённого примера будет похож на:

    string(1) "i"

### Смотрите также

- » Типы BSON
- » Поддерживаемые флаги регулярных выражений

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Возвращает шаблон Regex

### Описание

final public function MongoDB\BSON\Regex::getPattern(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает шаблон Regex.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Regex::getPattern()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

Вывод приведённого примера будет похож на:

    string(5) "regex"

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Regex.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Возвращает строковое представление Regex

### Описание

final public function MongoDB\BSON\Regex::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Regex.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Regex::__toString()

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

Результат выполнения приведённого примера:

    string(8) "/regex/i"

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\Regex::__construct — Создаёт новый Regex
- MongoDB\BSON\Regex::getFlags — Возвращает флаги Regex
- MongoDB\BSON\Regex::getPattern — Возвращает шаблон Regex
- MongoDB\BSON\Regex::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Regex::__toString — Возвращает строковое представление Regex

# Класс MongoDB\BSON\Timestamp

(mongodb >=1.0.0)

## Введение

Класс представляет » метку времени BSON. Значение состоит из 4-байтовой метки времени для представления секунд с начала эпохи и 4-байтового приращения.

> Замечание: Это внутренний тип СУБД MongoDB для репликации и шардирования. Тип не предназначен для общего хранения дат, вместо него лучше использовать класс MongoDB\BSON\UTCDateTime.

## Обзор класса

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейсStringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\TimestampInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Создаёт новый Timestamp

### Описание

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### Список параметров

`increment` (int)
  32-разрядное целое число, обозначающее увеличивающийся порядковый номер для операций в течение данной секунды.
`timestamp` (int)
  32-разрядное целое число, обозначающее секунды с начала эпохи Unix.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Timestamp::__construct()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

Результат выполнения приведённого примера:

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### Смотрите также

- » Типы BSON: Timestamps

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Возвращает компонент приращения Timestamp

### Описание

final public function MongoDB\BSON\Timestamp::getIncrement(): int

Компонент приращения Timestamp - это его младшие 32 бита, которые обозначают порядковый номер приращения для операций в течение данной секунды. Это значение читается как 32-разрядное целое число без знака с порядком байтов в старшем порядке.

> Замечание: Поскольку целочисленный тип в PHP — знаковый, некоторые значения, которые получают этим методом, на 32-битных платформах могут превратиться в отрицательные целые числа. Чтобы получить строковое представление беззнакового целого, пользуются шаблоном форматирования "%u" функции sprintf().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает компонент приращения Timestamp.

Внимание

В 32-битных системах этот метод может возвращать отрицательное число. Хотя части приращения и отметки времени типа отметки времени BSON состоят из двух 32-разрядных значений без знака, PHP не может представить их на 32-разрядных платформах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- » Типы BSON: Timestamps

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Возвращает компонент отметки времени Timestamp

### Описание

final public function MongoDB\BSON\Timestamp::getTimestamp(): int

Компонент отметки времени Timestamp - это его наиболее значимые 32 бита, которые обозначают количество секунд с начала эпохи Unix. Это значение читается, как 32-разрядное целое число без знака с порядком байтов в старшем порядке.

> Замечание: Поскольку целочисленный тип в PHP — знаковый, некоторые значения, которые получают этим методом, на 32-битных платформах могут превратиться в отрицательные целые числа. Чтобы получить строковое представление беззнакового целого, пользуются шаблоном форматирования "%u" функции sprintf().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает компонент отметки времени Timestamp.

Внимание

В 32-битных системах этот метод может возвращать отрицательное число. Хотя части приращения и отметки времени типа отметки времени BSON состоят из двух 32-разрядных значений без знака, PHP не может представить их на 32-разрядных платформах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- » Типы BSON: Timestamps

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Timestamp.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Возвращает строковое представление Timestamp

### Описание

final public function MongoDB\BSON\Timestamp::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Timestamp.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Timestamp::__toString()

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

Вывод приведённого примера будет похож на:

    string(11) "[1234:5678]"

### Смотрите также

- » Типы BSON: Timestamps

## Содержание

- MongoDB\BSON\Timestamp::__construct — Создаёт новый Timestamp
- MongoDB\BSON\Timestamp::getIncrement — Возвращает компонент приращения Timestamp
- MongoDB\BSON\Timestamp::getTimestamp — Возвращает компонент отметки времени Timestamp
- MongoDB\BSON\Timestamp::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Timestamp::__toString — Возвращает строковое представление Timestamp

# Класс MongoDB\BSON\UTCDateTime

(mongodb >=1.0.0)

## Введение

Класс представляет » BSON-дату. Значение — 64-разрядное целое число, которое представляет количество миллисекунд с 1 января 1970 г. — начала Unix-эпохи. Отрицательные значения представляют даты до 1970 года.

## Обзор класса

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.
PECL-модуль mongodb 1.3.0 | Класс теперь реализует интерфейс MongoDB\BSON\UTCDateTimeInterface.
PECL-модуль mongodb 1.2.0 | Класс теперь реализует интерфейсы Serializable и JsonSerializable.

# MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Создаёт новый объект UTCDateTime

### Описание

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### Список параметров

`milliseconds` (int|MongoDB\BSON\Int64|DateTimeInterface|null)
  Количество миллисекунд с начала Unix-эпохи — 1 января 1970 г. Отрицательные значения представляют даты до 1970 года. Параметр принимает значения в виде 64-разрядного целого числа (int). В целях совместимости с 32-разрядными системами параметр принимает также объекты MongoDB\BSON\Int64. Метод возьмёт количество миллисекунд с начала эпохи Unix из объекта DateTimeInterface, если его передали в аргументе. Метод возьмёт по умолчанию текущее время, если значение параметра будет равняться `null`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Параметр `milliseconds` больше не принимает аргументы с типом string или float.
PECL-модуль mongodb 1.20.0 | В целях совместимости с 32-разрядными платформами параметр `milliseconds` теперь принимает объекты MongoDB\BSON\Int64. Передача строк (string) и чисел с плавающей точкой (float) устарела.
PECL-модуль mongodb 1.2.0 | Аргумент `milliseconds` необязателен и по умолчанию равен `null` — текущему времени. Аргумент принимает также объекты DateTimeInterface, из которого метод возьмёт количество миллисекунд с начала эпохи Unix. Раньше метод принимал только значения типов int, float или string.

### Примеры

Пример #1 Пример создания нового объекта UTCDateTime методом MongoDB\BSON\UTCDateTime::__construct()

    <?php

    var_dump(new MongoDB\BSON\UTCDateTime);

    var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

    var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

    ?>

Вывод приведённого примера будет похож на:

    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1416445411987"
    }

### Смотрите также

- » BSON-тип Date

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\UTCDateTime.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Возвращает объект DateTime как представление объекта UTCDateTime

### Описание

final public function MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает представление объекта UTCDateTime в виде объекта класса DateTime. Часовой пояс в объекте DateTime предствляется значением UTC.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\UTCDatetime::toDateTime()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTime();

    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Вывод приведённого примера будет похож на:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Смотрите также

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Возвращает объект DateTimeImmutable как представление объекта UTCDateTime
- » BSON-тип Date

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Возвращает объект DateTimeImmutable как представление объекта UTCDateTime

### Описание

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает представление объекта UTCDateTime в виде объекта класса DateTimeImmutable. Часовой пояс в объекте DateTimeImmutable представляется значением UTC.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Примеры

Пример #1 Пример использования метода MongoDB\BSON\UTCDatetime::toDateTimeImmutable()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTimeImmutable();

    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Вывод приведённого примера будет похож на:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Смотрите также

- MongoDB\BSON\UTCDateTime::toDateTime() - Возвращает объект DateTime как представление объекта UTCDateTime
- » BSON-тип Date

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Возвращает строковое представление UTCDateTime

### Описание

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление UTCDateTime.

### Примеры

Пример #1 Пример использования MongoDB\BSON\UTCDateTime::__toString()

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

Результат выполнения приведённого примера:

    string(13) "1416445411987"

### Смотрите также

- » Типы BSON: Date

## Содержание

- MongoDB\BSON\UTCDateTime::__construct — Создаёт новый объект UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\UTCDateTime::toDateTime — Возвращает объект DateTime как представление объекта UTCDateTime
- MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Возвращает объект DateTimeImmutable как представление объекта UTCDateTime
- MongoDB\BSON\UTCDateTime::__toString — Возвращает строковое представление UTCDateTime

# Интерфейс MongoDB\BSON\Type

(mongodb >=1.0.0)

## Введение

Абстрактный базовый интерфейс, который не должен быть реализован напрямую.

## Обзор интерфейса

class MongoDB\BSON\Type {
}

Этот интерфейс не имеет методов. Его единственное назначение - быть базовым интерфейсом для всех классов типов BSON.

# Интерфейс MongoDB\BSON\Persistable

(mongodb >=1.0.0)

## Введение

Классы могут реализовывать этот интерфейс для использования преимуществ автоматического ODM (сопоставление документов объекта) поведения в модуле. Во время сериализации модуль вставляет свойство __pclass, которое содержит имя PHP-класса, в данные, которые возвращает метод MongoDB\BSON\Serializable::bsonSerialize(). Во время десериализации то же свойство __pclass будет использоваться для вывода PHP-класса (независимого от любой конфигурации типа карты), которая должна быть создана до вызова метода MongoDB\BSON\Unserializable::bsonUnserialize(). Дополнительную информацию даёт раздел «Сохранение данных».

> Замечание: Даже если метод MongoDB\BSON\Serializable::bsonSerialize() вернёт последовательный массив, внедрение свойства __pclass приведёт к сериализации объекта как BSON-документа.

## Обзор интерфейса

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* Методы */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* Наследуемые методы */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Предоставляет массив или документ для сериализации в формате BSON

### Описание

abstract public function MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Вызывается при сериализации объекта в BSON. Метод должен возвращать массив (array), stdClass или MongoDB\BSON\Document.

Возвращаемое значение всегда будет сериализовано в виде BSON-документа. Сериализованный документ будет включать поле, которое содержит имя класса объекта. По этой причине в этом методе невозможно вернуть экземпляр класса MongoDB\BSON\PackedArray.

Пользователям рекомендуется включать свойство _id (например, объект класса MongoDB\BSON\ObjectId, который инициализировали в конструкторе) при возврате данных для корневого BSON-документа. В отсутствие свойства _id модуль будет генерировать объект класса MongoDB\BSON\ObjectId для операций вставки, а сервер для операций обновления или вставки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив (array), объект класса stdClass или MongoDB\BSON\Document, который должен быть сериализован как BSON-документ.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL mongodb 1.17.0 | Теперь метод может также возвращать экземпляры классов MongoDB\BSON\Document в дополнение к массиву (array) и объекту класса stdClass.

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ
- MongoDB\BSON\Unserializable::bsonUnserialize() - Создаёт объект из BSON-массива или BSON-документа
- MongoDB\BSON\Persistable
- Сохранение данных

## Содержание

- MongoDB\BSON\Persistable::bsonSerialize — Предоставляет массив или документ для сериализации в формате BSON

# Интерфейс MongoDB\BSON\Serializable

(mongodb >=1.0.0)

## Введение

Классы, которые реализуют этот интерфейс, сами определяют, какие данные возвращать для сериализации в BSON-массив или BSON-документ вместо открытых свойств объекта.

## Обзор интерфейса

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* Методы */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Сериализует данные как BSON-массив или BSON-документ

### Описание

abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Метод вызывается во время сериализации объекта в BSON-формат. По условиям интерфейса метод возвращает массив (array), экземпляр класса stdClass, MongoDB\BSON\Document или MongoDB\BSON\PackedArray.

Корневые документы наподобие объектов класса, который реализует интерфейс MongoDB\BSON\Serializable и который передали в метод MongoDB\BSON\Document::fromPHP(), сериализуются как BSON-документ. Для значений полей ассоциативные массивы и экземпляры класса stdClass метод сериализует как BSON-документ, а последовательные массивы — массивы с последовательными числовыми индексами, которые начинаются с `0` — как BSON-массив.

При возврате данных для корневого BSON-документа пользователям рекомендуют включать в данные возврата свойство _id. Часто идентификатор инициализируют в конструкторе при инициализации объекта MongoDB\BSON\ObjectId, который включают в данные возврата как значение идентификатора. В отсутствие свойства _id модуль сгенерирует значение MongoDB\BSON\ObjectId для операций вставки, а сервер для операций обновления или вставки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив (array), объект класса stdClass, MongoDB\BSON\Document или MongoDB\BSON\PackedArray, который сериализует как BSON-массив или BSON-документ.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.17.0 | Изменили тип возврата array|object. Вместо типа object теперь возвращается тип stdClass. Классы, которые реализуют этот интерфейс, требуется изменить, чтобы методы больше не объявляли тип возврата object. Поскольку тип возврата объявляется заранее, в PHP 8.1 или более новых версиях при несовпадении типов возврата PHP выдаёт предупреждение об устаревании. В дополнение к изменениям, которые описал предыдущий параграф, теперь модуль также поддерживает возврат экземпляров классов MongoDB\BSON\Document и MongoDB\BSON\PackedArray. Обратите внимание, экземпляры класса MongoDB\BSON\PackedArray, которые возвращает метод, при сохранении в качестве корневых документов автоматически преобразовываются в объекты, а при сохранении в виде значения встроенного поля — в массивы.

### Примеры

Пример #1 Пример возврата методом MongoDB\BSON\Serializable::bsonSerialize() ассоциативного массива для корневого документа

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        private $id;

        function __construct()
        {
            $this->id = new MongoDB\BSON\ObjectId;
        }

        function bsonSerialize(): array
        {
            return ['_id' => $this->id, 'foo' => 'bar'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument())->toRelaxedExtendedJSON(), "\n";

    ?>

Вывод приведённого примера будет похож на:

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Пример #2 Пример возврата методом MongoDB\BSON\Serializable::bsonSerialize() последовательного массива для корневого документа

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray())->toRelaxedExtendedJSON(), "\n";

    ?>

Результат выполнения приведённого примера:

    { "0" : 1, "1" : 2, "2" : 3 }

Пример #3 Пример возврата методом MongoDB\BSON\Serializable::bsonSerialize() ассоциативного массива для поля документа

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return ['foo' => 'bar'];
        }
    }

    $value = ['document' => new MyDocument];
    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

Результат выполнения приведённого примера:

    { "document" : { "foo" : "bar" } }

Пример #4 Пример возврата методом MongoDB\BSON\Serializable::bsonSerialize() последовательного массива для поля документа

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    $value = ['array' => new MyArray];
    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

Результат выполнения приведённого примера:

    { "array" : [ 1, 2, 3 ] }

### Смотрите также

- MongoDB\BSON\Unserializable::bsonUnserialize() - Создаёт объект из BSON-массива или BSON-документа
- MongoDB\BSON\Persistable
- Сохранение данных

## Содержание

- MongoDB\BSON\Serializable::bsonSerialize — Сериализует данные как BSON-массив или BSON-документ

# Интерфейс MongoDB\BSON\Unserializable

(mongodb >=1.0.0)

## Введение

Классы, которые реализуют этот интерфейс, разрешается указывать в карте типов для десериализации BSON-массивов и BSON-документов, как корневых, так и встроенных.

## Обзор интерфейса

class MongoDB\BSON\Unserializable {
/* Методы */
abstract public function bsonUnserialize(array `$data`): void
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Создаёт объект из BSON-массива или BSON-документа

### Описание

abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void

Метод вызывается во время десериализации объекта из BSON-формата. Свойства BSON-массива или BSON-документа передадутся в метод в виде массива (array).

При обработке данных из BSON-документа требуется проверить, содержат ли данные свойство _id.

> Замечание: Метод играет роль конструктора объекта. Метод __construct() не будет вызываться после этого метода.

### Список параметров

`data` (array)
  Свойства в BSON-массиве или BSON-документе.

### Возвращаемые значения

Значение возврата этого метода игнорируется.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.

### Примеры

Пример #1 Пример десериализации данных методом MongoDB\BSON\Unserializable::bsonUnserialize()

    <?php

    class MyDocument implements MongoDB\BSON\Unserializable
    {
        private $data = [];

        function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }
    }

    $bson = MongoDB\BSON\Document::fromJSON('{"foo": "bar"}');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

Результат выполнения приведённого примера:

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Смотрите также

- MongoDB\BSON\Serializable::bsonSerialize() - Сериализует данные как BSON-массив или BSON-документ
- MongoDB\BSON\Persistable
- Сохранение данных

## Содержание

- MongoDB\BSON\Unserializable::bsonUnserialize — Создаёт объект из BSON-массива или BSON-документа

# Интерфейс MongoDB\BSON\BinaryInterface

(mongodb >=1.3.0)

## Введение

Этот интерфейс реализован MongoDB\BSON\Binary, но также может использоваться в качестве параметра, возвращаемого значения или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\BinaryInterface {
/* Методы */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Возвращает данные BinaryInterface

### Описание

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает данные BinaryInterface.

### Смотрите также

- MongoDB\BSON\Binary::getData() - Возвращает данные, которые содержит объект типа данных Binary

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Возвращает тип BinaryInterface

### Описание

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает тип BinaryInterface.

### Смотрите также

- MongoDB\BSON\Binary::getType() - Возвращает тип данных, которые содержит объект типа данных Binary

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Возвращает данные BinaryInterface

### Описание

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

Псевдоним метода MongoDB\BSON\BinaryInterface::getData().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает данные BinaryInterface.

### Смотрите также

- MongoDB\BSON\BinaryInterface::getData() - Возвращает данные BinaryInterface
- MongoDB\BSON\Binary::__toString() - Возвращает данные, которые содержит объект типа данных Binary

## Содержание

- MongoDB\BSON\BinaryInterface::getData — Возвращает данные BinaryInterface
- MongoDB\BSON\BinaryInterface::getType — Возвращает тип BinaryInterface
- MongoDB\BSON\BinaryInterface::__toString — Возвращает данные BinaryInterface

# Интерфейс MongoDB\BSON\Decimal128Interface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\Decimal128, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\Decimal128Interface {
/* Методы */
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Возвращает строковое представление Decimal128Interface

### Описание

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Decimal128Interface.

### Смотрите также

- MongoDB\BSON\Decimal128::__toString() - Возвращает строковое представление Decimal128

## Содержание

- MongoDB\BSON\Decimal128Interface::__toString — Возвращает строковое представление Decimal128Interface

# Интерфейс MongoDB\BSON\JavascriptInterface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\Javascript, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\JavascriptInterface {
/* Методы */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Возвращает код JavascriptInterface

### Описание

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код JavascriptInterface.

### Смотрите также

- MongoDB\BSON\Javascript::getCode() - Возвращает код JavaScript

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Возвращает области видимости документа JavascriptInterface

### Описание

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает области видимости документа JavascriptInterface.

### Смотрите также

- MongoDB\BSON\Javascript::getScope() - Возвращает область документа JavaScript

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Возвращает код JavascriptInterface

### Описание

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

Псевдоним метода MongoDB\BSON\JavascriptInterface::getCode().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает код JavascriptInterface.

### Смотрите также

- MongoDB\BSON\JavascriptInterface::getCode() - Возвращает код JavascriptInterface
- MongoDB\BSON\Javascript::__toString() - Возвращает код JavaScript

## Содержание

- MongoDB\BSON\JavascriptInterface::getCode — Возвращает код JavascriptInterface
- MongoDB\BSON\JavascriptInterface::getScope — Возвращает области видимости документа JavascriptInterface
- MongoDB\BSON\JavascriptInterface::__toString — Возвращает код JavascriptInterface

# Интерфейс MongoDB\BSON\MaxKeyInterface

(mongodb >=1.3.0)

## Введение

Этот интерфейс реализован MongoDB\BSON\Javascript, но также может использоваться в качестве параметра, возвращаемого значения или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\MaxKeyInterface {
}

Этот интерфейс не имеет методов.

# Интерфейс MongoDB\BSON\MinKeyInterface

(mongodb >=1.3.0)

## Введение

Этот интерфейс реализован MongoDB\BSON\Javascript, но также может использоваться в качестве параметра, возвращаемого значения или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\MinKeyInterface {
}

Этот интерфейс не имеет методов.

# Интерфейс MongoDB\BSON\ObjectIdInterface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\ObjectId, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\ObjectIdInterface {
/* Методы */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Возвращает компонент отметки времени ObjectIdInterface

### Описание

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает компонент отметки времени ObjectIdInterface.

### Смотрите также

- MongoDB\BSON\ObjectId::getTimestamp() - Возвращает метку времени ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Возвращает шестнадцатеричное представление ObjectIdInterface

### Описание

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает шестнадцатеричное представление ObjectIdInterface.

### Смотрите также

- MongoDB\BSON\ObjectId::__toString() - Возвращает шестнадцатеричное представление ObjectId

## Содержание

- MongoDB\BSON\ObjectIdInterface::getTimestamp — Возвращает компонент отметки времени ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Возвращает шестнадцатеричное представление ObjectIdInterface

# Интерфейс MongoDB\BSON\RegexInterface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\Regex, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\RegexInterface {
/* Методы */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Возвращает флаги RegexInterface

### Описание

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает флаги RegexInterface.

### Смотрите также

- MongoDB\BSON\Regex::getFlags() - Возвращает флаги Regex

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Возвращает шаблон RegexInterface

### Описание

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает шаблон RegexInterface.

### Смотрите также

- MongoDB\BSON\Regex::getPattern() - Возвращает шаблон Regex

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Возвращает строковое представление RegexInterface

### Описание

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление RegexInterface.

### Смотрите также

- MongoDB\BSON\Regex::__toString() - Возвращает строковое представление Regex

## Содержание

- MongoDB\BSON\RegexInterface::getFlags — Возвращает флаги RegexInterface
- MongoDB\BSON\RegexInterface::getPattern — Возвращает шаблон RegexInterface
- MongoDB\BSON\RegexInterface::__toString — Возвращает строковое представление RegexInterface

# Интерфейс MongoDB\BSON\TimestampInterface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\Timestamp, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\TimestampInterface {
/* Методы */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Возвращает инкрементный компонент TimestampInterface

### Описание

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает инкрементный компонент TimestampInterface.

Внимание

В 32-битных системах этот метод может возвращать отрицательное число. Хотя части приращения и отметки времени типа отметки времени BSON состоят из двух 32-разрядных значений без знака, PHP не может представлять их на 32-разрядных платформах.

### Смотрите также

- MongoDB\BSON\Timestamp::getIncrement() - Возвращает компонент приращения Timestamp

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Возвращает компонент отметки времени TimestampInterface

### Описание

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает компонент отметки времени TimestampInterface.

Внимание

В 32-битных системах этот метод может возвращать отрицательное число. Хотя части приращения и отметки времени типа отметки времени BSON состоят из двух 32-разрядных значений без знака, PHP не может представлять их на 32-разрядных платформах.

### Смотрите также

- MongoDB\BSON\Timestamp::getTimestamp() - Возвращает компонент отметки времени Timestamp

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Возвращает строковое представление TimestampInterface

### Описание

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление TimestampInterface.

### Смотрите также

- MongoDB\BSON\Timestamp::__toString() - Возвращает строковое представление Timestamp

## Содержание

- MongoDB\BSON\TimestampInterface::getIncrement — Возвращает инкрементный компонент TimestampInterface
- MongoDB\BSON\TimestampInterface::getTimestamp — Возвращает компонент отметки времени TimestampInterface
- MongoDB\BSON\TimestampInterface::__toString — Возвращает строковое представление TimestampInterface

# Интерфейс MongoDB\BSON\UTCDateTimeInterface

(mongodb >=1.3.0)

## Введение

Интерфейс реализуется классом MongoDB\BSON\UTCDateTime, но интерфейсный тип также возможно указать для параметра, значения возврата или типа свойства в классах пользовательского пространства.

## Обзор класса

class MongoDB\BSON\UTCDateTimeInterface {
/* Методы */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Возвращает представление DateTime этого UTCDateTimeInterface

### Описание

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает представление DateTime этого UTCDateTimeInterface. Возвращённый DateTime должен использовать часовой пояс UTC.

### Смотрите также

- MongoDB\BSON\UTCDateTime::toDateTime() - Возвращает объект DateTime как представление объекта UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Возвращает объект DateTimeImmutable, который представляет объект UTCDateTimeInterface

### Описание

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект DateTimeImmutable, который представляет объект UTCDateTimeInterface. Объект DateTimeImmutable вернётся в часовом поясе UTC.

### Смотрите также

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Возвращает объект DateTimeImmutable как представление объекта UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Возвращает строковое представление UTCDateTimeInterface

### Описание

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление UTCDateTimeInterface.

### Смотрите также

- MongoDB\BSON\UTCDateTime::__toString() - Возвращает строковое представление UTCDateTime

## Содержание

- MongoDB\BSON\UTCDateTimeInterface::toDateTime — Возвращает представление DateTime этого UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Возвращает объект DateTimeImmutable, который представляет объект UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Возвращает строковое представление UTCDateTimeInterface

# Класс MongoDB\BSON\DBPointer

(mongodb >=1.4.0)

## Введение

Класс представляет BSON-данные с типом DBPointer. Этот BSON-тип устарел, и объекты этого класса нельзя создать. PHP создаст объект этого класса из BSON-типа DBPointer во время преобразования BSON-данных в PHP, а при сохранении документов в базе данных преобразует объект обратно в BSON-данные.

## Обзор класса

class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Создаёт новый DBPointer (не используется)

### Описание

final private function MongoDB\BSON\DBPointer::__construct()

Объекты MongoDB\BSON\DBPointer создаются путём преобразования из устаревшего типа BSON и не могут быть созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- » BSON Types

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\DBPointer.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Возвращает пустую строку

### Описание

final public function MongoDB\BSON\DBPointer::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает пустую строку.

### Смотрите также

- » BSON Types

## Содержание

- MongoDB\BSON\DBPointer::__construct — Создаёт новый DBPointer (не используется)
- MongoDB\BSON\DBPointer::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\DBPointer::__toString — Возвращает пустую строку

# Класс MongoDB\BSON\Int64

(mongodb >=1.5.0)

## Введение

Класс представляет BSON-тип для 64-разрядного целого числа. Объекты класса создают при декодировании BSON-объекта в PHP-данные, когда 64-битное целое число невозможно представить как целое PHP-число на 32-битных платформах. Объекты класса поддерживают перегруженные арифметические, побитовые операторы и операторы сравнения.

При работе с необработанными BSON-данными через классы MongoDB\BSON\Document, MongoDB\BSON\PackedArray и MongoDB\BSON\Iterator любое 64-битное целое число возвращается как экземпляр этого класса независимо от платформы и доступности представления значения в виде целого PHP-числа. Это гарантирует, что значения передаются в обе стороны без изменения типа.

При кодировании в BSON-объект объекты этого класса преобразовываются обратно в 64-битный целочисленный тип, даже если значение помещается в 32-битное целое число. Это явно сохраняет значения как 64-разрядные целые BSON-числа.

## Обзор класса

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Методы */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.16.0 | Теперь класс доступен для инициализации на всех платформах. Добавили поддержку перегруженных арифметических, побитовых операторов и операторов сравнения.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.

# MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Создаёт новый Int64

### Описание

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Создаёт новый экземпляр MongoDB\BSON\Int64 для заданного целого числа.

### Список параметров

`value` (int|string)
  Значение, присваиваемое экземпляру Int64. Это значение может быть предоставлено как целое число (int) или строка (string), последнее требуется на 32-битных платформах для представления 64-битных значений.

### Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.16.0 | Метод стал доступен для поддержки создания экземпляров Int64 при работе с необработанным BSON.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.
- Выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException, если строка `value` не может быть разобрана как 64-битное целое число.

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Int64.

> Замечание: Вывод соответствует функции MongoDB\BSON\toCanonicalExtendedJSON(), которая использует » канонический расширенный формат JSON. Это отличается от других BSON-классов, которые используют устаревший расширенный JSON-формат для конкретного драйвера (MongoDB\BSON\toJSON()), чтобы обеспечить правильное представление 64-разрядного целочисленного значения на 32-разрядных платформах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Возвращает строковое представление Int64

### Описание

final public function MongoDB\BSON\Int64::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Int64.

### Примеры

Пример #1 Пример использования MongoDB\BSON\Int64::__toString()

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

Вывод приведённого примера будет похож на:

    string(19) "9223372036854775807"

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\Int64::__construct — Создаёт новый Int64
- MongoDB\BSON\Int64::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Int64::__toString — Возвращает строковое представление Int64

# Класс MongoDB\BSON\Symbol

(mongodb >=1.4.0)

## Введение

Класс представляет BSON-данные, которые принадлежат типу Symbol. Этот BSON-тип устарел, и объекты этого класса нельзя создать. PHP создаст объект этого класса из BSON-типа Symbol во время преобразования BSON-данных в PHP, а при сохранении документов в базе данных преобразует объект обратно в BSON-данные.

## Обзор класса

class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* Методы */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Создаёт новый Symbol (не используется)

### Описание

final private function MongoDB\BSON\Symbol::__construct()

Объекты MongoDB\BSON\Symbol создаются путём преобразования из устаревшего типа BSON и не могут быть созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Symbol.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Возвращает Symbol в виде строки

### Описание

final public function MongoDB\BSON\Symbol::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строковое представление Symbol.

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\Symbol::__construct — Создаёт новый Symbol (не используется)
- MongoDB\BSON\Symbol::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Symbol::__toString — Возвращает Symbol в виде строки

# Класс MongoDB\BSON\Undefined

(mongodb >=1.4.0)

## Введение

Класс представляет BSON-данные с типом Undefined. Этот BSON-тип устарел, и объекты этого класса нельзя создать. PHP создаст объект этого класса из BSON-типа Undefined при преобразовании BSON-данных в PHP, а при сохранении документов в базе данных преобразует объект обратно в BSON-данные.

## Обзор класса

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* Методы */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс больше не реализует интерфейс Serializable.
PECL-модуль mongodb 1.12.0 | Класс теперь реализует интерфейс Stringable для PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Создаёт новый Undefined (не используется)

### Описание

final private function MongoDB\BSON\Undefined::__construct()

Объекты MongoDB\BSON\Undefined создаются путём преобразования из устаревшего типа BSON и не могут быть созданы напрямую.

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- » Типы BSON

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Возвращает преобразуемое в JSON-формат представление

### Описание

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает данные, которым доступна сериализация функцией json_encode(), чтобы создать расширенное JSON-представление объекта MongoDB\BSON\Undefined.

> Замечание: Вывод соответствует выводу функции MongoDB\BSON\toJSON(), которая использует унаследованный, специфичный для драйвера, расширенный формат JSON. Он не обязательно будет подходить под » relaxed или » canonical представления расширенного JSON, используемых в MongoDB\BSON\toRelaxedExtendedJSON() и MongoDB\BSON\toCanonicalExtendedJSON(), соответственно.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- JsonSerializable::jsonSerialize() - Задаёт данные, которые должны быть сериализованы в JSON
- json_encode() - Возвращает JSON-представление данных
- MongoDB\BSON\toCanonicalExtendedJSON() - Возвращает Canonical Extended JSON-представление BSON-значения
- MongoDB\BSON\toRelaxedExtendedJSON() - Возвращает представление BSON-значения в слабом расширенном JSON-формате
- » Тип MongoDB Extended JSON

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Возвращает пустую строку

### Описание

final public function MongoDB\BSON\Undefined::__toString(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает пустую строку.

### Смотрите также

- » Типы BSON

## Содержание

- MongoDB\BSON\Undefined::__construct — Создаёт новый Undefined (не используется)
- MongoDB\BSON\Undefined::jsonSerialize — Возвращает преобразуемое в JSON-формат представление
- MongoDB\BSON\Undefined::__toString — Возвращает пустую строку

# Классы мониторинга и функции подписчика

## Содержание

- Функции
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\LogSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# Функции

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Регистрирует подписчика на событие мониторинга глобально

### Описание

function MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Метод регистрирует подписчика событий мониторинга глобально. Подписчик получит уведомление о каждом событии в модуле для любого менеджера.

> Замечание: Если подписчик `subscriber` уже зарегистрирован глобально, метод отработает без результата. Если подписчик `subscriber` также зарегистрирован с одним или несколькими менеджерами, он всё равно получит уведомление о каждом событии для каждого менеджера только один раз.

### Список параметров

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Подписчик событий мониторинга для глобальной регистрации.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\removeSubscriber() - Отменяет глобальную регистрацию подписчика на событие мониторинга
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Отменяет глобальную регистрацию подписчика на событие мониторинга

### Описание

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Отменяет глобальную регистрацию подписчика на событие мониторинга.

> Замечание: Если `subscriber` ещё не зарегистрирован глобально, функция отработает без результата.

### Список параметров

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  Подписчик на событие мониторинга для глобальной отмены регистрации.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::removeSubscriber() - Отменяет регистрацию подписчика на событие мониторинга в данном объекте Manager
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

## Содержание

- MongoDB\Driver\Monitoring\addSubscriber — Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Monitoring\removeSubscriber — Отменяет глобальную регистрацию подписчика на событие мониторинга

# Класс MongoDB\Driver\Monitoring\CommandFailedEvent

(mongodb >=1.3.0)

## Введение

Класс MongoDB\Driver\Monitoring\CommandFailedEvent содержит информацию о неудачной команде.

## Обзор класса

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Методы */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера, который выполнил команду.
port
  Порт сервера, который выполнил команду.
commandName
  Имя команды.
databaseName
  Имя базы данных.
duration
  Длительность команды в микросекундах. Длительность представляет собой расчётное значение, которое включает время отправки сообщения и получения ответа от сервера.
error
  Исключение, которое было выброшено при сбое команды.
reply
  Документ ответа об ошибке, который вернул сервер.
operationId
  Идентификатор операции. Используется для связывания событий между собой, например, для bulk-операций записи, которые могут порождать несколько команд.
requestId
  Идентификатор запроса. Используется для связывания события MongoDB\Driver\Monitoring\CommandFailedEvent с соответствующим MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  Идентификатор службы или `null`, если сервер не поддерживает его (то есть когда не используется режим балансировки нагрузки).
serverConnectionId
  Идентификатор соединения с сервером или `null`, если недоступен.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly. Свойство duration заменяет метод getDurationMicros().

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Возвращает имя команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Возвращает имя команды (например, `"find"`, `"aggregate"`).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Возвращает базу данных, в которой выполнилась команда

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает базу данных, в которой выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Возвращает длительность команды в микросекундах

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

Длительность команды - это рассчитанное значение, которое включает время отправки сообщения и получение ответа от сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает продолжительность команды в микросекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Возвращает исключение, связанное с неудачной командой

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает исключение (Exception), связанное с неудачной командой.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Возвращает имя хоста сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя хоста сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Возвращает идентификатор операции команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

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

> Замечание: Поскольку несколько команд могут совместно использовать один и тот же идентификатор операции, нецелесообразно использовать его для связывания объектов событий друг с другом. Вместо этого следует использовать идентификатор запроса, возвращённый MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор операции команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Возвращает порт сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает порт сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Возвращает документ ответа команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

Ответный документ будет преобразован из BSON в PHP с использованием правил десериализации по умолчанию (например, документы BSON будут преобразованы в stdClass).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ ответа команды в виде объекта stdClass.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)
- Сохранение данных

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Возвращает идентификатор запроса команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

Идентификатор запроса генерируется модулем и может использоваться для связывания объекта MongoDB\Driver\Monitoring\CommandFailedEvent с предыдущим объектом MongoDB\Driver\Monitoring\CommandStartedEvent.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор запроса команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Возвращает сервер, на котором выполнилась команда

Внимание

Метод УСТАРЕЛ с версии модуля 1.20.0, а версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать методы MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() и MongoDB\Driver\Monitoring\CommandFailedEvent::getPort().

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Метод возвращает сервер MongoDB\Driver\Server, на котором выполнилась команда.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект сервера MongoDB\Driver\Server, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Метод удалили.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Возвращает сервер, на котором выполнилась команда
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Возвращает идентификатор соединения с сервером для команды. Идентификатор подключения к серверу отличается от сервера (т.е. MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) и возвращается в поле "connectionId" ответа команды `hello` в MongoDB 4.2+.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор соединения с сервером или `null`, если он недоступен.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Если драйвер подключён к кластеру MongoDB через балансировщик нагрузки, идентификатор службы соответствует полю `serviceId` в ответе на команду `hello`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор службы балансировщика нагрузки или `null`, если драйвер не подключён к балансировщику нагрузки.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Возвращает имя команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Возвращает базу данных, в которой выполнилась команда
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Возвращает длительность команды в микросекундах
- MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Возвращает исключение, связанное с неудачной командой
- MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Возвращает имя хоста сервера для команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Возвращает порт сервера для команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Возвращает документ ответа команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Возвращает идентификатор запроса команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Возвращает сервер, на котором выполнилась команда
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

# Класс MongoDB\Driver\Monitoring\CommandStartedEvent

(mongodb >=1.3.0)

## Введение

Класс MongoDB\Driver\Monitoring\CommandStartedEvent содержит информацию о запущенной команды.

## Обзор класса

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Методы */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера, который выполнил команду.
port
  Порт сервера, который выполнил команду.
commandName
  Имя команды.
databaseName
  Имя базы данных.
command
  Документ команды.
operationId
  Идентификатор операции. Используется для связывания событий между собой, например, для bulk-операций записи, которые могут порождать несколько команд.
requestId
  Идентификатор запроса. Используется для связывания события MongoDB\Driver\Monitoring\CommandStartedEvent с соответствующим MongoDB\Driver\Monitoring\CommandSucceededEvent или MongoDB\Driver\Monitoring\CommandFailedEvent.
serviceId
  Идентификатор службы или `null`, если сервер не поддерживает его (то есть когда не используется режим балансировки нагрузки).
serverConnectionId
  Идентификатор соединения с сервером или `null`, если недоступен.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Возвращает документ команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

Документ ответа будет преобразован из BSON в PHP используя правила десериализации (например, документы BSON будут преобразованы в stdClass).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ команды в виде объекта stdClass.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)
- Сохранение данных

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Возвращает имя команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Возвращает имя команды (например, `"find"`, `"aggregate"`).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Возвращает базу данных, на которой выполнялась команда

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает базу данных, на которой была выполнена команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Возвращает имя хоста сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя хоста сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Возвращает идентификатор операции команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

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

> Замечание: Поскольку несколько команд могут совместно использовать один и тот же идентификатор операции, нецелесообразно использовать его для связывания объектов событий друг с другом. Вместо этого следует использовать идентификатор запроса, возвращённый MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор операции команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Возвращает порт сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает порт сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Возвращает идентификатор запроса команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

Идентификатор запроса генерируется модулем и может использоваться для связывания объекта MongoDB\Driver\Monitoring\CommandStartedEvent с последующим объектом MongoDB\Driver\Monitoring\CommandFailedEvent или MongoDB\Driver\Monitoring\CommandSucceededEvent.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор запроса команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Возвращает идентификатор запроса команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Возвращает сервер, на котором выполнилась команда

Внимание

Метод УСТАРЕЛ с версии модуля 1.20.0, а версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать методы MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() и MongoDB\Driver\Monitoring\CommandStartedEvent::getPort().

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Метод возвращает сервер MongoDB\Driver\Server, на котором выполнилась команда.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект сервера MongoDB\Driver\Server, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Метод удалили.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Возвращает сервер, на котором выполнилась команда
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Возвращает сервер, на котором выполнилась команда
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Возвращает идентификатор соединения с сервером для команды. Идентификатор соединения с сервером отличается от сервера (т.е. MongoDB\Driver\Monitoring\CommandStartedEvent::getServer()) и возвращается в поле "connectionId" из ответа команды `hello` в MongoDB 4.2+.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор соединения с сервером или `null`, если он недоступен.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Если драйвер подключён к кластеру MongoDB через балансировщик нагрузки, идентификатор службы соответствует полю `serviceId` в ответе на команду `hello`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор службы балансировщика нагрузки или `null`, если драйвер не подключён к балансировщику нагрузки.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Возвращает документ команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Возвращает имя команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Возвращает базу данных, на которой выполнялась команда
- MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Возвращает имя хоста сервера для команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Возвращает порт сервера для команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Возвращает идентификатор запроса команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Возвращает сервер, на котором выполнилась команда
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

# Класс MongoDB\Driver\Monitoring\CommandSucceededEvent

(mongodb >=1.3.0)

## Введение

Класс MongoDB\Driver\Monitoring\CommandSucceededEvent содержит информацию об успешной команде.

## Обзор класса

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Методы */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера, который выполнил команду.
port
  Порт сервера, который выполнил команду.
commandName
  Имя команды.
databaseName
  Имя базы данных.
duration
  Длительность команды в микросекундах. Длительность представляет собой расчётное значение, которое включает время отправки сообщения и получения ответа от сервера.
reply
  Документ ответа, который вернул сервер.
operationId
  Идентификатор операции. Используется для связывания событий между собой, например, для bulk-операций записи, которые могут порождать несколько команд.
requestId
  Идентификатор запроса. Используется для связывания события MongoDB\Driver\Monitoring\CommandSucceededEvent с соответствующим MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  Идентификатор службы или `null`, если сервер не поддерживает его (то есть когда не используется режим балансировки нагрузки).
serverConnectionId
  Идентификатор соединения с сервером или `null`, если недоступен.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly. Свойство duration заменяет метод getDurationMicros().

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Возвращает имя команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Возвращает имя команды (например, `"find"`, `"aggregate"`).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Возвращает базу данных, в которой выполнилась команда

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает базу данных, в которой выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Возвращает длительность команды в микросекундах

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

Длительность команды - это рассчитанное значение, которое включает время отправки сообщения и получение ответа от сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает продолжительность команды в микросекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Возвращает имя хоста сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает имя хоста сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Возвращает идентификатор операции команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

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

> Замечание: Поскольку несколько команд могут совместно использовать один и тот же идентификатор операции, нецелесообразно использовать его для связывания объектов событий друг с другом. Вместо этого следует использовать идентификатор запроса, возвращённый MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор операции команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Возвращает порт сервера для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает порт сервера, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Возвращает документ ответа команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

Документ ответа будет преобразован из BSON в PHP с использованием правил десериализации (например, документы BSON будут преобразованы в stdClass).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ ответа команды в виде объекта stdClass.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)
- Сохранение данных

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Возвращает идентификатор запроса команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

Идентификатор запроса генерируется модулем и может использоваться для связывания объекта MongoDB\Driver\Monitoring\CommandSucceededEvent с предыдущим объектом MongoDB\Driver\Monitoring\CommandStartedEvent.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор запроса команды.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Возвращает идентификатор запроса команды
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Возвращает сервер, на котором выполнилась команда

Внимание

Метод УСТАРЕЛ с версии модуля 1.20.0, а версии 2.0 метод удалили. Вместо этого метода приложениям лучше вызывать методы MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() и MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort().

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Метод возвращает сервер MongoDB\Driver\Server, на котором выполнилась команда.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект сервера MongoDB\Driver\Server, на котором выполнилась команда.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Метод удалили.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Возвращает сервер, на котором выполнилась команда
- MongoDB\Driver\Cursor::getServer() - Возвращает сервер, связанный с курсором
- MongoDB\Driver\WriteResult::getServer() - Возвращает сервер, который связан с этим результатом записи
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Возвращает идентификатор соединения с сервером для команды. Идентификатор соединения с сервером отличается от сервера (т.е. MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) и возвращается в поле "connectionId" из ответа команды `hello` в MongoDB 4.2+.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор соединения с сервером или `null`, если он недоступен.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

### Описание

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

Если драйвер подключён к кластеру MongoDB через балансировщик нагрузки, идентификатор службы соответствует полю `serviceId` в ответе на команду `hello`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор службы балансировщика нагрузки или `null`, если драйвер не подключён к балансировщику нагрузки.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Возвращает имя команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Возвращает базу данных, в которой выполнилась команда
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Возвращает длительность команды в микросекундах
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Возвращает имя хоста сервера для команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Возвращает идентификатор операции команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Возвращает порт сервера для команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Возвращает документ ответа команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Возвращает идентификатор запроса команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Возвращает сервер, на котором выполнилась команда
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Возвращает идентификатор соединения с сервером для команды
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Возвращает идентификатор службы балансировщика нагрузки для команды

# Класс MongoDB\Driver\Monitoring\ServerChangedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerChangedEvent инкапсулирует информацию об изменении описания сервера. Например, изменение типа сервера со вторичного на первичный изменит описание сервера.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* Методы */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
topologyId
  Идентификатор топологии.
newDescription
  Новое описание сервера.
previousDescription
  Предыдущее описание сервера.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Возвращает новое описание сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новое описание (MongoDB\Driver\ServerDescription) сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Возвращает предыдущее описание сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает предыдущее описание (MongoDB\Driver\ServerDescription) сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

### Описание

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Возвращает новое описание сервера
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Возвращает предыдущее описание сервера
- MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

# Класс MongoDB\Driver\Monitoring\ServerClosedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerClosedEvent инкапсулирует информацию о закрытом сервере. Это соответствует удалению сервера из топологии.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Методы */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
topologyId
  Идентификатор топологии.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

### Описание

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

# Класс MongoDB\Driver\Monitoring\ServerOpeningEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerOpeningEvent инкапсулирует информацию об открытом сервере. Это соответствует добавлению нового сервера в топологию.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Методы */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
topologyId
  Идентификатор топологии.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

### Описание

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Возвращает идентификатор топологии, связанный с этим сервером

# Класс MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent инкапсулирует информацию о неудачном сердцебиении сервера — команде » hello, которую отправил » мониторинг сервера.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* Методы */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
awaited
  Указывает, использовал ли heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому метод всегда возвращает `false`.
duration
  Длительность heartbeat в микросекундах. Длительность представляет собой расчётное значение, которое включает время отправки сообщения и получения ответа от сервера.
error
  Исключение, которое выбрасывается, когда heartbeat завершается неудачей.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly. Свойство duration заменяет метод getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Возвращает продолжительность heartbeat в микросекундах

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

Продолжительность heartbeat - это расчётное значение, которое включает в себя время отправки сообщения и получения ответа от сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает продолжительность heartbeat в микросекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Возвращает исключение, связанное с неудачным выполнением heartbeat

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает исключение (Exception), связанное с неудачным выполнением heartbeat.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Метод возвращает информацию о том, использовался ли в heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому этот метод всегда будет возвращать `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Возвращает продолжительность heartbeat в микросекундах
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Возвращает исключение, связанное с неудачным выполнением heartbeat
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

# Класс MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent инкапсулирует информацию о запущенном сердцебиении сервера — команде » hello, которую отправил » мониторинг сервера.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* Методы */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
awaited
  Указывает, использовал ли heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому метод всегда возвращает `false`.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Метод возвращает информацию о том, использовался ли в heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому этот метод всегда будет возвращать `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

# Класс MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent инкапсулирует информацию об успешном heartbeat сервера — команде » hello, которую отправил » мониторинг сервера.

## Обзор класса

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* Свойства */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* Методы */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## Свойства

host
  Имя хоста сервера.
port
  Порт сервера.
awaited
  Указывает, использовал ли heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому метод всегда возвращает `false`.
duration
  Длительность heartbeat в микросекундах. Длительность представляет собой расчётное значение, которое включает время отправки сообщения и получения ответа от сервера.
reply
  Документ ответа, который вернул сервер.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly. Свойство duration заменяет метод getDurationMicros().

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Возвращает продолжительность heartbeat в микросекундах

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

Продолжительность heartbeat - это расчётное значение, которое включает в себя время отправки сообщения и получения ответа от сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает продолжительность heartbeat в микросекундах.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Возвращает имя хоста сервера

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя хоста сервера.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Возвращает порт, на котором прослушивается сервер

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает порт, на котором прослушивается сервер.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Возвращает документ ответа heartbeat

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

Документ ответа будет преобразован из BSON в PHP с использованием правил десериализации по умолчанию (например, документы BSON будут преобразованы в stdClass).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает документ ответа heartbeat в виде объекта stdClass.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- Мониторинг производительности приложения (Application Performance Monitoring, или APM)
- Сохранение данных

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

### Описание

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Возвращает информацию о том, использовался ли в heartbeat потоковый протокол. Модуль не использует потоковый протокол для мониторинга, поэтому этот метод всегда будет возвращать `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `false`.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Возвращает продолжительность heartbeat в микросекундах
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Возвращает имя хоста сервера
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Возвращает порт, на котором прослушивается сервер
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Возвращает документ ответа heartbeat
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Возвращает информацию о том, использовался ли в heartbeat потоковый протокол

# Класс MongoDB\Driver\Monitoring\TopologyChangedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\TopologyChangedEvent инкапсулирует информацию об изменении описания топологии. Примером такого события станет изменение описания топологии при обнаружении в топологии нового первичного узла набора реплик.

## Обзор класса

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* Свойства */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* Методы */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

topologyId
  Идентификатор топологии.
newDescription
  Новое описание топологии.
previousDescription
  Предыдущее описание топологии.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Возвращает новое описание топологии

### Описание

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новое описание (MongoDB\Driver\TopologyDescription) топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Возвращает предыдущее описание топологии

### Описание

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает предыдущее описание (MongoDB\Driver\TopologyDescription) топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Возвращает идентификатор топологии

### Описание

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Возвращает новое описание топологии
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Возвращает предыдущее описание топологии
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Возвращает идентификатор топологии

# Класс MongoDB\Driver\Monitoring\TopologyClosedEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\TopologyClosedEvent инкапсулирует информацию о закрытой топологии.

> Замечание: Из-за поведения драйвера при обработке и сохранении соединения это событие наблюдается, только если менеджер MongoDB\Driver\Manager создали с параметром драйвера `"disableClientPersistence"` и освободили перед завершением запроса (RSHUTDOWN).

## Обзор класса

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* Свойства */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Методы */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

topologyId
  Идентификатор топологии.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Возвращает идентификатор топологии

### Описание

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Возвращает идентификатор топологии

# Класс MongoDB\Driver\Monitoring\TopologyOpeningEvent

(mongodb >=1.13.0)

## Введение

Класс MongoDB\Driver\Monitoring\TopologyOpeningEvent инкапсулирует информацию об открытой топологии.

> Замечание: Из-за поведения драйвера при обработке соединения и сохранении данных это событие наблюдается, только если менеджер MongoDB\Driver\Manager создали с параметром драйвера `"disableClientPersistence"` и освободили перед завершением запроса (RSHUTDOWN).

## Обзор класса

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* Свойства */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Методы */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Свойства

topologyId
  Идентификатор топологии.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Добавлены свойства public readonly.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Возвращает идентификатор топологии

### Описание

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор топологии.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

## Содержание

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Возвращает идентификатор топологии

# Интерфейс The MongoDB\Driver\Monitoring\CommandSubscriber

(mongodb >=1.3.0)

## Введение

Классы реализуют этот интерфейс для регистрации подписчика событий, который уведомляется о каждом успешном или неудачном событии команды. Более подробная информация доступна на странице Мониторинг производительности приложения (Application Performance Monitoring, или APM).

## Обзор интерфейса

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Методы */
abstract public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Метод уведомления о неудачной команде

### Описание

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void

Если подписчик зарегистрирован, этот метод вызывается, если возникла ошибка команды.

### Список параметров

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  Объект события, который содержит информацию о неудачной команде.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Метод уведомления о запущенной команде

### Описание

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void

Если подписчик зарегистрирован, этот метод вызывается при отправке команды на сервер.

### Список параметров

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  Объект события, который содержит информацию о запущенной команде.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Метод уведомления об успешной команде

### Описание

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void

Если подписчик зарегистрирован, этот метод вызывается при успешном выполнении команды.

### Список параметров

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  Объект события, который содержит информацию об успешной команде.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager
- Мониторинг производительности приложения (Application Performance Monitoring, или APM)

## Содержание

- MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Метод уведомления о неудачной команде
- MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Метод уведомления о запущенной команде
- MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Метод уведомления об успешной команде

# Интерфейс MongoDB\Driver\Monitoring\LogSubscriber

(mongodb >=1.17.0)

## Введение

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

Как и в случае с потоковым журналированием, глобально зарегистрировать логгер можно только методом MongoDB\Driver\Monitoring\addSubscriber(). Модуль не умеет различать сообщения журнала для отдельных объектов MongoDB\Driver\Manager.

## Обзор интерфейса

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Константы */
const int LEVEL_ERROR = 0;
const int LEVEL_CRITICAL = 1;
const int LEVEL_WARNING = 2;
const int LEVEL_MESSAGE = 3;
const int LEVEL_INFO = 4;
const int LEVEL_DEBUG = 5;
/* Методы */
abstract public function log(int `$level`, string `$domain`, string `$message`): void
}

## Предопределённые константы

`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_ERROR`
  Уровень журнала ошибок. Состояние ошибки, о котором модуль не в состоянии сообщить через свой API. Это самый серьёзный уровень журнала в модуле.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_CRITICAL`
  Критический уровень журнала. Состояние ошибки с несколько меньшей серьёзностью. Эта константа существует для согласованности с библиотекой libmongoc, однако, модуль вряд ли будет использовать его на практике.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_WARNING`
  Уровень журнала предупреждений. Указывает на ситуацию, при которой есть риск нежелательного поведения приложения.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_MESSAGE`
  Уровень журнала сообщений или уведомлений. Указывает на необычное, но не проблематичное событие.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_INFO`
  Информационный уровень журнала. Информация высокого уровня о нормальном поведении драйвера.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_DEBUG`
  Уровень журнала отладки. Подробная информация, полезная при отладке приложения.

# MongoDB\Driver\Monitoring\LogSubscriber::log

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Метод уведомления для сообщения журнала

### Описание

abstract public function MongoDB\Driver\Monitoring\LogSubscriber::log(int `$level`, string `$domain`, string `$message`): void

Если подписчик зарегистрирован, этот метод вызывается для каждого зарегистрированного сообщения.

### Список параметров

`level`
  Уровень серьезности. Одна из констант интерфейса.
`domain`
  Название компонента драйвера, который вывел сообщение журнала.
`message`
  Сообщение журнала.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально

## Содержание

- MongoDB\Driver\Monitoring\LogSubscriber::log — Метод уведомления для сообщения журнала

# Интерфейс MongoDB\Driver\Monitoring\SDAMSubscriber

(mongodb >=1.13.0)

## Введение

Классы реализуют этот интерфейс для регистрации подписчика событий, который получает уведомления о различных событиях SDAM. Дополнительная информация доступна в руководстве «» Обнаружение и мониторинг серверов» и «» Мониторинг SDAM».

## Обзор интерфейса

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Методы */
abstract public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Типы значений возврата, которые для методов интерфейса прежде объявили предварительными, стали обязательными.
PECL-модуль mongodb 1.15.0 | Типы значений возврата для интерфейсных методов модуля объявили как предварительные в PHP 8.0 и новее, что вызывает уведомления об устаревании в коде, который реализует этот интерфейс без объявления для значений возврата типов, которые соответствуют типам методов интерфейса. Уведомление об устаревании заглушают путём добавления атрибута `#[ReturnTypeWillChange]`.

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Уведомляет об изменении описания сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void

Метод вызывается при изменении описания сервера, если подписчик зарегистрирован. Например, изменении типа сервера со вторичного на первичный изменит описание сервера.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  Объект события, который инкапсулирует информацию об изменённом описании сервера.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Уведомляет о закрытии сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

Метод вызывается при удалении сервера из топологии, если подписчик зарегистрирован.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  Объект события, который инкапсулирует информацию о закрытом сервере.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Уведомляет о сбое контрольного сиглнала (heartbeat) сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void

Метод вызывается при сбое контрольного сигнала (heartbeat) сервера (т. е. команды » hello, которую выдал » мониторинг сервера), если подписчик зарегистрирован.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  Объект события, который инкапсулирует информацию о сбое heartbeat сервера.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Уведомляет о запуске контрольного сигнала (heartbeat) сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void

Метод вызывается при отправке на сервер контрольного сигнала (heartbeat) (т. е. команды » hello, которую выдал » мониторинг сервера) сервера, если подписчик зарегистрирован.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  Объект события, который инкапсулирует информацию о запущенном heartbeat сервера.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Уведомляет об успешном контрольном сигнале (heartbeat) сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void

Метод вызывается при успешном завершении контрольного сигнала (heartbeat) (т. е. команды » hello, которую выдал » мониторинг сервера) сервера, если подписчик зарегистрирован.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  Объект события, который инкапсулирует информацию об успешном heartbeat сервера.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Уведомляет об открытии сервера

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

Метод вызывается при добавлении нового сервера в топологию, если подписчик зарегистрирован.

### Список параметров

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  Объект события, который инкапсулирует информацию об открытом сервере.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Уведомляет об изменении описания топологии

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void

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

### Список параметров

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  Объект события, который инкапсулирует информацию об изменённом описании топологии.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Уведомляет о закрытии топологии

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void

Метод вызывается при закрытии топологии, если подписчик зарегистрирован.

> Замечание: Из-за поведения драйвера при обработке и сохранении соединения это событие наблюдается, только если менеджер MongoDB\Driver\Manager создали с параметром драйвера `"disableClientPersistence"` и освободили перед завершением запроса (RSHUTDOWN).

### Список параметров

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  Объект события, который инкапсулирует информацию о закрытой топологии.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Уведомляет об открытии топологии

### Описание

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void

Метод вызывается при открытии топологии, если подписчик зарегистрирован.

> Замечание: Из-за поведения драйвера при обработке и сохранении соединения это событие иногда не наблюдается, если менеджер MongoDB\Driver\Manager использует клиент библиотеки » libmongoc, который сохранили прежде.

### Список параметров

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  Объект события, который инкапсулирует информацию об открытой топологии.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Ошибки

- При ошибке парсинга аргумента метод выбрасывает исключение MongoDB\Driver\Exception\InvalidArgumentException.

### Смотрите также

- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Регистрирует подписчика на событие мониторинга глобально
- MongoDB\Driver\Manager::addSubscriber() - Регистрирует подписчика на событие мониторинга в данном объекте Manager

## Содержание

- MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Уведомляет об изменении описания сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Уведомляет о закрытии сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Уведомляет о сбое контрольного сиглнала (heartbeat) сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Уведомляет о запуске контрольного сигнала (heartbeat) сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Уведомляет об успешном контрольном сигнале (heartbeat) сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Уведомляет об открытии сервера
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Уведомляет об изменении описания топологии
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Уведомляет о закрытии топологии
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Уведомляет об открытии топологии

# Интерфейс MongoDB\Driver\Monitoring\Subscriber

(mongodb >=1.3.0)

## Введение

Базовый интерфейс для подписчиков событий. Используется как тип параметра в функциях MongoDB\Driver\Monitoring\addSubscriber() и MongoDB\Driver\Monitoring\removeSubscriber(), и не должен реализовываться напрямую.

## Обзор интерфейса

class MongoDB\Driver\Monitoring\Subscriber {
}

Этот интерфейс не имеет методов. Его единственная цель - быть базовым интерфейсом для всех подписчиков событий.

# Классы исключений

## Содержание

- MongoDB\Driver\Exception\AuthenticationException
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- Дерево классов

# Класс MongoDB\Driver\Exception\AuthenticationException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда драйвер не может выполнить аутентификацию с сервером.

## Обзор класса

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\BulkWriteException

(mongodb >= 1.0.0)

## Введение

Исключение выбрасывается при неудачной массовой операции записи.

## Обзор класса

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Свойства */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

writeResult

  Объект MongoDB\Driver\WriteResult, который связан с неудачной операцией записи.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Свойство writeResult теперь является public readonly.
PECL-модуль mongodb 2.0.0 | Класс теперь расширяет класс MongoDB\Driver\Exception\ServerException, а не MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Возвращает объект WriteResult для неудачной операции записи

### Описание

final public function MongoDB\Driver\Exception\BulkWriteException::getWriteResult(): MongoDB\Driver\WriteResult

Метод возвращает объект MongoDB\Driver\WriteResult для неудачной операции записи. Более подробную информацию о сбое получают методами MongoDB\Driver\WriteResult::getWriteErrors() и MongoDB\Driver\WriteResult::getWriteConcernError().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект MongoDB\Driver\WriteResult для неудачной операции записи.

### Примеры

Пример #1 Пример получения результата для неудачной операции записи методом MongoDB\Driver\Exception\BulkWriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite();
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Смотрите также

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи

## Содержание

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Возвращает объект WriteResult для неудачной операции записи

# Исключение MongoDB\Driver\Exception\BulkWriteCommandException

(mongodb >=2.1.0)

## Введение

Исключение выбрасывается при сбое выполнения команды MongoDB\Driver\BulkWriteCommand. Методы класса возвращают дополнительную информацию об ошибке, включая ответ сервера об ошибке и частичные результаты массовой записи.

## Обзор класса

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Свойства */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

errorReply
  Высокоуровневая ошибка, которая возникла при попытке связаться с сервером или выполнить массовую запись. Свойство содержит значение `null`, если исключение возникло из-за ошибок отдельных записей.
partialResult
  Объект MongoDB\Driver\BulkWriteCommandResult с результатами успешных операций, которые выполнились, прежде чем возникла ошибка. Свойство содержит значение `null`, если невозможно определить, что хотя бы одна запись выполнилась успешно и сервер подтвердил запись.
writeConcernErrors
  Массив объектов MongoDB\Driver\WriteConcernError с ошибками подтверждения записи, которые возникли при выполнении массовой записи. Список содержит больше одного элемента, если для выполнения массовой записи потребовалось больше одной серверной команды.
writeErrors
  Массив ошибок MongoDB\Driver\WriteError, которые возникли при выполнении отдельных операций записи. Ключи массива соответствуют индексу операции записи из объекта MongoDB\Driver\BulkWriteCommand. Карта содержит не больше одной записи для упорядоченной массовой записи.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Возвращает ошибку высокоуровневой команды

### Описание

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает высокоуровневую ошибку, которая возникла при попытке связаться с сервером или выполнить массовую запись. Метод возвращает значение `null`, если исключение возникло из-за ошибок отдельных записей.

### Примеры

Пример #1 Пример получения ошибки методом MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply()

    <?php

    $manager = new MongoDB\Driver\Manager();

    // Пример вызывает ошибку на стороне сервера командой configureFailPoint, чтобы сымитировать ошибку команды высокого уровня
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

Вывод приведённого примера будет похож на:

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Возвращает результаты успешных операций записи

### Описание

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект MongoDB\Driver\BulkWriteCommandResult с результатами успешных операций, которые выполнились, прежде чем возникла ошибка. Метод вернёт значение `null`, если невозможно определить, что хотя бы одна запись выполнилась успешно и сервер подтвердил запись.

### Примеры

Пример #1 Пример получения частичного результата, если хотя бы одна запись выполнилась успешно

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

Результат выполнения приведённого примера:

    int(1)

Пример #2 Пример получения частичного результата, когда ни одна запись не выполнилась успешно

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

Результат выполнения приведённого примера:

    NULL

### Смотрите также

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Возвращает ошибки подтверждения записи

### Описание

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов MongoDB\Driver\WriteConcernError с ошибками подтверждения записи, которые возникли при выполнении массовой записи. Список содержит больше одного элемента, если для выполнения массовой записи потребовалось больше одной серверной команды.

### Примеры

Пример #1 Пример получения ошибки подтверждения записи методом MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand();
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Возвращает ошибки записи

### Описание

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив ошибок MongoDB\Driver\WriteError, которые возникли при выполнении отдельных операций записи. Ключи массива соответствуют индексу операции записи из объекта MongoDB\Driver\BulkWriteCommand. Карта содержит не больше одной записи для упорядоченной массовой записи.

### Примеры

Пример #1 Пример получения ошибки записи методом MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors()

    <?php

    $manager = new MongoDB\Driver\Manager();

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### Смотрите также

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Выполняет операции записи через команду bulkWrite
- MongoDB\Driver\WriteError

## Содержание

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Возвращает ошибку высокоуровневой команды
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Возвращает результаты успешных операций записи
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Возвращает ошибки подтверждения записи
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Возвращает ошибки записи

# Класс MongoDB\Driver\Exception\CommandException

(mongodb >= 1.5.0)

## Введение

Выбрасывается, в случае возникновения ошибки команды.

## Обзор класса

abstract class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Свойства */
public readonly object $resultDocument;
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
final public function getResultDocument(): object
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

resultDocument

  Документ результата, связанный с неудачной командой.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.3.0 | Свойство resultDocument теперь является public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Возвращает результат документа для неудавшейся команды

### Описание

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Возвращает результат документа для неудавшейся команды.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Документ результата для неудавшейся команды.

### Смотрите также

- MongoDB\Driver\Manager::executeCommand() - Выполняет команду базы данных

## Содержание

- MongoDB\Driver\Exception\CommandException::getResultDocument — Возвращает результат документа для неудавшейся команды

# Класс MongoDB\Driver\Exception\ConnectionException

(mongodb >= 1.0.0)

## Введение

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

## Обзор класса

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\ConnectionTimeoutException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда драйверу не удаётся установить соединение с базой данных в течение определённого периода времени (connectTimeoutMS). или выбор сервера не удался (serverSelectionTimeoutMS).

## Обзор класса

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\EncryptionException

(mongodb >= 1.7.0)

## Введение

Базовый класс для исключений бросаемых в процессе шифрования на стороне клиента.

## Обзор класса

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Интерфейс MongoDB\Driver\Exception\Exception

(mongodb >= 1.0.0)

## Введение

Общий интерфейс для исключений модуля. Этим интерфейсом также пользуется библиотека, а также интерфейс помогает идентифицировать исключения, которые выбрасывает PHP-драйвер MongoDB (то есть модуль и библиотека).

## Обзор класса

class MongoDB\Driver\Exception\Exception {
}

# Класс MongoDB\Driver\Exception\ExecutionTimeoutException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда запрос или команда не завершается в течение определённого периода времени (например, » maxTimeMS).

## Обзор класса

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.5.0 | Теперь этот класс расширяет MongoDB\Driver\Exception\ServerException вместо MongoDB\Driver\Exception\RuntimeException.

# Класс MongoDB\Driver\Exception\InvalidArgumentException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда методу драйвера переданы некорректные аргументы (например, недопустимые типы опций).

## Обзор класса

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\LogicException

(mongodb >= 1.0.0)

## Введение

Выбрасывается при неправильном использовании драйвера (например, перемотка в начало курсора).

## Обзор класса

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\RuntimeException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда драйвер обнаруживает ошибку во время выполнения (например, внутренняя ошибка из » libmongoc).

## Обзор класса

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Свойства */
protected ?array $errorLabels;
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
final public function hasErrorLabel(string `$errorLabel`): bool
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

errorLabels
  Содержит массив меток ошибок для исключения. Например, метки ошибок могут использоваться для определения того, можно ли безопасно провести транзакцию, если присутствует метка TransientTransactionError. Существование определённой метки ошибки должно быть проверено с помощью MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() вместо интерпретации этого свойства errorLabels вручную.

## Список изменений

Версия | Описание
--- | ---
PECL mongodb 1.6.0 | Добавлены метод MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() и свойство MongoDB\Driver\Exception\RuntimeException::errorLabels.

# MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Возвращает информацию о том, связана ли метка ошибки с исключением

### Описание

final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool

Метод возвращает информацию о том, установили ли метку ошибки `errorLabel` для этого исключения. Метки ошибок устанавливаются либо сервером, либо модулем, чтобы указать конкретные ситуации, в которых может потребоваться принять решение о способе обработки конкретного исключения. Обычной ситуацией может быть определение того, можно ли безопасно повторить транзакцию, которая не удалась из-за временной ошибки (например, проблемы с сетью или конфликт транзакций). Примерами меток ошибок являются `TransientTransactionError` и `UnknownTransactionCommitResult`.

### Список параметров

`errorLabel`
  Название `errorLabel` для проверки.

### Возвращаемые значения

Связано ли переданное значение параметра `errorLabel` с соответствующим исключением.

### Смотрите также

- MongoDB\Driver\Session::commitTransaction() - Фиксирует транзакцию
- » Документация MongoDB по транзакциям

## Содержание

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Возвращает информацию о том, связана ли метка ошибки с исключением

# Класс MongoDB\Driver\Exception\ServerException

(mongodb >= 1.5.0)

## Введение

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

## Обзор класса

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\SSLConnectionException

(mongodb >= 1.0.0)

Внимание

Класс исключений УСТАРЕЛ с модуля версии 1.5.0, а в версии 2.0 исключение удалили. Модуль никогда не выбрасывал это исключение. Вместо этого исключения в приложениях лучше выбрасывать исключение MongoDB\Driver\Exception\ConnectionException.

## Введение

Исключение выбрасывается, когда драйверу не удаётся установить SSL-соединение с сервером.

## Обзор класса

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\UnexpectedValueException

(mongodb >= 1.0.0)

## Введение

Выбрасывается, когда драйвер сталкивается с неожиданным значением (например, во время сериализации или десериализации BSON).

## Обзор класса

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс MongoDB\Driver\Exception\WriteException

(mongodb >= 1.0.0)

Внимание

Класс исключений УСТАРЕЛ с версии модуля 1.20.0, а в версии 2.0 исключение удалили. Сам модуль не выбрасывал это исключение. Вместо этого исключения в приложениях лучше выбрасывать исключение MongoDB\Driver\Exception\BulkWriteException.

## Введение

Базовый класс для исключений, которые выбрасываются при ошибке операции записи. Исключение инкапсулирует объект MongoDB\Driver\WriteResult.

## Обзор класса

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Свойства */
protected MongoDB\Driver\WriteResult $writeResult;
/* Наследуемые свойства */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Методы */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Наследуемые методы */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

writeResult
  Объект MongoDB\Driver\WriteResult, который связан с неудачной операцией записи.

## Список изменений

Версия | Описание
--- | ---
PECL-модуль mongodb 2.0.0 | Класс удалили.
PECL-модуль mongodb 1.20.0 | Класс устарел, а в версии 2.0 его удалят.
PECL-модуль mongodb 1.5.0 | Класс теперь расширяет исключение MongoDB\Driver\Exception\ServerException, а не MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Возвращает объект WriteResult для ошибочной операции записи

### Описание

final public function MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Метод возвращает объект MongoDB\Driver\WriteResult для операции записи, которая завершилась ошибкой. Больше информации об ошибке дают методы MongoDB\Driver\WriteResult::getWriteErrors() и MongoDB\Driver\WriteResult::getWriteConcernError().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект MongoDB\Driver\WriteResult для операции записи, которая закончилась ошибкой.

### Примеры

Пример #1 Пример использования метода MongoDB\Driver\Exception\WriteException::getWriteResult()

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite();
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\WriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Смотрите также

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Выполняет операции записи

## Содержание

- MongoDB\Driver\Exception\WriteException::getWriteResult — Возвращает объект WriteResult для ошибочной операции записи

# Дерево классов исключений модуля MongoDB

Иерархию классов для исключений модуля MongoDB смоделировали по образцу исключений стандартной PHP-библиотеки SPL. Базовые классы расширяют свои SPL-аналоги и каждый класс исключения в модуле реализует интерфейс MongoDB\Driver\Exception\Exception.

- MongoDB\Driver\Exception\LogicException (расширяет LogicException)
- MongoDB\Driver\Exception\InvalidArgumentException (расширяет InvalidArgumentException)
- MongoDB\Driver\Exception\UnexpectedValueException (расширяет UnexpectedValueException)
- MongoDB\Driver\Exception\RuntimeException (расширяет RuntimeException)
  - MongoDB\Driver\Exception\ConnectionException
    - MongoDB\Driver\Exception\AuthenticationException
    - MongoDB\Driver\Exception\ConnectionTimeoutException
    - MongoDB\Driver\Exception\SSLConnectionException (устарел)
  - MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\ServerException
    - MongoDB\Driver\Exception\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (устарел)
      - MongoDB\Driver\Exception\BulkWriteException

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Обучающие материалы
  - Работа библиотеки PHP с драйвером MongoDB (PHPLIB)
  - Мониторинг производительности приложения (Application Performance Monitoring, или APM)
- Архитектура и внутреннее устройство драйвера — Обзор архитектуры драйвера и её особенностей
  - Архитектура — Обзор архитектуры
  - Соединения — Обработка и сохранение соединения
  - Сохранение данных — Сериализация и десериализация PHP-переменных в модуле MongoDB
- Безопасность
  - Атака с помощью инъекций в запросе
  - Атака с помощью инъекций в скриптах
- MongoDB\Driver — Классы модуля MongoDB
  - MongoDB\Driver\Manager — Класс MongoDB\Driver\Manager
  - MongoDB\Driver\Command — Класс MongoDB\Driver\Command
  - MongoDB\Driver\Query — Класс MongoDB\Driver\Query
  - MongoDB\Driver\BulkWrite — Класс MongoDB\Driver\BulkWrite
  - MongoDB\Driver\BulkWriteCommand — Класс MongoDB\Driver\BulkWriteCommand
  - MongoDB\Driver\Session — Класс MongoDB\Driver\Session
  - MongoDB\Driver\ClientEncryption — Класс MongoDB\Driver\ClientEncryption
  - MongoDB\Driver\ServerApi — Класс MongoDB\Driver\ServerApi
  - MongoDB\Driver\WriteConcern — Класс MongoDB\Driver\WriteConcern
  - MongoDB\Driver\ReadPreference — Класс MongoDB\Driver\ReadPreference
  - MongoDB\Driver\ReadConcern — Класс MongoDB\Driver\ReadConcern
  - MongoDB\Driver\Cursor — Класс MongoDB\Driver\Cursor
  - MongoDB\Driver\CursorId — Класс MongoDB\Driver\CursorId
  - MongoDB\Driver\CursorInterface — Интерфейс MongoDB\Driver\CursorInterface
  - MongoDB\Driver\Server — Класс MongoDB\Driver\Server
  - MongoDB\Driver\ServerDescription — Класс MongoDB\Driver\ServerDescription
  - MongoDB\Driver\TopologyDescription — Класс MongoDB\Driver\TopologyDescription
  - MongoDB\Driver\WriteConcernError — Класс MongoDB\Driver\WriteConcernError
  - MongoDB\Driver\WriteError — Класс MongoDB\Driver\WriteError
  - MongoDB\Driver\WriteResult — Класс MongoDB\Driver\WriteResult
  - MongoDB\Driver\BulkWriteCommandResult — Класс MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON — Классы и функции модуля MongoDB для работы с форматом BSON
  - Функции
  - MongoDB\BSON\Document — Класс MongoDB\BSON\Document
  - MongoDB\BSON\PackedArray — Класс MongoDB\BSON\PackedArray
  - MongoDB\BSON\Iterator — Класс MongoDB\BSON\Iterator
  - MongoDB\BSON\Binary — Класс MongoDB\BSON\Binary
  - MongoDB\BSON\VectorType — Перечисление MongoDB\BSON\VectorType
  - MongoDB\BSON\Decimal128 — Класс MongoDB\BSON\Decimal128
  - MongoDB\BSON\Javascript — Класс MongoDB\BSON\Javascript
  - MongoDB\BSON\MaxKey — Класс MongoDB\BSON\MaxKey
  - MongoDB\BSON\MinKey — Класс MongoDB\BSON\MinKey
  - MongoDB\BSON\ObjectId — Класс MongoDB\BSON\ObjectId
  - MongoDB\BSON\Regex — Класс MongoDB\BSON\Regex
  - MongoDB\BSON\Timestamp — Класс MongoDB\BSON\Timestamp
  - MongoDB\BSON\UTCDateTime — Класс MongoDB\BSON\UTCDateTime
  - MongoDB\BSON\Type — Интерфейс MongoDB\BSON\Type
  - MongoDB\BSON\Persistable — Интерфейс MongoDB\BSON\Persistable
  - MongoDB\BSON\Serializable — Интерфейс MongoDB\BSON\Serializable
  - MongoDB\BSON\Unserializable — Интерфейс MongoDB\BSON\Unserializable
  - MongoDB\BSON\BinaryInterface — Интерфейс MongoDB\BSON\BinaryInterface
  - MongoDB\BSON\Decimal128Interface — Интерфейс MongoDB\BSON\Decimal128Interface
  - MongoDB\BSON\JavascriptInterface — Интерфейс MongoDB\BSON\JavascriptInterface
  - MongoDB\BSON\MaxKeyInterface — Интерфейс MongoDB\BSON\MaxKeyInterface
  - MongoDB\BSON\MinKeyInterface — Интерфейс MongoDB\BSON\MinKeyInterface
  - MongoDB\BSON\ObjectIdInterface — Интерфейс MongoDB\BSON\ObjectIdInterface
  - MongoDB\BSON\RegexInterface — Интерфейс MongoDB\BSON\RegexInterface
  - MongoDB\BSON\TimestampInterface — Интерфейс MongoDB\BSON\TimestampInterface
  - MongoDB\BSON\UTCDateTimeInterface — Интерфейс MongoDB\BSON\UTCDateTimeInterface
  - MongoDB\BSON\DBPointer — Класс MongoDB\BSON\DBPointer
  - MongoDB\BSON\Int64 — Класс MongoDB\BSON\Int64
  - MongoDB\BSON\Symbol — Класс MongoDB\BSON\Symbol
  - MongoDB\BSON\Undefined — Класс MongoDB\BSON\Undefined
- MongoDB\Driver\Monitoring — Классы мониторинга и функции подписчика
  - Функции
  - MongoDB\Driver\Monitoring\CommandFailedEvent — Класс MongoDB\Driver\Monitoring\CommandFailedEvent
  - MongoDB\Driver\Monitoring\CommandStartedEvent — Класс MongoDB\Driver\Monitoring\CommandStartedEvent
  - MongoDB\Driver\Monitoring\CommandSucceededEvent — Класс MongoDB\Driver\Monitoring\CommandSucceededEvent
  - MongoDB\Driver\Monitoring\ServerChangedEvent — Класс MongoDB\Driver\Monitoring\ServerChangedEvent
  - MongoDB\Driver\Monitoring\ServerClosedEvent — Класс MongoDB\Driver\Monitoring\ServerClosedEvent
  - MongoDB\Driver\Monitoring\ServerOpeningEvent — Класс MongoDB\Driver\Monitoring\ServerOpeningEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — Класс MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — Класс MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  - MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — Класс MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  - MongoDB\Driver\Monitoring\TopologyChangedEvent — Класс MongoDB\Driver\Monitoring\TopologyChangedEvent
  - MongoDB\Driver\Monitoring\TopologyClosedEvent — Класс MongoDB\Driver\Monitoring\TopologyClosedEvent
  - MongoDB\Driver\Monitoring\TopologyOpeningEvent — Класс MongoDB\Driver\Monitoring\TopologyOpeningEvent
  - MongoDB\Driver\Monitoring\CommandSubscriber — Интерфейс The MongoDB\Driver\Monitoring\CommandSubscriber
  - MongoDB\Driver\Monitoring\LogSubscriber — Интерфейс MongoDB\Driver\Monitoring\LogSubscriber
  - MongoDB\Driver\Monitoring\SDAMSubscriber — Интерфейс MongoDB\Driver\Monitoring\SDAMSubscriber
  - MongoDB\Driver\Monitoring\Subscriber — Интерфейс MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Exception — Классы исключений
  - MongoDB\Driver\Exception\AuthenticationException — Класс MongoDB\Driver\Exception\AuthenticationException
  - MongoDB\Driver\Exception\BulkWriteException — Класс MongoDB\Driver\Exception\BulkWriteException
  - MongoDB\Driver\Exception\BulkWriteCommandException — Исключение MongoDB\Driver\Exception\BulkWriteCommandException
  - MongoDB\Driver\Exception\CommandException — Класс MongoDB\Driver\Exception\CommandException
  - MongoDB\Driver\Exception\ConnectionException — Класс MongoDB\Driver\Exception\ConnectionException
  - MongoDB\Driver\Exception\ConnectionTimeoutException — Класс MongoDB\Driver\Exception\ConnectionTimeoutException
  - MongoDB\Driver\Exception\EncryptionException — Класс MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\Exception — Интерфейс MongoDB\Driver\Exception\Exception
  - MongoDB\Driver\Exception\ExecutionTimeoutException — Класс MongoDB\Driver\Exception\ExecutionTimeoutException
  - MongoDB\Driver\Exception\InvalidArgumentException — Класс MongoDB\Driver\Exception\InvalidArgumentException
  - MongoDB\Driver\Exception\LogicException — Класс MongoDB\Driver\Exception\LogicException
  - MongoDB\Driver\Exception\RuntimeException — Класс MongoDB\Driver\Exception\RuntimeException
  - MongoDB\Driver\Exception\ServerException — Класс MongoDB\Driver\Exception\ServerException
  - MongoDB\Driver\Exception\SSLConnectionException — Класс MongoDB\Driver\Exception\SSLConnectionException
  - MongoDB\Driver\Exception\UnexpectedValueException — Класс MongoDB\Driver\Exception\UnexpectedValueException
  - MongoDB\Driver\Exception\WriteException — Класс MongoDB\Driver\Exception\WriteException
  - Дерево классов — Дерево классов исключений модуля MongoDB

# Драйверы и плагины MySQL

PHP предлагает ряд драйверов и MySQL-плагинов для доступа и работы с СУБД MySQL.

Раздел описывает различия и функциональность MySQL-модулей.

Модули, которые перечисляет раздел, поддерживают MySQL-протокол. Примеры совместимых серверов баз данных: » MariaDB Server, » MySQL Server, » Percona Server for MySQL и » TiDB.

# Обзор PHP-драйверов MySQL

# Введение

Доступ к базе данных MySQL получают через набор API-интерфейсов языка PHP. Пользователи выбирают между модулями mysqli или PDO_MySQL.

Это краткое руководство объясняет терминологию, которая описывает каждый API, даёт информацию о выборе API и информацию, которая помогает в выборе библиотеки MySQL для работы с API.

# Обзор терминологии

Раздел описывает инструменты, которые помогают программистам разрабатывать PHP-приложения, которые взаимодействуют с базой данных MySQL.

Об API-интерфейсе

Программный интерфейс приложения (англ. Application Programming Interface, API) определяет набор классов, методов, функций и переменных, к которым приложению потребуется обращаться, чтобы выполнить поставленные задачи. PHP-приложения взаимодействуют с базами данных через API-интерфейсы, которые приложениям обычно открывают PHP-модули.

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

Язык программирования PHP предлагает разработчикам несколько API-интерфейсов, через которые PHP-приложения взаимодействуют с базами данных MySQL. Документ описывает эти интерфейсы и даёт рекомендации по выбору конкретного способа подключения к базе данных из приложения.

О коннекторе

В MySQL-документации термин коннектор (англ. connector) относится к части программного обеспечения, которая разрешает приложению подключаться к серверу баз данных MySQL. БД MySQL предоставляет коннекторы для разных языков программирования, включая язык PHP.

Разработчику потребуется написать PHP-код, чтобы PHP-приложение научилось взаимодействовать с сервером баз данных: подключаться, отправлять запросы и выполнять другие операции, которые связаны с базой данных. Серверу баз данных потребуется ПО, чтобы предоставить API-интерфейс, через который PHP-приложение будет взаимодействовать с сервером, и чтобы управлять обменом информацией между приложением и сервером баз данных, для чего иногда также требуются промежуточные библиотеки. Это программное обеспечение называется коннектором, поскольку разрешает приложению подключаться (англ. to connect) к серверу баз данных.

О драйвере

Драйвер — часть программного обеспечения, которую разработали для взаимодействия приложения с конкретным типом сервера баз данных. Приложение вызывает методы коннектора, тот обращается к своему драйверу конкретной СУБД, а драйвер со своей стороны обращается к нижележащим библиотекам — клиентской библиотеке MySQL Client Library или встроенному драйверу MySQL Native Driver. Эти библиотеки реализуют низкоуровневый протокол взаимодействия с MySQL-сервером баз данных.

Например, PHP-модуль PDO, который поддерживает доступ к базам данных на уровне абстракции, содержит набор драйверов для доступа к конкретным базам данных. В список доступных модулю драйверов входит драйвер PDO_MYSQL, который разрешает модулю PDO взаимодействовать с сервером MySQL.

Термины «коннектор» и «драйвер» иногда употребляют как синонимы, это сбивает с толку. В MySQL-документации термин драйвер зарезервировали за программным обеспечением, которое предоставляет часть пакета коннектора для конкретной базы данных.

О модуле

В PHP-документации встречается ещё один термин — модуль. Код самого PHP состоит из ядра и дополнительных модулей, которые расширяют функциональность ядра. Для работы с СУБД MySQL ядро PHP расширили модулем `mysqli` и модулем PDO с MySQL-драйвером. Оба модуля включили в инфраструктуру модулей языка PHP.

Обычно модули предоставляют PHP-программисту API-интерфейс, через который разработчик получает доступ к функциям модуля программно. При этом отдельные модули в инфраструктуре PHP-модулей не раскрывают для программиста никаких интерфейсов.

MySQL-драйвер модуля PDO, например, не раскрывает API-интерфейс для программиста, но предоставляет интерфейс вышележащему абстрактному слою, который представляет модуль PDO.

Термины «API-интерфейс» и «модуль» нельзя воспринимать как одно и то же, поскольку модуль не обязан раскрывать API-интерфейс для программиста.

# Выбор API-интерфейса

PHP предлагает разные API-интерфейсы для доступа к СУБД MySQL. Примеры в следующем абзаце показывают взаимодействие с API-интерфейсом модулей mysqli и PDO. Каждый фрагмент кода создаёт соединение с MySQL-сервером, который работает на домене example.com. Код передаёт значение "user" как имя пользователя, а значение "password" как пароль.

Пример #1 Сравнение API-интерфейсов для взаимодействия с СУБД MySQL

    <?php

    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 'Привет, дорогой пользователь MySQL!' AS _message FROM DUAL");
    $row = $result->fetch_assoc();
    echo htmlentities($row['_message']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->query("SELECT 'Привет, дорогой пользователь MySQL!' AS _message FROM DUAL");
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['_message']);

    ?>

Пример #2 Сравнение подготовленных запросов

    <?php

    // Модуль mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $result = $statement->get_result();
    $row = $result->fetch_assoc();
    echo htmlentities($row['District']);

    // Модуль PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['District']);

    ?>

Сравнение функций модулей

Общая производительность обоих модулей примерно одинакова. Хотя производительность модуля составляет только часть общего времени выполнения веб-запроса PHP. Часто влияние составляет не более 0,1 %.

| ext/mysqli | PDO_MySQL
--- | --- | ---
Версия PHP, в которой представили модуль | 5.0 | 5.1
Входит в состав PHP 7.x и 8.x | Да | Да
Статус разработки | Активный | Активный
Жизненный цикл | Активный | Активный
Рекомендуется для новых проектов | Да | Да
Предлагает ООП-интерфейс | Да | Да
Предлагает процедурный интерфейс | Да | Нет
API поддерживает асинхронные неблокирующие запросы через драйвер mysqlnd | Да | Нет
Постоянные соединения | Да | Да
API поддерживает кодировки | Да | Да
API поддерживает подготовленные запросы на стороне сервера | Да | Да
API поддерживает подготовленные запросы на стороне клиента | Нет | Да
API поддерживает хранимые процедуры | Да | Да
API поддерживает множественные запросы | Да | Большинство
API поддерживает транзакции | Да | Да
Транзакции контролируются через SQL | Да | Да
Поддерживает функциональность MySQL 5.1+ | Да | Большинство

# Выбор библиотеки

Модули mysqli и PDO_MySQL — легковесные обёртки поверх клиентской библиотеки языка C. Модули работают либо с библиотекой драйвера mysqlnd, либо с клиентской библиотекой языка C `libmysqlclient`. Библиотеку выбирают на этапе компиляции.

Библиотека mysqlnd — часть дистрибутива PHP. Библиотека предлагает функции наподобие ленивых соединений и кеширования запросов, включая средства, которые недоступны в библиотеке libmysqlclient, поэтому настоятельно рекомендуется выбирать встроенную в PHP библиотеку mysqlnd. Документация по mysqlnd даёт дополнительную информацию и список средств и функциональности, которую предлагает драйвер.

Пример #1 Команды конфигурирования модуля mysqlnd или библиотеки libmysqlclient

    // Рекомендуется, компилируется с драйвером mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Рекомендуется, компилируется с драйвером mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // Не рекомендуется, компилируется с библиотекой libmysqlclient языка C
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Сравнение библиотек

PHP-программистам рекомендуют работать с драйвером mysqlnd, а не с клиентской библиотекой MySQL Client Server, которая распространяется как пакет libmysqlclient. Обе библиотеки поддерживаются и непрерывно совершенствуются.

| Родной PHP-драйвер MySQL Native Driver (mysqlnd) | Клиентская библиотека MySQL Client Server (`libmysqlclient`)
--- | --- | ---
Часть дистрибутива PHP | Да | Нет
Версия PHP, в которой появилась библиотека | 5.3.0 | Нет данных
Лицензия | PHP License 3.01 | Двойная лицензия
Статус разработки | Активный | Активный
Жизненный цикл | Окончание не анонсировано | Окончание не анонсировано
Компиляция по умолчанию (для всех модулей MySQL) | Да | Нет
Поддержка протокола сжатия | Да | Да
Поддержка протокола SSL | Да | Да
Поддержка именованных конвейеров | Да | Да
Неблокирующие асинхронные запросы | Да | Нет
Статистика производительности | Да | Нет
Конфигурация LOAD LOCAL INFILE учитывает директиву open_basedir | Да | нет
Взаимодействие со внутренней системой управления памятью PHP (например, соблюдение ограничений памяти PHP) | Да | Нет
Возврат числовых столбцов как целочисленных значений double (COM_QUERY) | Да | нет
Возврат числовых столбцов как строк (string) (COM_QUERY) | Да | Да
Поддержка API плагинов | Да | Ограниченно
Автоматическое переподключение | нет | опционально

# Основные понятия

## Содержание

- Буферизированные и небуферизированные запросы
- Кодировки символов

Эти основные понятия, связанные с драйвером MySQL для PHP.

## Буферизированные и небуферизированные запросы

По умолчанию запросы используют режим буферизации. Это значит, что результаты запроса немедленно поступают от сервера MySQL к PHP и сохраняются в памяти PHP-процесса. Это позволяет делать дополнительные операции, такие как подсчёт количества строк и перемещение (поиск) текущего указателя результата. Это также даёт возможность выполнять новые запросы в том же соединении во время работы над результатом последнего запроса. Недостаток режима буферизации является то, что большие наборы результатов могут потребовать довольно много количество оперативной памяти. Память остаётся занятой до тех пор, пока все указатели на результирующий набор не будут удалены или результирующий набор не будет явно освобождён, что автоматически происходит во время окончания последнего запроса. Термин "результат сохранения" ("store result") также используется для режима буферизации, так как весь результирующий набор сохраняется сразу.

> Замечание: При использовании libmysqlclient в качестве библиотеки ограничение памяти PHP не будет учитывать память используемую для результирующих наборов, если данные не будут сохранены в переменные PHP. С mysqlnd учёт памяти также будет включать в себя размер результирующего набора.

Небуферизованные MySQL запросы выполняются, а затем ожидают получения данных с сервера MySQL. Это использует меньше памяти на стороне PHP, но может увеличить нагрузку на сервер. Пока полный результирующий набор не будет передан с сервера, никакие дальнейшие запросы не могут быть отправлены через это же соединение. Небуферизированные запросы также могут быть отложены как "use result". Когда все строки из набора результатов извлечены, набор результатов исчезает и его нельзя повторно итерировать.

Исходя из этих характеристик, небуферизированные запросы следует использовать только в тех случаях, когда ожидается большой набор результатов, который будет обрабатываться последовательно. Небуферизованные запросы содержат ряд подводных камней, что усложняет их использование, например, количество строк в наборе результатов неизвестно до тех пор, пока не будет извлечена последняя строка. Буферизованные запросы - более простой и гибкий способ обработки наборов результатов.

Поскольку буферизированные запросы применяются по умолчанию, следующие примеры продемонстрируют как выполнить небуферизированные запросы в каждом из API

Пример #1 Пример небуферизированного запроса: mysqli

    <?php
    $mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
    $unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

Пример #2 Пример небуферизированного запроса: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
    $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

    $unbufferedResult = $pdo->query("SELECT Name FROM City");
    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

## Кодировки символов

В идеальном случае кодировка символов должна устанавливаться на уровне сервера и делать это согласно описанию в разделе » Конфигурация кодировки символов документации сервера MySQL. В качестве альтернативы каждый MySQL API предлагает метод для установки кодировки символов во время выполнения.

Предостережение

# Кодировка символов и экранирование символов

Кодировка символов должна быть чётко определена, поскольку влияет на каждое действие, в том числе на действия с последствиями для безопасности. Например, механизмы экранирования (такие как mysqli_real_escape_string() для mysqli и PDO::quote() для PDO_MySQL) зависят от этих настроек. Важно понимать, что эти функции не используют кодировку символов определённую в запросе, так например, следующие запросы не будут влиять на поведение этих функций:

Пример #1 Проблемы установки кодировки символов с помощью SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // Этот запрос не влияет на поведение $mysqli->real_escape_string();
    $mysqli->query("SET NAMES utf8mb4");

    // И этот не влияет на $mysqli->real_escape_string();
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // но вот этот запрос повлияет на поведение $mysqli->real_escape_string();
    $mysqli->set_charset('utf8mb4');

    // а этот НЕ повлияет, потому что нельзя использовать "-"
    $mysqli->set_charset('UTF-8'); // (utf8mb4, а не UTF-8)
    ?>

Примеры ниже демонстрируют, как правильно изменять кодировку символов во время выполнения, используя каждый из API.

> Замечание: Возможная путаница с UTF-8
> Поскольку имена кодировок символов в MySQL не содержат тире/дефис, строка "utf8" применяется в MySQL для установки кодировки UTF-8 (до 3 байт в кодировке Unicode UTF-8). Строка "UTF-8" неприемлема и выбросит ошибку при установке кодировки символов.

Пример #2 Пример установки кодировки символов: mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Первоначальная кодировка: ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Ошибка загрузки кодировки utf8mb4: %s\n", $mysqli->error);
        exit;
    }

    echo 'Ваша текущая кодировка: ' . $mysqli->character_set_name() . "\n";
    ?>

Пример #3 Пример установки кодировки символов: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Обзор терминологии
- Выбор API-интерфейса
- Выбор библиотеки
- Основные понятия
  - Буферизированные и небуферизированные запросы
  - Кодировки символов

# Улучшенный модуль MySQL (MySQL Improved)

# Введение

Модуль `mysqli` позволяет вам получить доступ к функциональности, которую предоставляет MySQL версии 4.1 и выше. Больше информации о сервере баз данных MySQL вы можете получить по адресу » http://www.mysql.com/.

Информация об использовании MySQL из PHP находится по адресу Краткий обзор

Документация MySQL находится по адресу » http://dev.mysql.com/doc/.

Некоторые части данной документации включены из руководства по MySQL с разрешения корпорации Oracle.

Все примеры, приведённые в документации, используют доступные свободно базы данных » world и » sakila.

# Краткий обзор

Раздел описывает инструменты, которые помогают программистам разрабатывать PHP-приложения, которые взаимодействуют с базой данных MySQL.

Об API-интерфейсе

Программный интерфейс приложения (англ. Application Programming Interface, API) определяет набор классов, методов, функций и переменных, к которым приложению потребуется обращаться, чтобы выполнить поставленные задачи. PHP-приложения взаимодействуют с базами данных через API-интерфейсы, которые приложениям обычно открывают PHP-модули.

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

Язык программирования PHP предлагает разработчикам несколько API-интерфейсов, через которые PHP-приложения взаимодействуют с базами данных MySQL. Документ описывает эти интерфейсы и даёт рекомендации по выбору конкретного способа подключения к базе данных из приложения.

О коннекторе

В MySQL-документации термин коннектор (англ. connector) относится к части программного обеспечения, которая разрешает приложению подключаться к серверу баз данных MySQL. БД MySQL предоставляет коннекторы для разных языков программирования, включая язык PHP.

Разработчику потребуется написать PHP-код, чтобы PHP-приложение научилось взаимодействовать с сервером баз данных: подключаться, отправлять запросы и выполнять другие операции, которые связаны с базой данных. Серверу баз данных потребуется ПО, чтобы предоставить API-интерфейс, через который PHP-приложение будет взаимодействовать с сервером, и чтобы управлять обменом информацией между приложением и сервером баз данных, для чего иногда также требуются промежуточные библиотеки. Это программное обеспечение называется коннектором, поскольку разрешает приложению подключаться (англ. to connect) к серверу баз данных.

О драйвере

Драйвер — часть программного обеспечения, которую разработали для взаимодействия приложения с конкретным типом сервера баз данных. Приложение вызывает методы коннектора, тот обращается к своему драйверу конкретной СУБД, а драйвер со своей стороны обращается к нижележащим библиотекам — клиентской библиотеке MySQL Client Library или встроенному драйверу MySQL Native Driver. Эти библиотеки реализуют низкоуровневый протокол взаимодействия с MySQL-сервером баз данных.

Например, PHP-модуль PDO, который поддерживает доступ к базам данных на уровне абстракции, содержит набор драйверов для доступа к конкретным базам данных. В список доступных модулю драйверов входит драйвер PDO_MYSQL, который разрешает модулю PDO взаимодействовать с сервером MySQL.

Термины «коннектор» и «драйвер» иногда употребляют как синонимы, это сбивает с толку. В MySQL-документации термин драйвер зарезервировали за программным обеспечением, которое предоставляет часть пакета коннектора для конкретной базы данных.

О модуле

В PHP-документации встречается ещё один термин — модуль. Код самого PHP состоит из ядра и дополнительных модулей, которые расширяют функциональность ядра. Для работы с СУБД MySQL ядро PHP расширили модулем `mysqli` и модулем PDO с MySQL-драйвером. Оба модуля включили в инфраструктуру модулей языка PHP.

Обычно модули предоставляют PHP-программисту API-интерфейс, через который разработчик получает доступ к функциям модуля программно. При этом отдельные модули в инфраструктуре PHP-модулей не раскрывают для программиста никаких интерфейсов.

MySQL-драйвер модуля PDO, например, не раскрывает API-интерфейс для программиста, но предоставляет интерфейс вышележащему абстрактному слою, который представляет модуль PDO.

Термины «API-интерфейс» и «модуль» нельзя воспринимать как одно и то же, поскольку модуль не обязан раскрывать API-интерфейс для программиста.

О главных API-интерфейсах языка PHP для работы с БД MySQL

PHP предлагает два API-интерфейса для подключения к серверу баз данных MySQL:

- PHP-модуль mysqli

- PHP-модуль PDO

Каждый модуль содержит достоинства, но встречаются и недостатки. Цель следующей части обзора состоит в кратком описании характеристик каждого API-интерфейса.

О PHP-модуле mysqli

Модуль `mysqli`, или улучшенный модуль MySQL (англ. improved MySQL), разработали, чтобы PHP-программисты получили выгоду, которую дают новые функции MySQL-систем версии 4.1.3 и выше. Модуль `mysqli` включается в пакет PHP версии 5 и выше.

Модуль `mysqli` содержит преимущества, главные из которых по сравнению с модулем `mysql` состоят в следующем:

- Объектно-ориентированный интерфейс

- Поддержка подготовленных запросов

- Поддержка мультизапросов

- Поддержка транзакций

- Расширенные инструменты отладки

Наравне с объектно-ориентированным интерфейсом модуль предоставляет и процедурный интерфейс.

Модуль `mysqli` встраивается в инфраструктуру модулей языка PHP, исходный код модуля лежит в каталоге ext/mysqli.

Подробнее о модуле `mysqli` рассказывает раздел MySQLi.

О модуле PDO

Модуль PDO — абстракция коннектора, которая определяет интерфейс доступа к базам данных для PHP-приложений. Модуль PDO раскрывает для PHP-приложений согласованный API-интерфейс, при взаимодействии с которым приложение не зависит от типа конкретного сервера баз данных, к которому подключается. Теоретически, при работе через API-интерфейс модуля PDO один сервер баз данных легко заменить другим, например поменять Firebird на MySQL, и для этого потребуются внести в PHP-код только незначительные изменения.

К другим примерам абстракций коннекторов баз данных относятся пакет JDBC для Java-приложений и пакет DBI для приложений на языке программирования Perl.

Преимущества модуля PDO состоят в чистоте, простоте и переносимости API-интерфейса, а главный недостаток модуля — недоступность продвинутых функций, которые поддерживаются последними версиями MySQL-сервера. К таким функциям, например, относятся множественные запросы, которые модуль PDO не поддерживает.

Модуль PDO встраивается в инфраструктуру модулей языка PHP, исходный код модуля лежит в директории ext/pdo.

Подробнее о модуле рассказывает раздел PDO.

О драйвере модуля PDO для работы с СУБД MySQL

MySQL-драйвер модуля PDO не относится к API-интерфейсу, который модуль раскрывает для программиста. MySQL-драйвер модуля PDO лежит на уровне ниже самого модуля PDO и взаимодействует с MySQL-сервером. Программист вызывает функции API-интерфейса модуля PDO, а модуль взаимодействует с драйвером для отправки данных и команд на MySQL-сервер.

MySQL-драйвер модуля PDO взаимодействует с MySQL-серверами, но модуль также включает драйверы для взаимодействия с серверами баз данных Firebird, PostgreSQL и другими СУБД.

MySQL-драйвер модуля PDO встраивается в инфраструктуру модулей языка PHP, исходный код модуля лежит в каталоге ext/pdo_mysql. Модуль не раскрывает API-интерфейс PHP-программисту.

Дополнительно о MySQL-драйвере модуля PDO рассказывает раздел PDO-драйвер СУБД MySQL.

О родном драйвере PHP для работы с СУБД MySQL

Модуль `mysqli` и MySQL-драйвер модуля PDO взаимодействуют с MySQL-сервером путём обращения к низкоуровневой библиотеке, которая реализует протокол взаимодействия с СУБД. Раньше единственной доступной библиотекой была клиентская библиотека MySQL Client Library, которая распространяется как пакет `libmysqlclient`.

Однако интерфейс, который предоставляла библиотека `libmysqlclient`, не был оптимизирован для взаимодействия с PHP-приложениями, поскольку библиотека `libmysqlclient` разрабатывалась для работы с приложениями на языке C. Поэтому как альтернативу MySQL-библиотеке `libmysqlclient` разработали родной PHP-драйвер для взаимодействия с СУБД MySQL — MySQL Native Driver, который распространяется как PHP-модуль и называется `mysqlnd`.

Модуль `mysqli` и PDO-драйвер для СУБД MySQL настраиваются отдельно — либо для работы с внешней библиотекой `libmysqlclient`, либо для работы с родным PHP-драйвером `mysqlnd`. Внутренний драйвер работает быстрее и расходует меньше памяти по сравнению с внешней библиотекой `libmysqlclient`, поскольку драйвер `mysqlnd` разработали непосредственно для работы в PHP-системах. Поэтому лучше предпочесть родной PHP-драйвер.

Родной PHP-драйвер для взаимодействия с СУБД MySQL встраивается в инфраструктуру модулей языка PHP, исходный код модуля лежит в каталоге ext/mysqlnd. Модуль не раскрывает API-интерфейс для PHP-программиста.

Сравнение функций модулей

Следующая таблица сравнивает функциональность основных методов подключения к СУБД MySQL из PHP-приложения:

Сравнение API-интерфейсов для взаимодействия PHP-приложений с СУБД MySQL
| PHP-модуль mysqli | PHP-модуль PDO через драйвер PDO_MySQL и родной PHP-драйвер для СУБД MySQL
--- | --- | ---
Версия PHP, в которой представили модуль | 5.0 | 5.0
Статус разработки MySQL | Разработка продолжается | Разработка продолжается
API поддерживает наборы символов | Да | Да
API поддерживает подготовленные запросы на стороне сервера | Да | Да
API поддерживает подготавливаемые запросы на стороне клиента | Нет | Да
API поддерживает хранимые процедуры | Да | Да
API поддерживает множественные запросы | Да | По большей части
Поддержка всего функционала MySQL 4.1+ | Да | По большей части

# Краткое руководство

## Содержание

- Процедурный и объектно-ориентированный интерфейс
- Соединения
- Выполнение запросов
- Подготавливаемые запросы
- Хранимые процедуры
- Множественные запросы
- API поддержка транзакций
- Метаданные

Это практическое руководство помогает освоить основные моменты API-интерфейса MySQL-сервера.

В этом руководстве приводится краткий обзор модуля mysqli. Для всех основных особенностей API-интерфейса приведены примеры PHP-кода. Также объясняются принципы работы баз данных в целом, чтобы иметь возможность описать какие-то отдельные моменты, присущие конкретно MySQL.

Требования: Знакомство с языком программирования PHP, SQL, а также знание основ работы с MySQL-сервером.

## Процедурный и объектно-ориентированный интерфейс

Модуль mysqli предоставляет двойной интерфейс программисту. Поддерживаются как процедурная, так и объектно-ориентированная парадигмы программирования.

Пользователи, переходящие со старого модуля mysql, возможно, предпочтут процедурный интерфейс. Он весьма схож с интерфейсом старого модуля, и во многих случаях функции отличаются только префиксом в имени. Некоторые mysqli-функции принимают дескриптор соединения первым аргументом, в отличие от соответствующих им функций старого модуля, которые принимают его в качестве последнего необязательного аргумента.

Пример #1 Простота перехода со старого модуля mysql

    <?php
    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Пожалуйста, не используйте устаревший модуль mysql в новых проектах.' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysql = mysql_connect("example.com", "user", "password");
    mysql_select_db("test");
    $result = mysql_query("SELECT 'Используйте вместо него модуль mysqli.' AS _msg FROM DUAL", $mysql);
    $row = mysql_fetch_assoc($result);
    echo $row['_msg'];
    ?>

Результат выполнения приведённого примера:

    Пожалуйста, не используйте устаревший модуль mysql в новых проектах. Используйте вместо него модуль mysqli.

Объектно-ориентированный интерфейс

В дополнение к процедурному пользователи могут использовать объектно-ориентированный интерфейс. Документация заточена именно под объектный интерфейс. Объектно-ориентированный интерфейс предлагает функции сгруппированные по цели их применения, что облегчает их поиск и освоение. Тем не менее, в практических примерах к функциям приводится код для обеих парадигм.

Каких-либо принципиальных отличий в производительности между интерфейсами нет. Пользователи вольны в выборе интерфейса, основываясь на личных предпочтениях.

Пример #2 Объектно-ориентированный и процедурный интерфейсы

    <?php

    $mysqli = mysqli_connect("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Мир, полный ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = $mysqli->query("SELECT 'выбора, чтобы угодить всем.' AS _msg FROM DUAL");
    $row = $result->fetch_assoc();
    echo $row['_msg'];

Результат выполнения приведённого примера:

    Мир, полный выбора, чтобы угодить всем.

Примеры в этом руководстве будут написаны в объектном стиле в виду того, что объектному подходу отдавалось предпочтение при создании документации.

Смешивание стилей

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

Пример #3 Плохой стиль программирования

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Этот код работает, но лучше так не писать.' AS _msg FROM DUAL");

    if ($row = $result->fetch_assoc()) {
        echo $row['_msg'];
    }

Результат выполнения приведённого примера:

    Этот код работает, но лучше так не писать.

Смотрите также

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- Общее описание функций модуля MySQLi

## Соединения

Сервер MySQL поддерживает различные способы передачи данных. Соединения могут использовать протоколы TCP/IP, сокеты Unix-доменов или именованные пайпы Windows.

Имя хоста `localhost` имеет особое значение. Оно используется только в сокетах Unix доменов. Чтобы открыть TCP/IP-соединение с локальным хостом, необходимо использовать `127.0.0.1` вместо имени хоста `localhost`.

Пример #1 Специальное назначение localhost

    <?php

    $mysqli = new mysqli("localhost", "user", "password", "database");

    echo $mysqli->host_info . "\n";

    $mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

    echo $mysqli->host_info . "\n";

Результат выполнения приведённого примера:

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Умолчания для параметров соединений

В зависимости от функции, осуществляющей подключение, какие-то параметры можно не задавать. Если параметр не задан, модуль попытается использовать значение по умолчанию для этого параметра, которое задано в конфигурационном файле PHP.

Пример #2 Задание значений по умолчанию

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

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

Встроенные библиотечные значения по умолчанию для параметров соединения

Если имя хоста не задано или передана пустая строка, клиентская библиотека использует для подключения к Unix-сокету хоста `localhost`. Если сокет не задан или передана пустая строка, и при этом запрошено подключение к Unix-сокету, библиотека попытается подключиться к сокету `/tmp/mysql.sock`.

В Windows-системах, если в качестве имени хоста передаётся `.`, библиотека попытается открыть соединение на основе именованного пайпа. В этом случае имя сокета будет воспринято как имя пайпа. Если имя сокета не задано, то будет использовано значение `\\.\pipe\MySQL`.

Если соединение не использует ни сокет Unix-домена, ни именованный пайп Windows, и при этом не задан порт для подключения, библиотека использует номер порта `3306`.

В драйвере mysqlnd и клиентской библиотеке MySQL (libmysqlclient) заложена та же логика определения умолчаний.

Настройки соединения

Настройки соединения позволяют, например, задать какие-то команды, которые нужно выполнить сразу после подключения, или отдать распоряжение использовать определённый набор символов. Настройки должны быть заданы до подключения к серверу.

Когда требуется задать настройки соединения, операция подключения выполняется в три этапа: функцией mysqli_init() или mysqli::__construct() создаётся дескриптор подключения, затем подключение настраивается с помощью функции mysqli::options(), и наконец устанавливается сетевое соединение с сервером посредством функции mysqli::real_connect().

Объединение подключений в пул

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

Каждый PHP-процесс использует свой пул подключений mysqli. В зависимости от конфигурации веб-сервера, PHP-процесс может обслуживать один или несколько запросов. Соответственно, соединение из пула могут последовательно использовать несколько скриптов.

Постоянное соединение

Новое подключение создаётся, только если в пуле не найдётся свободного подключения с теми же данными хоста, имени пользователя, пароля, сокета, порта и базы данных по умолчанию. Механизм постоянных соединений можно включать и выключать PHP директивой mysqli.allow_persistent. Максимальное количество соединений, которые может открыть скрипт, ограничено значением mysqli.max_links. Максимальное количество соединений, которые может открыть один PHP-процесс, ограничено значением mysqli.max_persistent. Следует заметить, что веб-сервер может порождать множество PHP процессов.

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

Модуль mysqli поддерживает обе интерпретации термина постоянное соединение: состояние соединения может сохраняться, а может и сбрасываться в изначальное. По умолчанию при извлечении из пула, соединение сбрасывается. mysqli делает это неявным вызовом функции mysqli::change_user() каждый раз, когда подключение используется повторно. С точки зрения пользователя подключение выглядит, как только что созданное.

Однако, вызов функции mysqli::change_user() довольно дорогостоящая операция. Для улучшения быстродействия можно перекомпилировать модуль с установленным флагом `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

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

Смотрите также

- mysqli::__construct()
- mysqli_init()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- MySQLi Configuration Options
- Persistent Database Connections

## Выполнение запросов

За выполнение запросов отвечают функции mysqli::query(), mysqli::real_query() и mysqli::multi_query(). Чаще всего применяется функция mysqli::query(), так как она выполняет сразу две задачи: выполняет запрос и буферизует на клиенте результат этого запроса (если он есть). Вызов mysqli::query() идентичен последовательному вызову функций mysqli::real_query() и mysqli::store_result().

Пример #1 Выполнение запросов

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

Буферизация результатов запроса

После выполнения запроса результаты можно либо получить сразу, либо считать строку за строкой с сервера. Буферизация набора результатов на стороне клиента позволяет серверу как можно раньше высвободить ресурсы, связанные с результатами запроса. Проще говоря, клиенты медленно используют наборы результатов. Поэтому рекомендуется использовать буферизованные наборы результатов. mysqli::query() объединяет выполнение запроса и буферизацию набора результатов.

PHP-приложения могут свободно оперировать данными внутри буферизованных результирующих наборов. Быстрая навигация по строкам наборов обусловлена тем, что наборы полностью располагаются в памяти клиента. Следует помнить, что зачастую обработка результатов на клиенте проще, нежели средствами сервера.

Пример #2 Навигация по строкам буферизованной результирующей таблицы

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

    echo "Обратный порядок...\n";
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        $row = $result->fetch_assoc();
        echo " id = " . $row['id'] . "\n";
    }

    echo "Исходный порядок строк...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Результат выполнения приведённого примера:

    Обратный порядок...
     id = 3
     id = 2
     id = 1
    Исходный порядок строк...
     id = 1
     id = 2
     id = 3

Небуферизованные результирующие наборы

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

Пример #3 Навигация по строкам небуферизованной результирующей таблицы

    <?php
    $mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
    $result = $mysqli->use_result();

    echo "Порядок строк в результирующем наборе...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Типы данных значений в результирующей таблице

Функции mysqli::query(), mysqli::real_query() и mysqli::multi_query() предназначены для выполнения не подготавливаемых запросов. На уровне протокола клиент-серверного взаимодействия MySQL за выполнение запросов отвечают команда `COM_QUERY` и текстовый протокол. Когда используется текстовый протокол, сервер MySQL перед отправкой клиенту преобразовывает все данные в результирующем наборе в текстовые строки. Это преобразование выполняется вне зависимости от типа данных SQL-столбца результирующей таблицы. Клиентские библиотеки mysql, в свою очередь, получают все данные, принимая их за строки. На клиенте не проводится никакого обратного преобразования к исходным типам, все данные, полученные приложением остаются PHP строками.

Пример #4 Текстовый протокол по умолчанию возвращает строки

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Результат выполнения приведённого примера:

    id = 1 (string)
    label = a (string)

Если используется библиотека mysqlnd, можно включить преобразование целочисленных значений и чисел с плавающей точкой из столбцов таблицы в PHP числа. Делается это заданием настройки подключения `MYSQLI_OPT_INT_AND_FLOAT_NATIVE`. В таком случае mysqlnd будет проверять метаданные столбцов и преобразовывать SQL-числа этих полей в PHP-числа, если эти значения не выходят за рамки допустимых диапазонов типов данных PHP. То есть, например, SQL INT число попадёт в PHP приложение в виде целого (integer).

Пример #5 Получение исходных типов данных в приложении

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli();
    $mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
    $mysqli->real_connect("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Результат выполнения приведённого примера:

    id = 1 (integer)
    label = a (string)

Смотрите также

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Подготавливаемые запросы

СУБД MySQL поддерживает подготавливаемые запросы. Подготавливаемые (или параметризованные) запросы используются для повышения эффективности, когда один запрос выполняется многократно и защищает от SQL-инъекций.

Принцип работы

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

MySQL сервер поддерживает неименованные, или позиционные, псевдопеременные `?`.

За подготовкой следует выполнение. Во время выполнения клиент связывает значения параметров и отправляет их на сервер. Сервер выполняет запрос со связанными значениями, используя ранее созданные внутренние ресурсы.

Пример #1 Подготовленный запрос

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Подготовленный запрос, шаг 1: подготовка */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Подготовленный запрос, шаг 2: связывание и выполнение */
    $id = 1;
    $label = 'PHP';
    $stmt->bind_param("is", $id, $label); // "is" означает, что $id связывается, как целое число, а $label — как строка

    $stmt->execute();

Повторное выполнение запроса

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

Пример #2 Выражение INSERT один раз подготавливается, а затем многократно выполняется

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Подготовленный запрос, шаг 1: подготовка */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Подготовленный запрос, шаг 2: связывание и выполнение */
    $stmt->bind_param("is", $id, $label); // "is" означает, что $id связывается, как целое число, а $label — как строка

    $data = [
        1 => 'PHP',
        2 => 'Java',
        3 => 'C++'
    ];
    foreach ($data as $id => $label) {
        $stmt->execute();
    }

    $result = $mysqli->query('SELECT id, label FROM test');
    var_dump($result->fetch_all(MYSQLI_ASSOC));

Результат выполнения приведённого примера:

    array(3) {
      [0]=>
      array(2) {
        ["id"]=>
        string(1) "1"
        ["label"]=>
        string(3) "PHP"
      }
      [1]=>
      array(2) {
        ["id"]=>
        string(1) "2"
        ["label"]=>
        string(4) "Java"
      }
      [2]=>
      array(2) {
        ["id"]=>
        string(1) "3"
        ["label"]=>
        string(3) "C++"
      }
    }

Каждый подготавливаемый запрос использует ресурсы сервера. Если запрос больше не нужен, его необходимо сразу закрыть. Если не сделать этого явно, запрос закроется сам, но только когда PHP освободит его дескриптор, как правило это происходит при выходе запроса из области видимости или при завершении работы скрипта.

Использование подготавливаемых запросов не всегда приводит к повышению эффективности. Если параметризованный запрос запускается лишь раз, это приводит к большему количеству клиент-серверных обменов данными, нежели при выполнении простого запроса. Именно по этой причине в примере выше выражение `SELECT` выполнялось, как обычный запрос.

Также имеет смысл рассмотреть SQL-синтаксис вставки множества значений в выражении INSERT. В примере выше мультивставка (значения для вставки перечисляются через запятую) в предложении INSERT обошлась бы дешевле, чем подготовленный запрос.

Пример #3 Меньше обменов данными при использовании мультивставок SQL

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $values = [1, 2, 3, 4];

    $stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
    $stmt->bind_param('iiii', ...$values);
    $stmt->execute();

Типы данных значений в результирующей таблице

В протоколе клиент-серверного взаимодействия MySQL для обычных и подготавливаемых запросов определены разные протоколы передачи данных клиенту. Параметризованные запросы используют так называемый двоичный протокол. Сервер MySQL посылает результирующий набор клиенту «как есть» в двоичном формате. Данные в таблице не преобразовываются в текст. Клиентские библиотеки получают двоичные данные и пытаются преобразовать значения в соответствующие типы данных PHP. Например, столбец результатов запроса типа SQL `INT` PHP примет и преобразует в тип integer.

Пример #4 Исходные типы данных

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();
    $result = $stmt->get_result();
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Результат выполнения приведённого примера:

    id = 1 (integer)
    label = PHP (string)

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

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

Результаты из подготовленного запроса можно получить либо привязав выходные переменные, либо запросив объект mysqli_result.

Выходные параметры нужно привязывать после выполнения запроса. Каждому столбцу результирующей таблицы должна соответствовать ровно одна переменная.

Пример #5 Привязка переменных к результату запроса

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $stmt->bind_result($out_id, $out_label);

    while ($stmt->fetch()) {
        printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
    }

Результат выполнения приведённого примера:

    id = 1 (integer), label = PHP (string)

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

Также можно буферизовать данные результирующих таблиц подготовленного запроса с помощью функции mysqli_stmt::store_result().

Извлечение результатов запроса посредством mysqli_result интерфейса

Вместо использования привязки переменных к результатам запроса, результирующие таблицы можно извлекать средствами интерфейса mysqli_result. Функция mysqli_stmt::get_result() возвращает буферизованный результирующий набор строк.

Пример #6 Использование mysqli_result для выборки результатов запроса

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $result = $stmt->get_result();

    var_dump($result->fetch_all(MYSQLI_ASSOC));

Результат выполнения приведённого примера:

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

Использование интерфейса mysqli_result имеет дополнительное преимущество в том, что буферизация результирующих таблиц на клиенте предлагает гибкую систему навигации по этим таблицам.

Пример #7 Буферизация результирующего набора для удобства чтения данных

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Неподготовленный запрос */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test");
    $stmt->execute();

    $result = $stmt->get_result();

    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        var_dump($result->fetch_assoc());
    }

Результат выполнения приведённого примера:

    array(2) {
      ["id"]=>
      int(3)
      ["label"]=>
      string(3) "C++"
    }
    array(2) {
      ["id"]=>
      int(2)
      ["label"]=>
      string(4) "Java"
    }
    array(2) {
      ["id"]=>
      int(1)
      ["label"]=>
      string(3) "PHP"
    }

Экранирование и SQL-инъекции

Привязанные переменные отправляются на сервер отдельно от запроса и таким образом не могут влиять на него. Сервер использует эти значения непосредственно в момент выполнения, уже после того, как был обработан шаблон выражения. Привязанные параметры не нуждаются в экранировании, так как они никогда не подставляются непосредственно в строку запроса. Необходимо отправлять тип привязанной переменной на сервер, чтобы определить соответствующее преобразование. Смотрите функцию mysqli_stmt::bind_param() для получения большей информации.

Такое разделение часто считается единственным способом обезопаситься от SQL-инъекции, но на самом деле такого же уровня безопасности можно добиться и с неподготовленными выражениями, если правильно отформатировать все значения. Важно отметить, что правильное форматирование — не то же самое, что и экранирование, и включает в себя больше логики. Таким образом, подготовленные выражения - просто более удобный и менее подверженный ошибкам способ для достижения такой безопасности базы данных.

Эмуляция подготовленного запроса на клиенте

В API нет возможности эмулировать подготавливаемые запросы на клиенте.

Смотрите также

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Хранимые процедуры

СУБД MySQL поддерживает хранимые процедуры. Под этим термином понимается последовательность операций, хранящаяся как единое целое в каталоге базы данных на сервере. Приложения могут вызывать и запускать хранимые процедуры. Для запуска хранимой процедуры используется SQL выражение `CALL`.

Параметры

Хранимые процедуры могут иметь параметры `IN`, `INOUT` и `OUT` в зависимости от версии MySQL. Интерфейс mysqli не делает различий между этими типами параметров.

Параметр IN

Входные параметры указываются внутри предложения `CALL`. При передаче входных параметров важно убедиться, что их значения корректно экранированы.

Пример #1 Вызов хранимой процедуры

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

    $mysqli->query("CALL p(1)");

    $result = $mysqli->query("SELECT id FROM test");

    var_dump($result->fetch_assoc());

Результат выполнения приведённого примера:

    array(1) {
      ["id"]=>
      string(1) "1"
    }

Параметр INOUT/OUT

Значения параметров `INOUT`/`OUT` доступны через переменные сессии.

Пример #2 Использование переменных сессии

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

    $mysqli->query("SET @msg = ''");
    $mysqli->query("CALL p(@msg)");

    $result = $mysqli->query("SELECT @msg as _p_out");

    $row = $result->fetch_assoc();
    echo $row['_p_out'];

Результат выполнения приведённого примера:

    Hi!

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

Обработка результирующих наборов

Хранимые процедуры могут возвращать результирующие наборы строк. Таблицы результатов работы хранимой процедуры нельзя корректно извлечь средствами mysqli::query(). Функция mysqli::query() выполняет две операции: запускает запрос и извлекает первый результирующий набор, помещая его в буфер. Хранимые процедуры могут возвращать более одного результирующего набора, но при использовании mysqli::query() все они, кроме первого, станут недоступны пользователю.

Результирующие таблицы хранимых процедур извлекаются функциями mysqli::real_query() или mysqli::multi_query(). Обе функции позволяют получить любое количество результирующих наборов, возвращённых SQL-запросами, таких как `CALL`. Если в процессе работы не удаётся извлечь все доступные результаты вызова хранимой процедуры, будет вызываться ошибка.

Пример #3 Извлечение результатов работы хранимой процедуры

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $mysqli->multi_query("CALL p()");

    do {
        if ($result = $mysqli->store_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($mysqli->next_result());

Результат выполнения приведённого примера:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "1"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "4"
      }
    }

Использование подготавливаемых запросов

Специальных средств для извлечения данных при использовании подготавливаемых запросов не требуется. Интерфейсы подготавливаемых и обычных запросов одинаковы. Однако, нужно учитывать, что не все версии MYSQL поддерживают подготовку в запросе SQL-выражения `CALL`.

Пример #4 Хранимые процедуры и подготавливаемые запросы

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($result = $stmt->get_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($stmt->next_result());

Результат выполнения приведённого примера:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(1)
      }
      [1]=>
      array(1) {
        [0]=>
        int(2)
      }
      [2]=>
      array(1) {
        [0]=>
        int(3)
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(2)
      }
      [1]=>
      array(1) {
        [0]=>
        int(3)
      }
      [2]=>
      array(1) {
        [0]=>
        int(4)
      }
    }

Само собой, поддерживается привязка результатов к объекту запроса.

Пример #5 Хранимые процедуры и подготавливаемые запросы с использованием привязки результатов

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($stmt->store_result()) {
            $stmt->bind_result($id_out);
            while ($stmt->fetch()) {
                echo "id = $id_out\n";
            }
        }
    } while ($stmt->next_result());

Результат выполнения приведённого примера:

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

Смотрите также

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Множественные запросы

MySQL поддерживает наличие нескольких SQL-запросов в тексте одного запроса, но требует особого обращения. Пересылка на сервер нескольких выражений в одном запроса уменьшает количество клиент-серверных взаимодействий, но требует специальной обработки.

Множественные запросы, или мультизапросы, должны запускаться функцией mysqli::multi_query(). Отдельные SQL-предложения в мультизапросе отделяются точкой с запятой. После выполнения мультизапроса все результирующие наборы, которые он вернул, необходимо извлечь.

MySQL-сервер поддерживает наличие в одном мультизапросе подзапросов, как возвращающих результирующий набор, так и не возвращающих.

Пример #1 Множественные запросы

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $sql = "SELECT COUNT(*) AS _num FROM test;
            INSERT INTO test(id) VALUES (1);
            SELECT COUNT(*) AS _num FROM test; ";

    $mysqli->multi_query($sql);

    do {
        if ($result = $mysqli->store_result()) {
            var_dump($result->fetch_all(MYSQLI_ASSOC));
            $result->free();
        }
    } while ($mysqli->next_result());

Результат выполнения приведённого примера:

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

Рассмотрение аспектов безопасности

Функции API mysqli::query() и mysqli::real_query() во время работы не устанавливают на сервере специальный флаг, необходимый для выполнения мультизапросов. Отдельная API-функция для мультизапросов позволяет снизить вероятность случайных SQL-инъекций. Злоумышленник может попытаться добавить в конец запроса выражения, вроде `; DROP DATABASE mysql` или `; SELECT SLEEP(999)`. Если ему это удастся, но не будет использоваться функция mysqli::multi_query(), сервер не выполнит внедрённое и опасное SQL-выражение.

Пример #2 SQL-инъекция

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
    ?>

Результат выполнения приведённого примера:

    PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax;
    check the manual that corresponds to your MySQL server version for the right syntax to
    use near 'DROP TABLE mysql.user' at line 1

Подготавливаемые запросы

Использование множества выражений в подготавливаемом запросе не поддерживается.

Смотрите также

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## API поддержка транзакций

Поддержка транзакций в СУБД MySQL зависит от используемого движка хранилища данных. Начиная с MySQL 5.5, по умолчанию используется движок InnoDB. InnoDB полностью поддерживает модель транзакций ACID.

Транзакциями можно управлять как средствами SQL, так и вызовами API-функций. Для включения и выключения режима автофиксации изменений (`autocommit`) рекомендуется пользоваться API функциями.

Пример #1 Установка режима автофиксации (`autocommit`) средствами SQL и функциями API

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Рекомендуется управлять настройками транзакций средствами API */
    $mysqli->autocommit(false);

    /* Не будет распознаваться и учитываться плагинами репликации и балансировки нагрузки */
    $mysqli->query('SET AUTOCOMMIT = 0');

Дополнительные службы сервера, такие как плагины репликации и балансировки нагрузки, могут отслеживать вызовы API-функций. Плагин репликации может сообщать балансировщику нагрузки о запущенной транзакции, если эта транзакция обслуживается API-функциями. Сервер не сможет распределять нагрузку между репликами базы, если смена режима автофиксации (`autocommit`), фиксация и откат транзакций осуществляются SQL-запросами.

Пример #2 Фиксация и откат

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $mysqli->autocommit(false);

    $mysqli->query("INSERT INTO test(id) VALUES (1)");
    $mysqli->rollback();

    $mysqli->query("INSERT INTO test(id) VALUES (2)");
    $mysqli->commit();

Следует заметить, что сервер MySQL не может откатить результаты всех запросов. Некоторые изменения фиксируются неявно.

Смотрите также

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Метаданные

Результирующий набор MySQL содержит метаданные. Эти данные описывают столбцы результирующей таблицы. Все сведения, которые передаёт MySQL, доступны через `mysqli` интерфейс. Модуль не изменяет получаемые данные, либо эти изменения незначительны. Различия между версиями MySQL также можно не принимать во внимание.

Метаданные доступны через интерфейс mysqli_result.

Пример #1 Доступ к метаданным результирующей таблицы

    <?php
    $mysqli = new mysqli("example.com", "user", "password", "database");
    if ($mysqli->connect_errno) {
        echo "Не удалось подключиться к MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    }

    $res = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    var_dump($res->fetch_fields());
    ?>

Результат выполнения приведённого примера:

    array(2) {
      [0]=>
      object(stdClass)#3 (13) {
        ["name"]=>
        string(4) "_one"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(1)
        ["length"]=>
        int(1)
        ["charsetnr"]=>
        int(63)
        ["flags"]=>
        int(32897)
        ["type"]=>
        int(8)
        ["decimals"]=>
        int(0)
      }
      [1]=>
      object(stdClass)#4 (13) {
        ["name"]=>
        string(4) "_two"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(5)
        ["length"]=>
        int(5)
        ["charsetnr"]=>
        int(8)
        ["flags"]=>
        int(1)
        ["type"]=>
        int(253)
        ["decimals"]=>
        int(31)
      }
    }

Подготавливаемые запросы

Метаданные результирующих наборов, полученных в результате выполнения подготовленных запросов, можно получить аналогичным образом. Подходящий дескриптор mysqli_result можно получить функцией mysqli_stmt::result_metadata().

Пример #2 Метаданные подготовленных запросов

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    $stmt->execute();
    $result = $stmt->result_metadata();
    var_dump($result->fetch_fields());

Смотрите также

- mysqli::query()
- mysqli_result::fetch_fields()

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Эти функции доступны только в PHP, который собран с поддержкой модуля mysqli.

MySQL 8

При запуске PHP до версии 7.1.16, а также PHP с версии 7.2 до версии 7.2.4 в качестве плагина шифрования паролей по умолчанию для сервера MySQL 8 устанавливают mysql_native_password, иначе будет выдана ошибка наподобие The server requested authentication method unknown to the client [caching_sha2_password], даже когда плагин caching_sha2_password не задан.

Причина этого в том, что на сервере MySQL 8 в качестве плагина по умолчанию указан caching_sha2_password, который не распознаётся старыми версиями PHP (модулем mysqlnd). Вместо него в файле конфигурации сервера my.cnf указывают — `default_authentication_plugin=mysql_native_password`. Плагин caching_sha2_password получил полную поддержку начиная с PHP 7.4.4. В предыдущих версиях PHP его поддерживает модуль mysql_xdevapi.

## Установка

Модуль `mysqli` был представлен с версией PHP 5.0.0. MySQL Native Driver был включён в PHP версии 5.3.0.

## Установка для Linux

Большинство дистрибутивов Unix включает бинарные версии PHP, которые в дальнейшем могут быть установлены. Несмотря на то, что бинарные версии, как правило, собраны с включённой поддержкой модулей MySQL, может потребоваться установка дополнительных пакетов с библиотеками модулей. Убедитесь, что менеджер пакетов, идущий с выбранным дистрибутивом, позволяет установить такие пакеты.

К примеру, на Ubuntu пакет `php5-mysql` устанавливает модули ext/mysql, ext/mysqli, и pdo_mysql. В CentOS пакет `php-mysql` также устанавливает три этих модуля.

Конечно, вы всегда можете собрать PHP из исходного кода. Сборка PHP из исходного кода позволяет выделить только те модули MySQL (а также клиентские библиотеки для каждого из модулей), которые требуется использовать.

Рекомендуется использовать библиотеку MySQL Native Driver, так как она повышает производительность и даёт доступ к функциям, недоступным при использовании MySQL Client Library. Смотрите Что такое MySQL Native Driver в PHP? для ознакомления с возможностями MySQL Native Driver.

Под `/path/to/mysql_config` подразумевается расположение программы `mysql_config`, поставляемой вместе с MySQL Server.

Вспомогательная таблица времени компиляции mysqli
Версия PHP | По умолчанию | Опции настройки: mysqlnd | Опции настройки: `libmysqlclient` | Список изменений
--- | --- | --- | --- | ---
5.4.x и выше | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | по умолчанию mysqlnd
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd поддерживается
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Недоступно | --with-mysqli=/path/to/mysql_config | mysqlnd не поддерживается

Необходимо отметить, что существует возможность свободно перемешивать модули MySQL и клиентские библиотеки. Например, можно активировать модуль MySQL, позволяющий использовать MySQL Client Library (libmysqlclient), и при этом настроить модуль `mysqli` для использования MySQL Native Driver. Таким образом, возможны любые перестановки модулей и клиентских библиотек.

## Установка для Windows

В Windows DLL php_mysqli.dll должен быть включён в php.ini.

Как и при включении любого модуля PHP (например, php_mysqli.dll), директива PHP extension_dir должна устанавливать каталог, в котором находятся модули PHP. Смотрите также раздел о самостоятельной установке PHP в Windows. Пример значения `extension_dir` - c:\php\ext.

> Замечание:

> Если при запуске веб-сервера возникает ошибка, подобная следующей: `"Unable to load dynamic library './php_mysqli.dll'"`, это происходит потому, что файл php_mysqli.dll не может быть найден системой.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации MySQLi
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | До PHP 7.2.16 и 7.3.3 значение по умолчанию равнялось "1".
mysqli.local_infile_directory |  | `INI_SYSTEM` | Доступно с PHP 8.1.0.
mysqli.allow_persistent | "1" | `INI_SYSTEM` |
mysqli.max_persistent | "-1" | `INI_SYSTEM` |
mysqli.max_links | "-1" | `INI_SYSTEM` |
mysqli.default_port | "3306" | `INI_ALL` |
mysqli.default_socket | NULL | `INI_ALL` |
mysqli.default_host | NULL | `INI_ALL` |
mysqli.default_user | NULL | `INI_ALL` |
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | Опцию удалили с PHP 8.2.0
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

Другие детали и определения констант семейства INI_* приводит раздел об изменениях конфигурации.

Краткое разъяснение конфигурационных директив.

`mysqli.allow_local_infile` bool

  Разрешает доступ к локальным с точки зрения PHP файлам через инструкции LOAD DATA.

`mysqli.local_infile_directory` string

  Разрешает ограничить загрузку LOAD DATA файлами, которые лежат в заданном каталоге.

`mysqli.allow_persistent` int

  Включает возможность создавать постоянные соединения функцией mysqli_connect().

`mysqli.max_persistent` int

  Максимальное количество постоянных соединений. Для неограниченного количества устанавливают значение 0.

`mysqli.max_links` int

  Максимальное количество MySQL-соединений на процесс.

`mysqli.default_port` int

  TCP-порт по умолчанию для соединения с сервером баз данных, если другое значение явно не указали. PHP получит значение в следующем порядке: из переменной среды окружения `MYSQL_TCP_PORT`, директивы `mysql-tcp` в файле /etc/services или константы `MYSQL_PORT`, которая задаётся во время компиляции, если значение по умолчанию не указали. Модуль Win32 использует только константу `MYSQL_PORT`.

`mysqli.default_socket` string

  Имя сокета по умолчанию для соединения с локальной базой данных, если имя сокета не указали явно.

`mysqli.default_host` string

  Имя сервера, которое используется, если имя не указали явно.

`mysqli.default_user` string

  Имя пользователя, используемое по умолчанию, если имя не указали явно.

`mysqli.default_pw` string

  Пароль по умолчанию для подключения к БД, если пароль не указали явно.

`mysqli.reconnect` int

  Автоматически восстанавливать соединение при его потере.

  > Замечание: Драйвер "mysqlnd" игнорирует настройку и её удалили в PHP 8.2.0.

`mysqli.rollback_on_cached_plink` bool

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

Пользователям нельзя устанавливать значение `MYSQL_OPT_READ_TIMEOUT` через API-вызовов или установку конфигурационных значений во время работы скрипта. Обратите внимание, что если бы установку разрешили, библиотека `libmysqlclient` и потоки по-разному обрабатывали бы значение `MYSQL_OPT_READ_TIMEOUT`.

# Модуль mysqli и постоянные соединения

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

В отличие от модуля mysql, в mysqli нет отдельной функции для создания постоянных соединений. Чтобы открыть постоянное соединение, при создании подключения к имени хоста нужно добавить префикс `p:`.

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

Тем не менее, в `mysqli` эта проблема решена. В модуле есть встроенный функционал, осуществляющий очистку соединений и переводящий их в состояние пригодное для использования. Код очистки, реализованный в `mysqli` включает следующие операции:

- Откат активных транзакций

- Закрытие и удаление временных таблиц

- Снятие блокировки с таблиц

- Сброс переменных сессии

- Закрытие подготовленных запросов (всегда происходит в PHP)

- Закрытие обработчиков

- Снятие блокировок, установленных функцией GET_LOCK()

Это позволяет быть уверенным в том, что возвращённые из пула соединения готовы к использованию в клиентских процессах.

Модуль `mysqli` делает очистку соединений автоматически путём вызова C-API функции `mysql_change_user()`.

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

Есть возможность отключить автоматическую очистку соединений, если скомпилировать PHP с директивой `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`.

> Замечание:

> Постоянные соединения поддерживаются модулем `mysqli` как при работе с родным MySQL-драйвером, так и при работе с клиентской библиотекой MySQL.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`MYSQLI_READ_DEFAULT_GROUP` (int)

  Считывает опции именованной группы из файла my.cnf или файла, который указали константой `MYSQLI_READ_DEFAULT_FILE`.

`MYSQLI_READ_DEFAULT_FILE` (int)

  Считывает опции из именованного файла параметров, а не из файла my.cnf.

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Указывает серверу, что клиенту разрешается работать в режиме песочницы с просроченными паролями. Константу передают в функцию mysqli_options().
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  Опция определяет каталог, из которого клиентской стороне разрешается загрузка данных из файла в таблицу через модификатор `LOCAL` в инструкции `LOAD DATA LOCAL`.
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  Время ожидания подключения в секундах.

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Время ожидания результата выполнения команды в секундах. Доступна с PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  Включает команду `LOAD LOCAL INFILE`.

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Преобразовывает целочисленные столбцы и столбцы с плавающей точкой обратно в числа PHP. Константа корректно работает только с драйвером mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  Размер внутреннего буфера команды или сети. Константа корректно работает только с драйвером mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Максимальный размер блока чтения в байтах при чтении тела пакета команд. Константа корректно работает только с драйвером mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  Команда, которую функция выполнит при подключении к MySQL-серверу. Функция автоматически перезапустит команду при переподключении.

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Указывает серверу, что клиенту разрешается работать в режиме песочницы с просроченными паролями. Константу передают в функцию mysqli_real_connect().
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  Возвращает количество совпавших, а не затронутых строк.
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  Проверяет сертификат сервера.
`MYSQLI_CLIENT_SSL` (int)

  Использовать протокол шифрования SSL. Прикладные программы не должны устанавливать эту опцию; опция устанавливается внутри клиентской библиотеки MySQL.

`MYSQLI_CLIENT_COMPRESS` (int)

  Использовать компрессию.

`MYSQLI_CLIENT_INTERACTIVE` (int)

  Ждать `interactive_timeout` секунд (вместо `wait_timeout`) бездействия перед закрытием соединения. Переменная сессии клиента `wait_timeout` будет установлена в значение переменной сессии `interactive_timeout`.

`MYSQLI_CLIENT_IGNORE_SPACE` (int)

  Разрешить пробелы после названий функций. Константа делает имена функций зарезервированными словами.

`MYSQLI_CLIENT_NO_SCHEMA` (int)

  Запретить синтаксис `db_name.tbl_name.col_name`.

`MYSQLI_CLIENT_MULTI_QUERIES`

  Разрешить выполнение в одном вызове функции mysqli_query() нескольких запросов, разделённых точкой с запятой.

`MYSQLI_STORE_RESULT` (int)

  Для использования буферизации наборов данных. Значение равно `0`.

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  С PHP 8.1 константа больше ни на что не влияет. До PHP 8.1 константу указывали для копирования результатов из внутреннего буфера драйвера mysqlnd в извлечённые PHP-переменные. По умолчанию драйвер mysqlnd будет использовать логику ссылок, чтобы избежать копирования и дублирования результатов, которые хранятся в памяти. Для конкретных наборов результатов, например, наборов результатов с большим количеством небольших строк, подход копирования может уменьшить общее потребление памяти, поскольку PHP-переменные, которые содержат результаты, могут освободиться раньше. Константа доступна только с драйвером `mysqlnd`. Константа объявлена устаревшей с PHP 8.4.0.
`MYSQLI_USE_RESULT` (int)

  Для работы с небуферизированными наборами результатов. Значение равно `1`.

`MYSQLI_ASSOC` (int)

  Столбцы возвращаются в виде ассоциативного массива с именами полей в качестве индексов.

`MYSQLI_NUM` (int)

  Столбцы возвращаются в виде индексного массива.

`MYSQLI_BOTH` (int)

  Столбцы возвращаются в виде массива, который содержит как числовой, так и ассоциативный индексы.

`MYSQLI_NOT_NULL_FLAG` (int)

  Информирует о том, что поле определили как `NOT NULL`.

`MYSQLI_PRI_KEY_FLAG` (int)

  Поле — часть первичного индекса.

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  Поле — часть уникального индекса.

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  Поле — часть индекса.

`MYSQLI_BLOB_FLAG` (int)

  Поле определили как `BLOB`.

`MYSQLI_UNSIGNED_FLAG` (int)

  Поле определили как `UNSIGNED`.

`MYSQLI_ZEROFILL_FLAG` (int)

  Поле определили как `ZEROFILL`.

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  Поле определили как `AUTO_INCREMENT`.

`MYSQLI_TIMESTAMP_FLAG` (int)

  Поле определили как `TIMESTAMP`.

`MYSQLI_SET_FLAG` (int)

  Поле определили как `SET`.

`MYSQLI_NUM_FLAG` (int)

  Поле определили как `NUMERIC`.

`MYSQLI_PART_KEY_FLAG` (int)

  Поле — часть многоколоночного индекса.

`MYSQLI_GROUP_FLAG` (int)

  Поле — часть инструкции `GROUP BY`.

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  В определении столбца нет предложения `DEFAULT`. Это не относится к столбцам `NULL`, поскольку значение по умолчанию такого столбца равно `NULL`, и `AUTO_INCREMENT`, поскольку у такого столбца есть значение по умолчанию, которое подразумевается.
`MYSQLI_TYPE_DECIMAL` (int)

  Поле определили как `DECIMAL`.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  Математическая точность полей `DECIMAL` или `NUMERIC`.

`MYSQLI_TYPE_BIT` (int)

  Поле определили как `BIT`.

`MYSQLI_TYPE_TINY` (int)

  Поле определили как `TINYINT`.

`MYSQLI_TYPE_SHORT` (int)

  Поле определили как `SMALLINT`.

`MYSQLI_TYPE_LONG` (int)

  Поле определили как `INT`.

`MYSQLI_TYPE_FLOAT` (int)

  Поле определили как `FLOAT`.

`MYSQLI_TYPE_DOUBLE` (int)

  Поле определили как `DOUBLE`.

`MYSQLI_TYPE_NULL` (int)

  Поле определили как `DEFAULT NULL`.

`MYSQLI_TYPE_TIMESTAMP` (int)

  Поле определили как `TIMESTAMP`.

`MYSQLI_TYPE_LONGLONG` (int)

  Поле определили как `BIGINT`.

`MYSQLI_TYPE_INT24` (int)

  Поле определили как `MEDIUMINT`.

`MYSQLI_TYPE_DATE` (int)

  Поле определили как `DATE`.

`MYSQLI_TYPE_TIME` (int)

  Поле определили как `TIME`.

`MYSQLI_TYPE_DATETIME` (int)

  Поле определили как `DATETIME`.

`MYSQLI_TYPE_YEAR` (int)

  Поле определили как `YEAR`.

`MYSQLI_TYPE_NEWDATE` (int)

  Поле определили как `DATE`.

`MYSQLI_TYPE_INTERVAL` (int)

  Псевдоним константы `MYSQLI_TYPE_ENUM`. Константа удалена с PHP 8.4.0.

`MYSQLI_TYPE_ENUM` (int)

  Поле определили как `ENUM`.

`MYSQLI_TYPE_SET` (int)

  Поле определили как `SET`.

`MYSQLI_TYPE_TINY_BLOB` (int)

  Поле определили как `TINYBLOB`.

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  Поле определили как `MEDIUMBLOB`.

`MYSQLI_TYPE_LONG_BLOB` (int)

  Поле определили как `LONGBLOB`.

`MYSQLI_TYPE_BLOB` (int)

  Поле определили как `BLOB`.

`MYSQLI_TYPE_VAR_STRING` (int)

  Поле определили как `VARCHAR`.

`MYSQLI_TYPE_STRING` (int)

  Поле определили как `CHAR` или `BINARY`.

`MYSQLI_TYPE_CHAR` (int)

  Поле определили как `TINYINT`. Для типа `CHAR` смотрите описание константы `MYSQLI_TYPE_STRING`.

`MYSQLI_TYPE_GEOMETRY` (int)

  Поле определили как `GEOMETRY`.

`MYSQLI_TYPE_JSON` (int)

  Поле определили как `JSON`. Константа корректно работает только с драйвером mysqlnd и MySQL 5.7.8 или выше.

`MYSQLI_TYPE_VECTOR` (int)

  Поле определили как `VECTOR`.

`MYSQLI_NEED_DATA`

  Доступно больше данных для связанной переменной.

`MYSQLI_ENUM_FLAG` (int)

  Поле определили как `ENUM`.

`MYSQLI_BINARY_FLAG` (int)

  Поле определили как `BINARY`.

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  Константа удалена с PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  Константа удалена с PHP 8.4.0.

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  Константа удалена с PHP 8.4.0.

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  Сообщить о запросе без индекса или с плохим индексом.

`MYSQLI_REPORT_ERROR` (int)

  Сообщить об ошибках вызова функций mysqli-модуля.

`MYSQLI_REPORT_STRICT` (int)

  Выбрасывать исключения `mysqli_sql_exception` вместо предупреждений, если возникла ошибка.

`MYSQLI_REPORT_ALL` (int)

  Включить все уведомления.

`MYSQLI_REPORT_OFF` (int)

  Отключает уведомления.

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  При работе функции mysqli_debug() для константы устанавливается значение 1.

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  Обновляет таблицу прав доступа. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_LOG` (int)

  Сбрасывает логи, точно так же, как и SQL-инструкция `FLUSH LOGS`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_TABLES` (int)

  Очищает кеш таблицы, точно так же, как и SQL-инструкция `FLUSH TABLES`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_HOSTS` (int)

  Очищает кеш хоста, точно так же, как и SQL-инструкция `FLUSH HOSTS`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_REPLICA` (int)

  Синоним константы `MYSQLI_REFRESH_SLAVE`. Константа доступна с PHP 8.1.0. Объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_STATUS` (int)

  Сбрасывает переменные состояния, точно так же, как и SQL-инструкция `FLUSH STATUS`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_THREADS` (int)

  Очищает кеш потока. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_SLAVE` (int)

  На ведомом сервере репликации (slave): сбрасывает информацию ведущего сервера (master) и перезапускает ведомый сервер. Аналогично выполнению SQL-инструкции `RESET SLAVE`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_MASTER` (int)

  На ведущем сервере репликации (master): удаляет бинарные файлы логов в бинарном индексе логов, и обрезает файл индекса. Аналогично выполнению SQL-инструкции `RESET MASTER`. Константа объявлена устаревшей с PHP 8.4.0.

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  Закрывает и снова открывает файлы лога резервного копирования. Константа объявлена устаревшей с PHP 8.4.0.
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  Добавляет предложение «AND CHAIN» к действиям функций mysqli_commit() или mysqli_rollback().

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  Добавляет предложение «AND NO CHAIN» к действиям функций mysqli_commit() или mysqli_rollback().

`MYSQLI_TRANS_COR_RELEASE` (int)

  Добавляет предложение «RELEASE» к действиям функций mysqli_commit() или mysqli_rollback().

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  Добавляет предложение «NO RELEASE» к действиям функций mysqli_commit() или mysqli_rollback().

`MYSQLI_TRANS_START_READ_ONLY` (int)

  Начинает транзакцию как «START TRANSACTION READ ONLY» с mysqli_begin_transaction().

`MYSQLI_TRANS_START_READ_WRITE` (int)

  Начинает транзакцию с инструкции «START TRANSACTION READ WRITE» при запуске функции mysqli_begin_transaction().

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  Начинает транзакцию с инструкции "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  Требуется MySQL 5.6.5 и выше.

`MYSQLI_IS_MARIADB` (bool)

  Определяет, собрали ли модуль mysqli с клиентской библиотекой MariaDB. Константа доступна с PHP 8.1.2.

`MYSQLI_ASYNC` (int)
  Запрос выполняется асинхронно, и набор результатов не возвращается сразу. Константа доступна только с драйвером `mysqlnd`.
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  При обновлении поле получит текущее значение времени.

# Основная информация о функциях модуля MySQLi

Основная информация о методах mysqli
Класс mysqli
ООП-интерфейс | Процедурный интерфейс | Синоним (не используйте!) | Описание
--- | --- | --- | ---
Свойства
$mysqli::affected_rows | mysqli_affected_rows() | - | Получает число строк, затронутых предыдущей операцией MySQL
$mysqli::client_info | mysqli_get_client_info() | - | Возвращает информацию о версии клиента MySQL в виде строки (string)
$mysqli::client_version | mysqli_get_client_version() | - | Возвращает информацию о версии клиента MySQL в виде числа (integer)
$mysqli::connect_errno | mysqli_connect_errno() | - | Возвращает код ошибки последнего соединения
$mysqli::connect_error | mysqli_connect_error() | - | Возвращает строковое описание ошибки последнего подключения
$mysqli::errno | mysqli_errno() | - | Возвращает код ошибки последнего вызова функции
$mysqli::error | mysqli_error() | - | Возвращает строковое описание последней ошибки
$mysqli::field_count | mysqli_field_count() | - | Возвращает число столбцов для последнего запроса
$mysqli::host_info | mysqli_get_host_info() | - | Возвращает строку, содержащую тип используемого соединения
$mysqli::protocol_version | mysqli_get_proto_info() | - | Возвращает версию используемого протокола MySQL
$mysqli::server_info | mysqli_get_server_info() | - | Возвращает версию сервера MySQL
$mysqli::server_version | mysqli_get_server_version() | - | Возвращает версию сервера MySQL в виде числа (integer)
$mysqli::info | mysqli_info() | - | Отображает информацию о наиболее часто исполняемом запросе
$mysqli::insert_id | mysqli_insert_id() | - | Возвращает автоматически сгенерированный id, использованный в последнем запросе
$mysqli::sqlstate | mysqli_sqlstate() | - | Возвращает ошибку SQLSTATE предыдущей операции MySQL
$mysqli::warning_count | mysqli_warning_count() | - | Возвращает число предупреждений последнего запроса для заданной ссылки
Методы
mysqli::autocommit() | mysqli_autocommit() | - | Выключает или выключает автоматическое подтверждение изменений базы данных
mysqli::change_user() | mysqli_change_user() | - | Изменяет пользователя (user) для указанного соединения с базой данных
mysqli::character_set_name() | mysqli_character_set_name() | Н/Д | Возвращает кодировку, установленную по умолчанию для соединения с базой данных
mysqli::close() | mysqli_close() | - | Закрывает открытое соединение с базой данных
mysqli::commit() | mysqli_commit() | - | Подтверждает текущую транзакцию
mysqli::__construct() | mysqli_connect() | - | Открыть новое соединение с MySQL сервером [Примечание: статический метод (т.е. метод класса)]
mysqli::debug() | mysqli_debug() | - | Выполняет операции отладки
mysqli::dump_debug_info() | mysqli_dump_debug_info() | - | Сбор отладочной информации в лог
mysqli::get_charset() | mysqli_get_charset() | - | Возвращает объект, описывающий кодировку
mysqli::get_connection_stats() | mysqli_get_connection_stats() | - | Возвращает статистку соединения клиента. Доступно только с модулем mysqlnd.
mysqli::get_client_info() | mysqli_get_client_info() | - | Возвращает версию клиента MySQL в виде строки
Н/Д | mysqli_get_client_stats() | - | Возвращает статистку клиента для каждого процесса. Доступно только с модулем mysqlnd.
mysqli::get_server_info() | mysqli_get_server_info() | - | Возвращает строку, содержащую версию сервера MySQL, к которому произведено подключение
mysqli::get_warnings() | mysqli_get_warnings() | - | Не документировано
mysqli::init() | mysqli_init() | - | Инициализирует MySQLi и возвращает ресурс для использования с mysqli_real_connect.
mysqli::kill() | mysqli_kill() | - | Создаёт запрос серверу на уничтожение MySQL-потока
mysqli::more_results() | mysqli_more_results() | - | Проверяет на наличие дополнительных результатов запроса из мульти-запроса
mysqli::multi_query() | mysqli_multi_query() | - | Выполняет запрос к базе данных
mysqli::next_result() | mysqli_next_result() | - | Выполняет подготовку следующего результата из multi_query
mysqli::options() | mysqli_options() | mysqli_set_opt() | Устанавливает опции
mysqli::ping() | mysqli_ping() | - | Производит пинг соединения с сервером, либо переподключение, если соединение было сброшено
mysqli::prepare() | mysqli_prepare() | - | Выполняет подготовку SQL-запроса (Prepared statement)
mysqli::query() | mysqli_query() | - | Выполняет запрос к базе данных
mysqli::real_connect() | mysqli_real_connect() | - | Открывает соединение с сервером MySQL
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Экранирует специальные символы в строке, используемой в SQL-запросе, принимая во внимание кодировку соединения
mysqli::real_query() | mysqli_real_query() | - | Выполняет SQL-запрос
mysqli::refresh() | mysqli_refresh() | - | Очищает таблицы или кеш, или сбрасывает информацию сервера репликации
mysqli::rollback() | mysqli_rollback() | - | Откатывает текущую транзакцию
mysqli::select_db() | mysqli_select_db() | - | Выбирает базу данных по умолчанию для выполнения запросов
mysqli::set_charset() | mysqli_set_charset() | - | Устанавливает кодировку клиента по умолчанию
mysqli::ssl_set() | mysqli_ssl_set() | - | Используется для установления защищённых соединений, используя SSL
mysqli::stat() | mysqli_stat() | - | Получает текущее состояние системы
mysqli::stmt_init() | mysqli_stmt_init() | - | Инициализирует и возвращает объект для использования с mysqli_stmt_prepare
mysqli::store_result() | mysqli_store_result() | - | Локально сохраняет результат, полученный последним запросом
mysqli::thread_id() | mysqli_thread_id() | - | Возвращает идентификатор потока для текущего соединения
mysqli::thread_safe() | mysqli_thread_safe() | - | Возвращает состояние безопасности потока
mysqli::use_result() | mysqli_use_result() | - | Инициирует получение результата

Основная информация о методах mysqli_stmt
MySQL_STMT
ООП-интерфейс | Процедурный интерфейс | Синоним (не используйте!) | Описание
--- | --- | --- | ---
Свойства
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | - | Возвращает число строк, изменённых, удалённых или вставленных при выполнении последней инструкции
$mysqli_stmt::errno | mysqli_stmt_errno() | - | Возвращает код ошибки последнего выполненного запроса
$mysqli_stmt::error | mysqli_stmt_error() | - | Возвращает строковое описание ошибки последнего запроса
$mysqli_stmt::field_count | mysqli_stmt_field_count() | - | Возвращает число полей в заданном запросе - не документировано
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | - | Получает ID, сгенерированное последней операцией INSERT
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | - | Возвращает число строк в результате выполнения запроса
$mysqli_stmt::param_count | mysqli_stmt_param_count() | Н/Д | Возвращает число параметров для заданного запроса
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | - | Возвращает ошибку SQLSTATE для последнего выполненного запроса
Методы
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | - | Используется для получения текущего значения атрибута запроса
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | - | Используется для модификации поведения подготовленного запроса
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | Н/Д | Передаётся переменные в подготовленный запрос как параметры
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | Н/Д | Передаёт переменные в подготовленный запрос для сохранения результатов
mysqli_stmt::close() | mysqli_stmt_close() | - | Закрывает подготовленный запрос
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | - | Производит поиск произвольной строки в результатах запроса
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Исполняет подготовленный запрос
mysqli_stmt::fetch() | mysqli_stmt_fetch() | Н/Д | Выборка результатов подготовленного запроса в связанные переменные
mysqli_stmt::free_result() | mysqli_stmt_free_result() | - | Освобождает память, хранящую результаты заданного дескриптором запроса
mysqli_stmt::get_result() | mysqli_stmt_get_result() | - | Получает результаты подготовленного запроса. Доступно только с модулем mysqlnd.
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | - | Не документировано
mysqli_stmt::more_results() | mysqli_stmt_more_results() | - | Проверяет наличие дополнительных результатов запроса в случае множественного запроса
mysqli_stmt::next_result() | mysqli_stmt_next_result() | - | Читает следующий результат из множественного запроса
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | - | Смотрите также $mysqli_stmt::num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | - | Выполняет подготовку SQL запроса для запуска
mysqli_stmt::reset() | mysqli_stmt_reset() | - | Сбрасывает подготовленный запрос
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | Н/Д | Возвращает метаданные результатов подготовленного запроса
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | Н/Д | Передача данных блоками
mysqli_stmt::store_result() | mysqli_stmt_store_result() | - | Передаёт результат из подготовленного запроса

Основная информация о методах mysqli_result
mysqli_result
ООП-интерфейс | Процедурный интерфейс | Синоним (не используйте!) | Описание
--- | --- | --- | ---
Свойства
$mysqli_result::current_field | mysqli_field_tell() | - | Получить смещение указателя на результат для текущего поля
$mysqli_result::field_count | mysqli_num_fields() | - | Получить количество полей в результате
$mysqli_result::lengths | mysqli_fetch_lengths() | - | Возвращает длины столбцов текущей строки в наборе результатов
$mysqli_result::num_rows | mysqli_num_rows() | - | Получает число строк в результате
Методы
mysqli_result::data_seek() | mysqli_data_seek() | - | Устанавливает указатель результата на произвольную строку в результате
mysqli_result::fetch_all() | mysqli_fetch_all() | - | Получает все результирующие строки и возвращает массив со строками в виде ассоциативного массива и/или нумерованного массива. Доступно только с модулем mysqlnd.
mysqli_result::fetch_array() | mysqli_fetch_array() | - | Получает результирующую строку в виде ассоциативного массива и/или нумерованного массива
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | - | Получает результирующую строку в виде ассоциативного массива
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Получает один столбец из следующей строки набора результатов
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | - | Получает метаданные для одного поля
mysqli_result::fetch_field() | mysqli_fetch_field() | - | Возвращает из результата следующее поле
mysqli_result::fetch_fields() | mysqli_fetch_fields() | - | Возвращает массив объектов из полей результата
mysqli_result::fetch_object() | mysqli_fetch_object() | - | Возвращает текущую строку результата в виде объекта
mysqli_result::fetch_row() | mysqli_fetch_row() | - | Получает строку результата как нумерованный массив
mysqli_result::field_seek() | mysqli_field_seek() | - | Устанавливает смещение указателя результата на определённое поле
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | - | Освобождает память, связанную с результатом

Основная информация о методах mysqli_driver
MySQL_Driver
ООП-интерфейс | Процедурный интерфейс | Синоним (не используйте!) | Описание
--- | --- | --- | ---
Свойства
$mysqli_driver::mysqli_report | mysqli_report() | Не документировано | Устанавливает режим отчёта об ошибках mysqli
Методы
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | - | Не документировано
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | - | Не документировано

> Замечание:

> Псевдонимы функций предназначены только для обеспечения обратной совместимости. Не используйте их в новых проектах.

# Класс mysqli

(PHP 5, PHP 7, PHP 8)

## Введение

Представляет связь между PHP и базой данных MySQL.

## Обзор класса

class mysqli {
/* Свойства */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* Методы */
public function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = MYSQLI_STORE_RESULT): mysqli_result|bool
public function real_connect(
?string `$hostname` = null,
?string `$username` = null,
#[\SensitiveParameter]?string `$password` = null,
?string `$database` = null,
?int `$port` = null,
?string `$socket` = null,
int `$flags` = 0
): bool
public function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = null): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — Получает число строк, затронутых предыдущей операцией MySQL

### Описание

Объектно-ориентированный стиль

int|string $mysqli->affected_rows;

Процедурный стиль

function mysqli_affected_rows(mysqli `$mysql`): int|string

Возвращает число строк, затронутых последним запросом `INSERT`, `UPDATE`, `REPLACE` или `DELETE`. Работает аналогично mysqli_num_rows() для выражений `SELECT`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Целое число, большее нуля, означает количество затронутых или полученных строк. Ноль означает, что записи для оператора `UPDATE` не обновлялись, ни одна строка не соответствовала выражению `WHERE` в запросе или что ни один запрос ещё не был выполнен. `-1` означает, что во время выполнения запроса произошла ошибка или что mysqli_affected_rows() была вызвана для небуферизованного запроса `SELECT`.

> Замечание:

> Если число затронутых строк больше чем максимальное значение целого числа (`PHP_INT_MAX`), то число затронутых строк будет возвращено в виде строки.

### Примеры

Пример #1 Пример использования $mysqli->affected_rows

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Добавление строк */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Затронутые строки (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* Обновление строк */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Затронутые строки (UPDATE): %d\n", $mysqli->affected_rows);

    /* Удаление строк */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Затронутые строки (DELETE): %d\n", $mysqli->affected_rows);

    /* Выборка всех строк */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Затронутые строки (SELECT): %d\n", $mysqli->affected_rows);

    /* Удаление таблицы Language */
    $mysqli->query("DROP TABLE Language");
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Добавление строк */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Затронутые строки (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* Обновление строк */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Затронутые строки (UPDATE): %d\n", mysqli_affected_rows($link));

    /* Удаление строк */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Затронутые строки (DELETE): %d\n", mysqli_affected_rows($link));

    /* Выборка всех строк */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Затронутые строки (SELECT): %d\n", mysqli_affected_rows($link));

    /* Удаление таблицы Language */
    mysqli_query($link, "DROP TABLE Language");
    ?>

Результат выполнения приведённых примеров:

    Затронутые строки (INSERT): 984
    Затронутые строки (UPDATE): 168
    Затронутые строки (DELETE): 815
    Затронутые строки (SELECT): 169

### Смотрите также

- mysqli_num_rows() - Получает количество строк в наборе результатов
- mysqli_info() - Извлекает информацию о последнем выполненном запросе

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — Включает или отключает автоматическую фиксацию изменений базы данных

### Описание

Объектно-ориентированный стиль

public function mysqli::autocommit(bool `$enable`): bool

Процедурный стиль

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

Включает или отключает режим автоматической фиксации изменений для соединения с базой данных.

Чтобы определить текущее состояние режима, используйте команду SQL `SELECT @@autocommit`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`enable`

  Включает или отключает режим автоматической фиксации изменений.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::autocommit()

Объектно-ориентированный стиль

    <?php

    /* Указать mysqli выбрасывать исключение в случае возникновения ошибки */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Движок таблиц должен поддерживать транзакции */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Отключить автоматическую фиксацию */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("Автоматическая фиксация: %s\n", $row[0]);

    try {
        /* Подготовить выражение для добавления */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Добавление каких-то значений */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Зафиксируйте данные в базе данных. Это не устанавливает autocommit=true */
        $mysqli->commit();
        print "Зафиксировано 2 строки в базе данных\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("Автоматическая фиксация: %s\n", $row[0]);

        /* Попробуйте вставить больше значений */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Установка autocommit=true вызовет фиксацию */
        $mysqli->autocommit(true);

        print "Зафиксировано 2 строки в базе данных\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Процедурный стиль

    <?php

    /* Указать mysqli выбрасывать исключение в случае возникновения ошибки */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Движок таблиц должен поддерживать транзакции */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Отключить автоматическую фиксацию */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("Автоматическая фиксация: %s\n", $row[0]);

    try {
        /* Подготовить выражение для добавления */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Добавление каких-то значений */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Зафиксируйте данные в базе данных. Это не устанавливает autocommit=true */
        mysqli_commit($mysqli);
        print "Зафиксировано 2 строки в базе данных\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("Автоматическая фиксация: %s\n", $row[0]);

        /* Попробуйте вставить больше значений */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Установка autocommit=true вызовет фиксацию */
        mysqli_autocommit($mysqli, true);

        print "Зафиксировано 2 строки в базе данных\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

Результат выполнения приведённых примеров:

    Автоматическая фиксация: 0
    Зафиксировано 2 строки в базе данных
    Автоматическая фиксация: 0
    Зафиксировано 2 строки в базе данных
    Автоматическая фиксация: 0
    Зафиксировано 2 строки в базе данных
    Автоматическая фиксация: 0
    Зафиксировано 2 строки в базе данных

### Примечания

> Замечание:

> Функция не работает с нетранзакционными типами таблиц (такими как MyISAM или ISAM).

### Смотрите также

- mysqli_begin_transaction() - Стартует транзакцию
- mysqli_commit() - Фиксирует текущую транзакцию
- mysqli_rollback() - Откат текущей транзакции

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Стартует транзакцию

### Описание

Объектно-ориентированный стиль

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

Процедурный стиль:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Стартует транзакцию. Требуется InnoDB (разрешён по умолчанию). Для дополнительной информации, как работают транзакции в MySQL, читайте » http://dev.mysql.com/doc/mysql/en/commit.html.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`flags`

  Корректные флаги:

  - `MYSQLI_TRANS_START_READ_ONLY`: Стартовать транзакцию как "START TRANSACTION READ ONLY". Требуется MySQL 5.6 или выше.

  - `MYSQLI_TRANS_START_READ_WRITE`: Стартовать транзакцию как "START TRANSACTION READ WRITE". Требуется MySQL 5.6 или выше.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`: Стартовать транзакцию как "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Точка сохранения транзакции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `name` теперь допускает значение null.

### Примеры

Пример #1 Пример использования mysqli::begin_transaction()

Объектно-ориентированный стиль

    <?php

    /* Указать mysqli выбрасывать исключение в случае возникновения ошибки */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Движок таблиц должен поддерживать транзакции */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Начало транзакции */
    $mysqli->begin_transaction();

    try {
        /* Добавление каких-то значений */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Попытка добавить недопустимые значения */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);
        $stmt->execute();

        /* Если код достигает этой точки без ошибок, фиксируем данные в базе данных. */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Процедурный стиль

    <?php

    /* Указать mysqli выбрасывать исключение в случае возникновения ошибки */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Движок таблиц должен поддерживать транзакции */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Начало транзакции */
    mysqli_begin_transaction($mysqli);

    try {
        /* Добавление каких-то значений */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Попытка добавить недопустимые значения */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
        mysqli_stmt_execute($stmt);

        /* Если код достигает этой точки без ошибок, фиксируем данные в базе данных. */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### Примечания

> Замечание:

> Функция не работает с нетранзакционными типами таблиц (такими как MyISAM или ISAM).

### Смотрите также

- mysqli_autocommit() - Включает или отключает автоматическую фиксацию изменений базы данных
- mysqli_commit() - Фиксирует текущую транзакцию
- mysqli_rollback() - Откат текущей транзакции

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Изменяет пользователя соединения с базой данных

### Описание

Объектно-ориентированный стиль

public function mysqli::change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool

Процедурный стиль

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter]string `$password`,
?string `$database`
): bool

Метод совершает попытку подключения к базе данных с заданными учётными данными.

В отличие от метода mysqli::connect() этот метод не отключит текущее соединение, если не получится открыть новое подключение.

Для успешной смены пользователя необходимы корректные параметры `username` и `password`, а также наличие достаточных прав для работы с базой. Если смена пользователя закончится ошибкой, сохранится текущая авторизация пользователя, до вызова функции.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`username`

  Имя пользователя для доступа к MySQL.

`password`

  Пароль для доступа к MySQL.

`database`

  Название базы данных. Соединение с сервером откроется без базы данных по умолчанию, если передали значение `null` или пустую строку.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример сброса сеанса подключения

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();

    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

    ?>

Результат выполнения приведённых примеров:

    База данных по умолчанию: world
    Значение переменной — NULL

Пример #2 Пример соединения без выбора базы данных по умолчанию при передаче в параметр `database` значения `null`

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->change_user("my_user", "my_password", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database: %s\n", $row[0]);

Результат выполнения приведённых примеров:

    Default database:

### Примечания

> Замечание:

> В результате вызова функции текущее соединение с базой данных начинает вести себя так, как будто создали новое соединение. Взов функции откатыает активные транзакции, закрывает временные таблицы и разблокирует таблицы, которые заблокировали прежде независимо от результата операции.

### Смотрите также

- mysqli_connect() - Псевдоним mysqli::__construct
- mysqli_select_db() - Устанавливает базу данных для выполняемых запросов

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — Возвращает текущую кодировку, установленную для соединения с БД

### Описание

Объектно-ориентированный стиль

public function mysqli::character_set_name(): string

Процедурный стиль

function mysqli_character_set_name(mysqli `$mysql`): string

Возвращает текущую кодировку, установленную для соединения с БД.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Текущая кодировка, установленная для соединения

### Примеры

Пример #1 Пример использования mysqli::character_set_name()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Установка кодировки по умолчанию */
    $mysqli->set_charset('utf8mb4');

    /* Вывод текущей кодировки */
    $charset = $mysqli->character_set_name();
    printf("Текущая кодировка - %s\n", $charset);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Установка кодировки по умолчанию */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Вывод текущей кодировки */
    $charset = mysqli_character_set_name($mysqli);
    printf("Текущая кодировка - %s\n", $charset);

Результат выполнения приведённых примеров:

    Текущая кодировка - utf8mb4

### Смотрите также

- mysqli_set_charset() - Задаёт набор символов
- mysqli_real_escape_string() - Экранирует специальные символы в строке для использования в SQL-выражении, используя текущий набор символов соединения

# mysqli::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — Закрывает ранее открытое соединение с базой данных

### Описание

Объектно-ориентированный стиль

public function mysqli::close(): true

Процедурный стиль

function mysqli_close(mysqli `$mysql`): true

Закрывает ранее открытое соединение с базой данных.

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

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает значение `true`. Ранее она возвращала значение `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования mysqli::close()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Закройте соединение, как только оно становится ненужным */
    $mysqli->close();

    foreach ($result as $row) {
        /* Обработка данных, полученных из базы данных */
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Закройте соединение, как только оно становится ненужным */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Обработка данных, полученных из базы данных */
    }

### Примечания

> Замечание:

> mysqli_close() не закрывает постоянные соединения. Для получения подробностей смотрите руководство по persistent connections.

### Смотрите также

- mysqli::__construct() - Устанавливает новое соединение с MySQL-сервером
- mysqli_init() - Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()
- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером
- mysqli_free_result() - Освобождает память, занятую результатами запроса

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — Фиксирует текущую транзакцию

### Описание

Объектно-ориентированный стиль

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

Процедурный стиль

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Фиксирует транзакцию для установленного соединения с базой данных.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`flags`

  Битовая маска констант `MYSQLI_TRANS_COR_*`.

`name`

  Если передан, то выполняется `COMMIT/*name*/`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `name` теперь допускает значение null.

### Примеры

Смотрите пример использования в разделе mysqli::begin_transaction().

### Примечания

> Замечание:

> Функция не работает с нетранзакционными типами таблиц (такими как MyISAM или ISAM).

### Смотрите также

- mysqli_autocommit() - Включает или отключает автоматическую фиксацию изменений базы данных
- mysqli_begin_transaction() - Стартует транзакцию
- mysqli_rollback() - Откат текущей транзакции
- mysqli_savepoint() - Установите именованную точку сохранения транзакции

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Возвращает код ошибки последней попытки соединения

### Описание

Объектно-ориентированный стиль

int $mysqli->connect_errno;

Процедурный стиль

function mysqli_connect_errno(): int

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция и свойство возвращают код ошибки последнего подключения. Код 0 означает, что соединение с БД установилось без ошибок.

Свойство возвращает код ошибки последней попытки установить соединение, в каком бы объекте соединения ни считывали свойство.

### Примеры

Пример #1 Пример получения кода ошибки из свойства $mysqli->connect_errno

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* Оператор @ подавляет предупреждения */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_errno) {
        /* Пример логирования ошибки */
        error_log('Ошибка соединения: ' . $mysqli->connect_errno);
    }

    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* Оператор @ подавляет предупреждения */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Пример логирования ошибки */
        error_log('Ошибка соединения: ' . mysqli_connect_errno());
    }

    ?>

### Смотрите также

- mysqli_connect() - Псевдоним mysqli::__construct
- mysqli_connect_error() - Возвращает описание последней ошибки подключения
- mysqli_errno() - Возвращает код ошибки последнего вызова функции
- mysqli_error() - Возвращает строку с описанием последней ошибки
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Возвращает описание последней ошибки подключения

### Описание

Объектно-ориентированный стиль

?string $mysqli->connect_error;

Процедурный стиль

function mysqli_connect_error(): ?string

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция и свойство возвращают сообщение об ошибке или значение `null`, если соединение с БД установилось без ошибок.

Свойство возвращает описание ошибки последней попытки установить соединение, в каком бы объекте соединения ни считывали свойство.

### Примеры

Пример #1 Пример получения описания ошибки из свойства $mysqli->connect_error

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* Оператор @ подавляет предупреждения */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if ($mysqli->connect_error) {
        /* Пример логирования ошибки */
        error_log('Ошибка при подключении: ' . $mysqli->connect_error);
    }

    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);

    /* Оператор @ подавляет предупреждения */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');

    if (!$link) {
        /* Пример логирования ошибки */
        error_log('Ошибка при подключении: ' . mysqli_connect_error());
    }

    ?>

### Смотрите также

- mysqli_connect() - Псевдоним mysqli::__construct
- mysqli_connect_errno() - Возвращает код ошибки последней попытки соединения
- mysqli_errno() - Возвращает код ошибки последнего вызова функции
- mysqli_error() - Возвращает строку с описанием последней ошибки
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Устанавливает новое соединение с MySQL-сервером

### Описание

Объектно-ориентированный стиль

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

Процедурный стиль

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Метод устанавливает соединение с работающим MySQL-сервером.

### Список параметров

`hostname`

  Может быть либо именем хоста, либо IP-адресом. При передаче `null`, значение извлекается из mysqli.default_host. По возможности вместо протокола TCP/IP будут использоваться каналы. Протокол TCP/IP используется, если указаны и имя хоста и номер порта, например, `localhost:3308`.

  Если перед именем хоста задать строку `p:`, то будет открыто постоянное соединение. Если соединение открыто из пула подключений, будет автоматически вызвана функция mysqli_change_user().

`username`

  Имя пользователя MySQL или `null` для принятия имени пользователя на основе ini-опции mysqli.default_user.

`password`

  Пароль MySQL или `null` для принятия пароля на основе ini-опции mysqli.default_pw.

`database`

  База данных по умолчанию, которая будет использоваться при выполнении запросов или `null`.

`port`

  Номер порта для попытки подключения к серверу MySQL или `null` для принятия порта на основе ini-опции mysqli.default_port.

`socket`

  Сокет или именованный пайп, который необходимо использовать или `null` для принятия сокета на основе ini-опции mysqli.default_socket.

  > Замечание:

  > Передача параметра `socket` не будет явно задавать тип соединения при подключении к серверу MySQL. То, как будет устанавливаться соединение с MySQL-сервером, определяется параметром `hostname`.

### Возвращаемые значения

Метод mysqli::__construct() всегда возвращает объект, представляющий соединение с сервером MySQL, независимо от того, было ли оно успешным или нет.

Функция mysqli_connect() возвращает объект, который представляет соединение с сервером MySQL или `false`, если возникла ошибка.

Метод mysqli::connect() возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка. До PHP 8.1.0 в случае успешного выполнения возвращалось значение `null`.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Метод mysqli::connect() теперь возвращает значение `true` вместо `null` в случае успешного выполнения.
7.4.0 | Все параметры теперь принимают значение `null`

### Примеры

Пример #1 Пример использования метода mysqli::__construct()

Объектно-ориентированный стиль

    <?php

    /* Требуется включить отчёт об ошибках для модуля mysqli, перед попыткой установить соединение */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');

    /* Установите желаемую кодировку после установления соединения */
    $mysqli->set_charset('utf8mb4');

    printf("Успешно... %s\n", $mysqli->host_info);

    ?>

Процедурный стиль

    <?php

    /* Требуется включить отчёт об ошибках для модуля mysqli, прежде чем пытаться установить соединение */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');

    /* Установите желаемую кодировку после установления соединения */
    mysqli_set_charset($mysqli, 'utf8mb4');

    printf("Успешно... %s\n", mysqli_get_host_info($mysqli));

    ?>

Вывод приведённых примеров будет похож на:

    Успешно... localhost via TCP/IP

Пример #2 Расширение класса mysqli

    <?php

    class FooMysqli extends mysqli
    {
        public function __construct($host, $user, $pass, $db, $port, $socket, $charset)
        {
            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
            parent::__construct($host, $user, $pass, $db, $port, $socket);
            $this->set_charset($charset);
        }
    }

    $db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

    ?>

Пример #3 Ручная обработка ошибок

Если отчёты об ошибках отключены, разработчик несёт ответственность за проверку и обработку ошибок

Объектно-ориентированный стиль

    <?php

    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
    if ($mysqli->connect_errno) {
        throw new RuntimeException('ошибка соединения mysqli: ' . $mysqli->connect_error);
    }

    /* Установите желаемую кодировку после установления соединения */
    $mysqli->set_charset('utf8mb4');
    if ($mysqli->errno) {
        throw new RuntimeException('ошибка mysqli: ' . $mysqli->error);
    }

    ?>

Процедурный стиль

    <?php

    error_reporting(0);
    mysqli_report(MYSQLI_REPORT_OFF);
    $mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
    if (mysqli_connect_errno()) {
        throw new RuntimeException('ошибка соединения mysqli: ' . mysqli_connect_error());
    }

    /* Установите желаемую кодировку после установления соединения */
    mysqli_set_charset($mysqli, 'utf8mb4');
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('ошибка mysqli: ' . mysqli_error($mysqli));
    }

    ?>

### Примечания

> Замечание: MySQLnd всегда подразумевает кодировку, которую использует по умолчанию сервер. Эта кодировка передаётся во время установки соединения/авторизации, которые использует mysqlnd.Libmysqlclient по умолчанию использует кодировку, установленную в файле my.cnf или явным вызовом функции mysqli_options() до вызова функции mysqli_real_connect(), но после вызова функции mysqli_connect().

> Замечание:

> Если используется Объектно-ориентированный стиль: Если соединение установить не удалось, метод всё равно вернёт объект. Проверить успешность создания подключения можно либо функцией mysqli_connect_error() или с помощью свойства mysqli->connect_error, как показано в примерах.

> Замечание:

> Если требуется задать дополнительные параметры подключения, вроде времени ожидания и т. п., то вместо этого метода необходимо вызывать функцию mysqli_real_connect().

> Замечание:

> Вызов конструктора без параметров идентичен вызову функции mysqli_init().

> Замечание:

> Ошибка «Can't create TCP/IP socket (10106)» обычно означает, что директива конфигурации variables_order не содержит символ `E`. В Windows системах, если окружение не скопировано, переменная среды `SYSTEMROOT` будет недоступна, и у PHP возникнут проблемы с загрузкой Winsock.

### Смотрите также

- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером
- mysqli_options() - Установка настроек
- mysqli_connect_errno() - Возвращает код ошибки последней попытки соединения
- mysqli_connect_error() - Возвращает описание последней ошибки подключения
- mysqli_close() - Закрывает ранее открытое соединение с базой данных

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Выполняет процедуры отладки

### Описание

Объектно-ориентированный стиль

public function mysqli::debug(string `$options`): true

Процедурный стиль

function mysqli_debug(string `$options`): true

Выполняет процедуры отладки, используя библиотеку Fred Fish.

### Список параметров

`options`

  Строка, содержащая выполняемую процедуру отладки

  Строка управления отладкой — это последовательность полей, разделённых двоеточиями, как показано ниже: ``

      <field_1>:<field_2>:<field_N>

  Каждое поле состоит из обязательного символа флага, за которым следует необязательный символ `,` и список модификаторов, разделённый запятыми: `flag[,modifier,modifier,...,modifier]`

  Допустимые символы флагов
  Символ `options` | Описание
  --- | ---
  O | `MYSQLND_DEBUG_FLUSH`
  A/a | `MYSQLND_DEBUG_APPEND`
  F | `MYSQLND_DEBUG_DUMP_FILE`
  i | `MYSQLND_DEBUG_DUMP_PID`
  L | `MYSQLND_DEBUG_DUMP_LINE`
  m | `MYSQLND_DEBUG_TRACE_MEMORY_CALLS`
  n | `MYSQLND_DEBUG_DUMP_LEVEL`
  o | вывод в файл
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает значение `true`. Ранее она возвращала значение `false` в случае возникновения ошибки.

### Примеры

Пример #1 Генерация файла трассировки

    <?php

    /* Создать файл трассировки в '/tmp/client.trace' на локальной машине (клиенте): */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### Примечания

> Замечание:

> Чтобы функция mysqli_debug() была доступна, необходимо скомпилировать клиентскую библиотеку MySQL с поддержкой отладки.

### Смотрите также

- mysqli_dump_debug_info() - Журналирование отладочной информации
- mysqli_report() - Псевдоним mysqli_driver->report_mode

# mysqli::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — Журналирование отладочной информации

### Описание

Объектно-ориентированный стиль

public function mysqli::dump_debug_info(): bool

Процедурный стиль

function mysqli_dump_debug_info(mysqli `$mysql`): bool

Функция разработана для запуска от имени пользователя с привилегиями SUPER и используется для сборки отладочной информации в журнал сервера MySQL, к которому произведено подключение.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mysqli_debug() - Выполняет процедуры отладки

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — Возвращает код ошибки последнего вызова функции

### Описание

Объектно-ориентированный стиль

int $mysqli->errno;

Процедурный стиль

function mysqli_errno(mysqli `$mysql`): int

Возвращает код ошибки последнего вызова функции MySQLi, завершившейся успешным выполнением или ошибкой.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Код ошибки последнего вызова функции в случае провала. При отсутствие ошибок выводит 0.

### Примеры

Пример #1 Пример использования $mysqli->errno

Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if ($mysqli->connect_errno) {
        printf("Соединение не удалось: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Код ошибки: %d\n", $mysqli->errno);
    }

    /* Закрыть соединение */
    $mysqli->close();
    ?>

Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Соединение не удалось: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Код ошибки: %d\n", mysqli_errno($link));
    }

    /* Закрыть соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Код ошибки: 1193

### Смотрите также

- mysqli_connect_errno() - Возвращает код ошибки последней попытки соединения
- mysqli_connect_error() - Возвращает описание последней ошибки подключения
- mysqli_error() - Возвращает строку с описанием последней ошибки
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

# mysqli::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — Возвращает строку с описанием последней ошибки

### Описание

Объектно-ориентированный стиль

string $mysqli->error;

Процедурный стиль

function mysqli_error(mysqli `$mysql`): string

Возвращает сообщение об ошибке последнего вызова функции MySQLi, который может успешно выполниться или провалиться.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Строка с описанием ошибки. Пустая строка, если ошибки нет.

### Примеры

Пример #1 Пример с $mysqli->error

Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if ($mysqli->connect_errno) {
        printf("Соединение не удалось: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Сообщение ошибки: %s\n", $mysqli->error);
    }

    /* Закрыть соединение */
    $mysqli->close();
    ?>

Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Соединение не удалось: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Сообщение ошибки: %s\n", mysqli_error($link));
    }

    /* Закрыть соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Сообщение ошибки: Unknown system variable 'a'

### Смотрите также

- mysqli_connect_errno() - Возвращает код ошибки последней попытки соединения
- mysqli_connect_error() - Возвращает описание последней ошибки подключения
- mysqli_errno() - Возвращает код ошибки последнего вызова функции
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Возвращает список ошибок выполнения последней запущенной команды

### Описание

Объектно-ориентированный стиль

array $mysqli->error_list;

Процедурный стиль

function mysqli_error_list(mysqli `$mysql`): array

Функция возвращает массив ошибок последнего вызова функции модуля MySQLi, даже если функция завершилась без ошибок.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает список ошибок в виде ассоциативного массива (array). Каждая элемент массива представляет отдельную ошибку и содержит номер ошибки, описание ошибки и код состояния sqlstate.

### Примеры

Пример #1 Пример получения списка ошибок функцией $mysqli->error_list

Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "nobody", "");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("При подключении возникла ошибка: %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* Закрываем соединение */
    $mysqli->close();

Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("При подключении возникла ошибка: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* Закрываем соединение */
    mysqli_close($link);

Результат выполнения приведённых примеров:

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### Смотрите также

- mysqli_connect_errno() - Возвращает код ошибки последней попытки соединения
- mysqli_connect_error() - Возвращает описание последней ошибки подключения
- mysqli_error() - Возвращает строку с описанием последней ошибки
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Подготавливает, связывает параметры и выполняет SQL-запрос

### Описание

Объектно-ориентированный стиль

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

Процедурный стиль

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Подготавливает SQL-запрос, связывает параметры и выполняет его. Метод mysqli::execute_query() является сокращением для mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute() и mysqli_stmt::get_result().

У шаблона запроса может быть ноль или более маркеров параметров со знаком вопроса (`?`), которые также называются заполнителями. Значения параметров должны быть представлены в виде массива (array), переданного в параметр `params`.

Подготовленный запрос создаётся под капотом, но он никогда не выводится за пределы функции. Невозможно получить доступ к свойствам запроса, как это можно сделать с объектом mysqli_stmt. Из-за этого ограничения информация о состоянии копируется в объект mysqli и доступна с помощью его методов, например, mysqli_affected_rows() или mysqli_error().

> Замечание:

> В случае, когда функции mysqli_execute_query() передаётся запрос, длина которого превышает `max_allowed_packet` сервера, возвращаемые коды ошибок различаются в зависимости от операционной системы. Поведение следующее:

> - В Linux возвращается код ошибки 1153. Сообщение об ошибке означает, что получен пакет размером более `max_allowed_packet` (got a packet bigger than `max_allowed_packet` bytes).

> - В Windows возвращается код ошибки 2006. Сообщение об ошибке означает, что сервер недоступен (server has gone away).

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`query`

  Запрос в виде строки. Он должен состоять из одного SQL-запроса.

  SQL-запрос может содержать ноль или более маркеров параметров, представленных символами вопросительного знака (`?`) в соответствующих позициях.

  > Замечание:

  > Эти метки можно встраивать только в определённые места в выражении. Например, они разрешены в списке `VALUES()` выражения `INSERT` (чтобы задать значения столбцов для строки), или в операциях сравнения предложения `WHERE` для задания сравниваемого значения. Однако они не разрешены в качестве идентификаторов (таких как имена таблиц или столбцов).

`params`

  Необязательный список в виде массива (array) с таким количеством элементов, сколько связанных параметров в выполняемом SQL-запросе. Каждое значение рассматривается как строка (string).

### Возвращаемые значения

Возвращает `false` в случае возникновения ошибки. Для успешных запросов, создающих набор результатов, таких как `SELECT, SHOW, DESCRIBE` или `EXPLAIN`, возвращает объект mysqli_result. Для других успешных запросов возвращается `true`.

### Примеры

Пример #1 Пример использования mysqli::execute_query()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = $mysqli->execute_query($query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = mysqli_execute_query($link, $query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Вывод приведённых примеров будет похож на:

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_execute() - Выполняет подготовленное утверждение
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Возвращает число столбцов, затронутых последним запросом

### Описание

Объектно-ориентированный стиль

int $mysqli->field_count;

Процедурный стиль

function mysqli_field_count(mysqli `$mysql`): int

Возвращает число столбцов, затронутых последним запросом для соединения, указанного в `mysql`. Эта функция может быть полезной при использовании mysqli_store_result() для того, чтобы определить выдан ли непустой результат, или в случае неизвестного назначения запроса.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Целое число, содержащее число полей в результате запроса.

### Примеры

Пример #1 Пример использования $mysqli->field_count

Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query( "DROP TABLE IF EXISTS friends");
    $mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $mysqli->real_query("SELECT * FROM friends");

    if ($mysqli->field_count) {
        /* Определить тип запроса (select/show или describe) */
        $result = $mysqli->store_result();

        /* Создать выборку */
        $row = $result->fetch_row();

        /* Очистить выборку */
        $result->close();
    }

    /* Закрыть соединение */
    $mysqli->close();
    ?>

Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    mysqli_real_query($link, "SELECT * FROM friends");

    if (mysqli_field_count($link)) {
        /* Определить тип запроса (select/show или describe) */
        $result = mysqli_store_result($link);

        /* Создать выборку */
        $row = mysqli_fetch_row($result);

        /* Очистить выборку */
        mysqli_free_result($result);
    }

    /* Закрыть соединение */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Возвращает объект со сведениями о кодировке

### Описание

Объектно-ориентированный стиль

public function mysqli::get_charset(): ?object

Процедурный стиль

function mysqli_get_charset(mysqli `$mysql`): ?object

Функция возвращает объект со свойствами текущей кодировки.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает объект со следующими свойствами:

`charset`

  Название кодировки.

`collation`

  Название сопоставления.

`dir`

  Каталог, в котором СУБД нашла описание кодировки, или "" для встроенных наборов символов.

`min_length`

  Минимальный размер символа в байтах.

`max_length`

  Максимальный размер символа в байтах.

`number`

  Внутренний номер кодировки.

`state`

  С PHP 8.2.0 независимо от кодировки возвращается `1`.

### Примеры

Пример #1 Пример извлечения информации об активной кодировке методом mysqli::get_charset()

Объектно-ориентированный стиль

    <?php

    $db = mysqli_init();
    $db->real_connect("localhost", "root", "", "test");
    $db->set_charset('latin1');
    var_dump($db->get_charset());

Процедурный стиль

    <?php

    $db = mysqli_init();
    mysqli_real_connect($db, "localhost", "root", "", "test");
    $db->set_charset('latin1');
    var_dump(mysqli_get_charset($db));

Результат выполнения приведённых примеров:

    object(stdClass)#2 (7) {
      ["charset"]=>
      string(6) "latin1"
      ["collation"]=>
      string(17) "latin1_swedish_ci"
      ["dir"]=>
      string(0) ""
      ["min_length"]=>
      int(1)
      ["max_length"]=>
      int(1)
      ["number"]=>
      int(8)
      ["state"]=>
      int(1)
    }

### Смотрите также

- mysqli_character_set_name() - Возвращает текущую кодировку, установленную для соединения с БД
- mysqli_set_charset() - Задаёт набор символов

# mysqli::$client_info

# mysqli::get_client_info

# mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — Получает информацию о MySQL-клиенте

### Описание

Объектно-ориентированный стиль

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

Процедурный стиль

function mysqli_get_client_info(?mysqli `$mysql` = null): string

Функция возвращает строку с версией клиентской MySQL-библиотеки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает строку, которая содержит версию клиентской библиотеки MySQL.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Вызов функции mysqli_get_client_info() с аргументом `mysql` устарел. Функции никогда не требовался этот параметр, но она ошибочно разрешала передавать для него аргумент и обрабатывала параметр как необязательный.
8.1.0 | Объектно-ориентированный стиль вызова метода mysqli::get_client_info() устарел.

### Примеры

Пример #1 Пример получения информации о MySQL-клиенте функцией mysqli_get_client_info

    <?php

    /* Для определения версии клиентской библиотеки MySQL
       не обязательно создавать соединение */

    printf("Версия клиентской библиотеки: %s\n", mysqli_get_client_info());

    ?>

### Смотрите также

- mysqli_get_client_version() - Возвращает информацию о клиенте MySQL в виде строки
- mysqli_get_server_info() - Возвращает версию MySQL сервера
- mysqli_get_server_version() - Возвращает версию сервера MySQL, представленную в виде integer

# mysqli::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — Возвращает информацию о клиенте MySQL в виде строки

### Описание

Объектно-ориентированный стиль

int $mysqli->client_version;

Процедурный стиль

function mysqli_get_client_version(): int

Возвращает версию клиента в виде целого числа.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Число, содержащее версию клиентской библиотеки MySQL в следующем формате: `main_version*10000 + minor_version *100 + sub_version`. К примеру, для версии 4.1.0 выведет 40100.

Целесообразно использовать для быстрого определения версии клиентской библиотеки и возможностей её применения.

### Примеры

Пример #1 mysqli_get_client_version

    <?php

    /* Для определения версии клиентской библиотеки MySQL
     нет необходимости в создании соединения*/

    printf("Версия клиентской библиотеки: %d\n", mysqli_get_client_version());
    ?>

### Смотрите также

- mysqli_get_client_info() - Получает информацию о MySQL-клиенте
- mysqli_get_server_info() - Возвращает версию MySQL сервера
- mysqli_get_server_version() - Возвращает версию сервера MySQL, представленную в виде integer

# mysqli::get_connection_stats

# mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — Возвращает статистику соединения с клиентом

### Описание

Объектно-ориентированный стиль

public function mysqli::get_connection_stats(): array

Процедурный стиль

function mysqli_get_connection_stats(mysqli `$mysql`): array

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

> Замечание:

> Доступно только с модулем mysqlnd.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования mysqli_get_connection_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Смотрите также

- Описание статистики

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — Возвращает строку, содержащую тип используемого соединения

### Описание

Объектно-ориентированный стиль

string $mysqli->host_info;

Процедурный стиль

function mysqli_get_host_info(mysqli `$mysql`): string

Возвращает строку, описывающую соединение, которое обозначено в параметре `mysql` (включая имя хоста сервера).

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Символьная строка, содержащая имя хоста сервера и тип подключения.

### Примеры

Пример #1 Пример использования $mysqli->host_info

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* вывод информации о хосте */
    printf("Информация о хосте: %s\n", $mysqli->host_info);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* вывод информации о хосте */
    printf("Информация о хосте: %s\n", mysqli_get_host_info($link));
    ?>

Результат выполнения приведённых примеров:

    Информация о хосте: Localhost via UNIX socket

### Смотрите также

- mysqli_get_proto_info() - Возвращает версию используемого MySQL протокола

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — Возвращает версию используемого MySQL протокола

### Описание

Объектно-ориентированный стиль

int $mysqli->protocol_version;

Процедурный стиль

function mysqli_get_proto_info(mysqli `$mysql`): int

Возвращает целое число, представляющее собой версию протокола MySQL, используемого для соединения, переданного в `mysql`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Возвращает целое число, представляющее версию протокола.

### Примеры

Пример #1 Пример использования $mysqli->protocol_version

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Вывести версию протокола */
    printf("Версия протокола: %d\n", $mysqli->protocol_version);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Вывести версию протокола */
    printf("Версия протокола: %d\n", mysqli_get_proto_info($link));
    ?>

Результат выполнения приведённых примеров:

    Версия протокола: 10

### Смотрите также

- mysqli_get_host_info() - Возвращает строку, содержащую тип используемого соединения

# mysqli::$server_info

# mysqli::get_server_info

# mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — Возвращает версию MySQL сервера

### Описание

Объектно-ориентированный стиль

string $mysqli->server_info;
public function mysqli::get_server_info(): string

Процедурный стиль

function mysqli_get_server_info(mysqli `$mysql`): string

Возвращает строку, содержащую версию сервера MySQL, к которому также подключён модуль MySQLi.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Строка символов, содержащая версию сервера.

### Примеры

Пример #1 Пример использования $mysqli->server_info

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* выводим версию сервера */
    printf("Версия сервера: %s\n", $mysqli->server_info);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* выводим версию сервера */
    printf("Версия сервера: %s\n", mysqli_get_server_info($link));
    ?>

Результат выполнения приведённых примеров:

    Версия сервера: 8.0.21

### Смотрите также

- mysqli_get_client_info() - Получает информацию о MySQL-клиенте
- mysqli_get_client_version() - Возвращает информацию о клиенте MySQL в виде строки
- mysqli_get_server_version() - Возвращает версию сервера MySQL, представленную в виде integer

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — Возвращает версию сервера MySQL, представленную в виде integer

### Описание

Объектно-ориентированный стиль

int $mysqli->server_version;

Процедурный стиль

function mysqli_get_server_version(mysqli `$mysql`): int

Функция mysqli_get_server_version() возвращает версию сервера, к которому создано соединение (переданное в параметре `mysql`) в виде целого числа.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Целочисленное представление версии сервера.

Это число собирается следующим образом `main_version * 10000 + minor_version * 100 + sub_version` (т.е. версия 4.1.0 будет представлена как 40100).

### Примеры

Пример #1 Пример использования $mysqli->server_version

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* выводим версию сервера */
    printf("Версия сервера: %d\n", $mysqli->server_version);
    ?>

Процедурный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* выводим версию сервера */
    printf("Версия сервера: %d\n", mysqli_get_server_version($link));
    ?>

Результат выполнения приведённых примеров:

    Версия сервера: 80021

### Смотрите также

- mysqli_get_client_info() - Получает информацию о MySQL-клиенте
- mysqli_get_client_version() - Возвращает информацию о клиенте MySQL в виде строки
- mysqli_get_server_info() - Возвращает версию MySQL сервера

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Получает результат SHOW WARNINGS

### Описание

Объектно-ориентированный стиль

public function mysqli::get_warnings(): mysqli_warning|false

Процедурный стиль

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Возвращает односвязный список, состоящий из объектов mysqli_warning или `false`, если предупреждений нет. Каждый объект в списке соответствует одной строке из результата `SHOW WARNINGS`. Вызов метода mysqli_warning::next() заполнит объект значениями из следующей строки.

> Замечание: Для получения предупреждающих сообщений рекомендуется использовать SQL-команду `SHOW WARNINGS [limit row_count]` вместо функции.

Внимание

Связанный список нельзя перемотать назад или восстановить снова.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Метод возвращает односвязный список, состоящий из объектов mysqli_warning или `false` если предупреждений нет.

### Примеры

Пример #1 Проход по связанному списку для извлечения всех предупреждений

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Номер ошибки: %s\n", $warning->errno);
                printf("Сообщение: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "user", "password", "test");

    mysqli_query($link, "SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if (mysqli_warning_count($link) > 0) {
        $warning = mysqli_get_warnings($link);
        if ($warning !== false) {
            do {
                printf("Номер ошибки: %s\n", $warning->errno);
                printf("Сообщение: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Результат выполнения приведённых примеров:

    Номер ошибки: 1365
    Сообщение: Division by 0
    Номер ошибки: 1292
    Сообщение: Truncated incorrect INTEGER value: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — Извлекает информацию о последнем выполненном запросе

### Описание

Объектно-ориентированный стиль

?string $mysqli->info;

Процедурный стиль

function mysqli_info(mysqli `$mysql`): ?string

Функция mysqli_info() возвращает строку с информацией о последнем выполненном запросе к базе данных. Описание строки приведено ниже:

Возможные возвращаемые значения mysqli_info
Тип запроса | Пример результирующей строки
--- | ---
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

> Замечание:

> Запросы, не попадающие в приведённый список, не поддерживаются. В таких ситуациях mysqli_info() вернёт пустую строку.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Строка символов представляющая дополнительную информацию о последнем запущенном запросе.

### Примеры

Пример #1 Пример использования $mysqli->info

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    $mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", $mysqli->info);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", mysqli_info($link));
    ?>

Результат выполнения приведённых примеров:

    Records: 150  Duplicates: 0  Warnings: 0

### Смотрите также

- mysqli_affected_rows() - Получает число строк, затронутых предыдущей операцией MySQL
- mysqli_warning_count() - Возвращает количество предупреждений, сгенерированных последним выполненным запросом
- mysqli_num_rows() - Получает количество строк в наборе результатов

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()

### Описание

Объектно-ориентированный стиль

#[\Deprecated]
public function mysqli::init(): ?bool

Процедурный стиль

function mysqli_init(): mysqli|false

Функция выделяет память или инициализирует объект MySQL для работы с функциями mysqli_options() и mysqli_real_connect().

> Замечание:

> Очередные вызовы функций модуля mysqli, за исключением функции mysqli_options(), завершается ошибкой, пока не вызовут функцию mysqli_real_connect().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод mysqli::init() возвращает значение `null`, если завершился успешно, или `false`, если возникла ошибка. Функция mysqli_init() возвращает объект, если завершилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Объектно-ориентированный стиль вызова метода mysqli::init() устарел. Замените вызов метода parent::init() вызовом метода parent::__construct().

### Примеры

Смотрите описание функции mysqli_real_connect().

### Смотрите также

- mysqli_options() - Установка настроек
- mysqli_close() - Закрывает ранее открытое соединение с базой данных
- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером
- mysqli_connect() - Псевдоним mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — Возвращает значение, созданное для столбца AUTO_INCREMENT последним запросом

### Описание

Объектно-ориентированный стиль

int|string $mysqli->insert_id;

Процедурный стиль

function mysqli_insert_id(mysqli `$mysql`): int|string

Возвращает идентификатор, сгенерированный запросом `INSERT` или `UPDATE` для таблицы со столбцом, имеющим атрибут `AUTO_INCREMENT`. В случае многострочного оператора `INSERT` он возвращает первое автоматически сгенерированное значение, которое было успешно добавлено.

Выполнение запроса `INSERT` или `UPDATE` с использованием MySQL-функции `LAST_INSERT_ID()` также изменит значение, возвращаемое mysqli_insert_id(). Если `LAST_INSERT_ID(expr)` использовался для генерации значения `AUTO_INCREMENT`, он возвращает значение последнего `expr` вместо сгенерированного значения `AUTO_INCREMENT`.

Возвращает `0`, если предыдущий оператор не изменил значение `AUTO_INCREMENT`. mysqli_insert_id() должен вызываться сразу после запроса, сгенерировавшего значение.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Значение поля `AUTO_INCREMENT`, которое было затронуто предыдущим запросом. Возвращает ноль, если предыдущий запрос не затронул таблицы, содержащие поле `AUTO_INCREMENT`.

Только запросы, выданные с использованием текущего соединения, влияют на возвращаемое значение. На значение не влияют запросы, выданные с использованием других подключений или клиентов.

> Замечание:

> Если число больше максимального значения целого числа, функция вернёт строку.

### Примеры

Пример #1 Пример функции $mysqli->insert_id

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    $mysqli->query($query);

    printf("ID новой записи: %d.\n", $mysqli->insert_id);

    /* удаление таблицы */
    $mysqli->query("DROP TABLE myCity");

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    mysqli_query($link, $query);

    printf("ID новой записи: %d.\n", mysqli_insert_id($link));

    /* удаление таблицы */
    mysqli_query($link, "DROP TABLE myCity");

Результат выполнения приведённых примеров:

    ID новой записи: 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — Просит сервер завершить MySQL-поток

Внимание

Начиная с PHP 8.4.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

Объектно-ориентированный стиль

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

Процедурный стиль

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

Функция отправляет на сервер запрос на завершение MySQL-потока с идентификатором, который указали в аргументе `process_id`. Значение идентификатора получают функцией mysqli_thread_id().

Работу текущего запроса останавливают SQL-командой `KILL QUERY processid`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод mysqli::kill() и функция mysqli_kill() устарели. Вместо них рекомендуют выполнять SQL-команду `KILL`.

### Примеры

Пример #1 Пример уничтожения потока методом mysqli::kill()

Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверка соединения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    /* Определение id процесса */
    $thread_id = $mysqli->thread_id;

    /* Убиваем соединение */
    $mysqli->kill($thread_id);

    /* Это вызовет ошибку */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Ошибка: %s\n", $mysqli->error);
        exit;
    }

    /* Закрываем соединение */
    $mysqli->close();

    ?>

Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверка соединения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    /* Опредеение id процесса */
    $thread_id = mysqli_thread_id($link);

    /* Убиваем соединение */
    mysqli_kill($link, $thread_id);

    /* Это вызовет ошибку */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Ошибка: %s\n", mysqli_error($link));
        exit;
    }

    /* Закрываем соединение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Error: MySQL server has gone away

### Смотрите также

- mysqli_thread_id() - Возвращает ID потока текущего подключения

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — Проверка, есть ли ещё результаты в мультизапросе

### Описание

Объектно-ориентированный стиль

public function mysqli::more_results(): bool

Процедурный стиль

function mysqli_more_results(mysqli `$mysql`): bool

Указывает, есть ли ещё доступные результирующие наборы от предыдущего вызова функции mysqli_multi_query().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Возвращается `true` в случае, если один или более результирующих наборов (включая ошибки) доступны после предыдущего вызова функции mysqli_multi_query(), иначе `false`.

### Примеры

Смотрите mysqli_multi_query().

### Смотрите также

- mysqli_multi_query() - Выполняет запросы к базе данных
- mysqli_next_result() - Подготовка следующего доступного результирующего набора из multi_query
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Выполняет запросы к базе данных

### Описание

Объектно-ориентированный стиль

public function mysqli::multi_query(string `$query`): bool

Процедурный стиль

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

Функция отправляет одну или пакет SQL-инструкций, которые требуется выполнить на сервере баз данных. Инструкции перечисляют через точку с запятой.

Внимание

# Предупреждение безопасности: SQL-инъекция

Вместо составления строки запроса с включением переменных значений необходимо подготавливать запросы. Либо строки запроса должны быть экранированы функцией mysqli_real_escape_string() и правильно отформатированы.

SQL-инструкции отправляются в одном сетевом запросе к базе данных и обрабатываются последовательно. Функция mysqli_multi_query() дожидается завершения обработки первой SQL-инструкции, а затем возвращает управление PHP. Тем временем MySQL-сервер продолжает асинхронно обрабатывать остальные инструкции и готовит результат для очередного извлечения PHP-функциями.

Пакетные запросы часто обрабатывают в цикле do-while. Соединение останется недоступным для выполнения других SQL-инструкций, пока MySQL не обработает, а PHP не извлечёт результаты пакета инструкций. Для перехода к следующему результату последовательности вызывают функцию mysqli_next_result(). Модуль mysqli заблокирует работу скрипта, если потребуется дождаться ответа MySQL-сервера о готовности следующего результата. Завершил ли сервер обработку инструкций и выдачу результатов, проверяют функцией mysqli_more_results().

Наборы результатов, которые возвращаются инструкциями наподобие `SELECT, SHOW, DESCRIBE` или `EXPLAIN`, извлекают функцией mysqli_use_result() или mysqli_store_result(). Из запросов, которые не возвращают набор результатов, этими же функциями получают информацию о количестве затронутых строк или другие метаданные.

Подсказка

Выполнение SQL-инструкций `CALL` при вызове хранимых процедур в ряде сценариев возвращает множественные наборы результатов. Наборы результатов из хранимых процедур с инструкциями `SELECT` возвращаются по мере выполнения инструкций в порядке определения внутри процедуры. В общем случае вызывающая сторона не знает, сколько наборов результатов вернёт процедура, и поэтому готовится получить множественные результаты. Конечный результат процедуры — статус, который не включает набор результатов. Статус указывает, выполнилась ли процедура успешно или возникла ошибка.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`query`

  Строка с SQL-инструкциями, которые требуется отправить в запросе и выполнить на сервере. Инструкции разделяются точкой с запятой.

### Возвращаемые значения

Функция возвращает `false`, если выполнение первой SQL-инструкции завершилось ошибкой. Перед проверкой ошибок по остальным инструкциям сначала вызывают функцию mysqli_next_result().

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример выполнения пакета SQL-инструкций методом mysqli::multi_query()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Выполнение пакета SQL-инструкций в одном запросе */
    $mysqli->multi_query($query);
    do {
        /* Сохранение набора результатов в PHP */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* Вывод разделителя */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Выполнение пакета SQL-инструкций в одном запросе */
    mysqli_multi_query($link, $query);
    do {
        /* Сохранение набора результатов в PHP */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
        }
        /* Вывод разделителя */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));

Вывод приведённых примеров будет похож на:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Смотрите также

- mysqli_query() - Выполняет запрос к базе данных
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_next_result() - Подготовка следующего доступного результирующего набора из multi_query
- mysqli_more_results() - Проверка, есть ли ещё результаты в мультизапросе

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — Подготовка следующего доступного результирующего набора из multi_query

### Описание

Объектно-ориентированный стиль

public function mysqli::next_result(): bool

Процедурный стиль

function mysqli_next_result(mysqli `$mysql`): bool

Подготавливает следующий доступный результирующий набор предыдущего вызова функции mysqli_multi_query(), который затем можно получить функциями mysqli_store_result() или mysqli_use_result().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Также возвращает `false`, если следующий оператор привёл к ошибке, в отличие от mysqli_more_results().

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Смотрите mysqli_multi_query().

### Смотрите также

- mysqli_multi_query() - Выполняет запросы к базе данных
- mysqli_more_results() - Проверка, есть ли ещё результаты в мультизапросе
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — Установка настроек

### Описание

Объектно-ориентированный стиль

public function mysqli::options(int `$option`, string|int `$value`): bool

Процедурный стиль

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

Используется для установки дополнительных настроек соединения и поведения подключения к базе данных.

Эту функцию можно вызывать неоднократно, чтобы задать несколько настроек.

mysqli_options() нужно вызывать после mysqli_init() и перед mysqli_real_connect().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`option`

  Настройка, которую требуется установить. Это может быть одно из следующих значений:

  Допустимые настройки
  Имя | Описание
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | Время ожидания соединения в секундах
  `MYSQLI_OPT_READ_TIMEOUT` | Время ожидания результата выполнения команды в секундах. Доступно с PHP 7.2.0.
  `MYSQLI_OPT_LOCAL_INFILE` | Включение/выключение `LOAD LOCAL INFILE`
  `MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` | Каталог, который будет использоваться для `LOAD DATA LOCAL INFILE`.
  `MYSQLI_INIT_COMMAND` | Команда, которую требуется выполнить сразу после подключения к серверу MySQL
  `MYSQLI_SET_CHARSET_NAME` | Кодировка, которая будет установлена по умолчанию.
  `MYSQLI_READ_DEFAULT_FILE` | Читать настройки из именованного файла вместо my.cnf Не поддерживается mysqlnd.
  `MYSQLI_READ_DEFAULT_GROUP` | Читать настройки из именованной группы в файле my.cnf или другом файле, заданным настройкой `MYSQL_READ_DEFAULT_FILE`. Не поддерживается mysqlnd.
  `MYSQLI_SERVER_PUBLIC_KEY` | Файл публичного ключа RSA для авторизации на базе SHA-256.
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | Размер внутреннего командного/сетевого буфера. Работает только с mysqlnd.
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | Максимальный размер блока для чтения в байтах при чтении командного пакета MySQL. Работает только с mysqlnd.
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | Преобразовывает столбцы типов integer и float к числам PHP при использовании неподготовленных выражений. Работает только с mysqlnd.
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | Проверять сертификат сервера или нет.
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | Должен ли клиент принимать просроченные пароли.
  `1` | Использовать ли сжатие сетевых коммуникаций.

`value`

  Значение настройки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Смотрите mysqli_real_connect().

### Примечания

> Замечание: MySQLnd всегда подразумевает кодировку, которую использует по умолчанию сервер. Эта кодировка передаётся во время установки соединения/авторизации, которые использует mysqlnd.Libmysqlclient по умолчанию использует кодировку, установленную в файле my.cnf или явным вызовом функции mysqli_options() до вызова функции mysqli_real_connect(), но после вызова функции mysqli_connect().

### Смотрите также

- mysqli_init() - Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()
- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — Проверяет соединение с сервером или пытается переподключиться, если соединение прервалось

Внимание

Начиная с PHP 8.4.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

Объектно-ориентированный стиль

#[\Deprecated]
public function mysqli::ping(): bool

Процедурный стиль

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

Функция проверяет соединение с сервером. PHP попытается автоматически переподключиться, если соединение прервалось и включена глобальная настройка mysqli.reconnect.

> Замечание: Драйвер `mysqlnd` игнорирует директиву `mysqli.reconnect` файла php.ini, поэтому не переподключается автоматически.

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

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод mysqli::ping() и функция mysqli_ping() устарели. Функция `reconnect` была недоступна с PHP 8.2.0, что делает эту функцию устаревшей.

### Примеры

Пример #1 Пример проверки соединения с сервером методом mysqli::ping()

Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверка соединения */
    if ($mysqli->connect_errno) {
        printf("Не удалось подключиться: %s\n", $mysqli->connect_error);
        exit();
    }

    /* Проверяем, жив ли сервер */
    if ($mysqli->ping()) {
        printf ("Соединение в порядке!\n");
    } else {
        printf ("Ошибка: %s\n", $mysqli->error);
    }

    /* закрываем соединение */
    $mysqli->close();

    ?>

Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверка соединения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    /* Проверяем, жив ли сервер */
    if (mysqli_ping($link)) {
        printf ("Соединение в порядке!\n");
    } else {
        printf ("Ошибка: %s\n", mysqli_error($link));
    }

    /* Закрываем соединение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Our connection is ok!

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — Опрашивает подключения

### Описание

Объектно-ориентированный стиль

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Процедурный стиль

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Функция опрашивает подключения. Функцию разрешно вызывать статически.

> Замечание:

> Доступно только с модулем mysqlnd.

### Список параметров

`read`

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

`error`

  Список соединений, на которых произошли ошибки, например, не удался запрос или соединение было потеряно.

`reject`

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

`seconds`

  Максимальное количество секунд ожидания, не должно быть отрицательным.

`microseconds`

  Максимальное количество миллисекунд ожидания, не должно быть отрицательным.

### Возвращаемые значения

Функция возвращает количество готовых к работе соединений в случае успешного выполнения, `false` в случае неудачи.

### Ошибки

Функция выбрасывает исключение ValueError, если не передан ни аргумент `read`, ни аргумент `error`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь функция выбрасывает исключение ValueError, если не передан ни аргумент `read`, ни аргумент `error`.

### Примеры

Пример #1 Пример использования функции mysqli_poll()

    <?php

    $link1 = mysqli_connect();
    $link1->query("SELECT 'test'", MYSQLI_ASYNC);
    $all_links = array($link1);
    $processed = 0;
    do {
        $links = $errors = $reject = array();
        foreach ($all_links as $link) {
            $links[] = $errors[] = $reject[] = $link;
        }
        if (!mysqli_poll($links, $errors, $reject, 1)) {
            continue;
        }
        foreach ($links as $link) {
            if ($result = $link->reap_async_query()) {
                print_r($result->fetch_row());
                if (is_object($result))
                    mysqli_free_result($result);
            } else die(sprintf("Ошибка MySQLi: %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));

    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => test
    )

### Смотрите также

- mysqli_query() - Выполняет запрос к базе данных
- mysqli_reap_async_query() - Получение результата асинхронного запроса

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — Подготавливает SQL выражение к выполнению

### Описание

Объектно-ориентированный стиль

public function mysqli::prepare(string `$query`): mysqli_stmt|false

Процедурный стиль

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

Подготавливает SQL-запрос и возвращает указатель на это выражение, который может использоваться для дальнейших операций с этим выражением. Запрос должен состоять из одного SQL-выражения.

Шаблон оператора может содержать ноль или несколько вопросительных знаков (`?`), меток параметров⁠, также называемых заполнителями. Метки параметров должны быть привязаны к переменным приложения с помощью mysqli_stmt_bind_param() перед выполнением выражения.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`query`

  Текст запроса в виде строки. Должен состоять из одного SQL-выражения.

  Выражение SQL может содержать ноль или более меток параметров, представленных знаками вопроса (`?`) в соответствующих позициях.

  > Замечание:

  > Эти метки можно встраивать только в определённые места в выражении. Например, они разрешены в списке `VALUES()` выражения `INSERT` (чтобы задать значения столбцов для строки), или в операциях сравнения предложения `WHERE` для задания сравниваемого значения. Однако они не разрешены в качестве идентификаторов (таких как имена таблиц или столбцов).

### Возвращаемые значения

mysqli_prepare() возвращает объект запроса или `false` в случае ошибки.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::prepare()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* создание подготавливаемого запроса */
    $stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");

    /* связывание параметров с метками */
    $stmt->bind_param("s", $city);

    /* выполнение запроса */
    $stmt->execute();

    /* связывание переменных с результатами запроса */
    $stmt->bind_result($district);

    /* получение значения */
    $stmt->fetch();

    printf("%s находится в округе %s\n", $city, $district);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* создание подготавливаемого запроса */
    $stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");

    /* связывание параметров с метками */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* выполнение запроса */
    mysqli_stmt_execute($stmt);

    /* связывание переменных с результатами запроса */
    mysqli_stmt_bind_result($stmt, $district);

    /* получение значения */
    mysqli_stmt_fetch($stmt);

    printf("%s находится в округе %s\n", $city, $district);
    ?>

Результат выполнения приведённых примеров:

    Amersfoort находится в округе Utrecht

### Смотрите также

- mysqli_stmt_execute() - Выполняет подготовленное утверждение
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt_bind_result() - Привязка переменных к подготовленному запросу для размещения результата
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result
- mysqli_stmt_close() - Закрывает подготовленный запрос

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Выполняет запрос к базе данных

### Описание

Объектно-ориентированный стиль

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Процедурный стиль

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Выполняет запрос `query` к базе данных.

Внимание

# Предупреждение безопасности: SQL-инъекция

Вместо составления строки запроса с включением переменных значений необходимо подготавливать запросы. Либо строки запроса должны быть экранированы функцией mysqli_real_escape_string() и правильно отформатированы.

Для не DML-запросов (не INSERT, UPDATE или DELETE), эта функция равносильна вызову функции mysqli_real_query(), а затем mysqli_use_result() или mysqli_store_result().

> Замечание:

> Если длина передаваемого в функцию mysqli_query() выражения больше значения системной переменной `max_allowed_packet` сервера, будет сгенерирована ошибка. MySQL-драйвер (`mysqlnd`) и клиентская библиотека MySQL (`libmysqlclient`) выбрасывают разные коды ошибок. Поведение функции будет следующим:

> - `mysqlnd` на платформе Linux возвращает код ошибки 1153. Сообщение об ошибке означает размер пакета превышает `max_allowed_packet` байт.

> - `mysqlnd` на платформе Windows возвращает код ошибки 2006. Это сообщение об ошибке означает отказ сервера.

> - `libmysqlclient` на всех платформах возвращает код ошибки 2006. Это сообщение об ошибке означает отказ сервера.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`query`

  Текст запроса.

`result_mode`

  Режим результата может быть одной из 3 констант, указывающих, как результат будет возвращён сервером MySQL.

  `MYSQLI_STORE_RESULT` (по умолчанию) — возвращает объект mysqli_result с буферизованным набором результатов.

  `MYSQLI_USE_RESULT` — возвращает объект mysqli_result с небуферизованным набором результатов. Пока есть отложенные записи, ожидающие выборки, линия соединения будет занята и все последующие вызовы будут возвращать ошибку `Commands out of sync`. Чтобы избежать ошибки, все записи должны быть получены с сервера или набор результатов должен быть отброшен путём вызова mysqli_free_result().

  `MYSQLI_ASYNC` (доступно с mysqlnd) — запрос выполняется асинхронно, набор результатов сразу не возвращается. Затем вызывают функцию mysqli_poll() для получения результатов по этим запросам. Можно использовать в сочетании с константой `MYSQLI_STORE_RESULT` или `MYSQLI_USE_RESULT`.

### Возвращаемые значения

Возвращает `false` в случае возникновения ошибки. В случае успешного выполнения запросов, которые создают набор результатов, таких как `SELECT, SHOW, DESCRIBE` или `EXPLAIN`, функция mysqli_query() вернёт объект mysqli_result. Для остальных успешных запросов mysqli_query() вернёт `true`.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::query()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Создание таблицы, не возвращает набор результатов */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Таблица myCity создана.\n");

    /* Запросы SELECT, возвращают набор результатов */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Запрос SELECT вернул %d строк.\n", $result->num_rows);

    /* Если нужно извлечь большой объем данных, используем MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Важно заметить, что мы не можем вызывать функции, которые взаимодействуют
       с сервером, пока не закроем набор результатов. Все подобные вызовы
       будут вызывать ошибку 'out of sync' */
    $mysqli->query("SET @a:='this will not work'");

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Создание таблицы, не возвращает набор результатов */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Таблица myCity создана.\n");

    /* Запросы SELECT, возвращают набор результатов */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Запрос SELECT вернул %d строк.\n", mysqli_num_rows($result));

    /* Если нужно извлечь большой объем данных, используем MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Важно заметить, что мы не можем вызывать функции, которые взаимодействуют
       с сервером, пока не закроем набор результатов. Все подобные вызовы
       будут вызывать ошибку 'out of sync' */
    mysqli_query($link, "SET @a:='this will not work'");

Результат выполнения приведённых примеров:

    Таблица myCity создана.
    Запрос SELECT вернул 10 строк.

    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### Смотрите также

- mysqli_execute_query() - Подготавливает, связывает параметры и выполняет SQL-запрос
- mysqli_real_query() - Выполнение SQL запроса
- mysqli_multi_query() - Выполняет запросы к базе данных
- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_free_result() - Освобождает память, занятую результатами запроса

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — Устанавливает соединение с MySQL-сервером

### Описание

Объектно-ориентированный стиль

public function mysqli::real_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Процедурный стиль

function mysqli_real_connect(
mysqli `$mysql`,
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

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

Эта функция отличается от функции mysqli_connect():

- Для работы mysqli_real_connect() необходим действительный объект, созданный функцией mysqli_init().

- Параметр `flags`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`hostname`

  Может быть либо именем хоста, либо IP-адресом. При передаче `null`, значение извлекается из mysqli.default_host. По возможности вместо протокола TCP/IP будут использоваться каналы. Протокол TCP/IP используется, если указаны и имя хоста и номер порта, например, `localhost:3308`.

`username`

  Имя пользователя MySQL или `null` для принятия имени пользователя на основе ini-опции mysqli.default_user.

`password`

  Пароль MySQL или `null` для принятия пароля на основе ini-опции mysqli.default_pw.

`database`

  База данных по умолчанию, которая будет использоваться при выполнении запросов или `null`.

`port`

  Номер порта для попытки подключения к серверу MySQL или `null` для принятия порта на основе ini-опции mysqli.default_port.

`socket`

  Задаёт номер порта для подключения к серверу MySQL.

  > Замечание:

  > Передача параметра `socket` не будет явно задавать тип соединения при подключении к серверу MySQL. То, как будет устанавливаться соединение с MySQL-сервером, определяется параметром `hostname`.

`flags`

  С помощью параметра `flags` можно задать некоторые настройки соединения:

  Поддерживаемые флаги
  Имя | Описание
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | Использовать протокол сжатия
  `MYSQLI_CLIENT_FOUND_ROWS` | Возвращать количество строк, подошедших условиям выборки, вместо количества затронутых запросом строк
  `MYSQLI_CLIENT_IGNORE_SPACE` | Допускать пробелы после имён функций. Делает все имена функций зарезервированными словами.
  `MYSQLI_CLIENT_INTERACTIVE` | Допускать `interactive_timeout` секунд (вместо `wait_timeout`) простоя, прежде чем закрыть соединение
  `MYSQLI_CLIENT_SSL` | Использовать SSL (шифрование)
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | Аналогично `MYSQLI_CLIENT_SSL`, но запрещает проверку SSL сертификата. Работает только с MySQL Native Driver и MySQL 5.6 и выше.

  > Замечание:

  > По причинам безопасности, флаг `MULTI_STATEMENT` не поддерживается в PHP. Если необходимо выполнять мультизапросы, используйте функцию mysqli_multi_query().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Все параметры теперь принимают значение `null`

### Примеры

Пример #1 Пример использования метода mysqli::real_connect()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Выполнено... ' . $mysqli->host_info . "\n";

Объектно-ориентированный стиль при расширении класса mysqli

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

    $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

    echo 'Выполнено... ' . $db->host_info . "\n";
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Выполнено... ' . mysqli_get_host_info($link) . "\n";
    ?>

Результат выполнения приведённых примеров:

    Выполнено... MySQL host info: localhost via TCP/IP

### Примечания

> Замечание: MySQLnd всегда подразумевает кодировку, которую использует по умолчанию сервер. Эта кодировка передаётся во время установки соединения/авторизации, которые использует mysqlnd.Libmysqlclient по умолчанию использует кодировку, установленную в файле my.cnf или явным вызовом функции mysqli_options() до вызова функции mysqli_real_connect(), но после вызова функции mysqli_connect().

### Смотрите также

- mysqli_connect() - Псевдоним mysqli::__construct
- mysqli_init() - Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()
- mysqli_options() - Установка настроек
- mysqli_ssl_set() - Используется для установления безопасных соединений, используя SSL
- mysqli_close() - Закрывает ранее открытое соединение с базой данных

# mysqli::real_escape_string

# mysqli::escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli::escape_string -- mysqli_real_escape_string — Экранирует специальные символы в строке для использования в SQL-выражении, используя текущий набор символов соединения

### Описание

Объектно-ориентированный стиль

public function mysqli::real_escape_string(string `$string`): string

Процедурный стиль

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

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

Предостережение

# Безопасность: набор символов по умолчанию

Набор символов должен быть задан либо на стороне сервера, либо с помощью API-функции mysqli_set_charset(). В противном случае mysqli_real_escape_string() работать не будет. За дополнительной информацией обращайтесь к документации наборы символов.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`string`

  Строка, которую требуется экранировать.

  Экранируемые символы `NUL (ASCII 0)`, `\n`, `\r`, `\`, `'`, `"` и ``CTRL`+`Z``.

### Возвращаемые значения

Возвращает экранированную строку.

### Примеры

Пример #1 Пример использования mysqli::real_escape_string()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* этот запрос с экранированным $city будет работать */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("Возвращённые строки: %d.\n", $result->num_rows);

    /* этот запрос завершится ошибкой, потому что мы не экранировали $city */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* этот запрос с экранированным $city будет работать */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("Возвращённые строки: %d.\n", mysqli_num_rows($result));

    /* этот запрос завершится ошибкой, потому что мы не экранировали $city */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

Вывод приведённых примеров будет похож на:

    Возвращённые строки: 1.

    Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 's-Hertogenbosch'' at line 1 in...

### Смотрите также

- mysqli_set_charset() - Задаёт набор символов

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — Выполнение SQL запроса

### Описание

Объектно-ориентированный стиль

public function mysqli::real_query(string `$query`): bool

Процедурный стиль

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

Выполняет одиночный запрос к базе данных, результаты которого можно получить или использовать функциями mysqli_store_result() или mysqli_use_result().

Внимание

# Предупреждение безопасности: SQL-инъекция

Вместо составления строки запроса с включением переменных значений необходимо подготавливать запросы. Либо строки запроса должны быть экранированы функцией mysqli_real_escape_string() и правильно отформатированы.

Чтобы определить, должен ли запрос возвращать результирующий набор, смотрите mysqli_field_count().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`query`

  Текст запроса в виде строки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Смотрите также

- mysqli_query() - Выполняет запрос к базе данных
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli::reap_async_query

# mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — Получение результата асинхронного запроса

### Описание

Объектно-ориентированный стиль

public function mysqli::reap_async_query(): mysqli_result|bool

Процедурный стиль

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

Получает результат асинхронного запроса.

> Замечание:

> Доступно только с модулем mysqlnd.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Возвращает `false` в случае возникновения ошибки. Для успешных запросов, которые производят набор результатов, таких как `SELECT, SHOW, DESCRIBE` или `EXPLAIN`, mysqli_reap_async_query() вернёт объект mysqli_result. Для других успешных запросов mysqli_reap_async_query() вернёт `true`.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Смотрите также

- mysqli_poll() - Опрашивает подключения

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — Обновляет таблицы или кеш

Внимание

Начиная с PHP 8.4.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

Объектно-ориентированный стиль

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

Процедурный стиль

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

Функция очищает таблицы или кеш, либо сбрасывает информацию сервера репликации.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`flags`

  Настройки обновления задаются константами семейства MYSQLI_REFRESH_*, которые описавает раздел документации «Константы модуля MySQLi».

  Смотрите также официальную документацию » MySQL Refresh.

### Возвращаемые значения

Функция возвращает значение `true`, если выполнилась успешно, иначе возвращает значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод mysqli::refresh() и функция mysqli_refresh() устарели. Вместо них рекомендуют выполнять SQL-команду `FLUSH`.

### Смотрите также

- mysqli_poll() - Опрашивает подключения

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — Удаляет именованную точку сохранения из списка точек сохранения текущей транзакции

### Описание

Объектно-ориентированный стиль

public function mysqli::release_savepoint(string `$name`): bool

Процедурный стиль:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

Функция идентична выполнению запроса `$mysqli->query("RELEASE SAVEPOINT `$name`");`. Она не запускает фиксацию или откат.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`name`

  Идентификатор точки сохранения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mysqli_savepoint() - Установите именованную точку сохранения транзакции

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — Откат текущей транзакции

### Описание

Объектно-ориентированный стиль

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

Процедурный стиль

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Откатывает текущую транзакцию.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`flags`

  Битовая маска констант `MYSQLI_TRANS_COR_*`.

`name`

  Если передана, то выполняется `ROLLBACK/*name*/`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `name` теперь допускает значение null.

### Примеры

Смотрите пример использования в разделе mysqli::begin_transaction().

### Примечания

> Замечание:

> Функция не работает с нетранзакционными типами таблиц (такими как MyISAM или ISAM).

### Смотрите также

- mysqli_begin_transaction() - Стартует транзакцию
- mysqli_commit() - Фиксирует текущую транзакцию
- mysqli_autocommit() - Включает или отключает автоматическую фиксацию изменений базы данных
- mysqli_release_savepoint() - Удаляет именованную точку сохранения из списка точек сохранения текущей транзакции

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — Установите именованную точку сохранения транзакции

### Описание

Объектно-ориентированный стиль

public function mysqli::savepoint(string `$name`): bool

Процедурный стиль:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

Функция идентична выполнению запроса `$mysqli->query("SAVEPOINT `$name`");`

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`name`

  Идентификатор точки сохранения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mysqli_release_savepoint() - Удаляет именованную точку сохранения из списка точек сохранения текущей транзакции

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — Устанавливает базу данных для выполняемых запросов

### Описание

Объектно-ориентированный стиль

public function mysqli::select_db(string `$database`): bool

Процедурный стиль

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

Устанавливает базу данных, которая будет использоваться при выполнении запросов к базе данных

> Замечание:

> Эта функция используется только для смены базы данных во время подключения. Вы можете выбрать базу данных, передав её четвёртым параметром в функции mysqli_connect().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`database`

  Имя базы данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::select_db()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* получаем имя текущей базы данных по умолчанию */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("База данных по умолчанию: %s.\n", $row[0]);

    /* изменяем базу данных по умолчанию на "world" */
    $mysqli->select_db("world");

    /* получаем имя текущей базы данных по умолчанию */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("База данных по умолчанию: %s.\n", $row[0]);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* получаем имя текущей базы данных по умолчанию */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("База данных по умолчанию: %s.\n", $row[0]);

    /* изменяем базу данных по умолчанию на "world" */
    mysqli_select_db($link, "world");

    /* получаем имя текущей базы данных по умолчанию */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("База данных по умолчанию: %s.\n", $row[0]);

Результат выполнения приведённых примеров:

    База данных по умолчанию: test.
    База данных по умолчанию: world.

### Смотрите также

- mysqli_connect() - Псевдоним mysqli::__construct
- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — Задаёт набор символов

### Описание

Объектно-ориентированный стиль

public function mysqli::set_charset(string `$charset`): bool

Процедурный стиль

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

Задаёт набор символов, который будет использоваться при обмене данными с сервером баз данных.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`charset`

  Набор символов, который необходимо установить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::set_charset()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Начальный набор символов: %s\n", $mysqli->character_set_name());

    /* Изменим набор символов на utf8mb4 */
    $mysqli->set_charset("utf8mb4");

    printf("Текущий набор символов: %s\n", $mysqli->character_set_name());

    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Начальный набор символов: %s\n", mysqli_character_set_name($link));

    /* Изменим набор символов на utf8mb4 */
    mysqli_set_charset($link, "utf8mb4");

    printf("Текущий набор символов: %s\n", mysqli_character_set_name($link));

    ?>

Результат выполнения приведённых примеров:

    Начальный набор символов: latin1
    Текущий набор символов: utf8mb4

### Примечания

> Замечание:

> Это предпочтительный способ установки набора символов. Функции mysqli_query() (например `SET NAMES utf8`) для этих целей не рекомендуется. Дополнительную информацию даёт страница «Наборы символов в MySQL».

### Смотрите также

- mysqli_character_set_name() - Возвращает текущую кодировку, установленную для соединения с БД
- mysqli_real_escape_string() - Экранирует специальные символы в строке для использования в SQL-выражении, используя текущий набор символов соединения
- Концепции кодировок MySQL
- » Список поддерживаемых MySQL наборов символов

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — Возвращает код состояния SQLSTATE последней MySQL операции

### Описание

Объектно-ориентированный стиль

string $mysqli->sqlstate;

Процедурный стиль

function mysqli_sqlstate(mysqli `$mysql`): string

Возвращает строку с SQLSTATE кодом последней ошибки. Этот код состоит из пяти символов. `'00000'` означает отсутствие ошибок. Эти коды определены в стандарте ANSI, а также в ODBC. Посмотреть список возможных значений можно на странице » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Замечание:

> Следует заметить, что ещё не все MySQL ошибки имеют отражение в SQLSTATE кодах. Для подобных ошибок используется код `HY000` (общая ошибка).

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Возвращает строку с SQLSTATE кодом последней ошибки. Этот код состоит из пяти символов. `'00000'` означает отсутствие ошибок.

### Примеры

Пример #1 Пример использования $mysqli->sqlstate

Объектно-ориентированный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Таблица City уже существует, поэтому мы должны получить ошибку */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Ошибка - SQLSTATE %s.\n", $mysqli->sqlstate);
    }
    ?>

Процедурный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Таблица City уже существует, поэтому мы должны получить ошибку */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Ошибка - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }
    ?>

Результат выполнения приведённых примеров:

    Ошибка - SQLSTATE 42S01.

### Смотрите также

- mysqli_errno() - Возвращает код ошибки последнего вызова функции
- mysqli_error() - Возвращает строку с описанием последней ошибки

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — Используется для установления безопасных соединений, используя SSL

### Описание

Объектно-ориентированный стиль

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Процедурный стиль

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Используется для установления безопасных соединений, используя SSL. Функцию необходимо вызывать до вызова mysqli_real_connect(). Для работы функции требуется включить поддержку OpenSSL, в противном случае функция делать ничего не будет.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`key`

  Путь и имя ключевого файла.

`certificate`

  Путь и имя файла сертификата.

`ca_certificate`

  Путь и имя файла с разрешениями сертификата.

`ca_path`

  Путь к директории, в которой хранятся доверенные CA-сертификаты SSL в формате PEM.

`cipher_algos`

  Список допустимых шифров для использования в SSL-шифровании.

### Возвращаемые значения

Функция возвращает логическое значение `true`. Если SSL установлен некорректно mysqli_real_connect() вернёт ошибку при попытке подключения.

### Смотрите также

- mysqli_options() - Установка настроек
- mysqli_real_connect() - Устанавливает соединение с MySQL-сервером

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — Получение информации о текущем состоянии системы

### Описание

Объектно-ориентированный стиль

public function mysqli::stat(): string|false

Процедурный стиль

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() возвращает строку с информацией, схожей с той, что предоставляет команда 'mysqladmin status'. Сюда включается время работы с момента загрузки в секундах, количество запущенных процессов, запросов, перезагрузок и открытых таблиц.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Строка с информацией о состоянии системы. `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования mysqli::stat()

Объектно-ориентированный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf("System status: %s\n", $mysqli->stat());
    ?>

Процедурный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("System status: %s\n", mysqli_stat($link));
    ?>

Результат выполнения приведённых примеров:

    Состояние системы: Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
    Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
    Memory in use: 8496K  Max memory used: 8560K

### Смотрите также

- mysqli_get_server_info() - Возвращает версию MySQL сервера

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — Инициализирует запрос и возвращает объект для использования в mysqli_stmt_prepare

### Описание

Объектно-ориентированный стиль

public function mysqli::stmt_init(): mysqli_stmt|false

Процедурный стиль

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

Выделяет память и инициализирует объект запроса, который можно использовать в функции mysqli_stmt_prepare().

> Замечание:

> Все последующие вызовы mysqli_stmt функций вызовут ошибку, пока не будет вызвана функция mysqli_stmt_prepare().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Возвращает объект.

### Смотрите также

- mysqli_stmt_prepare() - Подготавливает утверждение SQL к выполнению

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — Передаёт на клиента результирующий набор последнего запроса

### Описание

Объектно-ориентированный стиль

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

Процедурный стиль

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

Передаёт результирующий набор последнего запроса на соединении `mysql`. Дальнейшая работа с этим набором осуществляется функцией mysqli_data_seek().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`mode`

  Устанавливаемая опция. Начиная с PHP 8.1, параметр ни на что не влияет. Может иметь одно из следующих значений:

  Допустимые варианты
  Имя | Описание
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | Копирует результаты из внутреннего буфера mysqlnd в получаемые переменные PHP. По умолчанию mysqlnd использует ссылки, предотвращая копирование и дублирование результатов в памяти. В некоторых случаях, например, если результаты содержат много небольших рядов, копирование может уменьшить общее потребление памяти, так как переменные PHP, содержащие результат, можно освобождать раньше (доступно только при использовании mysqlnd)

### Возвращаемые значения

Возвращает буферизованный объект результата запроса или `false` в случае ошибки.

> Замечание:

> mysqli_store_result() возвращает `false`, если запрос не возвращает результирующей таблицы (например, в случае выражения INSERT). Также функция вернёт `false`, если данные из результирующего набора не удалось прочитать. Наличие ошибки можно проверить функцией mysqli_error(), которая в этом случае вернёт непустую строку; mysqli_errno() вернёт ненулевое значение; и mysqli_field_count() также вернёт ненулевое значение. Также возможной причиной возврата `false` после успешного вызова mysqli_query() может быть слишком большой результирующий набор (не хватает памяти для его размещения). Если функция mysqli_field_count() возвращает ненулевое значение, значит запрос вернул непустой результирующий набор.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Передача параметра параметра `mode` устарела. Начиная с PHP 8.1.0 параметр не имеет значения.

### Примеры

Смотрите mysqli_multi_query().

### Примечания

> Замечание:

> Даже несмотря на хорошую практику очищать память, занятую результатами запросов, посредством функции mysqli_free_result(), если mysqli_store_result() передаёт большой результирующий набор, это может стать проблемой.

### Смотрите также

- mysqli_real_query() - Выполнение SQL запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — Возвращает ID потока текущего подключения

### Описание

Объектно-ориентированный стиль

int $mysqli->thread_id;

Процедурный стиль

function mysqli_thread_id(mysqli `$mysql`): int

Функция mysqli_thread_id() возвращает ID потока текущего подключения. Идентификатор передают в функцию mysqli_kill(), чтобы завершить конкретный поток. Повторное подключение функцией mysqli_ping(), которое устанавливают после потери соединения, изменит идентификатор потока. Поэтому идентификатор потока получают, когда требуется.

> Замечание:

> Идентификатор потока назначается для каждого подключения отдельно. Поэтому после разрыва и повторной установки соединения назначается новый ID.

> Запущенный запрос завершают SQL-командой `KILL QUERY processid`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Функция возвращает ID потока текущего подключения.

### Примеры

Пример #1 Пример получения идентификатора потока текущего соединения методом $mysqli->thread_id

Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Возник сбой соединения: %s\n", mysqli_connect_error());
        exit();
    }

    /* Определяем ID потока */
    $thread_id = $mysqli->thread_id;

    /* Завершаем соединение */
    $mysqli->kill($thread_id);

    /* Этот блок кода вызовет ошибку */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Ошибка: %s\n", $mysqli->error);
        exit;
    }

    /* Закрываем соединение */
    $mysqli->close();

    ?>

Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Возник сбой соединения: %s\n", mysqli_connect_error());
        exit();
    }

    /* Определяем ID потока */
    $thread_id = mysqli_thread_id($link);

    /* Завершаем соединение */
    mysqli_kill($link, $thread_id);

    /* Этот блок кода вызовет ошибку */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Ошибка: %s\n", mysqli_error($link));
        exit;
    }

    /* Закрываем соединение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Error: MySQL server has gone away

### Смотрите также

- mysqli_kill() - Просит сервер завершить MySQL-поток

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — Показывает, безопасна ли работа с процессами

### Описание

Объектно-ориентированный стиль

public function mysqli::thread_safe(): bool

Процедурный стиль

function mysqli_thread_safe(): bool

Показывает, клиентская библиотека скомпилирована как потокобезопасная или нет.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если клиентская библиотека потокобезопасна, в противном случае `false`.

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Готовит результирующий набор на сервере к использованию

### Описание

Объектно-ориентированный стиль

public function mysqli::use_result(): mysqli_result|false

Процедурный стиль

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Используется для подготовки к использованию результирующего набора последнего запроса, запущенного функцией mysqli_real_query().

Чтобы результаты запроса стали доступны, после самого запроса необходимо вызывать либо эту функцию, либо mysqli_store_result(). Также вызов какой-либо из них предотвратит отказ следующих запросов на этом же соединении.

> Замечание:

> mysqli_use_result() не передаёт весь результирующий набор на клиента, а следовательно невозможно воспользоваться функцией mysqli_data_seek(), чтобы перемещаться по нему. Для этого нужно воспользоваться функцией mysqli_store_result(). mysqli_use_result() не следует использовать, если на стороне клиента данные результирующего набора долго обрабатываются, так как это задерживает работу сервера и не даёт другим процессам обновлять таблицы, данные из которых есть в результирующем наборе.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает небуферизованный объект результата запроса или `false` в случае возникновения ошибки.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli::use_result()

Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверка соединения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* выполняем мультизапрос */
    if ($mysqli->multi_query($query)) {
        do {
            /* получаем первый результирующий набор */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* печатаем разделитель */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверка соединения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* выполняем мультизапрос */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* получаем первый результирующий набор */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* печатаем разделитель */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Смотрите также

- mysqli_real_query() - Выполнение SQL запроса
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Возвращает количество предупреждений, сгенерированных последним выполненным запросом

### Описание

Объектно-ориентированный стиль

int $mysqli->warning_count;

Процедурный стиль

function mysqli_warning_count(mysqli `$mysql`): int

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

> Замечание: Для получения предупреждающих сообщений можно использовать следующую SQL-команду: `SHOW WARNINGS [limit row_count]`.

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().

### Возвращаемые значения

Количество предупреждений или ноль, если таковых нет.

### Примеры

Пример #1 Пример использования $mysqli->warning_count

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Результат выполнения приведённых примеров:

    Warning (1365): Division by 0

### Смотрите также

- mysqli_errno() - Возвращает код ошибки последнего вызова функции
- mysqli_error() - Возвращает строку с описанием последней ошибки
- mysqli_sqlstate() - Возвращает код состояния SQLSTATE последней MySQL операции

## Содержание

- mysqli::$affected_rows — Получает число строк, затронутых предыдущей операцией MySQL
- mysqli::autocommit — Включает или отключает автоматическую фиксацию изменений базы данных
- mysqli::begin_transaction — Стартует транзакцию
- mysqli::change_user — Изменяет пользователя соединения с базой данных
- mysqli::character_set_name — Возвращает текущую кодировку, установленную для соединения с БД
- mysqli::close — Закрывает ранее открытое соединение с базой данных
- mysqli::commit — Фиксирует текущую транзакцию
- mysqli::$connect_errno — Возвращает код ошибки последней попытки соединения
- mysqli::$connect_error — Возвращает описание последней ошибки подключения
- mysqli::__construct — Устанавливает новое соединение с MySQL-сервером
- mysqli::debug — Выполняет процедуры отладки
- mysqli::dump_debug_info — Журналирование отладочной информации
- mysqli::$errno — Возвращает код ошибки последнего вызова функции
- mysqli::$error — Возвращает строку с описанием последней ошибки
- mysqli::$error_list — Возвращает список ошибок выполнения последней запущенной команды
- mysqli::execute_query — Подготавливает, связывает параметры и выполняет SQL-запрос
- mysqli::$field_count — Возвращает число столбцов, затронутых последним запросом
- mysqli::get_charset — Возвращает объект со сведениями о кодировке
- mysqli::$client_info — Получает информацию о MySQL-клиенте
- mysqli::$client_version — Возвращает информацию о клиенте MySQL в виде строки
- mysqli::get_connection_stats — Возвращает статистику соединения с клиентом
- mysqli::$host_info — Возвращает строку, содержащую тип используемого соединения
- mysqli::$protocol_version — Возвращает версию используемого MySQL протокола
- mysqli::$server_info — Возвращает версию MySQL сервера
- mysqli::$server_version — Возвращает версию сервера MySQL, представленную в виде integer
- mysqli::get_warnings — Получает результат SHOW WARNINGS
- mysqli::$info — Извлекает информацию о последнем выполненном запросе
- mysqli::init — Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()
- mysqli::$insert_id — Возвращает значение, созданное для столбца AUTO_INCREMENT последним запросом
- mysqli::kill — Просит сервер завершить MySQL-поток
- mysqli::more_results — Проверка, есть ли ещё результаты в мультизапросе
- mysqli::multi_query — Выполняет запросы к базе данных
- mysqli::next_result — Подготовка следующего доступного результирующего набора из multi_query
- mysqli::options — Установка настроек
- mysqli::ping — Проверяет соединение с сервером или пытается переподключиться, если соединение прервалось
- mysqli::poll — Опрашивает подключения
- mysqli::prepare — Подготавливает SQL выражение к выполнению
- mysqli::query — Выполняет запрос к базе данных
- mysqli::real_connect — Устанавливает соединение с MySQL-сервером
- mysqli::real_escape_string — Экранирует специальные символы в строке для использования в SQL-выражении, используя текущий набор символов соединения
- mysqli::real_query — Выполнение SQL запроса
- mysqli::reap_async_query — Получение результата асинхронного запроса
- mysqli::refresh — Обновляет таблицы или кеш
- mysqli::release_savepoint — Удаляет именованную точку сохранения из списка точек сохранения текущей транзакции
- mysqli::rollback — Откат текущей транзакции
- mysqli::savepoint — Установите именованную точку сохранения транзакции
- mysqli::select_db — Устанавливает базу данных для выполняемых запросов
- mysqli::set_charset — Задаёт набор символов
- mysqli::$sqlstate — Возвращает код состояния SQLSTATE последней MySQL операции
- mysqli::ssl_set — Используется для установления безопасных соединений, используя SSL
- mysqli::stat — Получение информации о текущем состоянии системы
- mysqli::stmt_init — Инициализирует запрос и возвращает объект для использования в mysqli_stmt_prepare
- mysqli::store_result — Передаёт на клиента результирующий набор последнего запроса
- mysqli::$thread_id — Возвращает ID потока текущего подключения
- mysqli::thread_safe — Показывает, безопасна ли работа с процессами
- mysqli::use_result — Готовит результирующий набор на сервере к использованию
- mysqli::$warning_count — Возвращает количество предупреждений, сгенерированных последним выполненным запросом

# The mysqli_stmt class

(PHP 5, PHP 7, PHP 8)

## Введение

Представляет подготовленное выражение.

## Обзор класса

class mysqli_stmt {
/* Свойства */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* Методы */
public function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): bool
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## Свойства

id

  Сохраняет идентификатор оператора.

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Возвращает общее количество строк, изменённых, удалённых, вставленных или сопоставленных последним выполненным выражением

### Описание

Объектно-ориентированный стиль

int|string $mysqli_stmt->affected_rows;

Процедурный стиль

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Возвращает количество строк, изменённых запросом `INSERT`, `UPDATE` или `DELETE`. Работает аналогично mysqli_stmt_num_rows() для выражений `SELECT`.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Целое число больше нуля указывает количество затронутых или извлечённых строк. Ноль означает, что записи для оператора `UPDATE` не обновлялись, ни одна строка не соответствовала выражению `WHERE` в запросе или что ни один запрос ещё не был выполнен. `-1` означает, что во время выполнения запроса произошла ошибка или что для запроса `SELECT`, mysqli_stmt_affected_rows() была вызваны до вызова mysqli_stmt_store_result().

> Замечание:

> Если количество изменённых строк больше, чем максимальное значение для целого числа в PHP, то это количество будет возвращено в виде строкового значения.

### Примеры

Пример #1 Пример использования mysqli_stmt_affected_rows()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* создание временной таблицы */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* подготовка выражения */
    $stmt = $mysqli->prepare($query);

    /* связывание переменных */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* выполнение выражения */
    $stmt->execute();

    printf("Добавлено строк: %d\n", $stmt->affected_rows);
    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* создание временной таблицы */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* подготовка выражения */
    $stmt = mysqli_prepare($link, $query);

    /* связывание переменных */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* выполнение выражения */
    mysqli_stmt_execute($stmt);

    printf("Добавлено строк: %d\n", mysqli_stmt_affected_rows($stmt));
    ?>

Результат выполнения приведённых примеров:

    Добавлено строк: 17

### Смотрите также

- mysqli_stmt_num_rows() - Возвращает количество строк, полученных с сервера
- mysqli_stmt_store_result() - Сохраняет набор результатов во внутреннем буфере

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Получает текущее значение атрибута запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::attr_get(int `$attribute`): int

Процедурный стиль

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Используется для получения текущего значения атрибута запроса.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`attribute`

  Атрибут, который необходимо получить.

### Возвращаемые значения

Возвращает текущее значение атрибута.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Изменяет поведение подготовленного запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

Процедурный стиль

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Функция изменяет поведение подготовленного запроса. Функцию вызывают несколько раз для установки нескольких атрибутов.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`attribute`

  Атрибут, который требуется установить. Атрибут принимает следующие значения:

  Значения атрибута
  Символ | Описание
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Если значение равно `true`, то функция mysqli_stmt_store_result() обновляет метаданные значением `MYSQL_FIELD->max_length`.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Тип курсора, который нужно открыть для запроса при вызове функции mysqli_stmt_execute(). Параметр `value` принимает значения `MYSQLI_CURSOR_TYPE_NO_CURSOR` (по умолчанию) или `MYSQLI_CURSOR_TYPE_READ_ONLY`.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Количество строк, которые необходимо получить с сервера с курсором за один раз. Параметр `value` принимает значения в диапазоне от 1 до максимального значения беззнакового целого числа long. По умолчанию значение равно 1. Константа удалена с PHP 8.4.0.

  Если опцию `MYSQLI_STMT_ATTR_CURSOR_TYPE` указали вместе с `MYSQLI_CURSOR_TYPE_READ_ONLY`, то курсор открывается для запроса при вызове функции mysqli_stmt_execute(). Если уже есть открытый курсор из предыдущего вызова функции mysqli_stmt_execute(), то курсор закроется перед открытием нового. Функция mysqli_stmt_reset() также закрывает любой открытый курсор перед подготовкой запроса к повторному выполнению. Функция mysqli_stmt_free_result() закрывает любой открытый курсор.

  Если курсор открывается для подготовленного запроса, вызывать функцию mysqli_stmt_store_result() не обязательно.

`value`

  Значение, которое функция присвоит атрибуту.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Смотрите также

- » Connector/MySQL mysql_stmt_attr_set()

# mysqli_stmt::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Привязка переменных к параметрам подготавливаемого запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

Процедурный стиль

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Привязывает переменные к меткам параметров в SQL-выражении, которое было подготовлено функцией mysqli_prepare() или mysqli_stmt_prepare().

> Замечание:

> Если размер данных переменной превышает максимально допустимый размер пакета (max_allowed_packet), необходимо задать значение `b` параметру `types` и использовать функцию mysqli_stmt_send_long_data(), которая будет передавать данные пакетами.

> Замечание:

> При использовании mysqli_stmt_bind_param() совместно с call_user_func_array() необходимо соблюдать особую осторожность. Нужно принимать во внимание, что mysqli_stmt_bind_param() принимает в качестве параметров только ссылки на значения, в то время как call_user_func_array() принимает список параметров, которые могут передаваться как по ссылке, так и по значению.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`types`

  Строка, содержащая один или более символов, каждый из которых задаёт тип значения привязываемой переменной:

  Символы задающие тип
  Символ | Описание
  --- | ---
  i | у соответствующей переменной тип int
  d | у соответствующей переменной тип float
  s | у соответствующей переменной тип string
  b | соответствующая переменная является большим двоичным объектом (blob) и будет пересылаться пакетами

`var`
`vars`

  Количество переменных и длина строки `types` должны в точности соответствовать количеству параметров в запросе.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli_stmt::bind_param()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    $stmt->bind_param('sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    $stmt->execute();

    printf("строк добавлено: %d.\n", $stmt->affected_rows);

    /* Clean up table CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("строк удалено: %d.\n", $mysqli->affected_rows);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    $stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    mysqli_stmt_execute($stmt);

    printf("строк добавлено: %d.\n", mysqli_stmt_affected_rows($stmt));

    /* Clean up table CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("строк удалено: %d.\n", mysqli_affected_rows($link));

Результат выполнения приведённых примеров:

    строк добавлено: 1.
    1 row deleted.

Пример #2 Пример использования `...` для предоставления аргументов

Оператор `...` может использоваться для предоставления списка аргументов переменной длины, например в конструкции `WHERE IN`.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
    /* использование ... для предоставления аргументов */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("найдено строк: %d.\n", $stmt->num_rows());

Результат выполнения приведённых примеров:

    найдено строк: 10.

### Смотрите также

- mysqli_stmt_bind_result() - Привязка переменных к подготовленному запросу для размещения результата
- mysqli_stmt_execute() - Выполняет подготовленное утверждение
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными
- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_send_long_data() - Отправка данных блоками
- mysqli_stmt_errno() - Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt_error() - Возвращает строку с пояснением последней ошибки при выполнении запроса

# mysqli_stmt::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Привязка переменных к подготовленному запросу для размещения результата

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

Процедурный стиль

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Привязывает столбцы результирующего набора к переменным.

При вызове mysqli_stmt_fetch() для выборки данных, протокол клиент-серверного взаимодействия MySQL помещает выбранные данные в переменные `var`/`vars`, привязанные к столбцам результата выборки.

Столбцы можно привязывать и перепривязывать многократно, даже когда результирующий набор уже частично выбран. Новая привязка даст эффект при следующем вызове mysqli_stmt_fetch().

> Замечание:

> Все столбцы должны быть привязаны к переменным после вызова mysqli_stmt_execute() и до вызова mysqli_stmt_fetch(). В зависимости от типов данных столбцов привязанные переменные могут неявно изменять свой PHP тип.

> Замечание:

> В зависимости от типов столбцов связанные переменные могут незаметно изменяться на соответствующий тип PHP.

Подсказка

Функция полезна для простых результатов. Чтобы получить повторяемый набор результатов или каждую строку как массив или объект, используйте mysqli_stmt_get_result().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`var`

  Привязываемая переменная.

`vars`

  Остальные привязываемые переменные.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* подготовка запроса */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* привязка переменных к подготовленному запросу */
    $stmt->bind_result($col1, $col2);

    /* получение значений */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* подготовка запроса */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* привязка переменных к подготовленному запросу */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* получение значений */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }

Результат выполнения приведённых примеров:

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### Смотрите также

- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt_execute() - Выполняет подготовленное утверждение
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными
- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_prepare() - Подготавливает утверждение SQL к выполнению

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Закрывает подготовленный запрос

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::close(): true

Процедурный стиль

function mysqli_stmt_close(mysqli_stmt `$statement`): true

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

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает значение `true`. Ранее она возвращала значение `false` в случае возникновения ошибки.

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Конструктор для объекта mysqli_stmt

### Описание

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

Этот метод создаёт новый объект класса mysqli_stmt.

### Список параметров

`link`

  Корректный объект mysqli.

`query`

  Строка, содержащая SQL-запрос. Если данный параметр `null`, то результат будет аналогичен вызову mysqli_stmt_init(), в противном случае результат будет аналогичен вызову mysqli_prepare().

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `query` теперь допускает значение null.

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_init() - Инициализирует запрос и возвращает объект для использования в mysqli_stmt_prepare

# mysqli_stmt::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Корректирует указатель результата на произвольную строку в буферизованном результате

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::data_seek(int `$offset`): void

Процедурный стиль

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

Функция перемещает указатель буферизованного набора результатов в произвольную строку, заданную параметром `offset`.

Функция работает только с буферизованным внутренним набором результатов. Функция mysqli_stmt_store_result() должна быть вызвана до mysqli_stmt_data_seek().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`offset`

  Значение должно быть в диапазоне от 0 до числа строк минус один (0.. mysqli_stmt_num_rows() - 1).

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    $stmt->bind_result($name, $code);

    $stmt->store_result();

    /* переходим к строке 400 результирующей таблицы */
    $stmt->data_seek(399);

    $stmt->fetch();

    printf("Город: %s  Код страны: %s\n", $name, $code);
    ?>

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = mysqli_prepare($link, $query);

    mysqli_stmt_execute($stmt);

    mysqli_stmt_bind_result($stmt, $name, $code);

    mysqli_stmt_store_result($stmt);

    /* переходим к строке 400 результирующей таблицы */
    mysqli_stmt_data_seek($stmt, 399);

    mysqli_stmt_fetch($stmt);

    printf("Город: %s  Код страны: %s\n", $name, $code);
    ?>

Результат выполнения приведённых примеров:

    Город: Benin City  Код страны: NGA

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_store_result() - Сохраняет набор результатов во внутреннем буфере
- mysqli_stmt_num_rows() - Возвращает количество строк, полученных с сервера
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Возвращает код ошибки выполнения последнего запроса

### Описание

Объектно-ориентированный стиль

int $mysqli_stmt->errno;

Процедурный стиль

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

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

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Код ошибки. Ноль означает отсутствие ошибок.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    /* открываем соединение */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* удаляем таблицу */
        $mysqli->query("DROP TABLE myCountry");

        /* выполняем запрос */
        $stmt->execute();

        printf("Ошибка: %d.\n", $stmt->errno);

        /* закрываем запрос */
        $stmt->close();
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    /* открываем соединение */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* удаляем таблицу */
        mysqli_query($link, "DROP TABLE myCountry");

        /* выполняем запрос */
        mysqli_stmt_execute($stmt);

        printf("Ошибка: %d.\n", mysqli_stmt_errno($stmt));

        /* закрываем запрос */
        mysqli_stmt_close($stmt);
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Ошибка: 1146.

### Смотрите также

- mysqli_stmt_error() - Возвращает строку с пояснением последней ошибки при выполнении запроса
- mysqli_stmt_sqlstate() - Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Возвращает строку с пояснением последней ошибки при выполнении запроса

### Описание

Объектно-ориентированный стиль

string $mysqli_stmt->error;

Процедурный стиль

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Возвращает строку с сообщением об ошибке для последнего вызова функции, которая могла её вызвать.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Строка сообщения об ошибке. Пустая строка означает отсутствие ошибок.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    /* открываем соединение */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* удаляем таблицу */
        $mysqli->query("DROP TABLE myCountry");

        /* выполняем запрос */
        $stmt->execute();

        printf("Ошибка: %s.\n", $stmt->error);

        /* закрываем запрос */
        $stmt->close();
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    /* открываем соединение */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* удаляем таблицу */
        mysqli_query($link, "DROP TABLE myCountry");

        /* выполняем запрос */
        mysqli_stmt_execute($stmt);

        printf("Ошибка: %s.\n", mysqli_stmt_error($stmt));

        /* закрываем запрос */
        mysqli_stmt_close($stmt);
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Ошибка: Table 'world.myCountry' doesn't exist.

### Смотрите также

- mysqli_stmt_errno() - Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt_sqlstate() - Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом

# mysqli_stmt::$error_list

# mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — Возвращает список ошибок выполнения последнего запроса

### Описание

Объектно-ориентированный стиль

array $mysqli_stmt->error_list;

Процедурный стиль

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Возвращает список ошибок, возникших при выполнении последней операции над запросом, которая может завершаться успешно или неуспешно.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Список ошибок, каждая из которых представлена в виде массива (array), содержащего код ошибки, сообщение об ошибке, а также код состояния sqlstate.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    /* открываем соединение */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* удаляем таблицу */
        $mysqli->query("DROP TABLE myCountry");

        /* выполняем запрос */
        $stmt->execute();

        echo "Ошибка:\n";
        print_r($stmt->error_list);

        /* закрываем запрос */
        $stmt->close();
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    /* открываем соединение */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* удаляем таблицу */
        mysqli_query($link, "DROP TABLE myCountry");

        /* выполняем запрос */
        mysqli_stmt_execute($stmt);

        echo "Ошибка:\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* закрываем запрос */
        mysqli_stmt_close($stmt);
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Ошибка:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### Смотрите также

- mysqli_stmt_error() - Возвращает строку с пояснением последней ошибки при выполнении запроса
- mysqli_stmt_errno() - Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt_sqlstate() - Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Выполняет подготовленное утверждение

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::execute(?array `$params` = `null`): bool

Процедурный стиль

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Выполняет заранее подготовленное утверждение. Утверждение должно быть успешно подготовлено перед выполнением с использованием функции mysqli_prepare() или mysqli_stmt_prepare(), либо путём передачи второго аргумента в mysqli_stmt::__construct().

Если выполняются запросы `UPDATE`, `DELETE`, или `INSERT`, то количество изменённых строк можно определить функцией mysqli_stmt_affected_rows(). Если запрос возвращает набор результатов, его можно получить с помощью функции mysqli_stmt_get_result() или путём получения построчно непосредственно из оператора с помощью функции mysqli_stmt_fetch().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`params`

  Необязательный массив элементов (array) с количеством элементов равным количеству связанных параметров в выполняемом SQL-запросе. Каждое значение рассматривается как строка (string).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Добавлен необязательный параметр `params`.

### Примеры

Пример #1 Выполнение подготовленного оператора с привязкой переменных

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

    /* Подготавливаем утверждение на вставку строк */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Связываем переменные с метками */
    $stmt->bind_param("sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Выполняем утверждение */
    $stmt->execute();

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Выполняем утверждение */
    $stmt->execute();

    /* Получаем все строки из myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

    /* Подготавливаем утверждение на вставку строк */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Связываем переменные с метками */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Выполняем утверждение */
    mysqli_stmt_execute($stmt);

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Выполняем утверждение */
    mysqli_stmt_execute($stmt);

    /* Получаем все строки из myCity */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Результат выполнения приведённых примеров:

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

Пример #2 Выполнение подготовленного оператора с массивом значений

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

    /* Подготавливаем утверждение на вставку строк */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Выполняем утверждение */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Получаем все строки из myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

    /* Подготавливаем утверждение на вставку строк */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Выполняем утверждение */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Получаем все строки из myCity */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Результат выполнения приведённых примеров:

    Stuttgart (DEU,Baden-Wuerttemberg)

### Смотрите также

- mysqli_execute_query() - Подготавливает, связывает параметры и выполняет SQL-запрос
- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Связывает результаты подготовленного запроса с переменными

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::fetch(): ?bool

Процедурный стиль

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Функция связывает результаты подготовленного выражения с переменными, которые определили функцией mysqli_stmt_bind_result().

> Замечание:

> Обратите внимание, что каждый столбец требуется связать перед вызовом функции mysqli_stmt_fetch().

> Замечание:

> Функция не буферизует данные при передаче без вызова функции mysqli_stmt_store_result(), что снижает производительность (но также снижает затраты памяти).

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращаемые значения
Значение | Описание
--- | ---
`true` | Успех. Функция получила данные
`false` | Возникла ошибка
`null` | Больше нет строк и данных или возникло усечение данных

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Попытка соединения не удалась: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {
        /* Выполняем запрос */
        $stmt->execute();

        /* Связываем переменные результата */
        $stmt->bind_result($name, $code);

        /* Получаем значения */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Завершаем запрос */
        $stmt->close();
    }

    /* Закрываем соединение */
    $mysqli->close();

    ?>

Пример #2 Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Попытка соединения не удалась: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = mysqli_prepare($link, $query)) {
        /* Выполняем запрос */
        mysqli_stmt_execute($stmt);

        /* Связываем переменные результата */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* Получаем значения */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Завершаем запрос */
        mysqli_stmt_close($stmt);
    }

    /* Закрываем соединение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_errno() - Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt_error() - Возвращает строку с пояснением последней ошибки при выполнении запроса
- mysqli_stmt_bind_result() - Привязка переменных к подготовленному запросу для размещения результата

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Возвращает число столбцов в заданном выражении

### Описание

Объектно-ориентированный стиль

int $mysqli_stmt->field_count;

Процедурный стиль

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Возвращает число столбцов в подготовленном выражении.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает целое число, представляющее количество столбцов.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
    $stmt->bind_param('s', $code);
    $stmt->execute();
    $row = $stmt->get_result()->fetch_row();
    for ($i = 0; $i < $stmt->field_count; $i++) {
        printf("Значение номера столбца %d - %s", $i, $row[$i]);
    }

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
    mysqli_stmt_bind_param($stmt, 's', $code);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);
    $row = mysqli_fetch_row($result);
    for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
        printf("Значение номера столбца %d - %s", $i, $row[$i]);
    }

Вывод приведённых примеров будет похож на:

    Значение номера столбца 0 - France

### Смотрите также

- mysqli_stmt_num_rows() - Возвращает количество строк, полученных с сервера

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Освобождает память от результата запроса, указанного дескриптором

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::free_result(): void

Процедурный стиль

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Освобождает от результата запроса память, которая была зарезервирована с помощью mysqli_stmt_store_result().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- mysqli_stmt_store_result() - Сохраняет набор результатов во внутреннем буфере

# mysqli_stmt::get_result

# mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — Получает результат из подготовленного запроса в виде объекта mysqli_result

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::get_result(): mysqli_result|false

Процедурный стиль

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Извлекает набор результатов из подготовленного запроса в виде объекта mysqli_result. Данные будут загружены с сервера MySQL в PHP. Метод следует вызывать только для запросов, которые производят набор результатов.

> Замечание:

> Доступно только с модулем mysqlnd.

> Замечание:

> Эту функцию нельзя использовать совместно с mysqli_stmt_store_result(). Обе эти функции получают полный набор результатов с сервера MySQL.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает `false` в случае возникновения ошибки. Для успешных запросов, которые производят набор результатов, таких как `SELECT, SHOW, DESCRIBE` или `EXPLAIN` mysqli_stmt_get_result() вернёт объект mysqli_result. Для других успешных запросов mysqli_stmt_get_result() вернёт `false`. Функцию mysqli_stmt_errno() можно использовать, чтобы различать две причины появления `false`; из-за ошибки до PHP 7.4.13 для этой цели приходилось использовать mysqli_errno().

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param("s", $continent);

    $continentList = array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continentList= array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        mysqli_stmt_execute($stmt);
        $result = mysqli_stmt_get_result($stmt);
        while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Вывод приведённых примеров будет похож на:

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_result_metadata() - Возвращает метаданные результирующей таблицы подготавливаемого запроса
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными
- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_stmt_store_result() - Сохраняет набор результатов во внутреннем буфере

# mysqli_stmt::get_warnings

# mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Получает результат от SHOW WARNINGS

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::get_warnings(): mysqli_warning|false

Процедурный стиль

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Получает ID, сгенерированный предыдущей операцией INSERT

### Описание

Объектно-ориентированный стиль

int|string $mysqli_stmt->insert_id;

Процедурный стиль

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

# mysqli_stmt::more_results

# mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — Проверяет, есть ли ещё наборы строк в результате мультизапроса

### Описание

Объектно-ориентированный стиль:

public function mysqli_stmt::more_results(): bool

Процедурный стиль:

function mysqli_stmt_more_results(mysqli_stmt `$statement`): bool

Проверяет, есть ли ещё наборы строк в результате мультизапроса.

> Замечание:

> Доступно только с модулем mysqlnd.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает `true`, если ещё есть доступные результирующие наборы, `false` в противном случае.

### Смотрите также

- mysqli_stmt::next_result() - Читает следующий набор строк из мультизапроса
- mysqli::multi_query() - Выполняет запросы к базе данных

# mysqli_stmt::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — Читает следующий набор строк из мультизапроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::next_result(): bool

Процедурный стиль:

function mysqli_stmt_next_result(mysqli_stmt `$statement`): bool

Читает следующий набор строк из мультизапроса.

> Замечание:

> До PHP 8.1.0, функция доступна только с mysqlnd.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Теперь также доступно при сборке с libmysqlclient.

### Смотрите также

- mysqli_stmt::more_results() - Проверяет, есть ли ещё наборы строк в результате мультизапроса
- mysqli::multi_query() - Выполняет запросы к базе данных

# mysqli_stmt::$num_rows

# mysqli_stmt::num_rows

# mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — Возвращает количество строк, полученных с сервера

### Описание

Объектно-ориентированный стиль

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

Процедурный стиль

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Возвращает количество строк, помещённых в буфер в выражении. Функция будет работать только после вызова mysqli_stmt_store_result() для буферизации всего набора результатов в дескрипторе оператора.

Функция возвращает `0`, если с сервера не были получены все строки.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Целое число (int), представляющее количество буферизованных строк. Возвращает `0` в небуферизованном режиме, если с сервера не были получены все строки.

> Замечание: Если количество строк больше, чем `PHP_INT_MAX`, число будет возвращено как строка (string).

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* сохранение результата во внутреннем буфере */
    $stmt->store_result();

    printf("Число строк: %d.\n", $stmt->num_rows);

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* сохранение результата во внутреннем буфере */
    mysqli_stmt_store_result($stmt);

    printf("Число строк: %d.\n", mysqli_stmt_num_rows($stmt));

Результат выполнения приведённых примеров:

    Число строк: 20.

### Смотрите также

- mysqli_stmt_store_result() - Сохраняет набор результатов во внутреннем буфере
- mysqli_stmt_affected_rows() - Возвращает общее количество строк, изменённых, удалённых, вставленных или сопоставленных последним выполненным выражением
- mysqli_prepare() - Подготавливает SQL выражение к выполнению

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Возвращает количество параметров в запросе

### Описание

Объектно-ориентированный стиль

int $mysqli_stmt->param_count;

Процедурный стиль

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Возвращает количество меток параметров в подготовленном запросе.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает целое число равное количеству параметров.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("В запросе %d меток.\n", $marker);

        /* закрываем запрос */
        $stmt->close();
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = mysqli_stmt_param_count($stmt);
        printf("В запросе %d меток.\n", $marker);

        /* закрываем запрос */
        mysqli_stmt_close($stmt);
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    В запросе 2 меток.

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Подготавливает утверждение SQL к выполнению

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::prepare(string `$query`): bool

Процедурный стиль

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Подготавливает утверждение к выполнению. Запрос должен состоять из одного оператора SQL.

Шаблон утверждения может содержать ноль или несколько вопросительных знаков (`?`), меток параметров, также называемых заполнителями. Метки параметров должны быть привязаны к переменным приложения с помощью mysqli_stmt_bind_param() перед выполнением утверждения. строк.

> Замечание:

> В случае, если длина выражения, которое передаётся в mysqli_stmt_prepare(), больше, чем `max_allowed_packet` сервера, возвращаемые коды ошибки могут различаться в зависимости от используемого драйвера. А это может быть либо родной MySQL-драйвер (`mysqlnd`), либо клиентская библиотека MySQL (`libmysqlclient`). Поведение функции будет следующим:

> - `mysqlnd` на платформе Linux возвращает код ошибки 1153. Сообщение об ошибке означает размер пакета превышает `max_allowed_packet` байт.

> - `mysqlnd` на платформе Windows возвращает код ошибки 2006. Это сообщение об ошибке означает сервер недоступен.

> - `libmysqlclient` на всех платформах возвращает код ошибки 2006. Это сообщение об ошибке означает сервер недоступен.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`query`

  Текст запроса в виде строки. Запрос должен состоять из одного SQL-выражения.

  Утверждение SQL может содержать ноль или более меток параметров, представленных знаками вопроса (`?`) в соответствующих позициях.

  > Замечание:

  > Метки параметров запроса можно встраивать только в определённые места в выражении. Например, они допустимы в списке `VALUES()` выражения `INSERT` (чтобы задать значения столбцов для строки), или в операциях сравнения предложения `WHERE` для задания сравниваемого значения. Однако, эти метки недопустимы в качестве идентификаторов (таких как имена столбцов или таблиц).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример использования mysqli_stmt::prepare()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Создаём подготовленное утверждение */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* Связываем переменные с метками */
    $stmt->bind_param("s", $city);

    /* Выполняем запрос */
    $stmt->execute();

    /* Связываем переменные результата */
    $stmt->bind_result($district);

    /* Получаем значение */
    $stmt->fetch();

    printf("%s находится в районе %s\n", $city, $district);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Создаём подготовленное утверждение */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* Связываем переменные с метками */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* Выполняем запрос */
    mysqli_stmt_execute($stmt);

    /* Связываем переменные результата */
    mysqli_stmt_bind_result($stmt, $district);

    /* Получаем значение */
    mysqli_stmt_fetch($stmt);

    printf("%s находится в районе %s\n", $city, $district);

Результат выполнения приведённых примеров:

    Amersfoort находится в районе Utrecht

### Смотрите также

- mysqli_stmt_init() - Инициализирует запрос и возвращает объект для использования в mysqli_stmt_prepare
- mysqli_stmt_execute() - Выполняет подготовленное утверждение
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt_bind_result() - Привязка переменных к подготовленному запросу для размещения результата
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result
- mysqli_stmt_close() - Закрывает подготовленный запрос

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Сбрасывает результаты выполнения подготовленного запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::reset(): bool

Процедурный стиль

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Сбрасывает результаты выполнения подготовленного запроса на клиенте и на сервере и переводит запрос в состояние, как после подготовки.

Сбрасывает запрос на сервере, а также данные, переданные на сервер функцией mysqli_stmt_send_long_data(), очищает буфер результатов запроса и текущие ошибки. Функция не удаляет привязки параметров запроса, а также переданные на клиента результирующие наборы. Содержащиеся на клиенте результирующие наборы будут очищены при следующем выполнении запроса (или его закрытии).

Для подготовки запроса с другим SQL-текстом, используйте функцию mysqli_stmt_prepare().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Возвращает метаданные результирующей таблицы подготавливаемого запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::result_metadata(): mysqli_result|false

Процедурный стиль

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

Если запрос, переданный в mysqli_prepare(), генерирует результирующую таблицу, mysqli_stmt_result_metadata() возвращает объект, с помощью которого можно получить описание этого результирующего набора. В частности, можно получить количество полей и описание каждого отдельного поля.

Функция возвращает пустой объект mysqli_result, который можно использовать для доступа к метаданным из подготовленного запроса без необходимости извлекать фактические строки данных. Нет необходимости использовать её при использовании функции mysqli_stmt_get_result() для извлечения всего набора результатов из подготовленного запроса в виде объекта результата.

> Замечание:

> Полученный объектный указатель можно передавать в качестве аргумента в функции обработки метаданных результирующих таблиц, как например:

> - mysqli_num_fields()

> - mysqli_fetch_field()

> - mysqli_fetch_field_direct()

> - mysqli_fetch_fields()

> - mysqli_field_count()

> - mysqli_field_seek()

> - mysqli_field_tell()

> - mysqli_free_result()

> Замечание: Результирующий набор, возвращаемый из mysqli_stmt_result_metadata(), содержит только метаданные. В нем не будет строк выборки. Результаты запроса можно получить с помощью функции mysqli_stmt_fetch().

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает объект или `false` случае возникновения ошибки. Если оператор не возвращает набор результатов, также возвращается значение `false`.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("DROP TABLE IF EXISTS friends");
    $mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = $mysqli->prepare("SELECT id, name FROM friends");
    $stmt->execute();

    /* получаем результирующий набор метаданных */
    $result = $stmt->result_metadata();

    /* извлекаем информацию о столбце из метаданных */
    $field = $result->fetch_field();

    printf("Имя столбца: %s\n", $field->name);
    ?>

Пример #2 Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
    mysqli_stmt_execute($stmt);

    /* получаем результирующий набор метаданных */
    $result = mysqli_stmt_result_metadata($stmt);

    /* извлекаем информацию о столбце из метаданных */
    $field = mysqli_fetch_field($result);

    printf("Имя столбца: %s\n", $field->name);
    ?>

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_free_result() - Освобождает память, занятую результатами запроса
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result

# mysqli_stmt::send_long_data

# mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Отправка данных блоками

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

Процедурный стиль

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Позволяет пересылать данные параметра на сервер частями (или чанками), например, когда размер большого объекта (blob) превышает `max_allowed_packet`. Эту функцию можно запускать многократно, чтобы переслать части символьных или двоичных данных столбца. Данные в столбце должны иметь тип TEXT или BLOB.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().
`param_num`

  Указывает, с каким параметром связаны данные. Параметры нумеруются с нуля.

`data`

  Строка, содержащая пересылаемые данные.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
    $null = NULL;
    $stmt->bind_param("b", $null);
    $fp = fopen("messages.txt", "r");
    while (!feof($fp)) {
        $stmt->send_long_data(0, fread($fp, 8192));
    }
    fclose($fp);
    $stmt->execute();
    ?>

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_bind_param() - Привязка переменных к параметрам подготавливаемого запроса

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом

### Описание

Объектно-ориентированный стиль

string $mysqli_stmt->sqlstate;

Процедурный стиль

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Возвращает строку содержащую код SQLSTATE ошибки, вызванной в результате выполнения последней операции над запросом, которая может завершаться успешно или неуспешно. Этот код состоит из пяти символов. `'00000'` означает отсутствие ошибок. Значения этого кода определены в стандарте ANSI SQL, а также в ODBC. Полный список возможных кодов можно посмотреть на странице » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Возвращает строку, содержащую код ошибки SQLSTATE последней совершенной операции. Этот код состоит из пяти символов. `'00000'` означает отсутствие ошибок.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    /* Открываем соединение */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* удаляем таблицу */
        $mysqli->query("DROP TABLE myCountry");

        /* выполняем запрос */
        $stmt->execute();

        printf("Ошибка: %s.\n", $stmt->sqlstate);

        /* закрываем запрос */
        $stmt->close();
    }

    /* закрываем соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    /* Открываем соединение */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* удаляем таблицу */
        mysqli_query($link, "DROP TABLE myCountry");

        /* выполняем запрос */
        mysqli_stmt_execute($stmt);

        printf("Ошибка: %s.\n", mysqli_stmt_sqlstate($stmt));

        /* закрываем запрос */
        mysqli_stmt_close($stmt);
    }

    /* закрываем соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Ошибка: 42S02.

### Примечания

> Замечание:

> Следует отметить, что ещё не все ошибки MySQL имеют отражение в кодах SQLSTATE. Для таких ошибок используется общий код `HY000` (общая ошибка).

### Смотрите также

- mysqli_stmt_errno() - Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt_error() - Возвращает строку с пояснением последней ошибки при выполнении запроса

# mysqli_stmt::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Сохраняет набор результатов во внутреннем буфере

### Описание

Объектно-ориентированный стиль

public function mysqli_stmt::store_result(): bool

Процедурный стиль

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

Функцию следует вызывать для запросов, которые успешно создают набор результатов (например, `SELECT, SHOW, DESCRIBE, EXPLAIN`), только если необходимо буферизовать в PHP полный набор результатов. Каждый последующий вызов mysqli_stmt_fetch() будет возвращать буферизованные данные.

> Замечание:

> В остальных случаях вызывать mysqli_stmt_store_result() нет необходимости. Но если такой вызов совершён, ничего страшного не случится, это не повлияет на производительность и целостность данных. Чтобы убедиться, что запрос вернул результирующий набор, можно воспользоваться функцией mysqli_stmt_result_metadata(), которая в этом случае вернёт `false`.

### Список параметров

`stmt`
  Только для процедурного стиля: объект mysqli_stmt, который вернула функция mysqli_stmt_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* сохранение результата во внутреннем буфере */
    $stmt->store_result();

    printf("Число строк: %d.\n", $stmt->num_rows);

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* сохранение результата во внутреннем буфере */
    mysqli_stmt_store_result($stmt);

    printf("Число строк: %d.\n", mysqli_stmt_num_rows($stmt));
    ?>

Результат выполнения приведённых примеров:

    Количество строк: 20.

### Смотрите также

- mysqli_prepare() - Подготавливает SQL выражение к выполнению
- mysqli_stmt_result_metadata() - Возвращает метаданные результирующей таблицы подготавливаемого запроса
- mysqli_stmt_fetch() - Связывает результаты подготовленного запроса с переменными

## Содержание

- mysqli_stmt::$affected_rows — Возвращает общее количество строк, изменённых, удалённых, вставленных или сопоставленных последним выполненным выражением
- mysqli_stmt::attr_get — Получает текущее значение атрибута запроса
- mysqli_stmt::attr_set — Изменяет поведение подготовленного запроса
- mysqli_stmt::bind_param — Привязка переменных к параметрам подготавливаемого запроса
- mysqli_stmt::bind_result — Привязка переменных к подготовленному запросу для размещения результата
- mysqli_stmt::close — Закрывает подготовленный запрос
- mysqli_stmt::__construct — Конструктор для объекта mysqli_stmt
- mysqli_stmt::data_seek — Корректирует указатель результата на произвольную строку в буферизованном результате
- mysqli_stmt::$errno — Возвращает код ошибки выполнения последнего запроса
- mysqli_stmt::$error — Возвращает строку с пояснением последней ошибки при выполнении запроса
- mysqli_stmt::$error_list — Возвращает список ошибок выполнения последнего запроса
- mysqli_stmt::execute — Выполняет подготовленное утверждение
- mysqli_stmt::fetch — Связывает результаты подготовленного запроса с переменными
- mysqli_stmt::$field_count — Возвращает число столбцов в заданном выражении
- mysqli_stmt::free_result — Освобождает память от результата запроса, указанного дескриптором
- mysqli_stmt::get_result — Получает результат из подготовленного запроса в виде объекта mysqli_result
- mysqli_stmt::get_warnings — Получает результат от SHOW WARNINGS
- mysqli_stmt::$insert_id — Получает ID, сгенерированный предыдущей операцией INSERT
- mysqli_stmt::more_results — Проверяет, есть ли ещё наборы строк в результате мультизапроса
- mysqli_stmt::next_result — Читает следующий набор строк из мультизапроса
- mysqli_stmt::$num_rows — Возвращает количество строк, полученных с сервера
- mysqli_stmt::$param_count — Возвращает количество параметров в запросе
- mysqli_stmt::prepare — Подготавливает утверждение SQL к выполнению
- mysqli_stmt::reset — Сбрасывает результаты выполнения подготовленного запроса
- mysqli_stmt::result_metadata — Возвращает метаданные результирующей таблицы подготавливаемого запроса
- mysqli_stmt::send_long_data — Отправка данных блоками
- mysqli_stmt::$sqlstate — Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом
- mysqli_stmt::store_result — Сохраняет набор результатов во внутреннем буфере

# Класс mysqli_result

(PHP 5, PHP 7, PHP 8)

## Введение

Представляет результирующий набор, полученный из запроса в базу данных.

## Обзор класса

class mysqli_result implements IteratorAggregate {
/* Свойства */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* Методы */
public function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## Свойства

type

  Сохраняет буферизованный или небуферизованный результат в виде целого числа (int) (`MYSQLI_STORE_RESULT` или `MYSQLI_USE_RESULT` соответственно).

## Список изменений

Версия | Описание
--- | ---
8.0.0 | Класс mysqli_result теперь реализует интерфейс IteratorAggregate. Ранее вместо него был реализован интерфейс Traversable.

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Конструктор объекта mysqli_result

### Описание

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

Метод создаёт новый объект mysqli_result.

Метод можно использовать для создания объекта mysqli_result после вызова функции mysqli_real_query() или mysqli_multi_query(). Создание объекта вручную эквивалентно вызову функции mysqli_store_result() или mysqli_use_result().

### Список параметров

`mysql`
  Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
`result_mode`

  Режим результата может быть одной из двух констант, указывающих, как результат будет возвращён сервером MySQL:

  `MYSQLI_STORE_RESULT` (по умолчанию) - создаёт объект mysqli_result с буферизованным набором результатов.

  `MYSQLI_USE_RESULT` - создаёт объект mysqli_result с небуферизованным набором результатов. Пока есть ожидающие выборки записи, линия соединения будет занята и все последующие вызовы будут возвращать ошибку `Commands out of sync` (Команды не синхронизированы). Чтобы избежать ошибки, все записи должны быть получены с сервера или набор результатов должен быть отброшен путём вызова функции mysqli_free_result(). Для извлечения строк соединение должно оставаться открытым.

### Ошибки

Если уведомления об ошибках mysqli включены (`MYSQLI_REPORT_ERROR`) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим `MYSQLI_REPORT_STRICT`, вместо этого будет выброшено исключение mysqli_sql_exception.

### Примеры

Пример #1 Пример создания объекта mysqli_result

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* SELECT-запросы возвращают набор результатов */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("Запрос вернул %d записей.\n", $result->num_rows);

Вывод приведённых примеров будет похож на:

    Запрос вернул 10 записей.

### Смотрите также

- mysqli_multi_query() - Выполняет запросы к базе данных
- mysqli_real_query() - Выполнение SQL запроса
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Получает смещение указателя по отношению к текущему полю

### Описание

Объектно-ориентированный стиль

int $mysqli_result->current_field;

Процедурный стиль

function mysqli_field_tell(mysqli_result `$result`): int

Возвращает позицию указателя поля, используемую при последнем вызове mysqli_fetch_field(). Это значение может быть использовано как аргумент для mysqli_field_seek().

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Возвращает текущее смещение указателя поля.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Ошибка соединения: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Получить информацию о поле для всех столбцов */
        while ($finfo = $result->fetch_field()) {

            /* Получить смещение указателя поля */
            $currentfield = $result->current_field;

            printf("Столбец %d:\n", $currentfield);
            printf("Имя:     %s\n", $finfo->name);
            printf("Таблица:    %s\n", $finfo->table);
            printf("Макс. длина: %d\n", $finfo->max_length);
            printf("Флаги:    %d\n", $finfo->flags);
            printf("Тип:     %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Закрыть соединение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Ошибка соединения: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Получить информацию о поле для всех столбцов */
        while ($finfo = mysqli_fetch_field($result)) {

            /* Получить смещение указателя поля */
            $currentfield = mysqli_field_tell($result);

            printf("Столбец %d:\n", $currentfield);
            printf("Имя:     %s\n", $finfo->name);
            printf("Таблица:    %s\n", $finfo->table);
            printf("Макс. длина: %d\n", $finfo->max_length);
            printf("Флаги:    %d\n", $finfo->flags);
            printf("Тип:     %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Закрыть соединение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Столбец 1:
    Имя:     Name
    Таблица:    Country
    Макс. длина: 11
    Флаги:    1
    Тип:     254

    Столбец 2:
    Имя:     SurfaceArea
    Таблица:    Country
    Макс. длина: 10
    Флаги:    32769
    Тип:     4

### Смотрите также

- mysqli_fetch_field() - Возвращает следующее поле результирующего набора
- mysqli_field_seek() - Устанавливает указатель результата на заданное смещение поля

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Перемещает указатель результата на выбранную строку

### Описание

Объектно-ориентированный стиль

public function mysqli_result::data_seek(int `$offset`): bool

Процедурный стиль

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

Функция mysqli_data_seek() перемещает указатель в результате на строку, указанную в параметре `offset`.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`offset`

  Смещение строк. Должно быть между нулём и числом строк в результате минус один (0..mysqli_num_rows() - 1).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysqli::data_seek()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = $mysqli->query($query);

    /* Переход к строке 401 */
    $result->data_seek(400);

    /* Получение строки */
    $row = $result->fetch_row();

    printf("Город: %s  Код страны: %s\n", $row[0], $row[1]);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";

    $result = mysqli_query($link, $query);

    /* Переход к строке 401 */
    mysqli_data_seek($result, 400);

    /* Получение строки */
    $row = mysqli_fetch_row($result);

    printf ("Город: %s  Код страны: %s\n", $row[0], $row[1]);

Результат выполнения приведённых примеров:

    Город: Benin City  Код страны: NGA

Пример #2 Регулировка указателя результата при перемещении

Функция может быть полезна при перемещении по набору результатов для наложения настраиваемого порядка или перемотки набора результатов при многократном повторении.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
    $result = $mysqli->query($query);

    /* Перемещение по набору результатов в обратном порядке */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Получение строки */
        $row = $result->fetch_row();

        printf("Город: %s  Код страны: %s\n", $row[0], $row[1]);
    }

    /* Сброс указателя на начало набора результатов */
    $result->data_seek(0);

    print "\n";

    /* Снова перемещение по тому же набору результатов */
    while ($row = $result->fetch_row()) {
        printf("Город: %s  Код страны: %s\n", $row[0], $row[1]);
    }

Результат выполнения приведённых примеров:

    Город: Acmbaro  Код страны: MEX
    Город: Abuja  Код страны: NGA
    Город: Abu Dhabi  Код страны: ARE
    Город: Abottabad  Код страны: PAK

    Город: Abottabad  Код страны: PAK
    Город: Abu Dhabi  Код страны: ARE
    Город: Abuja  Код страны: NGA
    Город: Acmbaro  Код страны: MEX

### Примечания

> Замечание:

> Функция может быть использована только с буферизованными результатами, которые можно получить использованием функций mysqli_store_result() или mysqli_query().

### Смотрите также

- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_fetch_row() - Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_assoc() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_fetch_object() - Выбирает следующую строку из набора результатов в виде объекта
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_num_rows() - Получает количество строк в наборе результатов

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Выбирает все строки из результирующего набора и помещает их в ассоциативный массив, обычный массив или в оба

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

Процедурный стиль

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Возвращает двумерный массив всех строк результатов в виде ассоциативного массива, числового массива или обоих.

> Замечание:

> До PHP 8.1.0, функция доступна только с mysqlnd.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`mode`

  Этот необязательный параметр принимает значение константы, которая указывает на тип массива, в который требуется поместить данные. Возможные значения параметра: `MYSQLI_ASSOC`, `MYSQLI_NUM` или `MYSQLI_BOTH`.

### Возвращаемые значения

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

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Теперь также доступно при сборке с libmysqlclient.

### Примеры

Пример #1 Пример использования mysqli_result::fetch_all()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = $result->fetch_all(MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Результат выполнения приведённых примеров:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Смотрите также

- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_column() - Получает один столбец из следующей строки набора результатов
- mysqli_query() - Выполняет запрос к базе данных

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

Процедурный стиль

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Выбирает одну строку данных из набора результатов и возвращает её в виде массива. Каждый последующий вызов этой функции будет возвращать следующую строку в наборе результатов или `null`, если строк больше нет.

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

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

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`mode`

  Этот необязательный параметр принимает значение константы, которая указывает на тип массива, в который требуется поместить данные. Возможные значения параметра: `MYSQLI_ASSOC`, `MYSQLI_NUM` или `MYSQLI_BOTH`.

  При использовании константы `MYSQLI_ASSOC` функция будет вести себя идентично mysqli_fetch_assoc(), а при `MYSQLI_NUM` идентично функции mysqli_fetch_row(). При задании `MYSQLI_BOTH` функция создаст один массив, включающий атрибуты обоих вариантов.

### Возвращаемые значения

Возвращает массив, представляющий выбранную строку, `null`, если в наборе результатов больше нет строк или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysqli_result::fetch_array()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
    $result = $mysqli->query($query);

    /* числовой массив */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* ассоциативный массив */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* ассоциативный и числовой массивы */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
    $result = mysqli_query($mysqli, $query);

    /* числовой массив */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* ассоциативный массив */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* ассоциативный и числовой массивы */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Результат выполнения приведённых примеров:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Смотрите также

- mysqli_fetch_assoc() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_fetch_column() - Получает один столбец из следующей строки набора результатов
- mysqli_fetch_row() - Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_fetch_object() - Выбирает следующую строку из набора результатов в виде объекта
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_assoc(): array|null|false

Процедурный стиль

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Выбирает одну строку данных из набора результатов и возвращает её в виде ассоциативного массива. Каждый последующий вызов этой функции будет возвращать следующую строку в наборе результатов или `null`, если строк больше нет.

Если у двух и более столбцов в наборе результатов одинаковое имя, последний столбец будет иметь приоритет и перезапишет любые предыдущие данные. Для доступа к нескольким столбцам с одинаковым именем можно использовать функцию mysqli_fetch_row() для выборки массива с числовым индексом или в списке выбора SQL-запроса можно использовать псевдонимы, чтобы задать столбцам разные имена.

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Возвращает ассоциативный массив, представляющий выбранную строку, где каждое свойство представляет имя столбца набора результатов, `null`, если в наборе результатов больше нет строк или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysqli_result::fetch_assoc()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* извлечение ассоциативного массива */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* извлечение ассоциативного массива */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Вывод приведённых примеров будет похож на:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

Пример #2 Сравнение использования mysqli_result iterator и mysqli_result::fetch_assoc()

mysqli_result можно повторить с помощью `foreach`. Результирующий набор всегда будет повторяться с первой строки, независимо от текущей позиции.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

    // Используем итераторы
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // Не используем итераторы
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Вывод приведённого примера будет похож на:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

    ==================
    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Смотрите также

- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_column() - Получает один столбец из следующей строки набора результатов
- mysqli_fetch_row() - Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_fetch_object() - Выбирает следующую строку из набора результатов в виде объекта
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Получает один столбец из следующей строки набора результатов

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

Процедурный стиль

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Выбирает одну строку данных из набора результатов и возвращает столбец с указанным индексом, начиная с 0. Каждый последующий вызов этой функции будет возвращать значение из следующей строки в наборе результатов или `false`, если строк больше нет.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`column`

  Номер столбца, начиная с 0, который необходимо извлечь из строки. Если значение не указано, будет возвращён первый столбец.

### Возвращаемые значения

Возвращает один столбец из следующей строки набора результатов или `false`, если строк больше нет.

Внимание

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

### Примеры

Пример #1 Пример использования mysqli_result::fetch_column()

Объектно-ориентированный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");
    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";
    $result = $mysqli->query($query);
    /* получение значения из второго столбца */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

Процедурный стиль

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";
    $result = mysqli_query($mysqli, $query);
    /* получение значения из второго столбца */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

Вывод приведённых примеров будет похож на:

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### Смотрите также

- mysqli_fetch_all() - Выбирает все строки из результирующего набора и помещает их в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_assoc() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_fetch_object() - Выбирает следующую строку из набора результатов в виде объекта
- mysqli_fetch_row() - Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Возвращает следующее поле результирующего набора

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_field(): object|false

Процедурный стиль

function mysqli_fetch_field(mysqli_result `$result`): object|false

Метод возвращает информацию об одном столбце результирующего набора в виде объекта. Чтобы получить определения всех столбцов, просто запустите метод многократно.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Метод возвращает объект, который содержит определение поля или `false`, если столбцы в результирующей таблице закончились.

Свойства объекта
Свойство | Описание
--- | ---
name | Имя столбца
orgname | Исходное имя столбца, если указали псевдоним
table | Имя таблицы, которой принадлежит столбец (если не вычислено)
orgtable | Исходное имя таблицы, если указали псевдоним
def | Неиспользуемый. Всегда пустая строка
db | Имя базы данных
catalog | Неиспользуемый. Всегда `«def»`
max_length | Максимальная ширина поля результирующего набора. Начиная с PHP 8.1 это значение всегда равно `0`
length | Ширина поля в байтах. Для строковых столбцов значение длины зависит от кодировки соединения. Например, если кодировка — `latin1`, однобайтовый набор символов, значение длины для запроса `SELECT 'abc'` равно 3. Если кодировка — `utf8mb4`, многобайтовый набор символов, в котором символы занимают до 4 байтов, значение длины равно 12
charsetnr | Номер кодировки для поля
flags | Целое число, которое представляет битовые флаги для поля
type | Тип данных поля
decimals | Количество десятичных знаков для числовых полей и точность долей секунды для временных полей

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверяем подключение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Получаем информацию о каждом столбце */
        while ($finfo = $result->fetch_field()) {

            printf("Имя:         %s\n", $finfo->name);
            printf("Таблица:     %s\n", $finfo->table);
            printf("Макс. длина: %d\n", $finfo->max_length);
            printf("Флаги:       %d\n", $finfo->flags);
            printf("Тип:         %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Закрываем подключение */
    $mysqli->close();

    ?>

Пример #2 Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем подключение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Получаем информацию о каждом столбце */
        while ($finfo = mysqli_fetch_field($result)) {
            printf("Имя:           %s\n", $finfo->name);
            printf("Таблица:       %s\n", $finfo->table);
            printf("Макс. длина:   %d\n", $finfo->max_length);
            printf("Флаги:         %d\n", $finfo->flags);
            printf("Тип:         %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Закрываем подключение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Имя:         Name
    Таблица:     Country
    Макс. длина: 11
    Флаги:       1
    Тип:         254

    Имя:         SurfaceArea
    Таблица:     Country
    Макс. длина: 10
    Флаги:       32769
    Тип:         4

### Смотрите также

- mysqli_num_fields() - Получает количество полей в наборе результатов
- mysqli_fetch_field_direct() - Получает метаданные конкретного поля
- mysqli_fetch_fields() - Возвращает массив объектов, которые представляют поля результирующего набора
- mysqli_field_seek() - Устанавливает указатель результата на заданное смещение поля

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Получает метаданные конкретного поля

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_field_direct(int `$index`): object|false

Процедурный стиль

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Метод возвращает информацию о столбце результирующего набора в виде объекта.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`index`

  Номер поля. Число в диапазоне от `0` до `количество полей - 1`.

### Возвращаемые значения

Метод возвращает объект, который содержит определение поля, или `false`, если поле с номером, который задали для параметра `index`, недоступно.

Свойства объекта
Свойство | Описание
--- | ---
name | Имя столбца
orgname | Исходное имя столбца, если указали псевдоним
table | Имя таблицы, которой принадлежит столбец (если не вычислено)
orgtable | Исходное имя таблицы, если указали псевдоним
def | Неиспользуемый. Всегда пустая строка
db | Имя базы данных
catalog | Неиспользуемый. Всегда `«def»`
max_length | Максимальная ширина поля результирующего набора. Начиная с PHP 8.1 это значение всегда равно `0`
length | Ширина поля в байтах. Для строковых столбцов значение длины зависит от кодировки соединения. Например, если кодировка — `latin1`, однобайтовый набор символов, значение длины для запроса `SELECT 'abc'` равно 3. Если кодировка — `utf8mb4`, многобайтовый набор символов, в котором символы занимают до 4 байтов, значение длины равно 12
charsetnr | Номер кодировки для поля
flags | Целое число, которое представляет битовые флаги для поля
type | Тип данных поля
decimals | Количество десятичных знаков для числовых полей и точность долей секунды для временных полей

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверяем подключение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {
        /* Получаем метаданные столбца SurfaceArea */
        $finfo = $result->fetch_field_direct(1);

            printf("Имя:         %s\n", $finfo->name);
            printf("Таблица:     %s\n", $finfo->table);
            printf("Макс. длина: %d\n", $finfo->max_length);
            printf("Флаги:       %d\n", $finfo->flags);
            printf("Тип:         %d\n\n", $finfo->type);

        $result->close();
    }

    /* Закрываем подключение */
    $mysqli->close();

    ?>

Пример #2 Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверяем подключение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Получаем метаданные столбца SurfaceArea */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Имя:         %s\n", $finfo->name);
        printf("Таблица:     %s\n", $finfo->table);
        printf("Макс. длина: %d\n", $finfo->max_length);
        printf("Флаги:       %d\n", $finfo->flags);
        printf("Тип:         %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Закрываем подключение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Имя:         SurfaceArea
    Таблица:     Country
    Макс. длина: 10
    Флаги:       32769
    Тип:         4

### Смотрите также

- mysqli_num_fields() - Получает количество полей в наборе результатов
- mysqli_fetch_field() - Возвращает следующее поле результирующего набора
- mysqli_fetch_fields() - Возвращает массив объектов, которые представляют поля результирующего набора

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Возвращает массив объектов, которые представляют поля результирующего набора

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_fields(): array

Процедурный стиль

function mysqli_fetch_fields(mysqli_result `$result`): array

Метод служит той же цели, что и функция mysqli_fetch_field(), с той только разницей, что вместо возврата по одному объекту для каждого поля возвращает столбцы как массив объектов.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Метод возвращает массив объектов, которые содержат информацию об определении полей.

Свойства объекта
Свойство | Описание
--- | ---
name | Имя столбца
orgname | Исходное имя столбца, если указали псевдоним
table | Имя таблицы, которой принадлежит столбец (если не вычислено)
orgtable | Исходное имя таблицы, если указали псевдоним
def | Неиспользуемый. Всегда пустая строка
db | Имя базы данных
catalog | Неиспользуемый. Всегда `«def»`
max_length | Максимальная ширина поля результирующего набора. Начиная с PHP 8.1 это значение всегда равно `0`
length | Ширина поля в байтах. Для строковых столбцов значение длины зависит от кодировки соединения. Например, если кодировка — `latin1`, однобайтовый набор символов, значение длины для запроса `SELECT 'abc'` равно 3. Если кодировка — `utf8mb4`, многобайтовый набор символов, в котором символы занимают до 4 байтов, значение длины равно 12
charsetnr | Номер кодировки для поля
flags | Целое число, которое представляет битовые флаги для поля
type | Тип данных поля
decimals | Количество десятичных знаков для числовых полей и точность долей секунды для временных полей

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /* Проверяем соединение */
    if ($mysqli->connect_errno) {
        printf("Не удалось подключиться: %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {
        // Устанавливаем кодировку, чтобы показать влияние набора символов на некоторые значения (например, длину в байтах)
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Character Set: $charset\n";
        echo "======================\n";

        if ($result = $mysqli->query($query)) {

            /* Читаем информацию о полях для каждого столбца */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();

    ?>

Пример #2 Процедурный стиль

    <?php

    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /* Проверяем соединение */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {
        // Устанавливаем кодировку, чтобы показать влияние набора символов на некоторые значения (например, длину в байтах)
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Character Set: $charset\n";
        echo "======================\n";

        if ($result = mysqli_query($link, $query)) {
            /* Читаем информацию о полях для каждого столбца */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Name:      %s\n",   $val->name);
                printf("Table:     %s\n",   $val->table);
                printf("Max. Len:  %d\n",   $val->max_length);
                printf("Length:    %d\n",   $val->length);
                printf("charsetnr: %d\n",   $val->charsetnr);
                printf("Flags:     %d\n",   $val->flags);
                printf("Type:      %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    ======================
    Character Set: latin1
    ======================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    45
    charsetnr: 8
    Flags:     20489
    Type:      253

    ======================
    Character Set: utf8
    ======================
    Name:      actor_id
    Table:     actor
    Max. Len:  3
    Length:    5
    charsetnr: 63
    Flags:     49699
    Type:      2

    Name:      last_name
    Table:     actor
    Max. Len:  12
    Length:    135
    charsetnr: 33
    Flags:     20489

### Смотрите также

- mysqli_num_fields() - Получает количество полей в наборе результатов
- mysqli_fetch_field_direct() - Получает метаданные конкретного поля
- mysqli_fetch_field() - Возвращает следующее поле результирующего набора

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Выбирает следующую строку из набора результатов в виде объекта

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Процедурный стиль

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Функция выбирает одну строку данных из набора результатов и возвращает её как объект, где каждое свойство представляет имя столбца набора результатов. Каждый последующий вызов функции будет возвращать следующую строку в наборе результатов или `null`, если строк больше нет.

Последний столбец будет иметь приоритет и перезапишет любые предыдущие данные, если у двух и более столбцов в наборе результатов одинаковое имя. Для доступа к нескольким столбцам с одинаковым именем либо вызывают функцию mysqli_fetch_row() для выбора массива с числовой индексацией, либо в списке выбора SQL-запроса указывают псевдонимы, чтобы задать столбцам разные имена.

> Замечание: Функция устанавливает значения свойств объекта до вызова конструктора объекта.

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`class`

  Имя класса, объект которого нужно инстанцировать, задать значения его свойств и вернуть. Если параметр не задан, функция вернёт объект stdClass.

`constructor_args`

  Необязательный массив (array) параметров, которые будут переданы конструктору класса `class`.

### Возвращаемые значения

Функция возвращает объект, который представляет выбранную строку, в которой каждое свойство представляет имя столбца набора результатов, `null`, если в наборе результатов больше нет строк или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает исключение ValueError, когда аргумент `constructor_args` не пуст, а класс `class` не имеет конструктора.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь функция выбрасывает исключение ValueError, когда аргумент `constructor_args` не пуст, а класс `class` не имеет конструктора. Ранее функция выбрасывала исключение Exception.
8.0.0 | Параметр `constructor_args` теперь принимает пустой массив `[]` для конструкторов без параметров; раньше функция выбрасывала исключение.

### Примеры

Пример #1 Пример использования метода mysqli_result::fetch_object()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    while ($obj = $result->fetch_object()) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

    ?>

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($link, $query);

    while ($obj = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

    ?>

Результат выполнения приведённых примеров:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Смотрите также

- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_assoc() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_fetch_column() - Получает один столбец из следующей строки набора результатов
- mysqli_fetch_row() - Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Выбирает следующую строку из набора результатов и помещает её в обычный массив

### Описание

Объектно-ориентированный стиль

public function mysqli_result::fetch_row(): array|null|false

Процедурный стиль

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Выбирает одну строку данных из результирующего набора и возвращает её в виде массива, в котором индексы элементов соответствуют номерам столбцов (начиная с 0). Каждый последующий вызов функции будет возвращать массив с данными следующей строки набора или `null`, если строки закончились.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Возвращает нумерованный массив, представляющий выбранную строку, `null`, если в наборе результатов больше нет строк или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysqli_result::fetch_row()

Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* получение массива объектов */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* получение ассоциативного массива */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Результат выполнения приведённых примеров:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Смотрите также

- mysqli_fetch_array() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_fetch_assoc() - Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_fetch_column() - Получает один столбец из следующей строки набора результатов
- mysqli_fetch_object() - Выбирает следующую строку из набора результатов в виде объекта
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_data_seek() - Перемещает указатель результата на выбранную строку

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Получает количество полей в наборе результатов

### Описание

Объектно-ориентированный стиль

int $mysqli_result->field_count;

Процедурный стиль

function mysqli_num_fields(mysqli_result `$result`): int

Возвращает количество полей в наборе результатов.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Целое число (int), представляющее количество полей.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Получение количества полей в наборе результатов */
    $field_cnt = $result->field_count;

    printf("Получено %d полей.\n", $field_cnt);

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Получение количества полей в наборе результатов */
    $field_cnt = mysqli_num_fields($result);

    printf("Получено %d полей.\n", $field_cnt);

Результат выполнения приведённых примеров:

    Получено 4 полей.

### Смотрите также

- mysqli_fetch_field() - Возвращает следующее поле результирующего набора

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Устанавливает указатель результата на заданное смещение поля

### Описание

Объектно-ориентированный стиль

public function mysqli_result::field_seek(int `$index`): true

Процедурный стиль

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Устанавливает указатель поля на заданное смещение. Следующий вызов функции mysqli_fetch_field() извлечёт определение поля столбца, который связан со смещением.

> Замечание:

> Для поиска с начала строки необходимо установить нулевое значение смещения.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().
`index`

  Номер поля. Это значение должно быть в следующем диапазоне: от `0` до `количество полей - 1`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь функция каждый раз возвращает значение `true`. Раньше функция возвращала значение `false`, если возникала ошибка.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Ошибка соединения: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Получить информацию о поле во втором столбце */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Имя:     %s\n", $finfo->name);
        printf("Таблица:    %s\n", $finfo->table);
        printf("Макс. длина: %d\n", $finfo->max_length);
        printf("Флаги:    %d\n", $finfo->flags);
        printf("Тип:     %d\n\n", $finfo->type);

        $result->close();
    }

    /* Закрыть соединение */
    $mysqli->close();

    ?>

Пример #2 Процедурный стиль

    <?php

    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Проверить соединение */
    if (mysqli_connect_errno()) {
        printf("Ошибка соединения: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Получить информацию о поле во втором столбце */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Имя:     %s\n", $finfo->name);
        printf("Таблица:    %s\n", $finfo->table);
        printf("Макс. длина: %d\n", $finfo->max_length);
        printf("Флаги:    %d\n", $finfo->flags);
        printf("Тип:     %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Закрыть соединение */
    mysqli_close($link);

    ?>

Результат выполнения приведённых примеров:

    Имя:     SurfaceArea
    Таблица:    Country
    Макс. длина: 10
    Флаги:    32769
    Тип:     4

### Смотрите также

- mysqli_fetch_field() - Возвращает следующее поле результирующего набора

# mysqli_result::free

# mysqli_result::close

# mysqli_result::free_result

# mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — Освобождает память, занятую результатами запроса

### Описание

Объектно-ориентированный стиль

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

Процедурный стиль

function mysqli_free_result(mysqli_result `$result`): void

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

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Смотрите также

- mysqli_query() - Выполняет запрос к базе данных
- mysqli_stmt_get_result() - Получает результат из подготовленного запроса в виде объекта mysqli_result
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Извлекает внешний итератор

### Описание

public function mysqli_result::getIterator(): Iterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Возвращает длины полей текущей строки результирующего набора

### Описание

Объектно-ориентированный стиль

?array $mysqli_result->lengths;

Процедурный стиль

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

mysqli_fetch_lengths() возвращает массив, элементы которого представляют длины каждого поля текущей строки результирующего набора.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Массив целых чисел, представляющих размеры значений столбцов (исключая какие-либо завершающие нуль-символы). `false` в случае возникновения ошибки.

mysqli_fetch_lengths() относится только к текущей строке. Функция вернёт `false`, если будет вызвана до вызова mysqli_fetch_row/array/object или если в результирующем наборе больше нет строк.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* проверка подключения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* выведем длины полей */
        foreach ($result->lengths as $i => $val) {
            printf("Поле %2d имеет длину %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* закрываем подключение */
    $mysqli->close();
    ?>

Пример #2 Процедурный стиль

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* проверка подключения */
    if (mysqli_connect_errno()) {
        printf("Не удалось подключиться: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = mysqli_query($link, $query)) {

        $row = mysqli_fetch_row($result);

        /* выведем длины полей */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("Поле %2d имеет длину %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* закрываем подключение */
    mysqli_close($link);
    ?>

Результат выполнения приведённых примеров:

    Поле  1 имеет длину  3
    Поле  2 имеет длину  5
    Поле  3 имеет длину 13
    Поле  4 имеет длину  9
    Поле  5 имеет длину  6
    Поле  6 имеет длину  1
    Поле  7 имеет длину  6
    Поле  8 имеет длину  4
    Поле  9 имеет длину  6
    Поле 10 имеет длину  6
    Поле 11 имеет длину  5
    Поле 12 имеет длину 44
    Поле 13 имеет длину  7
    Поле 14 имеет длину  3
    Поле 15 имеет длину  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Получает количество строк в наборе результатов

### Описание

Объектно-ориентированный стиль

int|string $mysqli_result->num_rows;

Процедурный стиль

function mysqli_num_rows(mysqli_result `$result`): int|string

Возвращает число рядов в результирующей выборке.

Поведение функции mysqli_num_rows() зависит от того, используется ли буферизованная или не буферизованная результирующая выборка. Функция возвращает `0` для небуферизованных наборов результатов, если с сервера не были получены все строки.

### Список параметров

`result`
  Только для процедурного стиля: объект mysqli_result, который вернула функция mysqli_query(), mysqli_store_result(), mysqli_use_result() или mysqli_stmt_get_result().

### Возвращаемые значения

Возвращает целое число (int), представляющее количество выбранных строк. Возвращает `0` в небуферизованном режиме, если с сервера не были получены все строки.

> Замечание: Если количество строк больше, чем `PHP_INT_MAX`, число будет возвращено как строка (string).

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

    /* Получение количества строк в наборе результатов */
    $row_cnt = $result->num_rows;

    printf("Получено %d строк.\n", $row_cnt);
    ?>

Пример #2 Процедурный стиль

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

    /* Получение количества строк в наборе результатов */
    $row_cnt = mysqli_num_rows($result);

    printf("Получено %d строк.\n", $row_cnt);

Результат выполнения приведённых примеров:

    Получено 239 строк.

### Примечания

> Замечание:

> В отличие от функции mysqli_stmt_num_rows(), у этой функции нет варианта в объектно-ориентированном стиле. В объектно-ориентированном стиле используйте метод чтения.

### Смотрите также

- mysqli_affected_rows() - Получает число строк, затронутых предыдущей операцией MySQL
- mysqli_store_result() - Передаёт на клиента результирующий набор последнего запроса
- mysqli_use_result() - Готовит результирующий набор на сервере к использованию
- mysqli_query() - Выполняет запрос к базе данных
- mysqli_stmt_num_rows() - Возвращает количество строк, полученных с сервера

## Содержание

- mysqli_result::__construct — Конструктор объекта mysqli_result
- mysqli_result::$current_field — Получает смещение указателя по отношению к текущему полю
- mysqli_result::data_seek — Перемещает указатель результата на выбранную строку
- mysqli_result::fetch_all — Выбирает все строки из результирующего набора и помещает их в ассоциативный массив, обычный массив или в оба
- mysqli_result::fetch_array — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
- mysqli_result::fetch_assoc — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
- mysqli_result::fetch_column — Получает один столбец из следующей строки набора результатов
- mysqli_result::fetch_field — Возвращает следующее поле результирующего набора
- mysqli_result::fetch_field_direct — Получает метаданные конкретного поля
- mysqli_result::fetch_fields — Возвращает массив объектов, которые представляют поля результирующего набора
- mysqli_result::fetch_object — Выбирает следующую строку из набора результатов в виде объекта
- mysqli_result::fetch_row — Выбирает следующую строку из набора результатов и помещает её в обычный массив
- mysqli_result::$field_count — Получает количество полей в наборе результатов
- mysqli_result::field_seek — Устанавливает указатель результата на заданное смещение поля
- mysqli_result::free — Освобождает память, занятую результатами запроса
- mysqli_result::getIterator — Извлекает внешний итератор
- mysqli_result::$lengths — Возвращает длины полей текущей строки результирующего набора
- mysqli_result::$num_rows — Получает количество строк в наборе результатов

# Класс mysqli_driver

(PHP 5, PHP 7, PHP 8)

## Введение

Класс mysqli_driver является экземпляром шаблона monostate, то есть есть только один драйвер, к которому можно получить доступ через произвольное количество экземпляров mysqli_driver.

## Обзор класса

final class mysqli_driver {
/* Свойства */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## Свойства

client_info

  Версия заголовка Client API

client_version

  Версия Client

driver_version

  Версия MySQLi Driver

  Внимание

  Свойство объявлено устаревшим в PHP 8.1.0. Полагаться на свойство крайне не рекомендуется.

embedded

  Статус поддержки MySQLi Embedded

  Внимание

  Свойство удалено в PHP 8.0.0.

reconnect

  Разрешить или запретить переподключение (смотрите INI-директиву mysqli.reconnect)

  Внимание

  Свойство было удалено вместе с INI-директивой mysqli.reconnect в PHP 8.2.0.

report_mode

  Установить `MYSQLI_REPORT_OFF`, `MYSQLI_REPORT_ALL` или любую комбинацию из `MYSQLI_REPORT_STRICT` (вызов исключений для ошибок), `MYSQLI_REPORT_ERROR` (сообщение об ошибках) и `MYSQLI_REPORT_INDEX` (ошибки, связанные с индексами). Смотрите также mysqli_report().

## Список изменений

Версия | Описание
--- | ---
8.2.0 | Свойство mysqli_driver::$reconnect было удалено.
8.1.0 | Свойство mysqli_driver::$driver_version объявлено устаревшим.
8.0.0 | Свойство mysqli_driver::$embedded было удалено.
7.4.0 | Метод mysqli_driver::embedded_server_start() и mysqli_driver:embedded_server_end() были удалены.

# mysqli_driver::embedded_server_end

# mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Останавливает встроенный сервер

Внимание

В PHP 7.4.0 функцию УДАЛИЛИ.

### Описание

Объектно-ориентированный стиль

public function mysqli_driver::embedded_server_end(): void

Процедурный стиль

function mysqli_embedded_server_end(): void
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

# mysqli_driver::embedded_server_start

# mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Инициализирует и запускает встроенный сервер

Внимание

В PHP 7.4.0 функцию УДАЛИЛИ.

### Описание

Объектно-ориентированный стиль

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

Процедурный стиль

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Устанавливает режим сообщений об ошибках модулем mysqli

### Описание

Объектно-ориентированный стиль

int $mysqli_driver->report_mode;

Процедурный стиль

function mysqli_report(int `$flags`): true

В зависимости от флагов функция устанавливает в модуле mysqli режим сообщений об ошибках на уровень исключения, предупреждения или отключает сообщения об ошибках. Со значениями `MYSQLI_REPORT_ALL` или `MYSQLI_REPORT_INDEX` функция также будет информировать о запросах, в которых не указали индекс или указали неверный индекс.

Начиная с PHP 8.1.0 режим сообщений об ошибках по умолчанию равен побитовой маске `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Раньше значением по умолчанию был режим `MYSQLI_REPORT_OFF`.

### Список параметров

`flags`

  Флаги, которые поддерживает функция
  Имя | Описание
  --- | ---
  `MYSQLI_REPORT_OFF` | Отключить сообщения об ошибках
  `MYSQLI_REPORT_ERROR` | Сообщить об ошибках при вызовах функций модуля mysqli
  `MYSQLI_REPORT_STRICT` | Вместо предупреждений выбрасывать при ошибках исключение mysqli_sql_exception
  `MYSQLI_REPORT_INDEX` | Сообщить, если в запросе не указали индекс или указали неверный индекс
  `MYSQLI_REPORT_ALL` | Установить каждый параметр и сообщать обо всех ошибках

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Для режима сообщений об ошибках значение по умолчанию теперь равно `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`. Раньше значением по умолчанию было `MYSQLI_REPORT_OFF`.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php

    /* Включаем сообщения об ошибках */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* Функция выбросит исключение mysqli_sql_exception, если не получится подключиться */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* Этот запрос сообщит об ошибке */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* Этот запрос сообщит о неверном индексе, если для столбца population не создали индекс */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

    ?>

Пример #2 Процедурный стиль

    <?php

    /* Включаем сообщения об ошибках */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* Функция выбросит исключение mysqli_sql_exception, если не получится подключиться */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* Этот запрос сообщит об ошибке */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* Этот запрос сообщит о неверном индексе, если для столбца population не создали индекс */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

    ?>

Пример #3 Отчёт об ошибках, кроме ошибок неверного индекса

    <?php

    /* Включаем сообщения об ошибках */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    try {
        /* Функция выбросит исключение mysqli_sql_exception, если не получится подключиться */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* Этот запрос сообщит об ошибке */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* Этот запрос не сообщит об ошибках, даже если индекс недоступен */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

    ?>

### Смотрите также

- mysqli_sql_exception
- set_exception_handler() - Устанавливает пользовательскую функцию обработчика исключений
- error_reporting() - Определяет, о каких PHP-ошибках сообщать

## Содержание

- mysqli_driver::embedded_server_end — Останавливает встроенный сервер
- mysqli_driver::embedded_server_start — Инициализирует и запускает встроенный сервер
- mysqli_driver::$report_mode — Устанавливает режим сообщений об ошибках модулем mysqli

# Класс mysqli_warning

(PHP 5, PHP 7, PHP 8)

## Введение

Представляет предупреждение MySQL.

## Обзор класса

final class mysqli_warning {
/* Свойства */
public string $message;
public string $sqlstate;
public int $errno;
/* Методы */
private function __construct()
public function next(): bool
}

## Свойства

message

  Строка сообщения

sqlstate

  Код SQLstate

errno

  Номер ошибки

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Закрытый конструктор для запрета прямого создания экземпляра

### Описание

private function mysqli_warning::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Получает следующее предупреждение

### Описание

public function mysqli_warning::next(): bool

Изменяет информацию о предупреждении на следующее предупреждение, если это возможно.

После того как предупреждение было установлено на следующее предупреждение, будут доступны новые значения свойств `message`, `sqlstate` и `errno` из mysqli_warning.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если следующее предупреждение было получено успешно. Если больше нет предупреждений, вернёт `false`

## Содержание

- mysqli_warning::__construct — Закрытый конструктор для запрета прямого создания экземпляра
- mysqli_warning::next — Получает следующее предупреждение

# Класс mysqli_sql_exception

(PHP 5, PHP 7, PHP 8)

## Введение

Класс для обработки исключений mysqli.

## Обзор класса

final class mysqli_sql_exception extends RuntimeException {
/* Свойства */
protected string $sqlstate = "00000";
/* Методы */
public function getSqlState(): string
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Свойства

sqlstate

  Код sqlstate.

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Возвращает код ошибки SQLSTATE

### Описание

public function mysqli_sql_exception::getSqlState(): string

Возвращает строку, содержащую код последней ошибки SQLSTATE. Код ошибки состоит из пяти символов. Значения задаются ANSI SQL и ODBC. Список возможных значений можно посмотреть на странице » http://dev.mysql.com/doc/mysql/en/error-handling.html.

> Замечание:

> Обратите внимание, что не все ошибки MySQL ещё сопоставлены с SQLSTATE. Если ошибка не сопоставлена, используется значение `HY000` (общая ошибка).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую код последней ошибки SQLSTATE. Код ошибки состоит из пяти символов.

## Содержание

- mysqli_sql_exception::getSqlState — Возвращает код ошибки SQLSTATE

# Синонимы и устаревшие функции Mysqli

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — Псевдоним mysqli::__construct()

### Описание

Псевдоним функции mysqli::__construct()

> Замечание:

> Если режим исключения mysqli отключён и произошла ошибка соединения, тогда mysqli_connect() возвращает `false` вместо объекта. Для получения ошибки соединения можно использовать функцию mysqli_connect_error().

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — Псевдоним функции mysqli_real_escape_string()

### Описание

Псевдоним функции mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — Псевдоним mysqli_stmt_execute()

Внимание

Начиная с PHP 8.5.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

Псевдоним функции mysqli_stmt_execute().

### Смотрите также

- mysqli_stmt_execute() - Выполняет подготовленное утверждение

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — Получить клиентскую попроцессную статистику

### Описание

function mysqli_get_client_stats(): array

Возвращает клиентскую попроцессную статистику.

> Замечание:

> Доступно только с модулем mysqlnd.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив со статистикой.

### Примеры

Пример #1 Пример использования mysqli_get_client_stats()

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Смотрите также

- Описание метрик

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — Возвращает информацию об открытых и закешированных соединениях MySQL

### Описание

function mysqli_get_links_stats(): array

mysqli_get_links_stats() возвращает информацию об открытых и закешированных соединениях MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

mysqli_get_links_stats() возвращает ассоциативный массив из трёх целочисленных значений со следующими ключами:

`total`

  Целое число (int), означающее общее количество соединений с любыми статусами.

`active_plinks`

  Целое число (int), означающее количество активных постоянных (persistent) соединениях.

`cached_plinks`

  Целое число (int), означающее количество неактивных постоянных (persistent) соединениях.

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — Псевдоним mysqli_driver->report_mode

### Описание

Псевдоним функции mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — Псевдоним mysqli_options()

### Описание

Псевдоним функции mysqli_options().

## Содержание

- mysqli_connect — Псевдоним mysqli::__construct
- mysqli::escape_string — Псевдоним функции mysqli_real_escape_string
- mysqli_execute — Псевдоним mysqli_stmt_execute
- mysqli_get_client_stats — Получить клиентскую попроцессную статистику
- mysqli_get_links_stats — Возвращает информацию об открытых и закешированных соединениях MySQL
- mysqli_report — Псевдоним mysqli_driver->report_mode
- mysqli::set_opt — Псевдоним mysqli_options

# Список изменений

В классы, функции и методы модуля внесли следующие изменения.

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | Метод mysqli::kill и функция mysqli_kill устарели. Вместо них рекомендуют выполнять SQL-команду KILL.
| mysqli::ping | Метод mysqli::ping и функция mysqli_ping устарели. Функция reconnect была недоступна с PHP 8.2.0, что делает эту функцию устаревшей.
| mysqli::refresh | Метод mysqli::refresh и функция mysqli_refresh устарели. Вместо них рекомендуют выполнять SQL-команду FLUSH.
| mysqli::store_result | Передача параметра параметра mode устарела. Начиная с PHP 8.1.0 параметр не имеет значения.
8.3.0 | mysqli_result::fetch_object | Теперь функция выбрасывает исключение ValueError, когда аргумент constructor_args не пуст, а класс class не имеет конструктора. Ранее функция выбрасывала исключение Exception.
| mysqli::poll | Теперь функция выбрасывает исключение ValueError, если не передан ни аргумент read, ни аргумент error.
8.1.0 | mysqli_driver::$report_mode | Для режима сообщений об ошибках значение по умолчанию теперь равно MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT. Раньше значением по умолчанию было MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Теперь также доступно при сборке с libmysqlclient.
| mysqli_stmt::execute | Добавлен необязательный параметр params.
| mysqli_stmt::next_result | Теперь также доступно при сборке с libmysqlclient.
| mysqli::__construct | Метод mysqli::connect теперь возвращает значение true вместо null в случае успешного выполнения.
| mysqli::$client_info | Вызов функции mysqli_get_client_info с аргументом mysql устарел. Функции никогда не требовался этот параметр, но она ошибочно разрешала передавать для него аргумент и обрабатывала параметр как необязательный.
| mysqli::$client_info | Объектно-ориентированный стиль вызова метода mysqli::get_client_info устарел.
| mysqli::init | Объектно-ориентированный стиль вызова метода mysqli::init устарел. Замените вызов метода parent::init вызовом метода parent::__construct.
8.0.0 | mysqli_result::fetch_object | Параметр constructor_args теперь принимает пустой массив [] для конструкторов без параметров; раньше функция выбрасывала исключение.
| mysqli_result::field_seek | Теперь функция каждый раз возвращает значение true. Раньше функция возвращала значение false, если возникала ошибка.
| mysqli_stmt::close | Функция теперь возвращает значение true. Ранее она возвращала значение false в случае возникновения ошибки.
| mysqli_stmt::__construct | query теперь допускает значение null.
| mysqli::begin_transaction | name теперь допускает значение null.
| mysqli::close | Функция теперь возвращает значение true. Ранее она возвращала значение false в случае возникновения ошибки.
| mysqli::commit | name теперь допускает значение null.
| mysqli::debug | Функция теперь возвращает значение true. Ранее она возвращала значение false в случае возникновения ошибки.
| mysqli::rollback | name теперь допускает значение null.
7.4.0 | mysqli::__construct | Все параметры теперь принимают значение null
| mysqli::real_connect | Все параметры теперь принимают значение null

- Краткий обзор
- Краткое руководство
  - Процедурный и объектно-ориентированный интерфейс
  - Соединения
  - Выполнение запросов
  - Подготавливаемые запросы
  - Хранимые процедуры
  - Множественные запросы
  - API поддержка транзакций
  - Метаданные
- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Модуль mysqli и постоянные соединения
- Предопределённые константы
- Основная информация о функциях модуля MySQLi
- mysqli — Класс mysqli
  - mysqli::$affected_rows — Получает число строк, затронутых предыдущей операцией MySQL
  - mysqli::autocommit — Включает или отключает автоматическую фиксацию изменений базы данных
  - mysqli::begin_transaction — Стартует транзакцию
  - mysqli::change_user — Изменяет пользователя соединения с базой данных
  - mysqli::character_set_name — Возвращает текущую кодировку, установленную для соединения с БД
  - mysqli::close — Закрывает ранее открытое соединение с базой данных
  - mysqli::commit — Фиксирует текущую транзакцию
  - mysqli::$connect_errno — Возвращает код ошибки последней попытки соединения
  - mysqli::$connect_error — Возвращает описание последней ошибки подключения
  - mysqli::__construct — Устанавливает новое соединение с MySQL-сервером
  - mysqli::debug — Выполняет процедуры отладки
  - mysqli::dump_debug_info — Журналирование отладочной информации
  - mysqli::$errno — Возвращает код ошибки последнего вызова функции
  - mysqli::$error — Возвращает строку с описанием последней ошибки
  - mysqli::$error_list — Возвращает список ошибок выполнения последней запущенной команды
  - mysqli::execute_query — Подготавливает, связывает параметры и выполняет SQL-запрос
  - mysqli::$field_count — Возвращает число столбцов, затронутых последним запросом
  - mysqli::get_charset — Возвращает объект со сведениями о кодировке
  - mysqli::$client_info — Получает информацию о MySQL-клиенте
  - mysqli::$client_version — Возвращает информацию о клиенте MySQL в виде строки
  - mysqli::get_connection_stats — Возвращает статистику соединения с клиентом
  - mysqli::$host_info — Возвращает строку, содержащую тип используемого соединения
  - mysqli::$protocol_version — Возвращает версию используемого MySQL протокола
  - mysqli::$server_info — Возвращает версию MySQL сервера
  - mysqli::$server_version — Возвращает версию сервера MySQL, представленную в виде integer
  - mysqli::get_warnings — Получает результат SHOW WARNINGS
  - mysqli::$info — Извлекает информацию о последнем выполненном запросе
  - mysqli::init — Инициализирует MySQLi-коннектор и возвращает объект для работы с функцией mysqli_real_connect()
  - mysqli::$insert_id — Возвращает значение, созданное для столбца AUTO_INCREMENT последним запросом
  - mysqli::kill — Просит сервер завершить MySQL-поток
  - mysqli::more_results — Проверка, есть ли ещё результаты в мультизапросе
  - mysqli::multi_query — Выполняет запросы к базе данных
  - mysqli::next_result — Подготовка следующего доступного результирующего набора из multi_query
  - mysqli::options — Установка настроек
  - mysqli::ping — Проверяет соединение с сервером или пытается переподключиться, если соединение прервалось
  - mysqli::poll — Опрашивает подключения
  - mysqli::prepare — Подготавливает SQL выражение к выполнению
  - mysqli::query — Выполняет запрос к базе данных
  - mysqli::real_connect — Устанавливает соединение с MySQL-сервером
  - mysqli::real_escape_string — Экранирует специальные символы в строке для использования в SQL-выражении, используя текущий набор символов соединения
  - mysqli::real_query — Выполнение SQL запроса
  - mysqli::reap_async_query — Получение результата асинхронного запроса
  - mysqli::refresh — Обновляет таблицы или кеш
  - mysqli::release_savepoint — Удаляет именованную точку сохранения из списка точек сохранения текущей транзакции
  - mysqli::rollback — Откат текущей транзакции
  - mysqli::savepoint — Установите именованную точку сохранения транзакции
  - mysqli::select_db — Устанавливает базу данных для выполняемых запросов
  - mysqli::set_charset — Задаёт набор символов
  - mysqli::$sqlstate — Возвращает код состояния SQLSTATE последней MySQL операции
  - mysqli::ssl_set — Используется для установления безопасных соединений, используя SSL
  - mysqli::stat — Получение информации о текущем состоянии системы
  - mysqli::stmt_init — Инициализирует запрос и возвращает объект для использования в mysqli_stmt_prepare
  - mysqli::store_result — Передаёт на клиента результирующий набор последнего запроса
  - mysqli::$thread_id — Возвращает ID потока текущего подключения
  - mysqli::thread_safe — Показывает, безопасна ли работа с процессами
  - mysqli::use_result — Готовит результирующий набор на сервере к использованию
  - mysqli::$warning_count — Возвращает количество предупреждений, сгенерированных последним выполненным запросом
- mysqli_stmt — The mysqli_stmt class
  - mysqli_stmt::$affected_rows — Возвращает общее количество строк, изменённых, удалённых, вставленных или сопоставленных последним выполненным выражением
  - mysqli_stmt::attr_get — Получает текущее значение атрибута запроса
  - mysqli_stmt::attr_set — Изменяет поведение подготовленного запроса
  - mysqli_stmt::bind_param — Привязка переменных к параметрам подготавливаемого запроса
  - mysqli_stmt::bind_result — Привязка переменных к подготовленному запросу для размещения результата
  - mysqli_stmt::close — Закрывает подготовленный запрос
  - mysqli_stmt::__construct — Конструктор для объекта mysqli_stmt
  - mysqli_stmt::data_seek — Корректирует указатель результата на произвольную строку в буферизованном результате
  - mysqli_stmt::$errno — Возвращает код ошибки выполнения последнего запроса
  - mysqli_stmt::$error — Возвращает строку с пояснением последней ошибки при выполнении запроса
  - mysqli_stmt::$error_list — Возвращает список ошибок выполнения последнего запроса
  - mysqli_stmt::execute — Выполняет подготовленное утверждение
  - mysqli_stmt::fetch — Связывает результаты подготовленного запроса с переменными
  - mysqli_stmt::$field_count — Возвращает число столбцов в заданном выражении
  - mysqli_stmt::free_result — Освобождает память от результата запроса, указанного дескриптором
  - mysqli_stmt::get_result — Получает результат из подготовленного запроса в виде объекта mysqli_result
  - mysqli_stmt::get_warnings — Получает результат от SHOW WARNINGS
  - mysqli_stmt::$insert_id — Получает ID, сгенерированный предыдущей операцией INSERT
  - mysqli_stmt::more_results — Проверяет, есть ли ещё наборы строк в результате мультизапроса
  - mysqli_stmt::next_result — Читает следующий набор строк из мультизапроса
  - mysqli_stmt::$num_rows — Возвращает количество строк, полученных с сервера
  - mysqli_stmt::$param_count — Возвращает количество параметров в запросе
  - mysqli_stmt::prepare — Подготавливает утверждение SQL к выполнению
  - mysqli_stmt::reset — Сбрасывает результаты выполнения подготовленного запроса
  - mysqli_stmt::result_metadata — Возвращает метаданные результирующей таблицы подготавливаемого запроса
  - mysqli_stmt::send_long_data — Отправка данных блоками
  - mysqli_stmt::$sqlstate — Возвращает код ошибки SQLSTATE, вызванной в ходе выполнения последней операции над запросом
  - mysqli_stmt::store_result — Сохраняет набор результатов во внутреннем буфере
- mysqli_result — Класс mysqli_result
  - mysqli_result::__construct — Конструктор объекта mysqli_result
  - mysqli_result::$current_field — Получает смещение указателя по отношению к текущему полю
  - mysqli_result::data_seek — Перемещает указатель результата на выбранную строку
  - mysqli_result::fetch_all — Выбирает все строки из результирующего набора и помещает их в ассоциативный массив, обычный массив или в оба
  - mysqli_result::fetch_array — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив, обычный массив или в оба
  - mysqli_result::fetch_assoc — Выбирает следующую строку из набора результатов и помещает её в ассоциативный массив
  - mysqli_result::fetch_column — Получает один столбец из следующей строки набора результатов
  - mysqli_result::fetch_field — Возвращает следующее поле результирующего набора
  - mysqli_result::fetch_field_direct — Получает метаданные конкретного поля
  - mysqli_result::fetch_fields — Возвращает массив объектов, которые представляют поля результирующего набора
  - mysqli_result::fetch_object — Выбирает следующую строку из набора результатов в виде объекта
  - mysqli_result::fetch_row — Выбирает следующую строку из набора результатов и помещает её в обычный массив
  - mysqli_result::$field_count — Получает количество полей в наборе результатов
  - mysqli_result::field_seek — Устанавливает указатель результата на заданное смещение поля
  - mysqli_result::free — Освобождает память, занятую результатами запроса
  - mysqli_result::getIterator — Извлекает внешний итератор
  - mysqli_result::$lengths — Возвращает длины полей текущей строки результирующего набора
  - mysqli_result::$num_rows — Получает количество строк в наборе результатов
- mysqli_driver — Класс mysqli_driver
  - mysqli_driver::embedded_server_end — Останавливает встроенный сервер
  - mysqli_driver::embedded_server_start — Инициализирует и запускает встроенный сервер
  - mysqli_driver::$report_mode — Устанавливает режим сообщений об ошибках модулем mysqli
- mysqli_warning — Класс mysqli_warning
  - mysqli_warning::__construct — Закрытый конструктор для запрета прямого создания экземпляра
  - mysqli_warning::next — Получает следующее предупреждение
- mysqli_sql_exception — Класс mysqli_sql_exception
  - mysqli_sql_exception::getSqlState — Возвращает код ошибки SQLSTATE
- Синонимы и устаревшие функции Mysqli
  - mysqli_connect — Псевдоним mysqli::__construct
  - mysqli::escape_string — Псевдоним функции mysqli_real_escape_string
  - mysqli_execute — Псевдоним mysqli_stmt_execute
  - mysqli_get_client_stats — Получить клиентскую попроцессную статистику
  - mysqli_get_links_stats — Возвращает информацию об открытых и закешированных соединениях MySQL
  - mysqli_report — Псевдоним mysqli_driver->report_mode
  - mysqli::set_opt — Псевдоним mysqli_options
- Список изменений

# Mysql_xdevapi

# Введение

Модуль обеспечивает доступ к хранилищу документов MySQL через X DevAPI. X DevAPI - это общий API, предоставляемый несколькими коннекторами MySQL, обеспечивающий лёгкий доступ к реляционным таблицам, а также к коллекциям документов, которые представлены в JSON, из API с операциями в стиле CRUD.

X DevAPI использует X Protocol, клиент-серверный протокол нового поколения сервера MySQL 8.0.

Для получения общей информации о хранилище документов MySQL, пожалуйста, обратитесь к главе » Хранилище документов MySQL в руководстве MySQL.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Сборка / Компиляция из исходного кода

## Требования

Для этого модуля требуется сервер MySQL 8+ с включённым плагином X (по умолчанию).

Необходимые библиотеки для компиляции этого модуля: Boost (1.53.0 или выше), OpenSSL и Protobuf.

## Установка

Модуль » PECL не поставляется вместе с PHP.

Пример процедуры установки на Ubuntu 18.04 с PHP 7.2:

    // Зависимости
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP с нужными модулями; php7.2-dev, необходимым для компиляции
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Компиляция модуля
    $ pecl install mysql_xdevapi

Команда `pecl install` не включает модули PHP (по умолчанию), включение модулей PHP может быть сделано несколькими способами. Другой пример PHP 7.2 в Ubuntu 18.04:

    // Создание собственного ini файла
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Использование команды 'phpenmod' (примечание: это применимо для Debian/Ubuntu)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // Альтернативой 'phpenmod' является создание символической ссылки
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Давайте посмотрим, какие модули MySQL сейчас включены
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/mysql_xdevapi.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Mysql_xdevapi
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
xmysqlnd.collect_memory_statistics | 0 | `INI_SYSTEM` |
xmysqlnd.collect_statistics | 1 | `INI_ALL` |
xmysqlnd.debug |  | `INI_SYSTEM` |
xmysqlnd.mempool_default_size | 16000 | `INI_ALL` |
xmysqlnd.net_read_timeout | 31536000 | `INI_SYSTEM` |
xmysqlnd.trace_alloc |  | `INI_SYSTEM` |

Краткое разъяснение конфигурационных директив.

`xmysqlnd.collect_memory_statistics` int

`xmysqlnd.collect_statistics` int

`xmysqlnd.debug` string

`xmysqlnd.mempool_default_size` int

`xmysqlnd.net_read_timeout` int

`xmysqlnd.trace_alloc` string

## Сборка / Компиляция из исходного кода

Соображения по компиляции этого модуля из исходного кода.

- Имя модуля - 'mysql_xdevapi', поэтому используйте `--enable-mysql-xdevapi`.

- Boost: обязателен, при необходимости используйте параметр конфигурации --with-boost=DIR или задайте переменную окружения MYSQL_XDEVAPI_BOOST_ROOT. Требуются только файлы заголовков boost; не двоичные файлы.

- Google Protocol Buffers (protobuf): обязателен, при необходимости используйте параметр конфигурации --with-protobuf=DIR или задайте переменную окружения MYSQL_XDEVAPI_PROTOBUF_ROOT.

  При желании используйте `make protobufs` для создания файлов protobuf (*.pb.cc/.h) и `make clean-protobufs` для удаления созданных файлов protobuf.

  Примечание к protobuf на Windows: в зависимости от окружения может потребоваться статическая библиотека с многопоточным временем выполнения DLL. Для подготовки используйте следующие параметры: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / protocol compiler (protoc): обязательны, убедитесь, что во время сборки в PATH доступен правильный 'protoc'. Это особенно важно, поскольку пакетные сценарии Windows PHP SDK могут перезаписывать окружение.

- Bison: обязателен, и доступен из PATH.

  Примечание к bison на Windows: мы настоятельно рекомендуем, чтобы bison, поставляемый с выбранным PHP SDK, использовал ещё одну ошибку, похожую на "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): примечание: note: see declaration of 'zendparse'". Кроме того, пакетные сценарии Windows PHP SDK могут перезаписывать окружение.

- Примечания для Windows: Чтобы подготовить окружение, ознакомьтесь с официальной документацией по сборке Windows для » текущего SDK.

  Мы рекомендуем использовать обратную косую черту '\\' вместо косой черты '/' для всех путей.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`MYSQLX_CLIENT_SSL` (int)
`MYSQLX_TYPE_DECIMAL` (int)
`MYSQLX_TYPE_TINY` (int)
`MYSQLX_TYPE_SHORT` (int)
`MYSQLX_TYPE_SMALLINT` (int)
`MYSQLX_TYPE_MEDIUMINT` (int)
`MYSQLX_TYPE_INT` (int)
`MYSQLX_TYPE_BIGINT` (int)
`MYSQLX_TYPE_LONG` (int)
`MYSQLX_TYPE_FLOAT` (int)
`MYSQLX_TYPE_DOUBLE` (int)
`MYSQLX_TYPE_NULL` (int)
`MYSQLX_TYPE_TIMESTAMP` (int)
`MYSQLX_TYPE_LONGLONG` (int)
`MYSQLX_TYPE_INT24` (int)
`MYSQLX_TYPE_DATE` (int)
`MYSQLX_TYPE_TIME` (int)
`MYSQLX_TYPE_DATETIME` (int)
`MYSQLX_TYPE_YEAR` (int)
`MYSQLX_TYPE_NEWDATE` (int)
`MYSQLX_TYPE_ENUM` (int)
`MYSQLX_TYPE_SET` (int)
`MYSQLX_TYPE_TINY_BLOB` (int)
`MYSQLX_TYPE_MEDIUM_BLOB` (int)
`MYSQLX_TYPE_LONG_BLOB` (int)
`MYSQLX_TYPE_BLOB` (int)
`MYSQLX_TYPE_VAR_STRING` (int)
`MYSQLX_TYPE_STRING` (int)
`MYSQLX_TYPE_CHAR` (int)
`MYSQLX_TYPE_BYTES` (int)
`MYSQLX_TYPE_INTERVAL` (int)
`MYSQLX_TYPE_GEOMETRY` (int)
`MYSQLX_TYPE_JSON` (int)
`MYSQLX_TYPE_NEWDECIMAL` (int)
`MYSQLX_TYPE_BIT` (int)
`MYSQLX_LOCK_DEFAULT` (int)
`MYSQLX_LOCK_NOWAIT` (int)
`MYSQLX_LOCK_SKIP_LOCKED` (int)

# Список изменений

В классы, функции и методы модуля внесли следующие изменения.

### Общий журнал изменений модуля ext/mysql_xdevapi

Журнал изменений ссылается на модуль ext/mysql_xdevapi.

### Глобальные изменения ext/mysql_xdevapi

Версия | Описание
--- | ---
8.0.28 | Удалена поддержка TLSv1 и TLSv1.1. Значения "TLSv1", "TLSv1.0" и "TLSv1.1" теперь считаются недопустимыми для атрибута соединения "tls-versions".
8.0.26 | Поддержка TLSv1 и TLSv1.1 объявлена устаревшей.

# Примеры

Центральная точка входа в X DevAPI — функция mysql_xdevapi\getSession(), которая принимает URI сервера MySQL 8.0 и возвращает объект mysql_xdevapi\Session.

Пример #1 Подключение к серверу MySQL

    <?php

    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Не удалось установить соединение: " . $e->getMessage());
    }

    // ...используйте $session

    ?>

Сессия даёт полный доступ к API. Первый шаг для новой установки MySQL-сервера — создать схему базы данных с коллекцией для хранения данных:

Пример #2 Создание схемы и коллекции на сервере MySQL

    <?php

    $schema = $session->createSchema("test");
    $collection = $schema->createCollection("example");

    ?>

При сохранении данных их обычно кодируют в JSON-формат функцией json_encode(), который затем можно сохранить внутри коллекции.

В следующем примере данные сохраняются в коллекции, которую мы создали ранее, а затем снова извлекаем их части.

Пример #3 Хранение и получение данных

    <?php

    $marco = [
      "name" => "Marco",
      "age"  => 19,
      "job"  => "Programmer"
    ];
    $mike = [
      "name" => "Mike",
      "age"  => 39,
      "job"  => "Manager"
    ];

    $schema = $session->getSchema("test");
    $collection = $schema->getCollection("example");

    $collection->add($marco, $mike)->execute();

    var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());

    ?>

Вывод приведённого примера будет похож на:

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["age"]=>
      int(39)
      ["job"]=>
      string(7) "Manager"
      ["name"]=>
      string(4) "Mike"
    }

В примере показано, что сервер MySQL добавляет поле с именем `_id`, которое выступает в роли первичного ключа к документу.

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

Если нужно, можно использовать итераторы PHP для извлечения нескольких документов:

Пример #4 Извлечение и итерация нескольких документов

    <?php

    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["name"]} — {$doc["job"]}.\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    Марко — программист.
    Майк — менеджер.

# Функции Mysql_xdevapi

# expression

(No version information available, might only be in Git)

expression — Связывает подготовленные переменные утверждения в качестве параметров

### Описание

function mysql_xdevapi\expression(string `$expression`): object

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`expression`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\Expression()

    <?php
    $expression = mysql_xdevapi\Expression("[age,job]");

    $res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

Вывод приведённого примера будет похож на:

    <?php

# getSession

(No version information available, might only be in Git)

getSession — Подключается к серверу MySQL

### Описание

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Подключается к серверу MySQL.

### Список параметров

`uri`

  URI к серверу MySQL, такой как `mysqlx://user:password@host`.

  Формат URI:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: обязательный, протокол соединения

    В mysql_xdevapi это всегда 'mysqlx' (для X Protocol)

  - `user`: необязательный, учётная запись пользователя MySQL для аутентификации

  - `password`: необязательный, пароль пользователя MySQL для аутентификации

  - `target`: обязательный, экземпляр сервера, к которому относится соединение:

    * TCP-соединение (имя хоста, адрес IPv4 или адрес IPv6)

    * Путь к сокету Unix (локальный путь к файлу)

    * Именованный канал Windows (локальный путь к файлу)

  - `port`: необязательный, сетевой порт сервера MySQL.

    по умолчанию порт для X Protocol равен 33060

  - `?attribute=value`: этот элемент является необязательным и определяет словарь данных, который содержит различные параметры, в том числе:

    - Атрибут `auth` (механизм аутентификации), поскольку он относится к зашифрованным соединениям. Для получения дополнительной информации смотрите » Параметры команды для зашифрованных соединений. Поддерживаются следующие значения: `plain`, `mysql41`, `external`, и `sha256_mem`.

    - Атрибут `connect-timeout` влияет на соединение, а не на последующие операции. Он устанавливается для каждого соединения на одном или нескольких хостах.

      Введите положительное целое число, чтобы определить время ожидания соединения в секундах, или введите 0 (ноль), чтобы отключить время ожидания (бесконечно). Не определяя время ожидания подключения, вы используется значение по умолчанию 10.

      Связанные, переменные среды MYSQLX_CONNECTION_TIMEOUT (время ожидания в секундах) и MYSQLX_TEST_CONNECTION_TIMEOUT (используемые во время выполнения тестов) могут быть установлены и использованы вместо connect-timeout соединения в URI. Параметр URI подключения к connect-timeout имеет приоритет над переменными среды.

    - Необязательный атрибут `compression` принимает следующие значения: `preferred` (клиент договаривается с сервером, чтобы найти поддерживаемый алгоритм; соединение не сжато, если взаимно поддерживаемый алгоритм не найден), `required` (как "preferred", но соединение разрывается, если взаимно поддерживаемый алгоритм не найден), или `disabled` (соединение не сжато). По умолчанию используется `preferred`.

      Опция была добавлена в версии 8.0.20.

    - Необязательный атрибут `compression-algorithms` определяет желаемые алгоритмы сжатия (и их предпочтительный порядок использования): `zstd_stream`(псевдоним: zstd), `lz4_message` (псевдоним: lz4) или `deflate_stream` (псевдонимы: deflate или zlib). По умолчанию используется порядок (в зависимости от доступности системы): lz4_message, zstd_stream, затем deflate_stream. Например, при передаче compression-algorithms=[lz4, zstd_stream] используется lz4, если он доступен, в противном случае используется zstd_stream. Если оба недоступны, поведение зависит от значения сжатия, например, если compression=required, то произойдёт сбой с ошибкой.

      Опция была добавлена в версии 8.0.22.

  Пример #1 Примеры URI

      mysqlx://foobar
      mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
      mysqlx://foo:bar@localhost:33060
      mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33260?ssl-mode=required
      mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
      mysqlx://foo:bar@(/path/to/socket)
      mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
      mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33160/?connect-timeout=0
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

  Для получения дополнительной информации смотрите MySQL Shell » Подключение с использованием строки URI.

### Возвращаемые значения

Объект Session.

### Ошибки

Ошибка соединения вызывает Exception.

### Примеры

Пример #2 Пример использования mysql_xdevapi\getSession()

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Не удалось установить соединение: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => helloworld
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        [2] => mysql_xdevapi\Schema Object
            (
                [name] => mysql
            )
        [3] => mysql_xdevapi\Schema Object
            (
                [name] => performance_schema
            )
        [4] => mysql_xdevapi\Schema Object
            (
                [name] => sys
            )
    )

    80012

    array(4) {
      ["_id"]=>
      string(28) "00005ad66abf0001000400000003"
      ["age"]=>
      int(42)
      ["job"]=>
      string(7) "Butler"
      ["name"]=>
      string(4) "Alfred"
    }

## Содержание

- expression — Связывает подготовленные переменные утверждения в качестве параметров
- getSession — Подключается к серверу MySQL

# Интерфейс BaseResult

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\BaseResult {
/* Методы */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — Получает предупреждения последней операции

### Описание

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Получает предупреждения, сгенерированные последней операцией сервера MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов Warning последней операции. Каждый объект содержит сообщение об ошибке ('message'), уровень ошибки ('level') и код ошибки ('code'). Возвращается пустой массив, если ошибок нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# BaseResult::getWarningsCount

(No version information available, might only be in Git)

BaseResult::getWarningsCount — Получает количество предупреждений последней операции

### Описание

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Возвращает количество предупреждений, выданных последней операцией. В частности, эти предупреждения вызываются сервером MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество предупреждений последней операции.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Вывод приведённого примера будет похож на:

    2

## Содержание

- BaseResult::getWarnings — Получает предупреждения последней операции
- BaseResult::getWarningsCount — Получает количество предупреждений последней операции

# Класс Client

(No version information available, might only be in Git)

## Введение

Предоставляет доступ к пулу соединений.

## Обзор класса

class mysql_xdevapi\Client {
/* Методы */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

(No version information available, might only be in Git)

mysql_xdevapi\Client::close — Закрытие клиента

### Описание

public function mysql_xdevapi\Client::close(): bool

Закрывает все клиентские соединения с сервером.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если соединения закрыты.

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Конструктор класса Client

### Описание

private function mysql_xdevapi\Client::__construct()

Конструктор класса Client.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Client::__construct()

    <?php
    $pooling_options = '{
      "enabled": true,
        "maxSize": 10,
        "maxIdleTime": 3600,
        "queueTimeOut": 1000
    }';
    $client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
    $session = $client->getSession();

# Client::getClient

(No version information available, might only be in Git)

Client::getClient — Получает сеанс клиента

### Описание

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Получает сеанс, связанный с клиентом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Session.

## Содержание

- mysql_xdevapi\Client::close — Закрытие клиента
- Client::__construct — Конструктор класса Client
- Client::getClient — Получает сеанс клиента

# Класс Collection

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* Свойства */
public $name;
/* Методы */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## Свойства

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — Добавляет документ в коллекцию

### Описание

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Запускает добавление данного документа (документов) в коллекцию, поддерживаются несколько вариантов метода. Возможные варианты:

1. Добавление одного документа в виде строки JSON.

2. Добавление одного документа в виде массива, например: `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. В одну и ту же операцию можно добавить, как документ, так и несколько документов.

### Список параметров

`document`

  Один или несколько документов, это может быть либо JSON, либо массив полей с соответствующими значениями. Массив не может быть пустым.

  Сервер MySQL автоматически генерирует уникальные значения `_id` для каждого документа (рекомендуется), хотя оно также может быть добавлено вручную. Это значение должно быть уникальным, иначе операция добавления не будет выполнена.

### Возвращаемые значения

Объект CollectionAdd. Используйте execute() для возврата Result, который можно использовать для запроса количества затронутых элементов, количества предупреждений, сгенерированных операцией, или для получения списка сгенерированных идентификаторов для добавленных документов.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::add()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Добавление двух документов
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Добавление двух документов используя один объект JSON
    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    // Получение списка сгенерированных идентификаторов последней операции add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Примечания

> Замечание:

> MySQL Server 8.0 или выше генерирует уникальный _id, как показано в примере. Поле _id должно быть определено вручную, если используется MySQL Server 5.7.

# Collection::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — Добавляет или заменяет документ коллекции

### Описание

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Добавляет новый документ или заменяет существующий.

Вот несколько сценариев для этого метода:

- Если ни идентификатор, ни какое-либо уникальное значение ключа не конфликтуют с каким-либо документом в коллекции, то этот документ добавляется.

- Если идентификатор не соответствует ни одному документу, но одно или несколько уникальных значений ключей конфликтуют с документом в коллекции, выдаётся ошибка.

- Если идентификатор соответствует существующему документу и уникальные ключи не определены для коллекции, то документ заменяется.

- Если идентификатор соответствует существующему документу, или все уникальные ключи в документе замены соответствуют этому же документу или не конфликтуют с другими документами в коллекции, документ заменяется.

- Если идентификатор соответствует существующему документу, а один или несколько уникальных ключей соответствуют документу, отличному от коллекции, выдаётся ошибка.

### Список параметров

`id`

  Идентификатор фильтра. Если идентификатор или любое другое поле с уникальным индексом уже существует в коллекции, он обновит соответствующий документ.

  По умолчанию этот идентификатор автоматически генерируется MySQL Server при добавлении записи и упоминается, как поле с именем '_id'.

`doc`

  Это документ для добавления или замены, представляющий собой строку JSON.

### Возвращаемые значения

Объект Result.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::addOrReplaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Использование add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Использование addOrReplaceOne()
    // Примечания: мы передаём известное значение _id
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

(No version information available, might only be in Git)

Collection::__construct — Конструктор класса Collection

### Описание

private function mysql_xdevapi\Collection::__construct()

Создаёт объект Collection.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Уникальный _id (по умолчанию и рекомендуется) генерируется MySQL Server
    // Возвращает сгенерированные _id; в этом примере добавлена только одна запись, поэтому $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Вывод приведённого примера будет похож на:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

(No version information available, might only be in Git)

Collection::count — Получает количество документов

### Описание

public function mysql_xdevapi\Collection::count(): int

Функционал аналогичен операции SQL `SELECT COUNT(*)` на сервере MySQL для текущей схемы и коллекции. Другими словами, метод подсчитывает количество документов в коллекции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество документов в коллекции.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection
      ->add(
      '{"name": "Bernie",
        "jobs": [
          {"title":"Cat Herder","Salary":42000},
          {"title":"Father","Salary":0}
        ],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [
          {"title":"Scientist","Salary":18000},
          {"title":"Mother","Salary":0}
        ],
        "hobbies": ["Walking","Making pies"]}')
      ->execute();

    var_dump($collection->count());
    ?>

Результат выполнения приведённого примера:

    int(2)

# Collection::createIndex

(No version information available, might only be in Git)

Collection::createIndex — Создаёт индекс для коллекции

### Описание

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Создаёт индекс для коллекции.

Выдаётся исключение, если индекс с таким именем уже существует, или если определение индекса сформировано неправильно.

### Список параметров

`index_name`

  Имя индекса, который нужно создать. Должно быть корректным именем индекса, допустимым для SQL-запроса `CREATE INDEX`.

`index_desc_json`

  Определение индекса для создания. Содержит массив объектов IndexField, и каждый объект описывает один элемент документа для добавления в индекс, а также необязательную строку для типа индекса, который может быть INDEX (по умолчанию) или SPATIAL.

  Одно описание IndexField состоит из следующих полей:

  - `field`: строка, полный путь документа к элементу документа или полю для индексации.

  - `type`: строка, один из поддерживаемых типов столбцов SQL для сопоставления поля. Для числовых типов может быть добавлено необязательное ключевое слово UNSIGNED. Для типа TEXT может быть добавлена длина, учитываемая для индексации.

  - `required`: логическое значение, (необязательное) true, если поле должно быть обязательным в документе. По умолчанию используется значение `false`, за исключением типа `GEOJSON`, где по умолчанию используется значение `true`.

  - `options`: целое число, (необязательное) флаги специальных опций для использования при декодировании данных `GEOJSON`.

  - `srid`: целое число, (необязательное) значение srid для использования при декодировании данных `GEOJSON`.

  Ошибочно включать другие поля, не описанные выше, в документы IndexDefinition или IndexField.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::createIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // Создание текстового индекса
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // Пространственный индекс
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Индекс с несколькими полями
    $collection->createIndex(
      'myindex3',
      '{"fields": [
        {
          "field": "$.name",
          "type": "TEXT(20)",
          "required": true
        },
        {
          "field": "$.age",
          "type": "INTEGER"
        },
        {
          "field": "$.job",
          "type": "TEXT(30)",
          "required": false
        }
      ],
      "unique": true
      }'
    );

# Collection::dropIndex

(No version information available, might only be in Git)

Collection::dropIndex — Удаляет индекс коллекции

### Описание

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Удаляет индекс коллекции.

Данная операция не приведёт к возникновению ошибки, если индекс не существует, но в этом случае вернётся `false`.

### Список параметров

`index_name`

  Имя индекса коллекции для удаления.

### Возвращаемые значения

`true`, если операция DROP INDEX выполнена успешно, `false` в противном случае.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::dropIndex()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    $collection->createIndex(
      'myindex',
      '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
    );

    // ...

    if ($collection->dropIndex('myindex')) {
        echo "Индекс с названием 'myindex' был найден и удалён.";
    }
    ?>

Результат выполнения приведённого примера:

    Индекс с названием 'myindex' был найден и удалён.

# Collection::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — Проверяет, существует ли коллекция в базе данных

### Описание

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Проверяет, ссылается ли объект Collection на коллекцию в базе данных (схему).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` если коллекция существует в базе данных, иначе `false` если это не так.

Таблица, определённая двумя столбцами (doc и _id), считается коллекцией, и третьим столбцом _json_schema с MySQL 8.0.21. Добавление дополнительного столбца означает, что existsInDatabase() больше не будет видеть его как коллекцию.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    // ...

    if (!$collection->existsInDatabase()) {
        echo "Коллекция с именем addressbook не существует в базе данных. Что случилось?";
    }
    ?>

# Collection::find

(No version information available, might only be in Git)

Collection::find — Ищет документ

### Описание

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Ищет документ или набор документов в коллекции базы данных. Найденные документы возвращаются в виде объекта CollectionFind, из которого в дальнейшем можно извлекать результаты или изменять их.

### Список параметров

`search_condition`

  Хотя это необязательно, обычно определяется условие, сужающее результаты до подмножества документов.

  Условие могут составлять несколько элементов, синтаксис поддерживает привязку параметров. Выражение, используемое в качестве условия поиска, должно быть допустимым выражением SQL. Если условие поиска не указано (поле пустое), подразумевается find('true').

### Возвращаемые значения

Объект CollectionFind для проверки операции или получения найденных документов.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::find()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Альфред",     "age": 18, "job": "Дворецкий"}')->execute();
    $collection->add('{"name": "Боб",        "age": 19, "job": "Пловец"}')->execute();
    $collection->add('{"name": "Фред",       "age": 20, "job": "Строитель"}')->execute();
    $collection->add('{"name": "Уилма",      "age": 21, "job": "Учитель"}')->execute();
    $collection->add('{"name": "Джон",       "age": 22, "job": "Учитель"}')->execute();

    $find   = $collection->find('job LIKE :job AND age > :age');
    $result = $find
      ->bind(['job' => 'Учитель', 'age' => 20])
      ->sort('age DESC')
      ->limit(2)
      ->execute();

    print_r($result->fetchAll());
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b536100000000000000a8
                [age] => 22
                [job] => Учитель
                [name] => Джон
            )
        [1] => Array
            (
                [_id] => 00005b6b536100000000000000a7
                [age] => 21
                [job] => Учитель
                [name] => Уилма
            )
    )

# Collection::getName

(No version information available, might only be in Git)

Collection::getName — Получает название коллекции

### Описание

public function mysql_xdevapi\Collection::getName(): string

Получает название коллекции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Название коллекции в виде строки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    var_dump($collection->getName());
    ?>

Вывод приведённого примера будет похож на:

    string(6) "people"

# Collection::getOne

(No version information available, might only be in Git)

Collection::getOne — Получает один документ

### Описание

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Выбирает один документ из коллекции.

Это краткая запись для: `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### Список параметров

`id`

  _id документа в коллекции.

### Возвращаемые значения

Объект коллекции или `null`, если _id не соответствует документу.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::getOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Уникальный _id (по умолчанию и рекомендуется) генерируется MySQL Server
    // Возвращает сгенерированные _id; в этом примере только одна запись, поэтому $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Вывод приведённого примера будет похож на:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

(No version information available, might only be in Git)

Collection::getSchema — Возвращает объект Schema

### Описание

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Возвращает объект Schema, содержащий коллекцию.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Schema в случае успешного выполнения или `null`, если объект не может быть возвращён для данной коллекции.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    var_dump($collection->getSchema());
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

(No version information available, might only be in Git)

Collection::getSession — Возвращает объект Session

### Описание

public function mysql_xdevapi\Collection::getSession(): Session

Возвращает новый объект Session из объекта Collection.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Session.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    $newsession = $collection->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Session)#1 (0) {
    }
    object(mysql_xdevapi\Session)#4 (0) {
    }

# Collection::modify

(No version information available, might only be in Git)

Collection::modify — Изменяет документы коллекции

### Описание

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Изменяет документы коллекции, соответствующие определённым условиям поиска.

### Список параметров

`search_condition`

  Параметр должен быть допустимым выражением SQL, используемым для соответствия документам, которые нужно изменить. Это выражение может быть простым значением `true`, что соответствует всем документам, или может использовать функции и операторы, такие как `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` или `'_id IN ["2","5","7","10"]'`.

### Возвращаемые значения

Если операция не выполнена, функция вернёт объект Modify, который можно использовать для добавления дополнительных операций MODIFY.

Если операция MODIFY выполнена, то возвращаемый объект будет содержать результат операции.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::modify()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Альфред", "age": 18, "job": "Дворецкий"}')->execute();
    $collection->add('{"name": "Боб",    "age": 19, "job": "Художник"}')->execute();

    // Добавление двух работ для всех художников: артист и мастер
    $collection
      ->modify("job in ('Дворецкий', 'Художник')")
      ->arrayAppend('job', 'Артист')
      ->arrayAppend('job', 'Мастер')
      ->execute();

    // Удаление поля 'beer' из всех документов с возрастом 21
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

(No version information available, might only be in Git)

Collection::remove — Удаляет документы коллекции

### Описание

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Удаляет документы коллекции, которые удовлетворяют условиям поиска. Разрешено выполнение несколько операций и поддерживается привязка параметров.

### Список параметров

`search_condition`

  Должно быть корректным выражением SQL, которое будет использовано для сопоставления документов, которые нужно удалить. Выражение может быть таким же простым, как логическое значение `true`, которое соответствует всем документам, или оно может использовать функции и операторы наподобие `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` или `'_id IN ["2","5","7","10"]'`.

### Возвращаемые значения

Если операция не выполнена, функция вернёт объект Remove, который можно использовать для добавления дополнительных операций удаления.

Если операция удаления выполнена, то возвращённый объект будет содержать результат операции.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Collection::remove()

    <?php

    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Удаление всех художников
    $collection
        ->remove("job in ('Painter')")
        ->execute();

    // Удаление самого старого дворецкого
    $collection
        ->remove("job in ('Butler')")
        ->sort('age desc')
        ->limit(1)
        ->execute();

    // Удаление записи с наибольшим возрастом
    $collection
        ->remove('true')
        ->sort('age desc')
        ->limit(1)
        ->execute()
    ;

    ?>

# Collection::removeOne

(No version information available, might only be in Git)

Collection::removeOne — Удаляет один документ из коллекции

### Описание

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Метод удаляет один документ из коллекции по идентификатору. Этот метод — сокращённая запись вызова `Collection.remove("_id = :id").bind("id", id).execute()`.

### Список параметров

`id`

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

### Возвращаемые значения

Объект Result, который можно использовать для запроса количества затронутых элементов или количества предупреждений, которые сгенерировала операция.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Collection::removeOne()

    <?php

    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Обычно _id узнают другими способами,
    // но для этого примера давайте извлечём сгенерированный идентификатор и используем его
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if (!$result->getAffectedItemsCount()) {
        echo "Alfred с идентификатором $alfred_id не был удален.";
    } else {
        echo "До свидания, Alfred, ты можешь взять с собой _id $alfred_id.";
    }

    ?>

Вывод приведённого примера будет похож на:

    До свидания, Alfred, ты можешь взять с собой _id 00005b6b536100000000000000cb.

# Collection::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — Заменяет один документ коллекции

### Описание

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Обновляет (или заменяет) документ, по идентификатору, если он существует.

### Список параметров

`id`

  Идентификатор документа для замены или обновления. Обычно это _id, который был сгенерирован MySQL Server при добавлении записи.

`doc`

  Документ коллекции для обновления или замены документа, соответствующего параметру id.

  Документ может быть либо объектом документа, либо корректной строкой JSON, описывающей новый документ.

### Возвращаемые значения

Объект Result, который можно использовать для запроса количества затронутых элементов и количества предупреждений, сгенерированных операцией.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::replaceOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Обычно _id известен другими способами,
    // но для этого примера давайте извлечём сгенерированный идентификатор и используем его
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## Содержание

- Collection::add — Добавляет документ в коллекцию
- Collection::addOrReplaceOne — Добавляет или заменяет документ коллекции
- Collection::__construct — Конструктор класса Collection
- Collection::count — Получает количество документов
- Collection::createIndex — Создаёт индекс для коллекции
- Collection::dropIndex — Удаляет индекс коллекции
- Collection::existsInDatabase — Проверяет, существует ли коллекция в базе данных
- Collection::find — Ищет документ
- Collection::getName — Получает название коллекции
- Collection::getOne — Получает один документ
- Collection::getSchema — Возвращает объект Schema
- Collection::getSession — Возвращает объект Session
- Collection::modify — Изменяет документы коллекции
- Collection::remove — Удаляет документы коллекции
- Collection::removeOne — Удаляет один документ из коллекции
- Collection::replaceOne — Заменяет один документ коллекции

# Класс CollectionAdd

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* Методы */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — Конструктор класса CollectionAdd

### Описание

private function mysql_xdevapi\CollectionAdd::__construct()

Используется для добавления документа в коллекцию; вызывается из объекта Collection.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionAdd::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Добавляем два документа
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Добавляем два документа, используя один объект JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Получаем список сгенерированных идентификаторов из последнего выполнения add()
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Примечания

> Замечание:

> MySQL Server 8.0 или выше генерирует уникальный _id, как показано в примере. Поле _id должно быть определено вручную, если используется MySQL Server 5.7.

# CollectionAdd::execute

(No version information available, might only be in Git)

CollectionAdd::execute — Выполняет утверждение

### Описание

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

Метод execute необходим для отправки запроса операции CRUD на сервер MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Result, который можно использовать для проверки состояния операции, например, количества затронутых строк.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionAdd::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Добавляем два документа
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Добавляем два документа, используя один объект JSON
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Получаем список сгенерированных идентификаторов из последнего выполнения add()
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## Содержание

- CollectionAdd::__construct — Конструктор класса CollectionAdd
- CollectionAdd::execute — Выполняет утверждение

# Класс CollectionFind

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Методы */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

(No version information available, might only be in Git)

CollectionFind::bind — Привязывает значение к заполнителю запроса

### Описание

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

Позволяет пользователю привязать параметр к заполнителю в условии поиска операции поиска. Заполнитель имеет вид :NAME, где ':' - это общий префикс, который должен всегда существовать перед любым NAME, NAME - фактическое имя заполнителя. Функция bind принимает список заполнителей, если в условии поиска необходимо заменить несколько объектов.

### Список параметров

`placeholder_values`

  Значения для подстановки в условиях поиска; допускается несколько значений, которые передаются в виде массива, где "PLACEHOLDER_NAME => PLACEHOLDER_VALUE".

### Возвращаемые значения

Объект CollectionFind, или цепочка с execute() для возврата объекта Result.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::__construct

(No version information available, might only be in Git)

CollectionFind::__construct — Конструктор класса CollectionFind

### Описание

private function mysql_xdevapi\CollectionFind::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::execute

(No version information available, might only be in Git)

CollectionFind::execute — Выполняет утверждение

### Описание

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Выполняет операцию поиска; эта функциональность разрешена для цепочки методов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект класса mysql_xdevapi\DocResult, из которого можно либо получить результаты, либо запросить состояние операции.

### Примеры

Пример #1 Пример использования класса CollectionFind

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::fields

(No version information available, might only be in Git)

CollectionFind::fields — Устанавливает фильтр поля документа

### Описание

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Определяет столбцы, которые должен вернуть запрос. Если не определено, то возвращаются все столбцы.

### Список параметров

`projection`

  Может быть либо одной строкой, либо массивом строк, определяющих столбцы, которые нужно вернуть для каждого документа, который соответствует условию поиска.

### Возвращаемые значения

Возвращает объект класса CollectionFind, который можно использовать для дальнейшей обработки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::fields()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->fields('name')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — Устанавливает критерии группировки

### Описание

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

Эту функцию вызывают для группировки набора результатов по одному или нескольким столбцам. Её часто вызывают с агрегатными функциями, например: `COUNT`, `MAX`, `MIN`, `SUM` и т. д.

### Список параметров

`sort_expr`

  Столбец или столбцы, по которым будет проведена операция группировки, это может быть либо одна строка, либо массив строковых аргументов, по одному для каждого столбца.

### Возвращаемые значения

Возвращает объект класса CollectionFind, с которым можно будет работать далее.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\CollectionFind::groupBy()

    <?php

    // Предполагая, что $coll — корректный объект класса Collection

    // Извлекает все документы из коллекции и группирует результаты по полю 'name'
    $res = $coll->find()->groupBy('name')->execute();

    ?>

# CollectionFind::having

(No version information available, might only be in Git)

CollectionFind::having — Устанавливает условие для агрегатных функций

### Описание

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

Функция может использоваться после операции 'field', чтобы сделать выборку документов для извлечения.

### Список параметров

`sort_expr`

  Должно быть корректное выражение SQL, разрешено использование агрегатных функций.

### Возвращаемые значения

Объект CollectionFind, который можно использовать для дальнейшей обработки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::having()

    <?php

    //Предполагая, что $coll является корректным объектом Collection

    //Найти все документы, у которых 'age' больше 40,
    //В объекте Result возвращаются только столбцы 'name' и 'age'.
    $res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

    ?>

# CollectionFind::limit

(No version information available, might only be in Git)

CollectionFind::limit — Ограничивает количество возвращаемых документов

### Описание

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

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

### Список параметров

`rows`

  Максимальное количество документов.

### Возвращаемые значения

Объект CollectionFind, который можно использовать для дополнительной обработки; цепочка с методом execute() для возврата объекта DocResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::lockExclusive

(No version information available, might only be in Git)

CollectionFind::lockExclusive — Выполняет операцию с EXCLUSIVE LOCK

### Описание

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Накладывает на документ исключительную блокировку. До тех пор, пока документ заблокирован, другие транзакции не могут обновлять документ, выполнять выражения `SELECT ... LOCK IN SHARE MODE` или читать данные на отдельных уровнях изоляции транзакций. Согласованные чтения игнорируют любые блокировки, установленные для записей, которые существуют в представлении чтения.

Чтобы не было проблем с конкурентным доступом, имеет смысл вызывать этот метод совместно с методом mysql_xdevapi\Collection::modify(). По существу, эта функция использует блокировки строк для сериализации доступа к строкам.

### Список параметров

`lock_waiting_option`

  Дополнительная опция ожидания. Значение по умолчанию — `MYSQLX_LOCK_DEFAULT`. Допустимые значения определены константами:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Возвращаемые значения

Возвращает объект класса CollectionFind, с которым можно будет работать далее.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\CollectionFind::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockExclusive()
      ->execute();

    // ... выполняем операцию с объектом

    // Завершаем транзакцию и разблокируем документ
    $session->commit();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — Выполняет операцию с SHARED LOCK

### Описание

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Разрешает разделять документы между несколькими транзакциями, которые блокируются в режиме совместного доступа.

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

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

### Список параметров

`lock_waiting_option`

  Дополнительная опция ожидания. По умолчанию имеет значение `MYSQLX_LOCK_DEFAULT`. Допустимые значения представлены константами:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Возвращаемые значения

Возвращает объект класса CollectionFind, с которым можно будет работать далее.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\CollectionFind::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockShared()
      ->execute();

    // ... читаем объект в режиме совместного доступа

    // Завершаем транзакцию и разблокируем документ
    $session->commit();
    ?>

# CollectionFind::offset

(No version information available, might only be in Git)

CollectionFind::offset — Пропускает указанное количество возвращаемых элементов

### Описание

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Пропускает (смещает) это количество элементов, которые в противном случае были бы возвращены операцией поиска. Используйте совместно с методом limit().

При значении, превышающем размер набора результатов, приводит к пустому набору.

### Список параметров

`position`

  Количество элементов, которые нужно пропустить для операции limit().

### Возвращаемые значения

Объект CollectionFind, который можно использовать для дополнительной обработки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('age asc')
      ->offset(1)
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::sort

(No version information available, might only be in Git)

CollectionFind::sort — Устанавливает критерии сортировки

### Описание

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Сортирует набор результатов по полю, выбранному в аргументе sort_expr. Разрешённые направления: ASC (по возрастанию) или DESC (по убыванию). Операция эквивалентна операции SQL 'ORDER BY' и соответствует тому же набору правил.

### Список параметров

`sort_expr`

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

### Возвращаемые значения

Объект CollectionFind, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionFind::sort()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('job desc', 'age asc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000106"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000107"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

## Содержание

- CollectionFind::bind — Привязывает значение к заполнителю запроса
- CollectionFind::__construct — Конструктор класса CollectionFind
- CollectionFind::execute — Выполняет утверждение
- CollectionFind::fields — Устанавливает фильтр поля документа
- CollectionFind::groupBy — Устанавливает критерии группировки
- CollectionFind::having — Устанавливает условие для агрегатных функций
- CollectionFind::limit — Ограничивает количество возвращаемых документов
- CollectionFind::lockExclusive — Выполняет операцию с EXCLUSIVE LOCK
- CollectionFind::lockShared — Выполняет операцию с SHARED LOCK
- CollectionFind::offset — Пропускает указанное количество возвращаемых элементов
- CollectionFind::sort — Устанавливает критерии сортировки

# Класс CollectionModify

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* Методы */
public function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

(No version information available, might only be in Git)

CollectionModify::arrayAppend — Добавляет элемент в поле массива

### Описание

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Добавляет элемент в поле документа, когда несколько элементов поля представляются в виде массива. В отличие от arrayInsert(), arrayAppend() всегда добавляет новый элемент в конец массива, тогда как arrayInsert() может определять местоположение.

### Список параметров

`collection_field`

  Идентификатор поля, в которое вставляется новый элемент.

`expression_or_literal`

  Новый элемент для добавления в конец массива полей документа.

### Возвращаемые значения

Объект CollectionModify, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::arrayAppend()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::arrayInsert

(No version information available, might only be in Git)

CollectionModify::arrayInsert — Добавляет элемент в поле массива

### Описание

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Добавляет элемент в поле документа, когда поле — это массив из нескольких элементов. Через этот метод, в отличие от метода mysql_xdevapi\CollectionModify::arrayAppend(), можно указать, куда добавится новый элемент, определяя, после какого элемента он будет идти, тогда как метод mysql_xdevapi\CollectionModify::arrayAppend() добавляет новый элемент в конец массива.

### Список параметров

`collection_field`

  Определите элемент в массиве, после которого добавится новый элемент. Формат этого параметра: `FIELD_NAME[ INDEX ]`, где FIELD_NAME — это имя поля документа, в которое нужно добавить элемент, а INDEX — это INDEX элемента в поле.

  Поле INDEX основано на нуле, поэтому у первого элемента массива индекс — 0.

`expression_or_literal`

  Новый элемент для добавления после FIELD_NAME[ INDEX ]

### Возвращаемые значения

Объект CollectionModify, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::arrayInsert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayInsert('traits[1]', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010d
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Happy
                        [2] => Brother
                        [3] => Human
                    )
            )
    )

# CollectionModify::bind

(No version information available, might only be in Git)

CollectionModify::bind — Привязывает значение к заполнителю запроса

### Описание

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Привязывает параметр к заполнителю в условии поиска операции изменения.

Заполнитель имеет вид :NAME, где ':' - это общий префикс, который должен всегда существовать до любого NAME, где NAME - это имя заполнителя. Метод bind принимает список заполнителей, если в условии поиска операции изменения необходимо заменить несколько объектов.

### Список параметров

`placeholder_values`

  Подстановочные значения для замены в условии поиска. Допускается использование нескольких значений, которые необходимо передать в виде массива сопоставлений PLACEHOLDER_NAME->PLACEHOLDER_VALUE.

### Возвращаемые значения

Объект CollectionModify, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000110
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::__construct

(No version information available, might only be in Git)

CollectionModify::__construct — Конструктор класса CollectionModify

### Описание

private function mysql_xdevapi\CollectionModify::__construct()

Изменяет (обновляет) коллекцию и создаётся методом mysql_xdevapi\Collection::modify().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\CollectionModify::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::execute

(No version information available, might only be in Git)

CollectionModify::execute — Выполняет операцию изменения

### Описание

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

Метод execute необходим для отправки запроса операции CRUD на сервер MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Result, который можно использовать для проверки состояния операции, например, количества затронутых строк.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::execute()

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — Ограничивает количество изменяемых документов

### Описание

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Ограничивает количество документов, изменяемых этой операцией. При желании можно использовать skip() для определения значения смещения.

### Список параметров

`rows`

  Максимальное количество документов для изменения.

### Возвращаемые значения

Объект CollectionModify.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

    $collection
      ->modify("job = :job")
      ->bind(['job' => 'Teacher'])
      ->set('job', 'Principal')
      ->limit(1)
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000118
                [age] => 21
                [job] => Construction
                [name] => Fred
            )
        [1] => Array
            (
                [_id] => 00005b6b53610000000000000119
                [age] => 23
                [job] => Principal
                [name] => Wilma
            )
        [2] => Array
            (
                [_id] => 00005b6b5361000000000000011a
                [age] => 24
                [job] => Teacher
                [name] => Betty
            )
    )

# CollectionModify::patch

(No version information available, might only be in Git)

CollectionModify::patch — Исправляет документ

### Описание

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Принимает объект исправления и применяет его к одному или нескольким документам, и может обновлять несколько свойств документа.

### Список параметров

`document`

  Документ со свойствами, применяемыми к соответствующим документам.

### Возвращаемые значения

Объект CollectionModify.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::patch()

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

(No version information available, might only be in Git)

CollectionModify::replace — Заменяет поле документа

### Описание

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Заменяет (обновляет) данное значение поля новым.

### Список параметров

`collection_field`

  Путь документа к элементу для обновления.

`expression_or_literal`

  Значение, устанавливаемое для указанного атрибута.

### Возвращаемые значения

Объект CollectionModify.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::replace()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->replace("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000011b
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::set

(No version information available, might only be in Git)

CollectionModify::set — Устанавливает атрибут документа

### Описание

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Устанавливает или обновляет атрибуты документов в коллекции.

### Список параметров

`collection_field`

  Путь к документу (имя) элемента для установки.

`expression_or_literal`

  Значение для установки.

### Возвращаемые значения

Объект CollectionModify.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->set("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000111
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::skip

(No version information available, might only be in Git)

CollectionModify::skip — Пропускает элементы

### Описание

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Пропускает первые N элементов, которые иначе были бы возвращены операцией поиска. Если количество пропущенных элементов превышает размер набора результатов, операция поиска возвращает пустой набор.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`position`

  Количество пропускаемых элементов.

### Возвращаемые значения

Возвращает объект класса CollectionModify, с которым можно работать далее.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::skip()

    <?php

    $coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

    ?>

# CollectionModify::sort

(No version information available, might only be in Git)

CollectionModify::sort — Устанавливает критерии сортировки

### Описание

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Сортирует набор результатов по полю, переданному в аргументе sort_expr. Разрешённые направления сортировки: ASC (по возрастанию) или DESC (по убыванию). Эта операция эквивалентна операции SQL 'ORDER BY' и соответствует тому же набору правил.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`sort_expr`

  Можно указать одно или несколько выражений сортировки. Оценка выполняется слева направо, а выражения должны быть разделены запятой.

### Возвращаемые значения

Возвращает объект класса CollectionModify, с которым можно работать далее.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::sort()

    <?php

    $res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

    ?>

# CollectionModify::unset

(No version information available, might only be in Git)

CollectionModify::unset — Сбрасывает значение полей документа

### Описание

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Удаляет атрибуты из документов в коллекции.

### Список параметров

`fields`

  Атрибуты для удаления из документов в коллекции.

### Возвращаемые значения

Возвращает объект класса CollectionModify, с которым можно работать далее.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionModify::unset()

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## Содержание

- CollectionModify::arrayAppend — Добавляет элемент в поле массива
- CollectionModify::arrayInsert — Добавляет элемент в поле массива
- CollectionModify::bind — Привязывает значение к заполнителю запроса
- CollectionModify::__construct — Конструктор класса CollectionModify
- CollectionModify::execute — Выполняет операцию изменения
- CollectionModify::limit — Ограничивает количество изменяемых документов
- CollectionModify::patch — Исправляет документ
- CollectionModify::replace — Заменяет поле документа
- CollectionModify::set — Устанавливает атрибут документа
- CollectionModify::skip — Пропускает элементы
- CollectionModify::sort — Устанавливает критерии сортировки
- CollectionModify::unset — Сбрасывает значение полей документа

# Класс CollectionRemove

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Методы */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

(No version information available, might only be in Git)

CollectionRemove::bind — Привязывает значение к заполнителю

### Описание

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Привязывает параметр к заполнителю в условии поиска операции удаления.

Заполнитель имеет вид :NAME, где ':' - это общий префикс, который должен всегда указан перед любым NAME, где NAME - это имя заполнителя. Метод bind принимает список заполнителей, если в условии поиска операции удаления необходимо заменить несколько объектов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`placeholder_values`

  Значения заполнителя для замены в условии поиска. Допускается использование нескольких значений, которые необходимо передать в виде массива сопоставлений PLACEHOLDER_NAME->PLACEHOLDER_VALUE.

### Возвращаемые значения

Объект CollectionRemove, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionRemove::bind()

    <?php

    $res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

    ?>

# CollectionRemove::__construct

(No version information available, might only be in Git)

CollectionRemove::__construct — Конструктор класса CollectionRemove

### Описание

private function mysql_xdevapi\CollectionRemove::__construct()

Удаляет документы коллекции и создаётся экземпляром метода mysql_xdevapi\Collection::remove().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Collection::remove()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Удаление всех художников
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Удалить самого старого дворецкого
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Удалить запись с самым низким возрастом
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

(No version information available, might only be in Git)

CollectionRemove::execute — Выполняет операцию удаления

### Описание

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

Функция execute должна вызываться, чтобы заставить клиента отправить запрос операции CRUD на сервер.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Result.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionRemove::execute()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

(No version information available, might only be in Git)

CollectionRemove::limit — Ограничивает количество документов для удаления

### Описание

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Устанавливает максимальное количество документов для удаления.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`rows`

  Максимальное количество документов для удаления.

### Возвращаемые значения

Возвращает объект CollectionRemove, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionRemove::limit()

    <?php

    $res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

    ?>

# CollectionRemove::sort

(No version information available, might only be in Git)

CollectionRemove::sort — Устанавливает критерии сортировки

### Описание

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Сортирует набор результатов по полю, выбранному в аргументе sort_expr. Разрешённые направления: ASC (по возрастанию) или DESC (по убыванию). Эта операция эквивалентна операции SQL 'ORDER BY' и соответствует тому же набору правил.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`sort_expr`

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

### Возвращаемые значения

Объект CollectionRemove, который можно использовать для выполнения команды или для добавления дополнительных операций.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CollectionRemove::sort()

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## Содержание

- CollectionRemove::bind — Привязывает значение к заполнителю
- CollectionRemove::__construct — Конструктор класса CollectionRemove
- CollectionRemove::execute — Выполняет операцию удаления
- CollectionRemove::limit — Ограничивает количество документов для удаления
- CollectionRemove::sort — Устанавливает критерии сортировки

# Класс ColumnResult

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\ColumnResult {
/* Методы */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

(No version information available, might only be in Git)

ColumnResult::__construct — Конструктор класса ColumnResult

### Описание

private function mysql_xdevapi\ColumnResult::__construct()

Получает метаданные столбца, такие как набор символов; создаётся методом mysql_xdevapi\RowResult::getColumns().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\ColumnResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
    $session->sql("CREATE DATABASE nonsense")->execute();
    $session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
    $session->sql("INSERT INTO  nonsense.numbers values (42, 42)")->execute();

    $schema = $session->getSchema("nonsense");
    $table  = $schema->getTable("numbers");

    $result1 = $table->select('hello','world')->execute();

    // Возвращает массив объектов ColumnResult
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nМетка столбца " , $column->getColumnLabel();
        echo " принадлежит типу "       , $column->getType();
        echo " и это ", ($column->isNumberSigned() === 0) ? "беззнаковое число." : "знаковое число.";
    }

    // Альтернативный вариант
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Возвращает массив объектов FieldMetadata
    print_r($result2->getColumns());

Вывод приведённого примера будет похож на:

    Метка столбца hello принадлежит типу 19 и это знаковое число.
    Метка столбца world принадлежит типу 4 и это беззнаковое число.

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => hello
                [original_name] => hello
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 6
                [type_name] => FLOAT
                [name] => world
                [original_name] => world
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 31
                [length] => 12
                [flags] => 1
                [content_type] => 0
            )
    )

# ColumnResult::getCharacterSetName

(No version information available, might only be in Git)

ColumnResult::getCharacterSetName — Получает набор символов

### Описание

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getCharacterSetName()

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — Получает имя сопоставления

### Описание

public function mysql_xdevapi\ColumnResult::getCollationName(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getCollationName()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — Получает метку столбца

### Описание

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getColumnLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — Получает название столбца

### Описание

public function mysql_xdevapi\ColumnResult::getColumnName(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getColumnName()

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — Получает дробную длину цифры

### Описание

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Получает количество дробных цифр для столбца.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getFractionalDigits()

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — Получает длину поля столбца

### Описание

public function mysql_xdevapi\ColumnResult::getLength(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getLength()

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — Получает название схемы

### Описание

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Получает имя схемы, в которой хранится столбец.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getSchemaName()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — Получает метку таблицы

### Описание

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getTableLabel()

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — Получает название таблицы

### Описание

public function mysql_xdevapi\ColumnResult::getTableName(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Имя таблицы для столбца.

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getTableName()

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — Получает тип столбца

### Описание

public function mysql_xdevapi\ColumnResult::getType(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::getType()

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — Проверяет, задан ли числу знак

### Описание

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Получает информацию о столбцах таблицы и создаётся методом mysql_xdevapi\RowResult::getColumns().

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если столбцу задан знаковый тип.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\ColumnResult::isNumberSigned()

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — Проверяет, дополняется ли

### Описание

public function mysql_xdevapi\ColumnResult::isPadded(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если заданный столбец дополняется.

### Примеры

Пример #1 Пример использования mysql_xdevapi\ColumnResult::isPadded()

    <?php

    /* ... */

    ?>

## Содержание

- ColumnResult::__construct — Конструктор класса ColumnResult
- ColumnResult::getCharacterSetName — Получает набор символов
- ColumnResult::getCollationName — Получает имя сопоставления
- ColumnResult::getColumnLabel — Получает метку столбца
- ColumnResult::getColumnName — Получает название столбца
- ColumnResult::getFractionalDigits — Получает дробную длину цифры
- ColumnResult::getLength — Получает длину поля столбца
- ColumnResult::getSchemaName — Получает название схемы
- ColumnResult::getTableLabel — Получает метку таблицы
- ColumnResult::getTableName — Получает название таблицы
- ColumnResult::getType — Получает тип столбца
- ColumnResult::isNumberSigned — Проверяет, задан ли числу знак
- ColumnResult::isPadded — Проверяет, дополняется ли

# Интерфейс CrudOperationBindable

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CrudOperationBindable {
/* Методы */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — Привязывает значение к заполнителю

### Описание

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Привязывает значение к определённому заполнителю.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`placeholder_values`

  Имя заполнителей и значения для привязки.

### Возвращаемые значения

Объект CrudOperationBindable.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CrudOperationBindable::bind()

    <?php

    $res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
    $res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

    ?>

## Содержание

- CrudOperationBindable::bind — Привязывает значение к заполнителю

# Интерфейс CrudOperationLimitable

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CrudOperationLimitable {
/* Методы */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — Устанавливает лимит результата

### Описание

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

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

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`rows`

  Максимальное количество записей или документов.

### Возвращаемые значения

Объект CrudOperationLimitable.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CrudOperationLimitable::limit()

    <?php

    $res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
    $res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

    ?>

## Содержание

- CrudOperationLimitable::limit — Устанавливает лимит результата

# Интерфейс CrudOperationSkippable

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CrudOperationSkippable {
/* Методы */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — Количество операций для пропуска

### Описание

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Пропускает это количество записей в возвращаемой операции.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`skip`

  Количество пропускаемых элементов.

### Возвращаемые значения

Объект CrudOperationSkippable.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CrudOperationSkippable::skip()

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## Содержание

- CrudOperationSkippable::skip — Количество операций для пропуска

# Интерфейс CrudOperationSortable

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\CrudOperationSortable {
/* Методы */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — Сортирует результаты

### Описание

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Сортирует результирующий набор по полю, выбранному в аргументе sort_expr. Допустимый порядок сортировки: ASC (по возрастанию) или DESC (по убыванию). Эта операция эквивалентна операции SQL 'ORDER BY' и следует тому же набору правил.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`sort_expr`

  Может быть предоставлено одно или несколько выражений сортировки. Вычисление выполняется слева направо, и каждое выражение разделяется запятой.

### Возвращаемые значения

Объект CrudOperationSortable.

### Примеры

Пример #1 Пример использования mysql_xdevapi\CrudOperationSortable::sort()

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## Содержание

- CrudOperationSortable::sort — Сортирует результаты

# Интерфейс DatabaseObject

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\DatabaseObject {
/* Методы */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

(No version information available, might only be in Git)

DatabaseObject::existsInDatabase — Проверяет, существует ли объект в базе данных

### Описание

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Проверяет, ссылается ли объект базы данных на объект, который существует в базе данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если объект существует в базе данных, иначе `false`, если это не так.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DatabaseObject::existsInDatabase()

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — Получает имя объекта

### Описание

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Получает имя объекта базы данных.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Имя объекта базы данных.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DatabaseObject::getName()

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — Получает имя сессии

### Описание

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Получает сессию, связанную с объектом базы данных.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Session.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DatabaseObject::getSession()

    <?php

    $session = $dbObj->getSession();

    ?>

## Содержание

- DatabaseObject::existsInDatabase — Проверяет, существует ли объект в базе данных
- DatabaseObject::getName — Получает имя объекта
- DatabaseObject::getSession — Получает имя сессии

# Класс DocResult

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* Методы */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

(No version information available, might only be in Git)

DocResult::__construct — Конструктор DocResult

### Описание

private function mysql_xdevapi\DocResult::__construct()

Получить результаты и предупреждения документа, создаётся CollectionFind.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования DocResult

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Возвращает объект DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# DocResult::fetchAll

(No version information available, might only be in Git)

DocResult::fetchAll — Получить все строки

### Описание

public function mysql_xdevapi\DocResult::fetchAll(): array

Получить все результаты из результирующего набора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив со всеми результатами из запроса; каждый результат - это ассоциативный массив. Если нет строк результата запроса, то возвращается пустой массив.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DocResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Возвращает объект DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Вывод приведённого примера будет похож на:

    array(2) {

      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000123"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }

      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000122"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }

    }

# DocResult::fetchOne

(No version information available, might only be in Git)

DocResult::fetchOne — Получить одну строку

### Описание

public function mysql_xdevapi\DocResult::fetchOne(): array

Получить один результат из результирующего набора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Результат в виде ассоциативного массива, либо `null`, если результатов нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DocResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Возвращает объект DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

Вывод приведённого примера будет похож на:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000125"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

# DocResult::getWarnings

(No version information available, might only be in Git)

DocResult::getWarnings — Получить предупреждения с последней операции

### Описание

public function mysql_xdevapi\DocResult::getWarnings(): Array

Получает предупреждения от последней операции с MySQL-сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов с предупреждениями, вызванных последней операцией. Каждый объект содержит поля 'message', 'level' и 'code'. Возвращает пустой массив, если нет ошибок.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DocResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Возвращает объект DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Произошла ошибка:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Вывод приведённого примера будет похож на:

    There was an error:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
    )

# DocResult::getWarningsCount

(No version information available, might only be in Git)

DocResult::getWarningsCount — Получить количество предупреждений с последней операции

### Описание

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Возвращает количество предупреждений, вызванных последней операцией. В частности, эти предупреждения вызываются сервером MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество предупреждений с последней операции.

### Примеры

Пример #1 Пример использования mysql_xdevapi\DocResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Возвращает объект DocResult
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Произошла ошибка:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Вывод приведённого примера будет похож на:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## Содержание

- DocResult::__construct — Конструктор DocResult
- DocResult::fetchAll — Получить все строки
- DocResult::fetchOne — Получить одну строку
- DocResult::getWarnings — Получить предупреждения с последней операции
- DocResult::getWarningsCount — Получить количество предупреждений с последней операции

# Класс Exception

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Интерфейс Executable

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Executable {
/* Методы */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — Выполняет утверждение

### Описание

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Выполняет утверждение из операции сбора или запроса таблицы; эта функциональность разрешена для цепочки методов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Один из объектов Result, например, Result или SqlStatementResult.

### Примеры

Пример #1 Примеры использования execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

    var_dump($result_sql);

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("humans");

    $result_collection = $collection->add(
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}');

    $result_collection_executed = $result_collection->execute();

    var_dump($result_collection);
    var_dump($result_collection_executed);
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## Содержание

- Executable::execute — Выполняет утверждение

# Класс ExecutionStatus

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\ExecutionStatus {
/* Свойства */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## Свойства

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — Конструктор класса ExecutionStatus

### Описание

private function mysql_xdevapi\ExecutionStatus::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\ExecutionStatus::__construct()

    <?php

    /* ... */

    ?>

## Содержание

- ExecutionStatus::__construct — Конструктор класса ExecutionStatus

# Класс Expression

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Expression {
/* Свойства */
public $name;
/* Конструктор */
public function __construct(string `$expression`)
}

## Свойства

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Конструктор класса Expression

### Описание

public function mysql_xdevapi\Expression::__construct(string `$expression`)

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`expression`

### Примеры

Пример #1 Пример использования mysql_xdevapi\Expression::__construct()

    <?php

    /* ... */

    ?>

## Содержание

- Expression::__construct — Конструктор класса Expression

# Класс Result

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* Методы */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

(No version information available, might only be in Git)

Result::__construct — Конструктор класса Result

### Описание

private function mysql_xdevapi\Result::__construct()

Объект, который извлекает сгенерированные идентификаторы, значения AUTO_INCREMENT и предупреждения для набора Result.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Result::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

Результат выполнения приведённого примера:

    int(3)

# Result::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — Получает количество затронутых строк

### Описание

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Получает количество строк, затронутых предыдущей операцией.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество (как целое число) затронутых строк.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Result::getAffectedItemsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    var_dump( $res->getAffectedItemsCount() );
    ?>

Результат выполнения приведённого примера:

    int(1)

# Result::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — Получает значение автоинкремента

### Описание

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Получает последнее значение AUTO_INCREMENT (идентификатор последней вставки).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Значение AUTO_INCREMENT.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Result::getAutoIncrementValue()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

Результат выполнения приведённого примера:

    int(3)

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — Получает сгенерированные идентификаторы

### Описание

public function mysql_xdevapi\Result::getGeneratedIds(): array

Получает сгенерированные значения _id из последней операции. Уникальное поле _id генерируется сервером MySQL.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив сгенерированных _id из последней операции или пустой массив, если таковых нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Result::getGeneratedIds()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    $ids = $result->getGeneratedIds();
    var_dump($ids);
    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — Получает предупреждения последней операции

### Описание

public function mysql_xdevapi\Result::getWarnings(): array

Получает предупреждения последней операции Result.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов Warning последней операции. Каждый объект определяет 'message' об ошибке, 'level' ошибки и 'code' ошибки. Возвращается пустой массив, если ошибок нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# Result::getWarningsCount

(No version information available, might only be in Git)

Result::getWarningsCount — Получает количество предупреждений последней операции

### Описание

public function mysql_xdevapi\Result::getWarningsCount(): int

Получает количество предупреждений последней операции Result.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество предупреждений, сгенерированных последней операцией.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Вывод приведённого примера будет похож на:

    2

## Содержание

- Result::__construct — Конструктор класса Result
- Result::getAffectedItemsCount — Получает количество затронутых строк
- Result::getAutoIncrementValue — Получает значение автоинкремента
- Result::getGeneratedIds — Получает сгенерированные идентификаторы
- Result::getWarnings — Получает предупреждения последней операции
- Result::getWarningsCount — Получает количество предупреждений последней операции

# Класс RowResult

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* Методы */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

(No version information available, might only be in Git)

RowResult::__construct — Конструктор класса RowResult

### Описание

private function mysql_xdevapi\RowResult::__construct()

Представляет набор результатов, полученный при обращении к базе данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

    print_r($row);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchAll

(No version information available, might only be in Git)

RowResult::fetchAll — Получает все строки из результата

### Описание

public function mysql_xdevapi\RowResult::fetchAll(): array

Извлекает все строки из набора результатов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Числовой массив со всеми результатами запроса; каждый результат представляет собой ассоциативный массив. Возвращается пустой массив, если строк нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchOne

(No version information available, might only be in Git)

RowResult::fetchOne — Получает строку из результата

### Описание

public function mysql_xdevapi\RowResult::fetchOne(): array

Извлекает один результат из набора результатов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Результат в виде ассоциативного массива или `null`, если нет результатов.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

    print_r($row);

Вывод приведённого примера будет похож на:

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — Получает количество столбцов

### Описание

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Получает количество столбцов, присутствующих в наборе результатов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество столбцов; 0 если их нет

### Список изменений

Версия | Описание
--- | ---
8.0.14 | Метод переименован из getColumnCount() в getColumnsCount().

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getColumnsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    echo $sql->getColumnsCount();

Вывод приведённого примера будет похож на:

    2

# RowResult::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — Получает все имена столбцов

### Описание

public function mysql_xdevapi\RowResult::getColumnNames(): array

Получает имена столбцов, присутствующих в наборе результатов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Числовой массив имён столбцов таблицы или пустой массив, если набор результатов пуст.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getColumnNames()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $colnames = $sql->getColumnNames();

    print_r($colnames);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — Получает метаданные столбца

### Описание

public function mysql_xdevapi\RowResult::getColumns(): array

Получает метаданные столбцов, присутствующих в наборе результатов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов FieldMetadata, представляющих столбцы в результате, или пустой массив, если набор результатов пуст.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getColumns()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $cols = $sql->getColumns();

    print_r($cols);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 7
                [type_name] => BYTES
                [name] => name
                [original_name] => name
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 255
                [fractional_digits] => 0
                [length] => 65535
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => age
                [original_name] => age
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
    )

# RowResult::getWarnings

(No version information available, might only be in Git)

RowResult::getWarnings — Получает предупреждения последней операции

### Описание

public function mysql_xdevapi\RowResult::getWarnings(): array

Получает предупреждения от последней операции RowResult.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов Warning последней операции. Каждый объект определяет 'message' об ошибке, 'level' ошибки и 'code' ошибки. Возвращается пустой массив, если ошибок нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarnings()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# RowResult::getWarningsCount

(No version information available, might only be in Git)

RowResult::getWarningsCount — Получает количество предупреждений последней операции

### Описание

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Получает количество предупреждений последней операции RowResult.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество предупреждений, сгенерированных последней операцией.

### Примеры

Пример #1 Пример использования mysql_xdevapi\RowResult::getWarningsCount()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Вывод приведённого примера будет похож на:

    2

## Содержание

- RowResult::__construct — Конструктор класса RowResult
- RowResult::fetchAll — Получает все строки из результата
- RowResult::fetchOne — Получает строку из результата
- RowResult::getColumnsCount — Получает количество столбцов
- RowResult::getColumnNames — Получает все имена столбцов
- RowResult::getColumns — Получает метаданные столбца
- RowResult::getWarnings — Получает предупреждения последней операции
- RowResult::getWarningsCount — Получает количество предупреждений последней операции

# Класс Schema

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* Свойства */
public $name;
/* Методы */
public function createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## Свойства

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Конструктор класса Schema

### Описание

private function mysql_xdevapi\Schema::__construct()

Объект класса Schema предоставляет полный доступ к схеме (базе данных).

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Вывод приведённого примера будет похож на:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

# Schema::createCollection

(No version information available, might only be in Git)

Schema::createCollection — Добавляет коллекцию в схему

### Описание

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Создаёт коллекцию внутри схемы.

### Список параметров

`name`

  Имя коллекции.

`validate`

  Определение проверки в виде объекта JSON.

### Возвращаемые значения

Возвращает объект класса Collection.

### Список изменений

Версия | Описание
--- | ---
8.0.20 | Добавлен необязательный параметр validate.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::createCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Вывод приведённого примера будет похож на:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

Пример #2 Пример использования метода mysql_xdevapi\Schema::createCollection()

    <?php
     $collection = $schema->createCollection("mycollection", '{
        "validation": {
            "level": "strict",
            "schema": {
                "id": "http://json-schema.org/geo",
                "description": "A geographical coordinate",
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number"
                    },
                    "longitude": {
                        "type": "number"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        }
    }');
    // Успешное выполнение
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();
    // Ошибка, недопустимые типы (не числа)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — Удаляет коллекции из схемы

### Описание

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`collection_name`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::dropCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");

    $schema->createCollection("trees");
    $schema->dropCollection("trees");
    $schema->createCollection("buildings");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Вывод приведённого примера будет похож на:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [buildings] => mysql_xdevapi\Collection Object
            (
                [name] => buildings
            )
    )

# Schema::existsInDatabase

(No version information available, might only be in Git)

Schema::existsInDatabase — Проверяет, существует ли в базе данных

### Описание

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Проверяет, существует ли текущий объект (схема, таблица, коллекция или представление) в объекте схемы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если схема, таблица, коллекция или представление всё ещё существуют в схеме, в противном случае возвращает `false`.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    // ...

    // Эта коллекция всё ещё находится в базе данных (схеме)?
    if ($trees->existsInDatabase()) {
        echo "Да, коллекция 'trees' всё ещё существует.";
    }

Вывод приведённого примера будет похож на:

    Да, коллекция 'trees' всё ещё существует.

# Schema::getCollection

(No version information available, might only be in Git)

Schema::getCollection — Получает коллекцию из схемы

### Описание

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Получает коллекцию из схемы.

### Список параметров

`name`

  Имя коллекции для извлечения.

### Возвращаемые значения

Возвращает объект класса Collection для выбранной коллекции.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getCollection()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    var_dump($trees);

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — Получает коллекцию как объект класса Table

### Описание

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Получает коллекцию, но как объект Table вместо объекта Collection.

### Список параметров

`name`

  Имя коллекции, из которой создаётся экземпляр объекта Table.

### Возвращаемые значения

Возвращает объект класса mysql_xdevapi\Table для коллекции.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getCollectionAsTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $table      = $schema->getCollectionAsTable("people");
    $collection = $schema->getCollection("people");

    var_dump($table);
    var_dump($collection);

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Table)#4 (1) {
      ["name"]=>
      string(6) "people"
    }

    object(mysql_xdevapi\Collection)#5 (1) {
      ["name"]=>
      string(6) "people"
    }

# Schema::getCollections

(No version information available, might only be in Git)

Schema::getCollections — Получает все коллекции схемы

### Описание

public function mysql_xdevapi\Schema::getCollections(): array

Получает список коллекций для этой схемы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив всех коллекций в этой схеме, где каждое значение элемента массива является объектом класса Collection с именем коллекции в качестве ключа.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getCollections()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $collections = $schema->getCollections();
    var_dump($collections);
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      ["people"]=>
      object(mysql_xdevapi\Collection)#4 (1) {
        ["name"]=>
        string(6) "people"
      }
    }

# Schema::getName

(No version information available, might only be in Git)

Schema::getName — Получает имя схемы

### Описание

public function mysql_xdevapi\Schema::getName(): string

Получает имя схемы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    var_dump($schema->getName());
    ?>

Вывод приведённого примера будет похож на:

    string(11) "addressbook"

# Schema::getSession

(No version information available, might only be in Git)

Schema::getSession — Получает сессию схемы

### Описание

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Получает новый объект класса Session из объекта класса Schema.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект класса Session.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    $newsession = $schema->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Session)#1 (0) {
    }

    object(mysql_xdevapi\Session)#3 (0) {
    }

# Schema::getTable

(No version information available, might only be in Git)

Schema::getTable — Получает таблицу схемы

### Описание

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Получает объекта класса Table для указанной таблицы в схеме.

### Список параметров

`name`

  Имя таблицы.

### Возвращаемые значения

Возвращает объект класса Table.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getTable()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Schema::getTables

(No version information available, might only be in Git)

Schema::getTables — Получает таблицы схемы

### Описание

public function mysql_xdevapi\Schema::getTables(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив всех таблиц в этой схеме, где каждое значение элемента массива является объектом класса Table с именем таблицы в качестве ключа.

### Примеры

Пример #1 Пример использования метода mysql_xdevapi\Schema::getTables()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

    $schema = $session->getSchema("addressbook");
    $tables = $schema->getTables();

    var_dump($tables);
    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## Содержание

- Schema::__construct — Конструктор класса Schema
- Schema::createCollection — Добавляет коллекцию в схему
- Schema::dropCollection — Удаляет коллекции из схемы
- Schema::existsInDatabase — Проверяет, существует ли в базе данных
- Schema::getCollection — Получает коллекцию из схемы
- Schema::getCollectionAsTable — Получает коллекцию как объект класса Table
- Schema::getCollections — Получает все коллекции схемы
- Schema::getName — Получает имя схемы
- Schema::getSession — Получает сессию схемы
- Schema::getTable — Получает таблицу схемы
- Schema::getTables — Получает таблицы схемы

# Интерфейс SchemaObject

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* Методы */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — Получает объект схемы

### Описание

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Используется другими объектами для получения объекта схемы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Текущий объект Schema.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Вывод приведённого примера будет похож на:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## Содержание

- SchemaObject::getSchema — Получает объект схемы

# Класс Session

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Session {
/* Методы */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

(No version information available, might only be in Git)

Session::close — Закрывает сессию

### Описание

public function mysql_xdevapi\Session::close(): bool

Закрывает сессию с сервером.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если сессия закрыта.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::close()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->close();

# Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — Фиксирует транзакцию

### Описание

public function mysql_xdevapi\Session::commit(): Object

Фиксирует транзакцию.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект SqlStatementResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::commit()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();

    $collection->add('{"John":42, "Sam":33}')->execute();
    $savepoint = $session->setSavepoint();

    $session->commit();
    $session->close();

# Session::__construct

(No version information available, might only be in Git)

Session::__construct — Описание конструктора

### Описание

private function mysql_xdevapi\Session::__construct()

Объект Session, инициированный getSession().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — Создаёт новую схему

### Описание

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Создаёт новую схему.

### Список параметров

`schema_name`

  Имя схемы для создания.

### Возвращаемые значения

Объект Schema в случае успешного выполнения, в случае возникновения ошибки выдаёт исключение.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::createSchema()

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Инфо: Я создал схему с именем 'fruit'\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

Вывод приведённого примера будет похож на:

    Инфо: Я создал схему с именем 'fruit'

# Session::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — Удаляет схему

### Описание

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Удаляет схему (базу данных).

### Список параметров

`schema_name`

  Имя схемы для удаления.

### Возвращаемые значения

`true`, если схема удалена, или `false` если она не существует или не может быть удалена.

Генерируется ошибка уровня `E_WARNING`, если схема не существует.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::dropSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->dropSchema("addressbook");

    $session->close();
    ?>

# Session::generateUUID

(No version information available, might only be in Git)

Session::generateUUID — Получает новый UUID

### Описание

public function mysql_xdevapi\Session::generateUUID(): string

Генерирует универсальный уникальный идентификатор (UUID), сгенерированный в соответствии с » RFC 4122.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

UUID; строка длиной 32 символа.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::generateUuid()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

Вывод приведённого примера будет похож на:

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — Получает имя схемы по умолчанию

### Описание

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Получает схему по умолчанию, которая обычно задаётся в URI подключения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает схему по умолчанию, определённую подключением или `null`, если она не была установлена.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::getSchema()

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

Результат выполнения приведённого примера:

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — Получает новый объект схемы

### Описание

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

Новый объект Schema для указанного имени схемы.

### Список параметров

`schema_name`

  Имя схемы (базы данных), для которой нужно получить объект Schema.

### Возвращаемые значения

Объект Schema.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Вывод приведённого примера будет похож на:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — Получает схемы

### Описание

public function mysql_xdevapi\Session::getSchemas(): array

Получить объекты схемы для всех схем, доступных в сессии.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив, содержащий объекты, которые представляют все схемы, доступные в сессии.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::getSchemas()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => addressbook
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        ...

# Session::getServerVersion

(No version information available, might only be in Git)

Session::getServerVersion — Получает версию сервера

### Описание

public function mysql_xdevapi\Session::getServerVersion(): int

Получает версию сервера MySQL для сессии.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Версия сервера MySQL для сессии в виде целого числа, такого как "80012".

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::getServerVersion()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

Вывод приведённого примера будет похож на:

    int(80012)

# Session::listClients

(No version information available, might only be in Git)

Session::listClients — Получает список клиентов

### Описание

public function mysql_xdevapi\Session::listClients(): array

Получить список клиентских подключений к сессии MySQL сервера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив, содержащий текущих зарегистрированных клиентов. Элементы массива: "client_id", "user", "host", и "sql_session".

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::listClients()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

Вывод приведённого примера будет похож на:

    array(1) {
      [0]=>
      array(4) {
        ["client_id"]=>
        int(61)
        ["user"]=>
        string(4) "root"
        ["host"]=>
        string(9) "localhost"
        ["sql_session"]=>
        int(72)
      }
    }

# Session::quoteName

(No version information available, might only be in Git)

Session::quoteName — Добавляет кавычки

### Описание

public function mysql_xdevapi\Session::quoteName(string `$name`): string

Функция для экранирования имён и идентификаторов SQL. Экранирует идентификатор, указанный в соответствии с настройками текущего соединения. Эту функцию не следует использовать для экранирования значений.

### Список параметров

`name`

  Строка для экранирования.

### Возвращаемые значения

Экранированная строка.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::quoteName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $first = "MySQL's test";
    var_dump($first);
    var_dump($session->quoteName($first));

    $second = 'Another `test` "like" `this`';
    var_dump($second);
    var_dump($session->quoteName($second));
    ?>

Вывод приведённого примера будет похож на:

    string(12) "MySQL's test"
    string(14) "`MySQL's test`"

    string(28) "Another `test` "like" `this`"
    string(34) "`Another ``test`` "like" ``this```"

# Session::releaseSavepoint

(No version information available, might only be in Git)

Session::releaseSavepoint — Отменяет установленную точку сохранения

### Описание

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Отменяет ранее установленную точку сохранения.

### Список параметров

`name`

  Имя точки сохранения для отмены.

### Возвращаемые значения

Объект SqlStatementResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::releaseSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollback

(No version information available, might only be in Git)

Session::rollback — Откатывает транзакцию

### Описание

public function mysql_xdevapi\Session::rollback(): void

Откатывает транзакцию.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект SqlStatementResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::rollback()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollbackTo

(No version information available, might only be in Git)

Session::rollbackTo — Откатывает транзакцию до точки сохранения

### Описание

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Откатывает транзакцию до точки сохранения.

### Список параметров

`name`

  Имя точки сохранения для отката; без учёта регистра.

### Возвращаемые значения

Объект SqlStatementResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::rollbackTo()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint1 = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $savepoint2 = $session->setSavepoint();

    $session->rollbackTo($savepoint1);
    ?>

# Session::setSavepoint

(No version information available, might only be in Git)

Session::setSavepoint — Создаёт точку сохранения

### Описание

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Создаёт новую точку сохранения для транзакции.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`name`

  Название точки сохранения. Имя генерируется автоматически, если необязательный параметр `name` не определён, как 'SAVEPOINT1', 'SAVEPOINT2' и т.д.

### Возвращаемые значения

Название точки сохранения.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::setSavepoint()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::sql

(No version information available, might only be in Git)

Session::sql — Создаёт SQL-запрос

### Описание

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Создаёт собственный оператор SQL. Заполнители поддерживаются с помощью нативного синтаксиса "?". Использует метод `execute` для выполнения утверждения SQL.

### Список параметров

`query`

  Утверждение SQL для выполнения.

### Возвращаемые значения

Объект SqlStatement.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::sql()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE addressbook")->execute();
    ?>

# Session::startTransaction

(No version information available, might only be in Git)

Session::startTransaction — Начинает транзакцию

### Описание

public function mysql_xdevapi\Session::startTransaction(): void

Начинает новую транзакцию.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект SqlStatementResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Session::startTransaction()

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

## Содержание

- Session::close — Закрывает сессию
- Session::commit — Фиксирует транзакцию
- Session::__construct — Описание конструктора
- Session::createSchema — Создаёт новую схему
- Session::dropSchema — Удаляет схему
- Session::generateUUID — Получает новый UUID
- Session::getDefaultSchema — Получает имя схемы по умолчанию
- Session::getSchema — Получает новый объект схемы
- Session::getSchemas — Получает схемы
- Session::getServerVersion — Получает версию сервера
- Session::listClients — Получает список клиентов
- Session::quoteName — Добавляет кавычки
- Session::releaseSavepoint — Отменяет установленную точку сохранения
- Session::rollback — Откатывает транзакцию
- Session::rollbackTo — Откатывает транзакцию до точки сохранения
- Session::setSavepoint — Создаёт точку сохранения
- Session::sql — Создаёт SQL-запрос
- Session::startTransaction — Начинает транзакцию

# Класс SqlStatement

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\SqlStatement {
/* Константы */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Свойства */
public $statement;
/* Методы */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Свойства

statement

## Предопределённые константы

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — Связывает параметры утверждения

### Описание

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`param`

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::bind()

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — Описание конструктора

### Описание

private function mysql_xdevapi\SqlStatement::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::__construct()

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — Выполняет операцию

### Описание

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::execute()

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — Получает следующий результат

### Описание

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::getNextResult()

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — Получает результат

### Описание

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::getResult()

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — Проверяет, есть ли ещё результаты

### Описание

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если в наборе результатов есть больше объектов для выборки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Содержание

- SqlStatement::bind — Связывает параметры утверждения
- SqlStatement::__construct — Описание конструктора
- SqlStatement::execute — Выполняет операцию
- SqlStatement::getNextResult — Получает следующий результат
- SqlStatement::getResult — Получает результат
- SqlStatement::hasMoreResults — Проверяет, есть ли ещё результаты

# Класс SqlStatementResult

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* Методы */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

(No version information available, might only be in Git)

SqlStatementResult::__construct — Описание конструктора

### Описание

private function mysql_xdevapi\SqlStatementResult::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::__construct()

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — Получает все строки из результата

### Описание

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Извлекает все строки из набора результатов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Числовой массив со всеми результатами запроса; каждый результат представляет собой ассоциативный массив. Возвращается пустой массив, если строк нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::fetchAll()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

    print_r($rows);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# SqlStatementResult::fetchOne

(No version information available, might only be in Git)

SqlStatementResult::fetchOne — Получает одну строку

### Описание

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Получает одну строку из набора результатов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Результат, как ассоциативный массив. В случае отсутствия результата возвращается ноль.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::fetchOne()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

    print_r($rows);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — Получает затронутое количество строк

### Описание

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getAffectedItemsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — Получает количество столбцов

### Описание

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество столбцов; 0 если их нет

### Список изменений

Версия | Описание
--- | ---
8.0.14 | Метод переименован из getColumnCount() в getColumnsCount().

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getColumnsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — Получает имена столбцов

### Описание

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getColumnNames()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — Получает столбцы

### Описание

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getColumns()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — Получает сгенерированные идентификаторы

### Описание

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив сгенерированных _id из последней операции или пустой массив, если таковых нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getGeneratedIds()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — Получает последний идентификатор вставки

### Описание

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Идентификатор последней операции вставки.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getLastInsertId()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — Получает предупреждения от последней операции

### Описание

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив объектов Warning из последней операции. Каждый объект определяет 'message' об ошибке, 'level' ошибки и 'code' ошибки. Пустой массив возвращается, если ошибок нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getWarnings()

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — Получает количество предупреждений от последней операции

### Описание

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Количество предупреждений, выданных во время последней операции CRUD.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::getWarningsCount()

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — Проверяет, есть ли у результата данные

### Описание

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если в наборе результатов есть данные.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::hasData()

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — Получает следующий результат

### Описание

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Следующий объект Result из набора результатов.

### Примеры

Пример #1 Пример использования mysql_xdevapi\SqlStatementResult::nextResult()

    <?php

    /* ... */

    ?>

## Содержание

- SqlStatementResult::__construct — Описание конструктора
- SqlStatementResult::fetchAll — Получает все строки из результата
- SqlStatementResult::fetchOne — Получает одну строку
- SqlStatementResult::getAffectedItemsCount — Получает затронутое количество строк
- SqlStatementResult::getColumnsCount — Получает количество столбцов
- SqlStatementResult::getColumnNames — Получает имена столбцов
- SqlStatementResult::getColumns — Получает столбцы
- SqlStatementResult::getGeneratedIds — Получает сгенерированные идентификаторы
- SqlStatementResult::getLastInsertId — Получает последний идентификатор вставки
- SqlStatementResult::getWarnings — Получает предупреждения от последней операции
- SqlStatementResult::getWarningsCount — Получает количество предупреждений от последней операции
- SqlStatementResult::hasData — Проверяет, есть ли у результата данные
- SqlStatementResult::nextResult — Получает следующий результат

# Класс Statement

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Statement {
/* Константы */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Методы */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Предопределённые константы

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Описание конструктора

### Описание

private function mysql_xdevapi\Statement::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования конструктора mysql_xdevapi\Statement::__construct()

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — Получает следующий результат

### Описание

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\Statement::getNextResult()

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — Получает результат

### Описание

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\Statement::getResult()

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — Проверяет, есть ли ещё результаты

### Описание

public function mysql_xdevapi\Statement::hasMoreResults(): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования mysql_xdevapi\Statement::hasMoreResults()

    <?php

    /* ... */

    ?>

## Содержание

- Statement::__construct — Описание конструктора
- Statement::getNextResult — Получает следующий результат
- Statement::getResult — Получает результат
- Statement::hasMoreResults — Проверяет, есть ли ещё результаты

# Класс Table

(PECL mysql-xdevapi >= 8.0.11)

## Введение

Предоставляет доступ к таблице через операторы INSERT/SELECT/UPDATE/DELETE.

## Обзор класса

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* Свойства */
public $name;
/* Методы */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## Свойства

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Конструктор Table

### Описание

private function mysql_xdevapi\Table::__construct()

Создать объекты таблицы.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");
    ?>

# Table::count

(No version information available, might only be in Git)

Table::count — Получить количество строк

### Описание

public function mysql_xdevapi\Table::count(): int

Получить количество строк в таблице.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Общее количество строк в таблице.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->count());
    ?>

Результат выполнения приведённого примера:

    int(2)

# Table::delete

(No version information available, might only be in Git)

Table::delete — Удалить строки из таблицы

### Описание

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Удаляет строки из таблицы.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект TableDelete; используйте метод execute() для выполнения запроса delete

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::delete()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
    ?>

# Table::existsInDatabase

(No version information available, might only be in Git)

Table::existsInDatabase — Проверить, существует ли таблица в базе данных

### Описание

public function mysql_xdevapi\Table::existsInDatabase(): bool

Проверяет, существует ли данная таблица в базе данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если таблица существует в базе данных, иначе `false`, если таблицы нет.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::existsInDatabase()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->existsInDatabase()) {
      echo "Да, эта таблица всё ещё существует в схеме сессии.";
    }
    ?>

Вывод приведённого примера будет похож на:

    Да, эта таблица всё ещё существует в схеме сессии.

# Table::getName

(No version information available, might only be in Git)

Table::getName — Получить имя таблицы

### Описание

public function mysql_xdevapi\Table::getName(): string

Возвращает имя объекта базы данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Имя объекта базы данных.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::getName()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getName());
    ?>

Вывод приведённого примера будет похож на:

    string(5) "names"

# Table::getSchema

(No version information available, might only be in Git)

Table::getSchema — Получить схему таблицы

### Описание

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Извлечь схему, связанную с таблицей.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Schema.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::getSchema()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSchema());
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

(No version information available, might only be in Git)

Table::getSession — Получить таблицу сессий

### Описание

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Получить сессию, связанную с таблицей.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Session.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::getSession()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSession());
    ?>

Вывод приведённого примера будет похож на:

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

(No version information available, might only be in Git)

Table::insert — Вставить строки таблицы

### Описание

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Вставляет строки в таблицу.

### Список параметров

`columns`

  Столбцы для вставки данных. Может быть массивом с одним или несколькими значениями, либо строкой.

`more_columns`

  Определения дополнительных столбцов.

### Возвращаемые значения

Объект TableInsert; используйте метод execute() для выполнения выражения insert.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::insert()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# Table::isView

(No version information available, might only be in Git)

Table::isView — Проверить, является ли таблица представлением

### Описание

public function mysql_xdevapi\Table::isView(): bool

Определите, является ли базовый объект представлением или нет.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

`true`, если базовый объект является представлением, в противном случае `false`.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::isView()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->isView()) {
        echo "Это представление.";
    } else {
        echo "Это не представление.";
    }
    ?>

Результат выполнения приведённого примера:

    Это не представление.

# Table::select

(No version information available, might only be in Git)

Table::select — Выбрать строки из таблицы

### Описание

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Извлекает данные из таблицы.

### Список параметров

`columns`

  Столбцы для выбора данных. Может быть массивом с одним или несколькими значениями или строкой.

`more_columns`

  Дополнительные определения параметров столбцов.

### Возвращаемые значения

Объект TableSelect; используйте метод execute() для выполнения select и возврата объекта RowResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::count()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Table::update

(No version information available, might only be in Git)

Table::update — Обновить строки в таблице

### Описание

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Обновляет столбцы в таблице.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект TableUpdate; используйте метод execute() для выполнения выражения update.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Table::update()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
    ?>

## Содержание

- Table::__construct — Конструктор Table
- Table::count — Получить количество строк
- Table::delete — Удалить строки из таблицы
- Table::existsInDatabase — Проверить, существует ли таблица в базе данных
- Table::getName — Получить имя таблицы
- Table::getSchema — Получить схему таблицы
- Table::getSession — Получить таблицу сессий
- Table::insert — Вставить строки таблицы
- Table::isView — Проверить, является ли таблица представлением
- Table::select — Выбрать строки из таблицы
- Table::update — Обновить строки в таблице

# Класс TableDelete

(PECL mysql-xdevapi >= 8.0.11)

## Введение

Оператор для операций удаления в таблице.

## Обзор класса

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* Методы */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

(No version information available, might only be in Git)

TableDelete::bind — Связывает параметры запроса удаления

### Описание

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Привязывает значение к определённому заполнителю.

### Список параметров

`placeholder_values`

  Имя заполнителя и значение для привязки.

### Возвращаемые значения

Объект TableDelete.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::__construct

(No version information available, might only be in Git)

TableDelete::__construct — Конструктор класса TableDelete

### Описание

private function mysql_xdevapi\TableDelete::__construct()

Инициируется с помощью метода delete().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::execute

(No version information available, might only be in Git)

TableDelete::execute — Выполняет запрос на удаление

### Описание

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Выполняет запрос на удаление.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Result.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::limit

(No version information available, might only be in Git)

TableDelete::limit — Ограничивает строки для удаления

### Описание

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Устанавливает максимальное количество записей или документов для удаления.

### Список параметров

`rows`

  Максимальное количество записей или документов для удаления.

### Возвращаемые значения

Объект TableDelete.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::orderby

(No version information available, might only be in Git)

TableDelete::orderby — Устанавливает критерии сортировки удаления

### Описание

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

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

### Список параметров

`orderby_expr`

  Определение сортировки.

### Возвращаемые значения

Объект TableDelete.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("age = :age")
      ->bind(['age' => 42])
      ->orderby("name DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::where

(No version information available, might only be in Git)

TableDelete::where — Устанавливает условие поиска для удаления

### Описание

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Устанавливает условие поиска для фильтрации.

### Список параметров

`where_expr`

  Определяет условие поиска для фильтрации документов или записей.

### Возвращаемые значения

Объект TableDelete.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableDelete::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("id = :id")
      ->bind(['id' => 42])
      ->limit(1)
      ->execute();

    ?>

## Содержание

- TableDelete::bind — Связывает параметры запроса удаления
- TableDelete::__construct — Конструктор класса TableDelete
- TableDelete::execute — Выполняет запрос на удаление
- TableDelete::limit — Ограничивает строки для удаления
- TableDelete::orderby — Устанавливает критерии сортировки удаления
- TableDelete::where — Устанавливает условие поиска для удаления

# Класс TableInsert

(PECL mysql-xdevapi >= 8.0.11)

## Введение

Оператор для операций вставки в таблице.

## Обзор класса

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* Методы */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

(No version information available, might only be in Git)

TableInsert::__construct — Конструктор класса TableInsert

### Описание

private function mysql_xdevapi\TableInsert::__construct()

Инициируется с помощью метода insert().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableInsert::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::execute

(No version information available, might only be in Git)

TableInsert::execute — Выполняет запрос вставки

### Описание

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Выполняет утверждение.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Result.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableInsert::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::values

(No version information available, might only be in Git)

TableInsert::values — Добавляет значения вставки строки

### Описание

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Устанавливает значения для вставки.

### Список параметров

`row_values`

  Значения (массив) столбцов для вставки.

### Возвращаемые значения

Объект TableInsert.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableInsert::values()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

## Содержание

- TableInsert::__construct — Конструктор класса TableInsert
- TableInsert::execute — Выполняет запрос вставки
- TableInsert::values — Добавляет значения вставки строки

# Класс TableSelect

(PECL mysql-xdevapi >= 8.0.11)

## Введение

Оператор для операций поиска записи в таблице.

## Обзор класса

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* Методы */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

(No version information available, might only be in Git)

TableSelect::bind — Привязывает параметры запроса выборки

### Описание

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Привязывает значение к определённому заполнителю.

### Список параметров

`placeholder_values`

  Название заполнителя и значение для привязки.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

(No version information available, might only be in Git)

TableSelect::__construct — Конструктор класса TableSelect

### Описание

private function mysql_xdevapi\TableSelect::__construct()

Объект, возвращаемый методом select(); Используйте execute() для выполнения запроса.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — Выполняет оператор выборки

### Описание

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Выполняет утверждение выборки, связывая его с методом execute().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект RowResult.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — Устанавливает критерии группировки выборки

### Описание

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Устанавливает критерии группировки для набора результатов.

### Список параметров

`sort_expr`

  Критерии группировки.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::groupBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [count] => 1
                [age] => 31
            )
        [1] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::having

(No version information available, might only be in Git)

TableSelect::having — Устанавливает выбор с условием

### Описание

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Устанавливает условие для записей для рассмотрения в операциях агрегатной функции.

### Список параметров

`sort_expr`

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

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::having()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->having('count > 1')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

(No version information available, might only be in Git)

TableSelect::limit — Ограничивает выбранные строки

### Описание

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

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

### Список параметров

`rows`

  Максимальное количество записей или документов.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — Выполняет EXCLUSIVE LOCK

### Описание

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Выполняет операцию чтения с EXCLUSIVE LOCK. Только один замок может быть активным одновременно.

### Список параметров

`lock_waiting_option`

  Необязательный параметр ожидания, который по умолчанию равен `MYSQLX_LOCK_DEFAULT`. Допустимые значения:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::lockExclusive()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockExclusive(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::lockShared

(No version information available, might only be in Git)

TableSelect::lockShared — Выполняет SHARED LOCK

### Описание

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Выполняет операцию чтения с SHARED LOCK. Только один замок может быть активным одновременно.

### Список параметров

`lock_waiting_option`

  Необязательный параметр ожидания, который по умолчанию равен `MYSQLX_LOCK_DEFAULT`. Допустимые значения:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::lockShared()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockShared(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::offset

(No version information available, might only be in Git)

TableSelect::offset — Устанавливает предел смещения

### Описание

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Пропускает указанное количество строк в результате.

### Список параметров

`position`

  Предел смещения.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::offset()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->offset(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — Устанавливает критерии сортировки выборки

### Описание

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Устанавливает порядок по критериям.

### Список параметров

`sort_expr`

  Выражения, которые определяют порядок по критериям. Может быть массивом с одним или несколькими выражениями или строкой.

`sort_exprs`

  Дополнительные параметры sort_expr.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::orderBy()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->orderBy('name desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
        [1] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::where

(No version information available, might only be in Git)

TableSelect::where — Устанавливает условие поиска выборки

### Описание

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Устанавливает условие поиска для фильтрации.

### Список параметров

`where_expr`

  Определяет условие поиска для фильтрации документов или записей.

### Возвращаемые значения

Объект TableSelect.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableSelect::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## Содержание

- TableSelect::bind — Привязывает параметры запроса выборки
- TableSelect::__construct — Конструктор класса TableSelect
- TableSelect::execute — Выполняет оператор выборки
- TableSelect::groupBy — Устанавливает критерии группировки выборки
- TableSelect::having — Устанавливает выбор с условием
- TableSelect::limit — Ограничивает выбранные строки
- TableSelect::lockExclusive — Выполняет EXCLUSIVE LOCK
- TableSelect::lockShared — Выполняет SHARED LOCK
- TableSelect::offset — Устанавливает предел смещения
- TableSelect::orderby — Устанавливает критерии сортировки выборки
- TableSelect::where — Устанавливает условие поиска выборки

# Класс TableUpdate

(PECL mysql-xdevapi >= 8.0.11)

## Введение

Оператор для операций обновления записи в таблице.

## Обзор класса

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* Методы */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

(No version information available, might only be in Git)

TableUpdate::bind — Привязывает параметры запроса на обновление

### Описание

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Привязывает значение к определённому заполнителю.

### Список параметров

`placeholder_values`

  Имя заполнителя и значение для привязки, определённое, как массив JSON.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::bind()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()
      ->set('status', 'admin')
      ->where('name = :name and age > :age')
      ->bind(['name' => 'Bernie', 'age' => 2000])
      ->execute();

    ?>

# TableUpdate::__construct

(No version information available, might only be in Git)

TableUpdate::__construct — Конструктор класса TableUpdate

### Описание

private function mysql_xdevapi\TableUpdate::__construct()

Инициируется с помощью метода update().

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::__construct()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::execute

(No version information available, might only be in Git)

TableUpdate::execute — Выполняет запрос на обновление

### Описание

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Выполняет утверждение обновления.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::execute()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::limit

(No version information available, might only be in Git)

TableUpdate::limit — Ограничивает количество строк для обновления

### Описание

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Устанавливает максимальное количество записей или документов обновления.

### Список параметров

`rows`

  Максимальное количество записей или документов для обновления.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::limit()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::orderby

(No version information available, might only be in Git)

TableUpdate::orderby — Устанавливает критерии сортировки

### Описание

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Устанавливает критерии сортировки.

### Список параметров

`orderby_expr`

  Выражения, которые определяют порядок по критериям. Может быть массивом с одним или несколькими выражениями или строкой.

`orderby_exprs`

  Дополнительные параметры sort_expr.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::orderby()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();
    ?>

# TableUpdate::set

(No version information available, might only be in Git)

TableUpdate::set — Добавляет поле для обновления

### Описание

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Обновляет значение столбца для записей в таблице.

### Список параметров

`table_field`

  Имя столбца, подлежащего обновлению.

`expression_or_literal`

  Значение, которое будет установлено в указанном столбце.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::set()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::where

(No version information available, might only be in Git)

TableUpdate::where — Устанавливает фильтр поиска

### Описание

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Устанавливает условие поиска для фильтрации.

### Список параметров

`where_expr`

  Условие поиска для фильтрации документов или записей.

### Возвращаемые значения

Объект TableUpdate.

### Примеры

Пример #1 Пример использования mysql_xdevapi\TableUpdate::where()

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

## Содержание

- TableUpdate::bind — Привязывает параметры запроса на обновление
- TableUpdate::__construct — Конструктор класса TableUpdate
- TableUpdate::execute — Выполняет запрос на обновление
- TableUpdate::limit — Ограничивает количество строк для обновления
- TableUpdate::orderby — Устанавливает критерии сортировки
- TableUpdate::set — Добавляет поле для обновления
- TableUpdate::where — Устанавливает фильтр поиска

# Класс Warning

(PECL mysql-xdevapi >= 8.0.11)

## Введение

## Обзор класса

class mysql_xdevapi\Warning {
/* Свойства */
public $message;
public $level;
public $code;
/* Конструктор */
private function __construct()
}

## Свойства

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Конструктор класса Warning

### Описание

private function mysql_xdevapi\Warning::__construct()

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Примеры

Пример #1 Пример использования mysql_xdevapi\Warning::__construct()

    <?php

    /* ... */

    ?>

## Содержание

- Warning::__construct — Конструктор класса Warning

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Сборка / Компиляция из исходного кода
- Предопределённые константы
- Список изменений
- Примеры
- Функции Mysql_xdevapi
  - expression — Связывает подготовленные переменные утверждения в качестве параметров
  - getSession — Подключается к серверу MySQL
- mysql_xdevapi\BaseResult — Интерфейс BaseResult
  - BaseResult::getWarnings — Получает предупреждения последней операции
  - BaseResult::getWarningsCount — Получает количество предупреждений последней операции
- mysql_xdevapi\Client — Класс Client
  - mysql_xdevapi\Client::close — Закрытие клиента
  - Client::__construct — Конструктор класса Client
  - Client::getClient — Получает сеанс клиента
- mysql_xdevapi\Collection — Класс Collection
  - Collection::add — Добавляет документ в коллекцию
  - Collection::addOrReplaceOne — Добавляет или заменяет документ коллекции
  - Collection::__construct — Конструктор класса Collection
  - Collection::count — Получает количество документов
  - Collection::createIndex — Создаёт индекс для коллекции
  - Collection::dropIndex — Удаляет индекс коллекции
  - Collection::existsInDatabase — Проверяет, существует ли коллекция в базе данных
  - Collection::find — Ищет документ
  - Collection::getName — Получает название коллекции
  - Collection::getOne — Получает один документ
  - Collection::getSchema — Возвращает объект Schema
  - Collection::getSession — Возвращает объект Session
  - Collection::modify — Изменяет документы коллекции
  - Collection::remove — Удаляет документы коллекции
  - Collection::removeOne — Удаляет один документ из коллекции
  - Collection::replaceOne — Заменяет один документ коллекции
- mysql_xdevapi\CollectionAdd — Класс CollectionAdd
  - CollectionAdd::__construct — Конструктор класса CollectionAdd
  - CollectionAdd::execute — Выполняет утверждение
- mysql_xdevapi\CollectionFind — Класс CollectionFind
  - CollectionFind::bind — Привязывает значение к заполнителю запроса
  - CollectionFind::__construct — Конструктор класса CollectionFind
  - CollectionFind::execute — Выполняет утверждение
  - CollectionFind::fields — Устанавливает фильтр поля документа
  - CollectionFind::groupBy — Устанавливает критерии группировки
  - CollectionFind::having — Устанавливает условие для агрегатных функций
  - CollectionFind::limit — Ограничивает количество возвращаемых документов
  - CollectionFind::lockExclusive — Выполняет операцию с EXCLUSIVE LOCK
  - CollectionFind::lockShared — Выполняет операцию с SHARED LOCK
  - CollectionFind::offset — Пропускает указанное количество возвращаемых элементов
  - CollectionFind::sort — Устанавливает критерии сортировки
- mysql_xdevapi\CollectionModify — Класс CollectionModify
  - CollectionModify::arrayAppend — Добавляет элемент в поле массива
  - CollectionModify::arrayInsert — Добавляет элемент в поле массива
  - CollectionModify::bind — Привязывает значение к заполнителю запроса
  - CollectionModify::__construct — Конструктор класса CollectionModify
  - CollectionModify::execute — Выполняет операцию изменения
  - CollectionModify::limit — Ограничивает количество изменяемых документов
  - CollectionModify::patch — Исправляет документ
  - CollectionModify::replace — Заменяет поле документа
  - CollectionModify::set — Устанавливает атрибут документа
  - CollectionModify::skip — Пропускает элементы
  - CollectionModify::sort — Устанавливает критерии сортировки
  - CollectionModify::unset — Сбрасывает значение полей документа
- mysql_xdevapi\CollectionRemove — Класс CollectionRemove
  - CollectionRemove::bind — Привязывает значение к заполнителю
  - CollectionRemove::__construct — Конструктор класса CollectionRemove
  - CollectionRemove::execute — Выполняет операцию удаления
  - CollectionRemove::limit — Ограничивает количество документов для удаления
  - CollectionRemove::sort — Устанавливает критерии сортировки
- mysql_xdevapi\ColumnResult — Класс ColumnResult
  - ColumnResult::__construct — Конструктор класса ColumnResult
  - ColumnResult::getCharacterSetName — Получает набор символов
  - ColumnResult::getCollationName — Получает имя сопоставления
  - ColumnResult::getColumnLabel — Получает метку столбца
  - ColumnResult::getColumnName — Получает название столбца
  - ColumnResult::getFractionalDigits — Получает дробную длину цифры
  - ColumnResult::getLength — Получает длину поля столбца
  - ColumnResult::getSchemaName — Получает название схемы
  - ColumnResult::getTableLabel — Получает метку таблицы
  - ColumnResult::getTableName — Получает название таблицы
  - ColumnResult::getType — Получает тип столбца
  - ColumnResult::isNumberSigned — Проверяет, задан ли числу знак
  - ColumnResult::isPadded — Проверяет, дополняется ли
- mysql_xdevapi\CrudOperationBindable — Интерфейс CrudOperationBindable
  - CrudOperationBindable::bind — Привязывает значение к заполнителю
- mysql_xdevapi\CrudOperationLimitable — Интерфейс CrudOperationLimitable
  - CrudOperationLimitable::limit — Устанавливает лимит результата
- mysql_xdevapi\CrudOperationSkippable — Интерфейс CrudOperationSkippable
  - CrudOperationSkippable::skip — Количество операций для пропуска
- mysql_xdevapi\CrudOperationSortable — Интерфейс CrudOperationSortable
  - CrudOperationSortable::sort — Сортирует результаты
- mysql_xdevapi\DatabaseObject — Интерфейс DatabaseObject
  - DatabaseObject::existsInDatabase — Проверяет, существует ли объект в базе данных
  - DatabaseObject::getName — Получает имя объекта
  - DatabaseObject::getSession — Получает имя сессии
- mysql_xdevapi\DocResult — Класс DocResult
  - DocResult::__construct — Конструктор DocResult
  - DocResult::fetchAll — Получить все строки
  - DocResult::fetchOne — Получить одну строку
  - DocResult::getWarnings — Получить предупреждения с последней операции
  - DocResult::getWarningsCount — Получить количество предупреждений с последней операции
- mysql_xdevapi\Exception — Класс Exception
- mysql_xdevapi\Executable — Интерфейс Executable
  - Executable::execute — Выполняет утверждение
- mysql_xdevapi\ExecutionStatus — Класс ExecutionStatus
  - ExecutionStatus::__construct — Конструктор класса ExecutionStatus
- mysql_xdevapi\Expression — Класс Expression
  - Expression::__construct — Конструктор класса Expression
- mysql_xdevapi\Result — Класс Result
  - Result::__construct — Конструктор класса Result
  - Result::getAffectedItemsCount — Получает количество затронутых строк
  - Result::getAutoIncrementValue — Получает значение автоинкремента
  - Result::getGeneratedIds — Получает сгенерированные идентификаторы
  - Result::getWarnings — Получает предупреждения последней операции
  - Result::getWarningsCount — Получает количество предупреждений последней операции
- mysql_xdevapi\RowResult — Класс RowResult
  - RowResult::__construct — Конструктор класса RowResult
  - RowResult::fetchAll — Получает все строки из результата
  - RowResult::fetchOne — Получает строку из результата
  - RowResult::getColumnsCount — Получает количество столбцов
  - RowResult::getColumnNames — Получает все имена столбцов
  - RowResult::getColumns — Получает метаданные столбца
  - RowResult::getWarnings — Получает предупреждения последней операции
  - RowResult::getWarningsCount — Получает количество предупреждений последней операции
- mysql_xdevapi\Schema — Класс Schema
  - Schema::__construct — Конструктор класса Schema
  - Schema::createCollection — Добавляет коллекцию в схему
  - Schema::dropCollection — Удаляет коллекции из схемы
  - Schema::existsInDatabase — Проверяет, существует ли в базе данных
  - Schema::getCollection — Получает коллекцию из схемы
  - Schema::getCollectionAsTable — Получает коллекцию как объект класса Table
  - Schema::getCollections — Получает все коллекции схемы
  - Schema::getName — Получает имя схемы
  - Schema::getSession — Получает сессию схемы
  - Schema::getTable — Получает таблицу схемы
  - Schema::getTables — Получает таблицы схемы
- mysql_xdevapi\SchemaObject — Интерфейс SchemaObject
  - SchemaObject::getSchema — Получает объект схемы
- mysql_xdevapi\Session — Класс Session
  - Session::close — Закрывает сессию
  - Session::commit — Фиксирует транзакцию
  - Session::__construct — Описание конструктора
  - Session::createSchema — Создаёт новую схему
  - Session::dropSchema — Удаляет схему
  - Session::generateUUID — Получает новый UUID
  - Session::getDefaultSchema — Получает имя схемы по умолчанию
  - Session::getSchema — Получает новый объект схемы
  - Session::getSchemas — Получает схемы
  - Session::getServerVersion — Получает версию сервера
  - Session::listClients — Получает список клиентов
  - Session::quoteName — Добавляет кавычки
  - Session::releaseSavepoint — Отменяет установленную точку сохранения
  - Session::rollback — Откатывает транзакцию
  - Session::rollbackTo — Откатывает транзакцию до точки сохранения
  - Session::setSavepoint — Создаёт точку сохранения
  - Session::sql — Создаёт SQL-запрос
  - Session::startTransaction — Начинает транзакцию
- mysql_xdevapi\SqlStatement — Класс SqlStatement
  - SqlStatement::bind — Связывает параметры утверждения
  - SqlStatement::__construct — Описание конструктора
  - SqlStatement::execute — Выполняет операцию
  - SqlStatement::getNextResult — Получает следующий результат
  - SqlStatement::getResult — Получает результат
  - SqlStatement::hasMoreResults — Проверяет, есть ли ещё результаты
- mysql_xdevapi\SqlStatementResult — Класс SqlStatementResult
  - SqlStatementResult::__construct — Описание конструктора
  - SqlStatementResult::fetchAll — Получает все строки из результата
  - SqlStatementResult::fetchOne — Получает одну строку
  - SqlStatementResult::getAffectedItemsCount — Получает затронутое количество строк
  - SqlStatementResult::getColumnsCount — Получает количество столбцов
  - SqlStatementResult::getColumnNames — Получает имена столбцов
  - SqlStatementResult::getColumns — Получает столбцы
  - SqlStatementResult::getGeneratedIds — Получает сгенерированные идентификаторы
  - SqlStatementResult::getLastInsertId — Получает последний идентификатор вставки
  - SqlStatementResult::getWarnings — Получает предупреждения от последней операции
  - SqlStatementResult::getWarningsCount — Получает количество предупреждений от последней операции
  - SqlStatementResult::hasData — Проверяет, есть ли у результата данные
  - SqlStatementResult::nextResult — Получает следующий результат
- mysql_xdevapi\Statement — Класс Statement
  - Statement::__construct — Описание конструктора
  - Statement::getNextResult — Получает следующий результат
  - Statement::getResult — Получает результат
  - Statement::hasMoreResults — Проверяет, есть ли ещё результаты
- mysql_xdevapi\Table — Класс Table
  - Table::__construct — Конструктор Table
  - Table::count — Получить количество строк
  - Table::delete — Удалить строки из таблицы
  - Table::existsInDatabase — Проверить, существует ли таблица в базе данных
  - Table::getName — Получить имя таблицы
  - Table::getSchema — Получить схему таблицы
  - Table::getSession — Получить таблицу сессий
  - Table::insert — Вставить строки таблицы
  - Table::isView — Проверить, является ли таблица представлением
  - Table::select — Выбрать строки из таблицы
  - Table::update — Обновить строки в таблице
- mysql_xdevapi\TableDelete — Класс TableDelete
  - TableDelete::bind — Связывает параметры запроса удаления
  - TableDelete::__construct — Конструктор класса TableDelete
  - TableDelete::execute — Выполняет запрос на удаление
  - TableDelete::limit — Ограничивает строки для удаления
  - TableDelete::orderby — Устанавливает критерии сортировки удаления
  - TableDelete::where — Устанавливает условие поиска для удаления
- mysql_xdevapi\TableInsert — Класс TableInsert
  - TableInsert::__construct — Конструктор класса TableInsert
  - TableInsert::execute — Выполняет запрос вставки
  - TableInsert::values — Добавляет значения вставки строки
- mysql_xdevapi\TableSelect — Класс TableSelect
  - TableSelect::bind — Привязывает параметры запроса выборки
  - TableSelect::__construct — Конструктор класса TableSelect
  - TableSelect::execute — Выполняет оператор выборки
  - TableSelect::groupBy — Устанавливает критерии группировки выборки
  - TableSelect::having — Устанавливает выбор с условием
  - TableSelect::limit — Ограничивает выбранные строки
  - TableSelect::lockExclusive — Выполняет EXCLUSIVE LOCK
  - TableSelect::lockShared — Выполняет SHARED LOCK
  - TableSelect::offset — Устанавливает предел смещения
  - TableSelect::orderby — Устанавливает критерии сортировки выборки
  - TableSelect::where — Устанавливает условие поиска выборки
- mysql_xdevapi\TableUpdate — Класс TableUpdate
  - TableUpdate::bind — Привязывает параметры запроса на обновление
  - TableUpdate::__construct — Конструктор класса TableUpdate
  - TableUpdate::execute — Выполняет запрос на обновление
  - TableUpdate::limit — Ограничивает количество строк для обновления
  - TableUpdate::orderby — Устанавливает критерии сортировки
  - TableUpdate::set — Добавляет поле для обновления
  - TableUpdate::where — Устанавливает фильтр поиска
- mysql_xdevapi\Warning — Класс Warning
  - Warning::__construct — Конструктор класса Warning

# Оригинальный API-интерфейс доступа к MySQL-серверам

# Введение

Модуль устарел с PHP 5.5.0, а в PHP версии 7.0.0 модуль удалили. Вместо устаревшего модуля с MySQL-серверами работают через модуль mysqli или PDO_MySQL. Дополнительную информацию о выборе API-интерфейса для взаимодействия с СУБД MySQL содержит «Обзор API-интерфейсов для подключения к MySQL».

Функции модуля открывают доступ к серверам баз данных MySQL. Подробнее о MySQL рассказывет сайт » http://www.mysql.com/.

Документация к MySQL доступна по адресу » http://dev.mysql.com/doc/.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для использования этих функций PHP должен быть собран с поддержкой MySQL.

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

## Установка

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

Для компиляции просто используйте опцию конфигурации --with-mysql[=DIR], где необязательный параметр `[DIR]` указывает на директорию с установленным MySQL.

Несмотря на то, что модуль MySQL совместим с MySQL 4.1.0 и выше, он не поддерживает дополнительную функциональность, предоставляемую этими версиями. Для получения такой возможности воспользуйтесь модулем MySQLi.

Если вы хотите установить модуль mysql совместно с mysqli, то для избежания каких-либо конфликтов необходимо использовать одну и ту же клиентскую библиотеку.

## Установка на Linux-системы

Примечание: `[DIR]` является путём к файлам клиентской библиотеки MySQL (заголовкам и библиотекам), которые можно скачать с » MySQL.

Таблица компиляции ext/mysql по версиям PHP
PHP Версия | По умолчанию | Опции настройки: mysqlnd | Опции настройки: `libmysqlclient` | Список изменений
--- | --- | --- | --- | ---
4.x.x | libmysqlclient | Недоступно | --without-mysql для отключения | MySQL включён по умолчанию, клиентские библиотеки MySQL входят в поставку PHP
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Недоступно | --with-mysql=[DIR] | MySQL больше не включён по умолчанию, и клиентские библиотеки MySQL больше не входят в поставку PHP
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | Стал доступен mysqlnd
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd выбирается по умолчанию

## Установка на Windows-системы

## PHP 5.0.x, 5.1.x, 5.2.x

Поддержка MySQL больше не включена по умолчанию, поэтому для её включения необходимо подключить php_mysql.dll DLL внутри php.ini. Кроме этого, PHP понадобится доступ к клиентской библиотеке MySQL. Файл libmysql.dll поставляется в Windows дистрибутиве PHP, и для корректного общения PHP с MySQL, данный файл должен быть доступен в системном пути Windows PATH. О том как это сделать, смотрите FAQ "Как добавить мою PHP директорию в системный PATH на Windows?". Хотя копирование libmysql.dll в системную папку Windows также сработает (потому что системная папка находится по умолчанию в PATH), это не рекомендуется.

Как и при включении любого другого модуля PHP (в том числе и php_mysql.dll), директива extension_dir должна указывать на директорию, содержащую PHP-модули. Смотрите также Инструкции по ручной установке в Windows . Пример значения extension_dir для PHP 5: `c:\php\ext`

> Замечание: Если при старте веб-сервера происходит подобная ошибка: `"Unable to load dynamic library './php_mysql.dll'"`, ("Невозможно подгрузить динамическую библиотеку './php_mysql.dll'"), то это случается из-за того, что на вашей системе не может быть найдена php_mysql.dll и/или libmysql.dll.

## PHP 5.3.0+

MySQL Native Driver включён по умолчанию. В том числе php_mysql.dll, но без требования и использования libmysql.dll.

## Замечания по установке MySQL

Внимание

Сбои в работе PHP могут возникнуть при загрузке этого модуля вместе с модулем recode. За дополнительной информацией обращайтесь к разделу о модуле для recode.

> Замечание: Если вам требуется поддержка кодировок отличных от latin, (установленной по умолчанию), вам придётся установить внешнюю библиотеку libmysqlclient, скомпилированную с их поддержкой.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Директивы конфигурации MySQL
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mysql.allow_local_infile | "1" | `INI_SYSTEM` |
mysql.allow_persistent | "1" | `INI_SYSTEM` |
mysql.max_persistent | "-1" | `INI_SYSTEM` |
mysql.max_links | "-1" | `INI_SYSTEM` |
mysql.trace_mode | "0" | `INI_ALL` |
mysql.default_port | NULL | `INI_ALL` |
mysql.default_socket | NULL | `INI_ALL` |
mysql.default_host | NULL | `INI_ALL` |
mysql.default_user | NULL | `INI_ALL` |
mysql.default_password | NULL | `INI_ALL` |
mysql.connect_timeout | "60" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`mysql.allow_local_infile` int
  Разрешает доступ к локальным файлам, с точки зрения PHP, с помощью инструкций LOAD DATA
`mysql.allow_persistent` bool
  Позволять ли постоянные соединения с MySQL.
`mysql.max_persistent` int
  Максимальное количество постоянных соединений c MySQL на один процесс.
`mysql.max_links` int
  Максимальное количество соединений с MySQL на один процесс, включая постоянные соединения.
`mysql.trace_mode` bool
  Режим трассировки. Если включена опция `mysql.trace_mode`, будут отображаться предупреждения при сканировании таблиц/индексов, непустых результирующих наборов (result sets), а также ошибки SQL. (Добавлено в версии PHP 4.3.0)
`mysql.default_port` string
  TCP-порт, используемый для соединения с базой данных по умолчанию (если не был указан другой). Если эта директива опущена, порт будет взят из переменной среды MYSQL_TCP_PORT, значения `mysql-tcp` в файле /etc/services или константы `MYSQL_PORT`, указанной при компиляции, в указанном порядке. Win32 использует только константу `MYSQL_PORT`.
`mysql.default_socket` string
  Имя сокета по умолчанию, используемого для соединения с локальной базой данных, если не был указан другой.
`mysql.default_host` string
  Адрес сервера по умолчанию, используемый для соединения с сервером базы данных, если не указан другой. Не работает в SQL safe mode.
`mysql.default_user` string
  Имя пользователя по умолчанию, используемое для соединения с сервером базы данных, если не указано другое. Не работает в SQL safe mode.
`mysql.default_password` string
  Пароль по умолчанию, используемый для соединения с сервером базы данных, если не указан другой. Не работает в SQL safe mode.
`mysql.connect_timeout` int
  Время ожидания ответа до разрыва соединения в секундах. Linux также использует это значение при ожидании первого ответа от сервера.

## Типы ресурсов

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

# Список изменений

В классы, функции и методы модуля внесли следующие изменения.

### Общий список изменений для модуля ext/mysql

Этот список изменений ссылается на модуль ext/mysql.

### Глобальные изменения в ext/mysql

Следующий список представляет собой подборку изменений модуля ext/mysql.

Версия | Описание
--- | ---
7.0.0 | Этот модуль удалён из PHP. Подробности тут Выбор API-интерфейса.

### Изменения в существующих функциях

Нижеследующий список является компиляцией всех изменений в функциях ext/mysql.

Version | Function | Description
--- | --- | ---

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Можно указать дополнительные клиентские флаги для функций mysql_connect() и mysql_pconnect() functions. Предопределены следующие константы:

Клиентские константы MySQL
Константа | Описание
--- | ---
`MYSQL_CLIENT_COMPRESS` | Использовать протокол сжатия
`MYSQL_CLIENT_IGNORE_SPACE` | Разрешает использовать пробелы после имён функций
`MYSQL_CLIENT_INTERACTIVE` | Позволяет interactive_timeout секунд (вместо wait_timeout) бездействия до закрытия соединения.
`MYSQL_CLIENT_SSL` | Использовать SSL-шифрование. Этот флаг доступен только начиная с версии 4.x клиентской библиотеки MySQL. Версия 3.23.x поставляется как в PHP 4, так и с бинарным дистрибутивом Windows в PHP 5.

Функция mysql_fetch_array() использует константы для определения типа возвращаемого массива. Предопределены следующие константы:

Константы выборки MySQL
Константа | Описание
--- | ---
`MYSQL_ASSOC` | Результат возвращается в ассоциативном массиве с именами колонок в качестве индексов.
`MYSQL_BOTH` | Результат возвращается в массиве, содержащем как численные индексы, так и имена колонок в качестве индексов.
`MYSQL_NUM` | Результат возвращается в массиве, содержащем численные индексы. Индексы начинаются с 0 (0 содержит первую колонку).

# Примеры

## Содержание

- Обзорный пример модуля MySQL

## Обзорный пример модуля MySQL

Этот простой пример показывает, как соединиться с базой данных, выполнить запрос, распечатать результат и отсоединиться.

Пример #1 Пример работы с MySQL

    <?php
    // Соединяемся, выбираем базу данных
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        or die('Не удалось соединиться: ' . mysql_error());
    echo 'Соединение успешно установлено';
    mysql_select_db('my_database') or die('Не удалось выбрать базу данных');

    // Выполняем SQL-запрос
    $query = 'SELECT * FROM my_table';
    $result = mysql_query($query) or die('Запрос не удался: ' . mysql_error());

    // Выводим результаты в html
    echo "<table>\n";
    while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Освобождаем память от результата
    mysql_free_result($result);

    // Закрываем соединение
    mysql_close($link);
    ?>

# Функции СУБД MySQL

## Примечания

> Замечание: Большинство функций MySQL принимают `link_identifier` как последний, опциональный параметр. Если он не указан, то используется последнее открытое соединение. Если соединений нет, то модуль пытается открыть соединение используя параметры, указанные в php.ini. В случае неудачи, функции возвращают `false`.

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — Возвращает число затронутых прошлой операцией рядов

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_affected_rows()
- PDOStatement::rowCount()

### Описание

function mysql_affected_rows(resource `$link_identifier` = NULL): int

Возвращает количество рядов, затронутых последним INSERT, UPDATE, REPLACE или DELETE запросом, связанным с дескриптором `link_identifier`.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает количество изменённых записей в случае успешного выполнения, и -1 в случае если последний запрос не удался.

Если последний запрос был DELETE без указания WHERE и, соответственно, таблица была очищена, функция вернёт ноль во всех версиях MySQL до 4.1.2.

При использовании UPDATE, MySQL не обновит колонки, уже содержащие новое значение. Вследствие этого, функция mysql_affected_rows() не всегда возвращает количество рядов, подошедших под условия, только количество рядов, обновлённых запросом.

Запрос REPLACE сначала удаляет запись с указанным первичным ключом, а потом вставляет новую. Данная функция возвращает количество удалённых записей вместе с количеством вставленных.

В случае использования запросов типа "INSERT ... ON DUPLICATE KEY UPDATE", возвращаемое значение будет равно `1` в случае, если была произведена вставка, или `2` при обновлении существующего ряда.

### Примеры

Пример #1 Пример использования mysql_affected_rows()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* здесь функция вернёт корректное число удалённых записей */
    mysql_query('DELETE FROM mytable WHERE id < 10');
    printf("Удалено записей: %d\n", mysql_affected_rows());

    /* если WHERE всегда возвращает false, то функция возвращает 0 */
    mysql_query('DELETE FROM mytable WHERE 0');
    printf("Удалено записей: %d\n", mysql_affected_rows());
    ?>

Вывод приведённого примера будет похож на:

    Удалено записей: 10
    Удалено записей: 0

Пример #2 Пример использования mysql_affected_rows() с транзакциями

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Обновляем ряды */
    mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
    printf ("Обновлено записей: %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

Вывод приведённого примера будет похож на:

    Обновлено записей: 10

### Примечания

> Замечание: Транзакции
> При использовании транзакций mysql_affected_rows() нужно вызывать после запросов INSERT, UPDATE, DELETE, но не после COMMIT.

> Замечание: Запросы SELECT
> Чтобы получить количество рядов, возвращённых SELECT-запросом, используйте функцию mysql_num_rows().

> Замечание: Каскадные внешние ключи
> mysql_affected_rows() не подсчитывает ряды, неявно изменённые ограничениями ON DELETE CASCADE и/или ON UPDATE CASCADE.

### Смотрите также

- mysql_num_rows() - Возвращает количество рядов результата запроса
- mysql_info() - Возвращает информацию о последнем запросе

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — Возвращает кодировку соединения

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_character_set_name()

### Описание

function mysql_client_encoding(resource `$link_identifier` = NULL): string

Возвращает значение переменной MySQL `character_set`.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования mysql_client_encoding()

    <?php
    $link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $charset = mysql_client_encoding($link);

    echo "Текущая кодировка: $charset\n";
    ?>

Вывод приведённого примера будет похож на:

    Текущая кодировка: latin1

### Смотрите также

- mysql_set_charset() - Устанавливает кодировку клиента
- mysql_real_escape_string() - Экранирует специальные символы в строках для использования в выражениях SQL

# mysql_close

(PHP 4, PHP 5)

mysql_close — Закрывает соединение с сервером MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_close()
- PDO: Присвоить значение `null` объекту PDO

### Описание

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() закрывает непостоянное соединение с базой данных MySQL, на которое указывает переданный дескриптор. Если параметр `link_identifier` не указан, закрывается последнее открытое (текущее) соединение.

Открытые непостоянные соединения MySQL и результирующие наборы автоматически удаляются сразу по окончании работы PHP-скрипта. Поэтому закрывать соединения и очищать результирующие наборы не обязательно, но рекомендуется, поскольку это сразу же освободит ресурсы базы данных и память, которую занимают результаты выборки, что часто положительно сказывается на производительности. Больше информации даёт раздел «Освобождение ресурсов».

### Список параметров

`link_identifier`
  Соединение MySQL. Если не указано, то будет использовано последнее соединение, открытое mysql_connect(). Если соединение не найдено или не установлено, то будет сгенерирована ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_close()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);
    ?>

Результат выполнения приведённого примера:

    Успешно соединились

### Примечания

> Замечание: mysql_close() не закрывает постоянные соединения, созданные функцией mysql_pconnect(). Для дополнительной информации смотрите руководство по постоянным соединениям.

### Смотрите также

- mysql_connect() - Открывает соединение с сервером MySQL
- mysql_free_result() - Освобождает память от результата запроса

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — Открывает соединение с сервером MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_connect()
- PDO::__construct()

### Описание

function mysql_connect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
bool `$new_link` = `false`,
int `$client_flags` = 0
): resource|false

Открывает новое соединение с сервером MySQL или использует уже существующее.

### Список параметров

`server`
  Сервер MySQL. Может также включать номер порта, например, "hostname:port" или путь к локальному сокету, например, ":/path/to/socket" для локального сервера. Если PHP-директива mysql.default_host не определена (по умолчанию), то значением по умолчанию является 'localhost:3306'. В SQL safe mode этот параметр игнорируется и всегда используется значение 'localhost:3306'.
`username`
  Имя пользователя. Значение по умолчанию определяется директивой mysql.default_user. В SQL safe mode этот параметр будет проигнорирован и будет использован пользователь, владеющий процессом сервера.
`password`
  Пароль. Значение по умолчанию определяется директивой mysql.default_password. В SQL safe mode этот параметр будет проигнорирован и в качестве пароля будет использована пустая строка.
`new_link`
  Если второй вызов функции mysql_connect() произошёл с теми же аргументами, то новое соединение не будет установлено. Вместо этого функция вернёт ссылку на уже установленное соединение. Параметр `new_link` может заставить функцию mysql_connect() открыть ещё одно соединение, даже если соединение с аналогичными параметрами уже открыто. В SQL safe mode этот параметр игнорируется.
`client_flags`
  Параметр `client_flags` должен быть комбинацией из следующих констант: 128 (включает обработку `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` or `MYSQL_CLIENT_INTERACTIVE`. Подробнее читайте в разделе Клиентские константы MySQL. В SQL safe mode этот параметр игнорируется.

### Возвращаемые значения

Возвращает дескриптор соединения с MySQL в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_connect()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);
    ?>

Пример #2 Пример использования mysql_connect() с синтаксисом `hostname:port`

    <?php
    // соединяемся с example.com на порту 3307
    $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);

    // соединяемся с localhost на порту 3307
    $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);
    ?>

Пример #3 Пример использования mysql_connect() с синтаксисом ":/path/to/socket"

    <?php
    // соединяемся к localhost по сокету, т.е. /tmp/mysql.sock

    // вариант 1: не указываем localhost
    $link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);

    // вариант 2: указываем localhost
    $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    echo 'Успешно соединились';
    mysql_close($link);
    ?>

### Примечания

> Замечание: При указании параметру `server` значения "localhost" или "localhost:port" клиентская библиотека MySQL будет пытаться соединиться с локальным сокетом. Если вы всё же хотите использовать TCP/IP, используйте адрес "127.0.0.1" вместо "localhost". Если клиентская библиотека пытается подключиться не к тому локальному сокету, правильный путь должен быть установлен через указание директивы php.ini mysql.default_host в php.ini, после чего можно оставлять параметр `server` пустым.

> Замечание: Соединение с сервером будет закрыто при завершении исполнения скрипта, если только до этого оно не было закрыто с помощью функции mysql_close().

> Замечание: Ошибка "Can't create TCP/IP socket (10106)" (Невозможно создать сокет TCP/IP) обычно означает, что конфигурационная директива variables_order не содержит символ `E`. В Windows, если в окружение не будет скопирована переменная окружения `SYSTEMROOT`, то PHP будет испытывать проблемы при загрузке Winsock.

### Смотрите также

- mysql_pconnect() - Устанавливает постоянное соединение с сервером MySQL
- mysql_close() - Закрывает соединение с сервером MySQL

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — Создаёт базу данных MySQL

Внимание

Функция устарела в PHP 4.3.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- mysqli_query()
- PDO::query()

### Описание

function mysql_create_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_create_db() пытается создать базу данных на сервере, с которым ассоциирован переданный дескриптор соединения.

### Список параметров

`database_name`
  Имя создаваемой базы данных.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример создания базы данных MySQL

Функция mysql_create_db() не рекомендуется к использованию. Предпочтительнее использовать mysql_query() с SQL-запросом создания базы данных `CREATE DATABASE`.

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }

    $sql = 'CREATE DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "База my_db успешно создана\n";
    } else {
        echo 'Ошибка при создании базы данных: ' . mysql_error() . "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    База my_db успешно создана

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_createdb()

> Замечание: Данная функция не будет доступна, если модуль MySQL был скомпилирован клиентской библиотекой MySQL версии 4.x.

### Смотрите также

- mysql_query() - Посылает запрос MySQL
- mysql_select_db() - Выбирает базу данных MySQL

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — Перемещает внутренний указатель в результате запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### Описание

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() перемещает внутренний указатель результата запроса, с которым связан переданный дескриптор, к ряду с указанным номером. Следующий вызов к функции получения данных MySQL, такой как mysql_fetch_assoc(), вернёт именно его.

Нумерация `row_number` начинается с 0. `row_number` должен быть значением в диапазоне от 0 до mysql_num_rows() - 1. Однако, если результат пуст (mysql_num_rows() == 0), то попытка сдвига указателя к нулевому ряду завершится неудачей - будет вызвана ошибка уровня `E_WARNING` и mysql_data_seek() вернёт `false`.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`row_number`
  Желаемый номер ряда в полученном дескрипторе результата.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_data_seek()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    $db_selected = mysql_select_db('sample_db');
    if (!$db_selected) {
        die('Не удалось выбрать базу данных: ' . mysql_error());
    }
    $query = 'SELECT last_name, first_name FROM friends';
    $result = mysql_query($query);
    if (!$result) {
        die('Ошибка запроса: ' . mysql_error());
    }
    /* получение рядов в обратном порядке */
    for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($result, $i)) {
            echo "Не удалось переместиться к ряду $i: " . mysql_error() . "\n";
            continue;
        }

        if (!($row = mysql_fetch_assoc($result))) {
            continue;
        }

        echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
    }

    mysql_free_result($result);
    ?>

### Примечания

> Замечание: Функция mysql_data_seek() может быть использована только с mysql_query(), но не с mysql_unbuffered_query().

### Смотрите также

- mysql_query() - Посылает запрос MySQL
- mysql_num_rows() - Возвращает количество рядов результата запроса
- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_fetch_array() - Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_fetch_object() - Обрабатывает ряд результата запроса и возвращает объект

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — Возвращает название базы данных из вызова к mysql_list_dbs()

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- Запрос: `SELECT DATABASE()`

### Описание

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

Возвращает название базы данных из вызова к mysql_list_dbs().

### Список параметров

`result`
  Дескриптор результата, полученный из вызова mysql_list_dbs().
`row`
  Индекс в результате.
`field`
  Имя поля.

### Возвращаемые значения

Возвращает название базы данных в случае успешного выполнения, или `false` в случае ошибки. В случае возврата `false` используйте mysql_error() для определения природы ошибок.

### Примеры

Пример #1 Пример использования mysql_db_name()

    <?php
    error_reporting(E_ALL);

    $link = mysql_connect('dbhost', 'username', 'password');
    $db_list = mysql_list_dbs($link);

    $i = 0;
    $cnt = mysql_num_rows($db_list);
    while ($i < $cnt) {
        echo mysql_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_dbname()

### Смотрите также

- mysql_list_dbs() - Возвращает список баз данных, доступных на сервере
- mysql_tablename() - Возвращает имя таблицы, содержащей указанное поле

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — Переключается на указанную базу данных и посылает запрос

Внимание

Функция устарела в PHP 5.3.0, а в PHP в 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Также смотрите раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- mysqli_select_db() then the query
- PDO::__construct()

### Описание

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() выбирает базу данных и выполняет запрос к ней.

### Список параметров

`database`
  Имя базы данных, на которую произойдёт переключение.
`query`
  Запрос MySQL. Данные в запросе должны быть корректно проэкранированы.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает ресурс результата запроса к MySQL или `false` в случае возникновения ошибки. Функция также возвращает `true`/`false` для `INSERT`/`UPDATE`/`DELETE` запросов для индикации успеха/провала.

### Примеры

Пример #1 Пример использования альтернативы mysql_db_query()

    <?php

    if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Не удалось подключиться к mysql';
        exit;
    }

    if (!mysql_select_db('mysql_dbname', $link)) {
        echo 'Не удалось выбрать базу данных';
        exit;
    }

    $sql    = 'SELECT foo FROM bar WHERE id = 42';
    $result = mysql_query($sql, $link);

    if (!$result) {
        echo "Ошибка DB, запрос не удался\n";
        echo 'MySQL Error: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_assoc($result)) {
        echo $row['foo'];
    }

    mysql_free_result($result);

    ?>

### Примечания

> Замечание: Учтите, что эта функция НЕ переключает соединение обратно к предыдущей базе данных. Другими словами, вы не можете использовать эту функцию, чтобы временно переключиться на другую базу данных и выполнить запрос. Переключиться обратно вам придётся вручную. Крайне рекомендуется использовать синтаксис `database.table` в SQL-запросах или функцию mysql_select_db(), вместо использования этой функции.

### Смотрите также

- mysql_query() - Посылает запрос MySQL
- mysql_select_db() - Выбирает базу данных MySQL

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — Уничтожает базу данных MySQL

Внимание

Функция устарела в PHP 4.3.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- Выполнить запрос `DROP DATABASE`

### Описание

function mysql_drop_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_drop_db() пытается уничтожить базу данных на сервере, на который ссылается переданный дескриптор соединения. Данная функция устарела, используйте вместо неё mysql_query() с запросом `DROP DATABASE`.

### Список параметров

`database_name`
  Имя удаляемой базы данных.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Альтернативный пример использования mysql_drop_db()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Не удалось подключиться к базе данных: ' . mysql_error());
    }

    $sql = 'DROP DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "База данных my_db была успешно удалена\n";
    } else {
        echo 'Ошибка при удалении базы данных: ' . mysql_error() . "\n";
    }
    ?>

### Примечания

Внимание

Эта функция недоступна, если модуль был скомпилирован с клиентской библиотекой MySQL версии 4.x.

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_dropdb()

### Смотрите также

- mysql_query() - Посылает запрос MySQL

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — Возвращает численный код ошибки выполнения последней операции с MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_errno()
- PDO::errorCode()

### Описание

function mysql_errno(resource `$link_identifier` = NULL): int

Возвращает код ошибки последней функции работы с MySQL.

Ошибки работы с MySQL больше не вызывают сообщений в PHP. Вместо этого используйте функцию mysql_errno(), чтобы получить код ошибки. Учтите, что функция возвращает код ошибки только последней выполненной функции (исключая mysql_error() и mysql_errno()). Проверяйте результат работы функции до вызова следующей.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает код ошибки последней функции работы с MySQL, или `0` (ноль), если операция выполнена успешно.

### Примеры

Пример #1 Пример использования mysql_errno()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!mysql_select_db("nonexistentdb", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link). "\n";
    }

    mysql_select_db("kossu", $link);
    if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Смотрите также

- mysql_error() - Возвращает текст ошибки последней операции с MySQL
- » Коды ошибок MySQL

# mysql_error

(PHP 4, PHP 5)

mysql_error — Возвращает текст ошибки последней операции с MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_error()
- PDO::errorInfo()

### Описание

function mysql_error(resource `$link_identifier` = NULL): string

Возвращает текст ошибки выполнения последней функции MySQL. Ошибки работы с MySQL больше не вызывают сообщений в PHP. Вместо этого используйте функцию mysql_error(), для получения сообщения об ошибке. Учтите, что функция возвращает текст ошибки только последней выполненной функции MySQL (исключая mysql_error() и mysql_errno()), поэтому убедитесь, что вы вызываете данную функцию до вызова следующей функции MySQL.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает текст ошибки выполнения последней функции MySQL, или `''` (пустую строку), если операция выполнена успешно.

### Примеры

Пример #1 Пример использования mysql_error()

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    mysql_select_db("nonexistentdb", $link);
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";

    mysql_select_db("kossu", $link);
    mysql_query("SELECT * FROM nonexistenttable", $link);
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    ?>

Вывод приведённого примера будет похож на:

    1049: Unknown database 'nonexistentdb'
    1146: Table 'kossu.nonexistenttable' doesn't exist

### Смотрите также

- mysql_errno() - Возвращает численный код ошибки выполнения последней операции с MySQL
- » Коды ошибок MySQL

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — Экранирует строку для использования в mysql_query

Внимание

Функция устарела в PHP 4.3.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- mysqli_escape_string()
- PDO::quote()

### Описание

function mysql_escape_string(string `$unescaped_string`): string

Функция экранирует `unescaped_string` таким образом, после чего её можно безопасно использовать в mysql_query(). Данная функция устарела.

Функция идентична mysql_real_escape_string(), исключая тот факт, что mysql_real_escape_string() принимает параметром ещё и идентификатор соединения и экранирует строку с учётом текущей кодировки. mysql_escape_string() не делает этого и результат работы не зависит от кодировки, в который вы работаете с БД.

### Список параметров

`unescaped_string`
  Экранируемая строка.

### Возвращаемые значения

Возвращает экранируемую строку.

### Примеры

Пример #1 Пример использования mysql_escape_string()

    <?php
    $item = "Zak's Laptop";
    $escaped_item = mysql_escape_string($item);
    printf("Escaped string: %s\n", $escaped_item);
    ?>

Результат выполнения приведённого примера:

    Escaped string: Zak\'s Laptop

### Примечания

> Замечание: mysql_escape_string() не экранирует символы `%` и `_`.

### Смотрите также

- mysql_real_escape_string() - Экранирует специальные символы в строках для использования в выражениях SQL

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_array()
- PDOStatement::fetch()

### Описание

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

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

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`result_type`
  Тип возвращаемого массива. Является константой и может принимать следующие значения: `MYSQL_ASSOC`, `MYSQL_NUM` и `MYSQL_BOTH`.

### Возвращаемые значения

Возвращает массив строк, соответствующих обработанному ряду результата запроса, или `false`, если рядов больше нет. Тип возвращаемого массива зависит от значения параметра `result_type`. При использовании `MYSQL_BOTH` (по умолчанию), вы получите массив, состоящий как из ассоциативных индексов, так и из численных. `MYSQL_ASSOC` вернёт только ассоциативные индексы (аналогично функции mysql_fetch_assoc()), а `MYSQL_NUM` - только численные (аналогично функции mysql_fetch_row()).

Если несколько колонок в результате будут иметь одинаковые названия, то будет возвращена последняя колонка. Чтобы получить доступ к другим колонкам с тем же именем, используйте численные индексы массива или псевдонимы в запросе. В случае псевдонимов используйте именно их - вы не сможете использовать настоящие имена колонок.

### Примеры

Пример #1 Запрос с применением псевдонимов для дублирующихся имён колонок

    SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

Пример #2 mysql_fetch_array() с `MYSQL_NUM`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Ошибка соединения: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
        printf("ID: %s  Имя: %s", $row[0], $row[1]);
    }

    mysql_free_result($result);
    ?>

Пример #3 mysql_fetch_array() с `MYSQL_ASSOC`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Ошибка соединения: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
        printf("ID: %s  Имя: %s", $row["id"], $row["name"]);
    }

    mysql_free_result($result);
    ?>

Пример #4 mysql_fetch_array() с `MYSQL_BOTH`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Ошибка соединения: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
        printf ("ID: %s  Имя: %s", $row[0], $row["name"]);
    }

    mysql_free_result($result);
    ?>

### Примечания

> Замечание: Производительность
> Важно заметить, что mysql_fetch_array() работает незначительно медленнее, чем mysql_fetch_row(), в то же время предоставляя намного более удобный доступ к данным.

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Смотрите также

- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_data_seek() - Перемещает внутренний указатель в результате запроса
- mysql_query() - Посылает запрос MySQL

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — Возвращает ряд результата запроса в качестве ассоциативного массива

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_assoc()
- PDOStatement::fetch() с параметром `mode` заданным как `PDO::FETCH_ASSOC`

### Описание

function mysql_fetch_assoc(resource `$result`): array

Возвращает ассоциативный массив, соответствующий полученному ряду и сдвигает вперёд внутренний указатель результата. Функция mysql_fetch_assoc() аналогична вызову функции mysql_fetch_array() со вторым необязательным параметром, равным MYSQL_ASSOC. Функция возвращает только ассоциативный массив.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Возвращает ассоциативный массив строк, соответствующий полученному ряду, либо `false` если рядов больше нет.

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

### Примеры

Пример #1 Расширенный пример использования mysql_fetch_assoc()

    <?php

    $conn = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!$conn) {
        echo "Unable to connect to DB: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("mydbname")) {
        echo "Unable to select mydbname: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as userid, fullname, userstatus
            FROM   sometable
            WHERE  userstatus = 1";

    $result = mysql_query($sql);

    if (!$result) {
        echo "Could not successfully run query ($sql) from DB: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($result) == 0) {
        echo "No rows found, nothing to print so am exiting";
        exit;
    }

    // До тех пор, пока в результате содержатся ряды, помещаем их в ассоциативный массив.
    // Замечание: если запрос возвращает только один ряд - нет нужды в цикле.
    // Замечание: если вы добавите extract($row); в начало цикла, вы сделаете
    //            доступными переменные $userid, $fullname и $userstatus
    while ($row = mysql_fetch_assoc($result)) {
        echo $row["userid"];
        echo $row["fullname"];
        echo $row["userstatus"];
    }

    mysql_free_result($result);

    ?>

### Примечания

> Замечание: Производительность
> Важно отметить, что mysql_fetch_assoc() лишь незначительно медленнее, чем mysql_fetch_row(), но в то же время предоставляет важную дополнительную информацию.

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Смотрите также

- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_fetch_array() - Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_data_seek() - Перемещает внутренний указатель в результате запроса
- mysql_query() - Посылает запрос MySQL
- mysql_error() - Возвращает текст ошибки последней операции с MySQL

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — Возвращает информацию о колонке из результата запроса в виде объекта

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### Описание

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

Возвращает объект, содержащий информацию о колонке. Эту функцию можно использовать для получения информации о полях в переданном результате запроса.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. Если смещение не указано, функция возвращает информацию о первой колонке, которая ещё не была обработана этой функцией. Нумерация `field_offset` начинается с `0`.

### Возвращаемые значения

Возвращает object, содержащий информацию о колонке. Объект содержит следующие свойства:

- name - название колонки
- table - название таблицы, которой принадлежит колонка, или псевдоним таблицы, если он был определён
- max_length - максимальная длина колонки
- not_null - 1, если колонка не может быть `null`
- primary_key - 1, если колонка является первичным индексом
- unique_key - 1, если колонка является уникальным индексом
- multiple_key - 1, если колонка является неуникальным индексом
- numeric - 1, если колонка численная
- blob - 1, если колонка является BLOB
- type - тип колонки
- unsigned - 1, если колонка не содержит знака (unsigned)
- zerofill - 1, если колонка заполняется нулями (zero-filled)

### Примеры

Пример #1 Пример использования mysql_fetch_field()

    <?php
    $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$conn) {
        die('Ошибка при соединении: ' . mysql_error());
    }
    mysql_select_db('database');
    $result = mysql_query('select * from table');
    if (!$result) {
        die('Ошибка в запросе: ' . mysql_error());
    }
    /* получаем данные о колонке */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
        echo "Информация о колонке $i:<br />\n";
        $meta = mysql_fetch_field($result, $i);
        if (!$meta) {
            echo "Информация недоступна<br />\n";
        }
        echo "<pre>
    blob:         $meta->blob
    max_length:   $meta->max_length
    multiple_key: $meta->multiple_key
    name:         $meta->name
    not_null:     $meta->not_null
    numeric:      $meta->numeric
    primary_key:  $meta->primary_key
    table:        $meta->table
    type:         $meta->type
    unique_key:   $meta->unique_key
    unsigned:     $meta->unsigned
    zerofill:     $meta->zerofill
    </pre>";
        $i++;
    }
    mysql_free_result($result);
    ?>

### Примечания

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Если поля или таблицы имеют дополнительные имена в запросе SQL, то будет возвращены эти дополнительные имена. Исходное имя может быть получено, например, с помощью mysqli_result::fetch_field().

### Смотрите также

- mysql_field_seek() - Устанавливает внутренний указатель результата на переданное смещение поля

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — Возвращает длину каждого поля в результате

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### Описание

function mysql_fetch_lengths(resource `$result`): array|false

Возвращает массив длин для каждого поля, содержащегося в последнем ряду результата, полученном из MySQL.

mysql_fetch_lengths() возвращает длины каждого поля, содержащегося в последнем ряду, обработанном функциями mysql_fetch_row(), mysql_fetch_assoc(), mysql_fetch_array() и mysql_fetch_object() в массиве, начинающемся с 0.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Массив (array) длин в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_fetch_lengths()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Ошибка выполнения запроса: ' . mysql_error();
        exit;
    }
    $row     = mysql_fetch_assoc($result);
    $lengths = mysql_fetch_lengths($result);

    print_r($row);
    print_r($lengths);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [id] => 42
        [email] => user@example.com
    )
    Array
    (
        [0] => 2
        [1] => 16
    )

### Смотрите также

- mysql_field_len() - Возвращает длину указанного поля
- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- strlen() - Получает длину строки

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — Обрабатывает ряд результата запроса и возвращает объект

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_object()
- PDOStatement::fetch() с параметром `mode` заданным как `PDO::FETCH_OBJ`

### Описание

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

Возвращает объект со свойствами, соответствующими колонкам в обработанном ряду и сдвигает внутренний указатель результата вперёд.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`class_name`
  Имя класса. Будет создан экземпляр указанного класса, заполнен свойствами и возвращён. Если не указан, возвращается экземпляр stdClass.
`params`
  Необязательный массив (array) параметров, передаваемых в конструктор создаваемого экземпляра `class_name`.

### Возвращаемые значения

Возвращает объект (object) со строковыми свойствами, соответствующими полученному ряду, или `false`, если рядов больше нет.

### Примеры

Пример #1 Пример использования mysql_fetch_object()

    <?php
    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");
    $result = mysql_query("select * from mytable");
    while ($row = mysql_fetch_object($result)) {
        echo $row->user_id;
        echo $row->fullname;
    }
    mysql_free_result($result);
    ?>

Пример #2 Пример использования mysql_fetch_object()

    <?php
    class foo {
        public $name;
    }

    mysql_connect("hostname", "user", "password");
    mysql_select_db("mydb");

    $result = mysql_query("select name from mytable limit 1");
    $obj = mysql_fetch_object($result, 'foo');
    var_dump($obj);
    ?>

### Примечания

> Замечание: Производительность
> В плане скорости эта функция аналогична mysql_fetch_array() и почти также быстра, как mysql_fetch_row() (разница незначительна).

> Замечание: mysql_fetch_object() работает аналогично mysql_fetch_array(), с единственным отличием - функция возвращает объект вместо массива. Это, кроме всего прочего, означает, что вы сможете работать с полями только по имени колонок, а не индексов (числа не могут быть свойствами объекта).

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Смотрите также

- mysql_fetch_array() - Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_data_seek() - Перемещает внутренний указатель в результате запроса
- mysql_query() - Посылает запрос MySQL

# mysql_fetch_row

(PHP 4, PHP 5)

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

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_row()
- PDOStatement::fetch() с параметром `mode` заданным как `PDO::FETCH_NUM`

### Описание

function mysql_fetch_row(resource `$result`): array

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

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Возвращает массив строк с числовыми индексами, содержащий данные обработанного ряда, или `false`, если рядов не осталось.

mysql_fetch_row() обрабатывает один ряд результата, на который ссылается переданный указатель. Ряд возвращается в виде массива. Каждая колонка располагается в следующей ячейке массива, начиная с нулевого индекса

### Примеры

Пример #1 Получение одного ряда с помощью mysql_fetch_row()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Ошибка запроса: ' . mysql_error();
        exit;
    }
    $row = mysql_fetch_row($result);

    echo $row[0]; // 42
    echo $row[1]; // email
    ?>

### Примечания

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Смотрите также

- mysql_fetch_array() - Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_fetch_object() - Обрабатывает ряд результата запроса и возвращает объект
- mysql_data_seek() - Перемещает внутренний указатель в результате запроса
- mysql_fetch_lengths() - Возвращает длину каждого поля в результате
- mysql_result() - Возвращает данные результата запроса

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — Возвращает флаги, связанные с указанным полем результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field_direct() [flags]
- PDOStatement::getColumnMeta() [flags]

### Описание

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() возвращает флаги, связанные с указанным полем. Каждый флаг возвращается как отдельное слово, отделённое от предыдущего пробелом. Полученное значение можно разбить в массив, используя функцию explode().

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает строку с флагами, связанными с результатом или `false`, если возникла ошибка.

Возвращаются следующие флаги, если ваша версия MySQL их уже поддерживает: `"not_null"`, `"primary_key"`, `"unique_key"`, `"multiple_key"`, `"blob"`, `"unsigned"`, `"zerofill"`, `"binary"`, `"enum"`, `"auto_increment"` и `"timestamp"`.

### Примеры

Пример #1 Пример использования mysql_field_flags()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Ошибка в запросе: ' . mysql_error();
        exit;
    }
    $flags = mysql_field_flags($result, 0);

    echo $flags;
    print_r(explode(' ', $flags));
    ?>

Вывод приведённого примера будет похож на:

    not_null primary_key auto_increment
    Array
    (
        [0] => not_null
        [1] => primary_key
        [2] => auto_increment
    )

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_fieldflags()

### Смотрите также

- mysql_field_type() - Возвращает тип указанного поля из результата запроса
- mysql_field_len() - Возвращает длину указанного поля

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — Возвращает длину указанного поля

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### Описание

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() возвращает длину указанного поля.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Длина указанного поля в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_field_len()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Не удалось выполнить запрос: ' . mysql_error();
        exit;
    }

    // Получит длину поля id так, как указано в структуре базы данных
    $length = mysql_field_len($result, 0);
    echo $length;
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_fieldlen()

### Смотрите также

- mysql_fetch_lengths() - Возвращает длину каждого поля в результате
- strlen() - Получает длину строки

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — Возвращает название указанной колонки результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field_direct() [name] или [orgname]
- PDOStatement::getColumnMeta() [name]

### Описание

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() возвращает название колонки с указанным индексом.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Название поля по указанному индексу в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_field_name()

    <?php
    /* Таблица пользователей состоит из трёх колонок:
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения с MySQL: ' . mysql_error());
    }
    $dbname = 'mydb';
    $db_selected = mysql_select_db($dbname, $link);
    if (!$db_selected) {
        die("Не удалось выбрать базу $dbname: " . mysql_error());
    }
    $res = mysql_query('select * from users', $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

Результат выполнения приведённого примера:

    user_id
    password

### Примечания

> Замечание: Имена полей, возвращаемые этой функцией являются зависимыми от регистра.

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_fieldname()

### Смотрите также

- mysql_field_type() - Возвращает тип указанного поля из результата запроса
- mysql_field_len() - Возвращает длину указанного поля

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — Устанавливает внутренний указатель результата на переданное смещение поля

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_field_seek()
- PDOStatement::fetch() с использованием параметров `cursor_orientation` и `offset`

### Описание

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

Перемещает указатель к полю с указанным смещением. Если следующий вызов функции mysql_fetch_field() не содержит смещения, то будет возвращено смещение, содержащееся в mysql_field_seek().

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- mysql_fetch_field() - Возвращает информацию о колонке из результата запроса в виде объекта

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — Возвращает название таблицы, которой принадлежит указанное поле

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field_direct() [table] или [orgtable]
- PDOStatement::getColumnMeta() [table]

### Описание

function mysql_field_table(resource `$result`, int `$field_offset`): string

Возвращает название таблицы, которой принадлежит указанное поле.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Имя таблицы в случае успешного выполнения.

### Примеры

Пример #1 Пример использования mysql_field_table()

    <?php

    $query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // получаем результат из базы данных
    $result = mysql_query($query);

    // выводит имя таблицы и имя поля
    for ($i = 0; $i < mysql_num_fields($result); ++$i) {
        $table = mysql_field_table($result, $i);
        $field = mysql_field_name($result, $i);

        echo  "$table: $field\n";
    }

    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_fieldtable()

### Смотрите также

- mysql_list_tables() - Извлекает список таблиц базы данных MySQL

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — Возвращает тип указанного поля из результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] или [pdo_type]

### Описание

function mysql_field_type(resource `$result`, int `$field_offset`): string

Функция mysql_field_type() аналогична функции mysql_field_name(). Аргументы одинаковы, но вместо имени колонки возвращается её тип.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`field_offset`
  Числовое смещение поля. `field_offset` начинается с `0`. Если `field_offset` не существует, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Поля могут быть следующих типов: `"int"`, `"real"`, `"string"`, `"blob"` и других, подробно описанных » документации MySQL.

### Примеры

Пример #1 Пример использования mysql_field_type()

    <?php
    mysql_connect("localhost", "mysql_username", "mysql_password");
    mysql_select_db("mysql");
    $result = mysql_query("SELECT * FROM func");
    $fields = mysql_num_fields($result);
    $rows   = mysql_num_rows($result);
    $table  = mysql_field_table($result, 0);
    echo "Ваша таблица '" . $table . "' содержит " . $fields . " поля и " . $rows . " запись\n";
    echo "В таблице есть следующие поля:\n";
    for ($i=0; $i < $fields; $i++) {
        $type  = mysql_field_type($result, $i);
        $name  = mysql_field_name($result, $i);
        $len   = mysql_field_len($result, $i);
        $flags = mysql_field_flags($result, $i);
        echo $type . " " . $name . " " . $len . " " . $flags . "\n";
    }
    mysql_free_result($result);
    mysql_close();
    ?>

Вывод приведённого примера будет похож на:

    Ваша таблица 'func' содержит 4 поля и 1 запись
    В таблице есть следующие поля:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_fieldtype()

### Смотрите также

- mysql_field_name() - Возвращает название указанной колонки результата запроса
- mysql_field_len() - Возвращает длину указанного поля

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — Освобождает память от результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_free_result()
- Присвоение значения `null` переменной PDO объекта, или PDOStatement::closeCursor()

### Описание

function mysql_free_result(resource `$result`): bool

mysql_free_result() высвободит всю память, занимаемую результатом, на который ссылается переданный дескриптор `result`.

mysql_free_result() нуждается в вызове только в том случае, если вы всерьёз обеспокоены тем, сколько памяти используют ваши запросы к БД, возвращающие большое количество данных. Вся память, используемая для хранения этих данных автоматически очистится в конце работы скрипта.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Если в качестве параметра `result` передан не ресурс, то будет вызвана ошибка уровня E_WARNING. Стоит также заметить, что mysql_query() возвращает resource только для запросов SELECT, SHOW, EXPLAIN и DESCRIBE.

### Примеры

Пример #1 Пример использования mysql_free_result()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Не удалось выполнить запрос: ' . mysql_error();
        exit;
    }
    /* Используем результат, подразумевая, что после этого он нам больше не нужен */
    $row = mysql_fetch_assoc($result);

    /* Теперь освобождаем результат и продолжаем дальнейшую работу над нашим скриптом */
    mysql_free_result($result);

    echo $row['id'];
    echo $row['email'];
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_freeresult()

### Смотрите также

- mysql_query() - Посылает запрос MySQL
- is_resource() - Определяет, относится ли переменная к типу ресурса

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — Возвращает данные о MySQL-клиенте

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_get_client_info()
- PDO::getAttribute() с параметром `attribute` заданным как `PDO::ATTR_CLIENT_VERSION`

### Описание

function mysql_get_client_info(): string

mysql_get_client_info() возвращает строку, содержащую версию клиентской библиотеки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Версия клиентской библиотеки MySQL.

### Примеры

Пример #1 Пример использования mysql_get_client_info()

    <?php
    printf("Версия клиентской библиотеки MySQL: %s\n", mysql_get_client_info());
    ?>

Вывод приведённого примера будет похож на:

    Версия клиентской библиотеки MySQL: 3.23.39

### Смотрите также

- mysql_get_host_info() - Возвращает информацию о соединении с MySQL
- mysql_get_proto_info() - Возвращает информацию о протоколе MySQL
- mysql_get_server_info() - Возвращает информацию о сервере MySQL

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — Возвращает информацию о соединении с MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_get_host_info()
- PDO::getAttribute() с параметром `attribute` заданным как `PDO::ATTR_CONNECTION_STATUS`

### Описание

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

Описывает тип используемого соединения, указанного переданным дескриптором соединения, включая имя хоста.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает строку, описывающую тип используемого соединения, указанного переданным дескриптором соединения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_get_host_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    printf("Тип соединения с MySQL: %s\n", mysql_get_host_info());
    ?>

Вывод приведённого примера будет похож на:

    Тип соединения с MySQL: Localhost via UNIX socket

### Смотрите также

- mysql_get_client_info() - Возвращает данные о MySQL-клиенте
- mysql_get_proto_info() - Возвращает информацию о протоколе MySQL
- mysql_get_server_info() - Возвращает информацию о сервере MySQL

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — Возвращает информацию о протоколе MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_get_proto_info()

### Описание

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

Возвращает информацию о протоколе MySQL.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает используемый протокол MySQL в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_get_proto_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    printf("Версия протокола MySQL: %s\n", mysql_get_proto_info());
    ?>

Вывод приведённого примера будет похож на:

    Версия протокола MySQL: 10

### Смотрите также

- mysql_get_client_info() - Возвращает данные о MySQL-клиенте
- mysql_get_host_info() - Возвращает информацию о соединении с MySQL
- mysql_get_server_info() - Возвращает информацию о сервере MySQL

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — Возвращает информацию о сервере MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_get_server_info()
- PDO::getAttribute() с параметром `attribute` заданным как `PDO::ATTR_SERVER_VERSION`

### Описание

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

Возвращает версию сервера MySQL.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает версию сервера MySQL в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_get_server_info()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    printf("Версия сервера MySQL: %s\n", mysql_get_server_info());
    ?>

Вывод приведённого примера будет похож на:

    Версия сервера MySQL: 4.0.1-alpha

### Смотрите также

- mysql_get_client_info() - Возвращает данные о MySQL-клиенте
- mysql_get_host_info() - Возвращает информацию о соединении с MySQL
- mysql_get_proto_info() - Возвращает информацию о протоколе MySQL
- phpversion() - Получает текущую версию PHP

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — Возвращает информацию о последнем запросе

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_info()

### Описание

function mysql_info(resource `$link_identifier` = NULL): string

Возвращает подробную информацию о последнем запросе.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает информацию о запросе в случае успешного выполнения, или `false` в случае возникновения ошибки. Смотрите пример ниже для каких запросов возвращается информация и как выглядят возвращаемые значения. Для не перечисленных запросов будет возвращено значение `false`.

### Примеры

Пример #1 Корректные виды запросов MySQL

Числа расставлены только для примера -- их значения зависят от результата запроса.

    INSERT INTO ... SELECT ...
    String format: Records: 23 Duplicates: 0 Warnings: 0
    INSERT INTO ... VALUES (...),(...),(...)...
    String format: Records: 37 Duplicates: 0 Warnings: 0
    LOAD DATA INFILE ...
    String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
    ALTER TABLE
    String format: Records: 60 Duplicates: 0 Warnings: 0
    UPDATE
    String format: Rows matched: 65 Changed: 65 Warnings: 0

### Примечания

> Замечание: mysql_info() возвращает значение не равное `false` для INSERT ... VALUES только в том случае, если в запросе присутствует несколько списков значений.

### Смотрите также

- mysql_affected_rows() - Возвращает число затронутых прошлой операцией рядов
- mysql_insert_id() - Возвращает идентификатор, сгенерированный при последнем INSERT-запросе
- mysql_stat() - Возвращает текущий статус сервера

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — Возвращает идентификатор, сгенерированный при последнем INSERT-запросе

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_insert_id()
- PDO::lastInsertId()

### Описание

function mysql_insert_id(resource `$link_identifier` = NULL): int

Возвращает идентификатор, сгенерированный колонкой с AUTO_INCREMENT последним запросом (обычно INSERT).

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Идентификатор, сгенерированный колонкой с AUTO_INCREMENT последним запросом в случае успешного выполнения, `0`, если последний запрос не генерирует значение AUTO_INCREMENT value, и `false`, если соединение MySQL не было установлено.

### Примеры

Пример #1 Пример использования mysql_insert_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    mysql_select_db('mydb');

    mysql_query("INSERT INTO mytable (product) values ('kossu')");
    printf("Идентификатор последней вставленной записи %d\n", mysql_insert_id());
    ?>

### Примечания

Предостережение

mysql_insert_id() конвертирует возвращаемый функцией MySQL C API тип значения функции `mysql_insert_id()` в тип `long` (называемый int в PHP). Если ваша колонка AUTO_INCREMENT имеет тип BIGINT (64 бита), то значение, возвращаемое функцией в результате преобразования может быть искажено. Используйте вместо данной функции внутреннюю MySQL-функцию LAST_INSERT_ID() в SQL-запросе. Подробнее о максимальных значениях целых чисел смотрите в разделе документации, посвящённом целым числам.

> Замечание: Так как mysql_insert_id() работает с последним выполненным запросом, вызывайте mysql_insert_id() сразу же после запроса, генерирующего новое значение.

> Замечание: Значение в SQL функции MySQL `LAST_INSERT_ID()` всегда содержит последний сгенерированный ID и не обнуляется между запросами.

### Смотрите также

- mysql_query() - Посылает запрос MySQL
- mysql_info() - Возвращает информацию о последнем запросе

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — Возвращает список баз данных, доступных на сервере

Внимание

Функция устарела с PHP 5.4.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- SQL запрос: `SHOW DATABASES`

### Описание

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

Возвращает указатель на результат, содержащий список баз данных, доступных на указанном сервере.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает resource результата в случае успешного выполнения, или `false` в случае возникновения ошибки. Используйте функцию mysql_tablename(), чтобы получить данные из результата, или любую другую функцию, работающую с результатами запросов, например mysql_fetch_array().

### Примеры

Пример #1 Пример использования mysql_list_dbs()

    <?php
    // Без использования mysql_list_dbs()
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $res = mysql_query("SHOW DATABASES");

    while ($row = mysql_fetch_assoc($res)) {
        echo $row['Database'] . "\n";
    }

    // Устарело, начиная с PHP 5.4.0
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $db_list = mysql_list_dbs($link);

    while ($row = mysql_fetch_object($db_list)) {
         echo $row->Database . "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    database1
    database2
    database3

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_listdbs()

### Смотрите также

- mysql_db_name() - Возвращает название базы данных из вызова к mysql_list_dbs
- mysql_select_db() - Выбирает базу данных MySQL

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — Возвращает список колонок таблицы

Внимание

Функция устарела с PHP 5.4.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- SQL запрос: `SHOW COLUMNS FROM sometable`

### Описание

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

Возвращает информацию о таблице с переданным именем.

Эта функция устарела. Вместо неё рекомендуется использовать mysql_query() с SQL-запросом `SHOW COLUMNS FROM table [LIKE 'name']`.

### Список параметров

`database_name`
  Имя опрашиваемой базы данных.
`table_name`
  Имя опрашиваемой таблицы.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Дескриптор результата (resource) в случае успешного выполнения, или `false` в случае возникновения ошибки.

Возвращаемый результат может быть обработан с помощью следующих функций: mysql_field_flags(), mysql_field_len(), mysql_field_name() и mysql_field_type().

### Примеры

Пример #1 Пример использования mysql_list_fields()

    <?php
    $result = mysql_query("SHOW COLUMNS FROM sometable");
    if (!$result) {
        echo 'Ошибка при выполнении запроса: ' . mysql_error();
        exit;
    }
    if (mysql_num_rows($result) > 0) {
        while ($row = mysql_fetch_assoc($result)) {
            print_r($row);
        }
    }
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [Field] => id
        [Type] => int(7)
        [Null] =>
        [Key] => PRI
        [Default] =>
        [Extra] => auto_increment
    )
    Array
    (
        [Field] => email
        [Type] => varchar(100)
        [Null] =>
        [Key] =>
        [Default] =>
        [Extra] =>
    )

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_listfields()

### Смотрите также

- mysql_field_flags() - Возвращает флаги, связанные с указанным полем результата запроса
- mysql_info() - Возвращает информацию о последнем запросе

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — Возвращает список процессов MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_thread_id()

### Описание

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

Возвращает список текущих процессов на сервере MySQL.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Дескриптор результата (resource) в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_list_processes()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

    $result = mysql_list_processes($link);
    while ($row = mysql_fetch_assoc($result)){
        printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
            $row["Command"], $row["Time"]);
    }
    mysql_free_result($result);
    ?>

Вывод приведённого примера будет похож на:

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### Смотрите также

- mysql_thread_id() - Возвращает идентификатор текущего потока
- mysql_stat() - Возвращает текущий статус сервера

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — Извлекает список таблиц базы данных MySQL

Внимание

Функция устарела в PHP 4.3.0, а в PHP 7.0.0 функцию удалили вместе с модулем MySQL. Вместо этой функции пользуются модулями MySQLi или PDO_MySQL, которые активно развиваются. Смотрите также раздел «MySQL: выбор API». Разработчикам доступны следующие альтернативы:

- SQL запрос: `SHOW TABLES FROM dbname`

### Описание

function mysql_list_tables(string `$database`, resource `$link_identifier` = NULL): resource|false

Функция возвращает список имён таблиц базы данных MySQL.

Функция устарела. Вместо неё рекомендуют использовать функцию mysql_query() с запросом `SHOW TABLES [FROM db_name] [LIKE 'pattern']`.

### Список параметров

`database`
  Имя базы данных.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

В случае успешного выполнения функция возвращает дескриптор результата (resource) или `false`, если возникла ошибка.

Для работы с результатом запроса вызывают функцию mysql_tablename() или другую функцию, которая умеет это делать, например функцию mysql_fetch_array().

### Примеры

Пример #1 Пример извлечения списка таблиц БД MySQL функцией mysql_list_tables()

    <?php

    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Ошибка подключения к mysql';
        exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
        echo "Ошибка базы, не удалось получить список таблиц\n";
        echo 'Ошибка MySQL: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_row($result)) {
        echo "Таблица: {$row[0]}\n";
    }

    mysql_free_result($result);

    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_listtables()

### Смотрите также

- mysql_list_dbs() - Возвращает список баз данных, доступных на сервере
- mysql_tablename() - Возвращает имя таблицы, содержащей указанное поле

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — Возвращает количество полей результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_num_fields()
- PDOStatement::columnCount()

### Описание

function mysql_num_fields(resource `$result`): int|false

Возвращает количество полей в результате запроса.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Возвращает количество полей в результате запроса (resource) в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_num_fields()

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Не удалось выполнить запрос: ' . mysql_error();
        exit;
    }

    /* возвращает 2, так как id,email === двум полям */
    echo mysql_num_fields($result);
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_numfields()

### Смотрите также

- mysql_select_db() - Выбирает базу данных MySQL
- mysql_query() - Посылает запрос MySQL
- mysql_fetch_field() - Возвращает информацию о колонке из результата запроса в виде объекта
- mysql_num_rows() - Возвращает количество рядов результата запроса

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — Возвращает количество рядов результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### Описание

function mysql_num_rows(resource `$result`): int|false

Возвращает количество рядов результата запроса. Эта команда работает только с запросами SELECT или SHOW, возвращающих актуальный результат запроса. Чтобы получить количество рядов, обработанных функциями INSERT, UPDATE, REPLACE и DELETE, используйте функцию mysql_affected_rows().

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().

### Возвращаемые значения

Количество рядов в результате запроса в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_num_rows()

    <?php

    $link = mysql_connect("localhost", "mysql_user", "mysql_password");
    mysql_select_db("database", $link);

    $result = mysql_query("SELECT * FROM table1", $link);
    $num_rows = mysql_num_rows($result);

    echo "Получено $num_rows рядов\n";

    ?>

### Примечания

> Замечание: При использовании mysql_unbuffered_query() функция mysql_num_rows() не вернёт корректного значения до тех пор, пока все ряды не будут получены.

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_numrows()

### Смотрите также

- mysql_affected_rows() - Возвращает число затронутых прошлой операцией рядов
- mysql_connect() - Открывает соединение с сервером MySQL
- mysql_data_seek() - Перемещает внутренний указатель в результате запроса
- mysql_select_db() - Выбирает базу данных MySQL
- mysql_query() - Посылает запрос MySQL

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — Устанавливает постоянное соединение с сервером MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_connect() с `p:` префиксом хоста
- PDO::__construct() с опцией драйвера `PDO::ATTR_PERSISTENT`

### Описание

function mysql_pconnect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
int `$client_flags` = 0
): resource

Устанавливает постоянное соединение с сервером MySQL.

mysql_pconnect() работает аналогично mysql_connect() с двумя важными отличиями.

Во-первых, при соединении функция пытается найти уже открытый (постоянный) указатель на тот же сервер с тем же пользователем и паролем. Если он найден, возвращён функцией будет именно он, вместо открытия нового соединения.

Во-вторых, соединение с SQL-сервером не будет закрыто, когда работа скрипта закончится. Вместо этого, оно останется рабочим для будущего использования (mysql_close() также не закрывает постоянные соединения, открытые mysql_pconnect()).

Соединения такого типа называют 'постоянными'.

### Список параметров

`server`
  Сервер MySQL. Может также включать номер порта, например, "hostname:port" или путь к локальному сокету, например, ":/path/to/socket" для локального хоста. Если директива mysql.default_host не определена (по умолчанию), то по умолчанию используется значение 'localhost:3306'
`username`
  Имя пользователя. По умолчанию используется имя пользователя, владеющего серверным процессом.
`password`
  Пароль. По умолчанию используется пустая строка.
`client_flags`
  Параметр `client_flags` может быть комбинацией следующих констант: 128 (включает обработку `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` и `MYSQL_CLIENT_INTERACTIVE`.

### Возвращаемые значения

Возвращает дескриптор постоянного соединения MySQL в случае успешного выполнения, и `false` в случае возникновения ошибки.

### Примечания

> Замечание: Учтите, что соединения такого типа работают только, если PHP установлен как модуль. За дополнительной информацией обращайтесь к разделу "Постоянные соединения с базами данных".

Внимание

Использование постоянных соединений может потребовать некоторой настройки Apache и MySQL. Убедитесь, что вы не превысите максимальное число дозволенных соединений в MySQL.

### Смотрите также

- mysql_connect() - Открывает соединение с сервером MySQL
- "Постоянные соединения с базами данных"

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Проверяет соединение с сервером и пересоединяется при необходимости

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_ping()

### Описание

function mysql_ping(resource `$link_identifier` = NULL): bool

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

> Замечание: Автоматическое восстановление соединения по умолчанию отключено в версиях MySQL >= 5.0.3.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает `true`, если соединение в рабочем состоянии и `false` в противном случае.

### Примеры

Пример #1 Пример использования mysql_ping()

    <?php
    set_time_limit(0);

    $conn = mysql_connect('localhost', 'mysqluser', 'mypass');
    $db   = mysql_select_db('mydb');

    /* Подразумевается что этот запрос будет выполняться достаточно долго */
    $result = mysql_query($sql);
    if (!$result) {
        echo 'Запрос #1 не удался, выходим.';
        exit;
    }

    /* Проверяем что соединение ещё работает, если нет, соединяемся заново */
    if (!mysql_ping($conn)) {
        echo 'Соединение потеряно, выходим после запроса #1';
        exit;
    }
    mysql_free_result($result);

    /* Соединение ещё работает, выполняем ещё один запрос */
    $result2 = mysql_query($sql2);
    ?>

### Смотрите также

- mysql_thread_id() - Возвращает идентификатор текущего потока
- mysql_list_processes() - Возвращает список процессов MySQL

# mysql_query

(PHP 4, PHP 5)

mysql_query — Посылает запрос MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_query()
- PDO::query()

### Описание

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() посылает один запрос (посылка нескольких запросов не поддерживается) активной базе данных сервера, на который ссылается переданный дескриптор `link_identifier`.

### Список параметров

`query`
  SQL-запрос Запрос не должен заканчиваться точкой с запятой. Данные в запросе должны быть корректно проэкранированы.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Для запросов SELECT, SHOW, DESCRIBE, EXPLAIN и других запросов, возвращающих результат из нескольких рядов, mysql_query() возвращает дескриптор результата запроса (resource), или `false` в случае возникновения ошибки.

Для других типов SQL-запросов, INSERT, UPDATE, DELETE, DROP и других, mysql_query() возвращает `true` в случае успешного выполнения и `false` в случае возникновения ошибки.

Полученный дескриптор результата нужно передать в функцию mysql_fetch_assoc() или любую другую функцию, работающую с результатами запросов.

Используйте mysql_num_rows() для выяснения количества рядов в результате SELECT-запроса или mysql_affected_rows() для выяснения количества обработанных рядов запросами DELETE, INSERT, REPLACE и UPDATE.

mysql_query() также завершится с ошибкой и вернёт `false`, если у пользователя нет доступа к какой-либо из таблиц, фигурирующих в запросе.

### Примеры

Пример #1 Неверный запрос

Следующий запрос составлен неправильно и mysql_query() вернёт `false`.

    <?php
    $result = mysql_query('SELECT * WHERE 1 = 1');
    if (!$result) {
        die('Неверный запрос: ' . mysql_error());
    }

    ?>

Пример #2 Верный запрос

Следующий запрос верен, поэтому mysql_query() вернёт resource.

    <?php
    // Эти данные, к примеру, могли быть получены от пользователя
    $firstname = 'fred';
    $lastname  = 'fox';

    // Формируем запрос
    // Это лучший способ выполнить SQL-запрос
    // Ещё примеры можно найти в документации mysql_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends
        WHERE firstname='%s' AND lastname='%s'",
        mysql_real_escape_string($firstname),
        mysql_real_escape_string($lastname));

    // Выполняем запрос
    $result = mysql_query($query);

    // Проверяем результат
    // Это показывает реальный запрос, посланный к MySQL, а также ошибку. Удобно при отладке.
    if (!$result) {
        $message  = 'Неверный запрос: ' . mysql_error() . "\n";
        $message .= 'Запрос целиком: ' . $query;
        die($message);
    }

    // Используем результат
    // Попытка напечатать $result не выведет информацию, которая в нем хранится
    // Необходимо использовать какую-либо mysql-функцию, работающую с результатом запроса
    // Смотрите также mysql_result(), mysql_fetch_array(), mysql_fetch_row() и т.п.
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Освобождаем ресурсы, ассоциированные с результатом
    // Это делается автоматически в конце скрипта
    mysql_free_result($result);
    ?>

### Смотрите также

- mysql_connect() - Открывает соединение с сервером MySQL
- mysql_error() - Возвращает текст ошибки последней операции с MySQL
- mysql_real_escape_string() - Экранирует специальные символы в строках для использования в выражениях SQL
- mysql_result() - Возвращает данные результата запроса
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_unbuffered_query() - Посылает запрос MySQL без авто-обработки результата и его буферизации

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Экранирует специальные символы в строках для использования в выражениях SQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_real_escape_string()
- PDO::quote()

### Описание

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

Экранирует специальные символы в `unescaped_string`, принимая во внимание кодировку соединения, таким образом, что результат можно безопасно использовать в SQL-запросе в функции mysql_query(). Если вставляются бинарные данные, то к ним так же необходимо применять эту функцию.

mysql_real_escape_string() вызывает библиотечную функцию MySQL mysql_real_escape_string, которая добавляет обратную косую черту к следующим символам: `\x00`, `\n`, `\r`, `\`, `'`, `"` и `\x1a`.

Эта функция должна всегда (за несколькими исключениями) использоваться для того, чтобы обезопасить данные, вставляемые в запрос перед отправкой его в MySQL.

Предостережение

# Безопасность: кодировка символов по умолчанию

Кодировка символов должна устанавливаться как на сервере, так и с помощью функции mysql_set_charset(), чтобы влиять на поведение mysql_real_escape_string(). Подробнее описано в разделе кодировка символов.

### Список параметров

`unescaped_string`
  Экранируемая строка.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает строку, в которой экранированы все необходимые символы, или `false` в случае возникновения ошибки.

### Ошибки

Запуск этой функции без существующего соединения с MySQL вызовет ошибку уровня `E_WARNING`. Данную функцию можно запускать только если есть соединение с MySQL.

### Примеры

Пример #1 Простой пример использования mysql_real_escape_string()

    <?php
    // Соединение
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        OR die(mysql_error());

    // Запрос
    $query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
                mysql_real_escape_string($user),
                mysql_real_escape_string($password));
    ?>

Пример #2 Пример использования mysql_real_escape_string() без наличия соединения

Этот пример показывает, что произойдёт, если вызвать эту функцию без наличия соединения с MySQL.

    <?php
    // Коннекта к MySQL нет

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

Вывод приведённого примера будет похож на:

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

Пример #3 Пример взлома с использованием SQL-инъекции

    <?php
    // Мы никак не проверили переменную $_POST['password'],
    // а она может содержать совсем не то, что мы ожидали. Например:
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // посылаем запрос, чтобы проверить имя и пароль пользователя
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // посмотрим, какой запрос будет отправлен в MySQL:
    echo $query;
    ?>

Запрос, который будет отправлен в MySQL:

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

Это позволит кому угодно войти в систему без пароля.

### Примечания

> Замечание: Функцию mysql_real_escape_string() можно использовать только после того, как установлено соединение с MySQL. В противном случае возникнет ошибка уровня `E_WARNING`, а функция возвратит `false`. Если `link_identifier` не указан, используется последнее открытое соединение.

> Замечание: Если не пользоваться этой функцией, то запрос становится уязвимым для взлома с помощью SQL-инъекций.

> Замечание: mysql_real_escape_string() не экранирует символы `%` и `_`. Эти знаки являются масками групп символов в операторах MySQL `LIKE`, `GRANT` и `REVOKE`.

### Смотрите также

- mysql_set_charset() - Устанавливает кодировку клиента
- mysql_client_encoding() - Возвращает кодировку соединения

# mysql_result

(PHP 4, PHP 5)

mysql_result — Возвращает данные результата запроса

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_data_seek() в связке с mysqli_field_seek() и mysqli_fetch_field()
- PDOStatement::fetchColumn()

### Описание

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Возвращает содержимое одного поля из набора результата MySQL.

Работая с большими результатами запросов, следует использовать одну из функций, обрабатывающих сразу целый ряд результата (указаны ниже). Так как эти функции возвращают значение нескольких ячеек сразу, они НАМНОГО быстрее mysql_result(). Кроме того, учтите, что указание численного смещения работает намного быстрее, чем указание колонки, или колонки с таблицей через точку.

### Список параметров

`result`
  Обрабатываемый результат запроса. Этот результат может быть получен с помощью функции mysql_query().
`row`
  Номер получаемого ряда из результата. Нумерация рядов начинается с `0`.
`field`
  Имя или смещение получаемого поля. Может быть как смещением поля, именем поля, так и именем поля вместе с таблицей (таблица.поле). Если для поля был указан псевдоним ('select foo as bar from...'), используйте его вместо имени самого поля. Если не указан, возвращается первое поле.

### Возвращаемые значения

Содержимое одного поля из набора результата MySQL в случае успешного выполнения, или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования mysql_result()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Ошибка соединения: ' . mysql_error());
    }
    if (!mysql_select_db('database_name')) {
        die('Ошибка выбора базы данных: ' . mysql_error());
    }
    $result = mysql_query('SELECT name FROM work.employee');
    if (!$result) {
        die('Ошибка выполнения запроса:' . mysql_error());
    }
    echo mysql_result($result, 2); // выведет имя третьего сотрудника

    mysql_close($link);
    ?>

### Примечания

> Замечание: Вызовы функции mysql_result() не должны смешиваться с другими функциями, работающими с результатом запроса.

### Смотрите также

- mysql_fetch_row() - Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_fetch_array() - Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_fetch_assoc() - Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_fetch_object() - Обрабатывает ряд результата запроса и возвращает объект

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — Выбирает базу данных MySQL

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_select_db()
- PDO::__construct() (раздел о dsn)

### Описание

function mysql_select_db(string `$database_name`, resource `$link_identifier` = NULL): bool

Выбирает для работы указанную базу данных на сервере, на который ссылается переданный дескриптор соединения. Каждый последующий вызов функции mysql_query() будет работать с выбранной базой данных.

### Список параметров

`database_name`
  Имя выбираемой базы данных.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_select_db()

    <?php

    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Не удалось соединиться : ' . mysql_error());
    }

    // выбираем foo в качестве текущей базы данных
    $db_selected = mysql_select_db('foo', $link);
    if (!$db_selected) {
        die ('Не удалось выбрать базу foo: ' . mysql_error());
    }
    ?>

### Примечания

> Замечание: Для обратной совместимости может быть использован следующий устаревший псевдоним: mysql_selectdb()

### Смотрите также

- mysql_connect() - Открывает соединение с сервером MySQL
- mysql_pconnect() - Устанавливает постоянное соединение с сервером MySQL
- mysql_query() - Посылает запрос MySQL

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — Устанавливает кодировку клиента

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_set_charset()
- PDO: Добавлением `charset` в строку соединения, например `charset=utf8`

### Описание

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

Устанавливает кодировку по умолчанию для текущего соединения.

### Список параметров

`charset`
  Корректное название кодировки.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание: Данная функция требует MySQL версии 5.0.7 или выше.

> Замечание: Это наиболее предпочитаемый способ для смены кодировки. Использование mysql_query() в этих целях (например `SET NAMES utf8`) не рекомендуется. Смотрите раздел кодировка символов в MySQL для подробной информации.

### Смотрите также

- Настройка кодировок символов в MySQL
- » Список поддерживаемых MySQL кодировок
- mysql_client_encoding() - Возвращает кодировку соединения

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — Возвращает текущий статус сервера

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_stat()
- PDO::getAttribute() с параметром `attribute` заданным как `PDO::ATTR_SERVER_INFO`

### Описание

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() возвращает текущий статус сервера.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Возвращает строку с данными аптайма, количества потоков, запросов, количеством открытых таблиц и таблиц с сброшенным внутренним кешем (flush tables), а также количество запросов в секунду. Для получения полного списка других переменных вам необходимо будет использовать SQL-запрос `SHOW STATUS`. Если передан некорректный `link_identifier`, то будет возвращён `null`.

### Примеры

Пример #1 Пример использования mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $status = explode('  ', mysql_stat($link));
    print_r($status);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Uptime: 5380
        [1] => Threads: 2
        [2] => Questions: 1321299
        [3] => Slow queries: 0
        [4] => Opens: 26
        [5] => Flush tables: 1
        [6] => Open tables: 17
        [7] => Queries per second avg: 245.595
    )

Пример #2 Альтернативный пример использования mysql_stat()

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $result = mysql_query('SHOW STATUS', $link);
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
    }
    ?>

Вывод приведённого примера будет похож на:

    back_log = 50
    basedir = /usr/local/
    bdb_cache_size = 8388600
    bdb_log_buffer_size = 32768
    bdb_home = /var/db/mysql/
    bdb_max_lock = 10000
    bdb_logdir =
    bdb_shared_data = OFF
    bdb_tmpdir = /var/tmp/
    ...

### Смотрите также

- mysql_get_server_info() - Возвращает информацию о сервере MySQL
- mysql_list_processes() - Возвращает список процессов MySQL

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — Возвращает имя таблицы, содержащей указанное поле

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- SQL запрос: `SHOW TABLES`

### Описание

function mysql_tablename(resource `$result`, int `$i`): string|false

Возвращает имя таблицы из `result`.

Данная функция устарела. Вместо неё рекомендуется использование mysql_query() с SQL-запросом `SHOW TABLES [FROM db_name] [LIKE 'pattern']`.

### Список параметров

`result`
  Дескриптор результата типа resource, полученный из вызова mysql_list_tables().
`i`
  Целочисленный индекс (номер ряда/таблицы)

### Возвращаемые значения

Имя таблицы в случае успешного выполнения или `false`, если возникла ошибка.

Используйте функцию mysql_tablename() для работы с результатом запроса, либо любую другую функцию, способную это делать, например, mysql_fetch_array().

### Примеры

Пример #1 Пример использования mysql_tablename()

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password");
    $result = mysql_list_tables("mydb");
    $num_rows = mysql_num_rows($result);
    for ($i = 0; $i < $num_rows; $i++) {
        echo "Table: ", mysql_tablename($result, $i), "\n";
    }

    mysql_free_result($result);
    ?>

### Примечания

> Замечание: Для определения количества таблиц в результате запроса можно использовать функцию mysql_num_rows().

### Смотрите также

- mysql_list_tables() - Извлекает список таблиц базы данных MySQL
- mysql_field_table() - Возвращает название таблицы, которой принадлежит указанное поле
- mysql_db_name() - Возвращает название базы данных из вызова к mysql_list_dbs

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — Возвращает идентификатор текущего потока

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- mysqli_thread_id()

### Описание

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

mysql_thread_id() возвращает идентификатор текущего потока. Если соединение потеряно и вы пересоединились с помощью mysql_ping(), то идентификатор потока изменится. Это означает, что вам не следует получать данный идентификатор и хранить его для дальнейшего использования. Вызывайте функцию тогда, когда он вам нужен.

### Список параметров

`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Идентификатор потока в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования mysql_thread_id()

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $thread_id = mysql_thread_id($link);
    if ($thread_id){
        printf("Идентификатор текущего потока: %d\n", $thread_id);
    }
    ?>

Вывод приведённого примера будет похож на:

    Идентификатор текущего потока: 73

### Смотрите также

- mysql_ping() - Проверяет соединение с сервером и пересоединяется при необходимости
- mysql_list_processes() - Возвращает список процессов MySQL

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — Посылает запрос MySQL без авто-обработки результата и его буферизации

Внимание

Данный модуль устарел начиная с версии PHP 5.5.0, и удалён в PHP 7.0.0. Используйте вместо него MySQLi или PDO_MySQL. Смотрите также инструкцию MySQL: выбор API. Альтернативы для этой функции:

- See: Буферизованные и не буферизованные запросы

### Описание

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() посылает запрос MySQL `query` без автоматической обработки и буферизации её результата, в отличие от функции mysql_query(). Это позволяет сохранить достаточно большое количество памяти для SQL-запросов, возвращающих большое количество данных. Кроме того, вы можете начать работу с полученными данными сразу после того, как первый ряд был получен: вам не приходится ждать до конца SQL-запроса. При использовании mysql_unbuffered_query() с несколькими соединениями MySQL, вы должны указать необязательный параметр `link_identifier`.

### Список параметров

`query`
  Запускаемый SQL-запрос. Данные в запросе должны быть корректно проэкранированы.
`link_identifier`
  Соединение MySQL. Если идентификатор соединения не был указан, будет использовано последнее соединение, открытое mysql_connect(). Если такое соединение не было найдено, функция попытается создать таковое, как если бы mysql_connect() была вызвана без параметров. Если соединение не было найдено и не смогло быть создано, генерируется ошибка уровня `E_WARNING`.

### Возвращаемые значения

Для SELECT, SHOW, DESCRIBE и EXPLAIN запросов mysql_unbuffered_query() возвращает resource в случае успешного выполнения, или `false` в случае возникновения ошибки.

Для остальных типов SQL-запросов, UPDATE, DELETE, DROP и т.д., mysql_unbuffered_query() возвращает `true` в случае успеха и `false` в случае возникновения ошибки.

### Примечания

> Замечание: Однако, плюсы использования mysql_unbuffered_query() имеют свою цену: вы не можете использовать функции mysql_num_rows() и mysql_data_seek() с результатом запроса, возвращённым этой функцией, пока не будут получены все ряды. Кроме того, вы должны будете обработать все ряды запроса до отправки нового запроса, используя тот же `link_identifier`.

### Смотрите также

- mysql_query() - Посылает запрос MySQL

## Содержание

- mysql_affected_rows — Возвращает число затронутых прошлой операцией рядов
- mysql_client_encoding — Возвращает кодировку соединения
- mysql_close — Закрывает соединение с сервером MySQL
- mysql_connect — Открывает соединение с сервером MySQL
- mysql_create_db — Создаёт базу данных MySQL
- mysql_data_seek — Перемещает внутренний указатель в результате запроса
- mysql_db_name — Возвращает название базы данных из вызова к mysql_list_dbs
- mysql_db_query — Переключается на указанную базу данных и посылает запрос
- mysql_drop_db — Уничтожает базу данных MySQL
- mysql_errno — Возвращает численный код ошибки выполнения последней операции с MySQL
- mysql_error — Возвращает текст ошибки последней операции с MySQL
- mysql_escape_string — Экранирует строку для использования в mysql_query
- mysql_fetch_array — Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
- mysql_fetch_assoc — Возвращает ряд результата запроса в качестве ассоциативного массива
- mysql_fetch_field — Возвращает информацию о колонке из результата запроса в виде объекта
- mysql_fetch_lengths — Возвращает длину каждого поля в результате
- mysql_fetch_object — Обрабатывает ряд результата запроса и возвращает объект
- mysql_fetch_row — Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
- mysql_field_flags — Возвращает флаги, связанные с указанным полем результата запроса
- mysql_field_len — Возвращает длину указанного поля
- mysql_field_name — Возвращает название указанной колонки результата запроса
- mysql_field_seek — Устанавливает внутренний указатель результата на переданное смещение поля
- mysql_field_table — Возвращает название таблицы, которой принадлежит указанное поле
- mysql_field_type — Возвращает тип указанного поля из результата запроса
- mysql_free_result — Освобождает память от результата запроса
- mysql_get_client_info — Возвращает данные о MySQL-клиенте
- mysql_get_host_info — Возвращает информацию о соединении с MySQL
- mysql_get_proto_info — Возвращает информацию о протоколе MySQL
- mysql_get_server_info — Возвращает информацию о сервере MySQL
- mysql_info — Возвращает информацию о последнем запросе
- mysql_insert_id — Возвращает идентификатор, сгенерированный при последнем INSERT-запросе
- mysql_list_dbs — Возвращает список баз данных, доступных на сервере
- mysql_list_fields — Возвращает список колонок таблицы
- mysql_list_processes — Возвращает список процессов MySQL
- mysql_list_tables — Извлекает список таблиц базы данных MySQL
- mysql_num_fields — Возвращает количество полей результата запроса
- mysql_num_rows — Возвращает количество рядов результата запроса
- mysql_pconnect — Устанавливает постоянное соединение с сервером MySQL
- mysql_ping — Проверяет соединение с сервером и пересоединяется при необходимости
- mysql_query — Посылает запрос MySQL
- mysql_real_escape_string — Экранирует специальные символы в строках для использования в выражениях SQL
- mysql_result — Возвращает данные результата запроса
- mysql_select_db — Выбирает базу данных MySQL
- mysql_set_charset — Устанавливает кодировку клиента
- mysql_stat — Возвращает текущий статус сервера
- mysql_tablename — Возвращает имя таблицы, содержащей указанное поле
- mysql_thread_id — Возвращает идентификатор текущего потока
- mysql_unbuffered_query — Посылает запрос MySQL без авто-обработки результата и его буферизации

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Список изменений
- Предопределённые константы
- Примеры
  - Обзорный пример модуля MySQL
- MySQL — Функции СУБД MySQL
  - mysql_affected_rows — Возвращает число затронутых прошлой операцией рядов
  - mysql_client_encoding — Возвращает кодировку соединения
  - mysql_close — Закрывает соединение с сервером MySQL
  - mysql_connect — Открывает соединение с сервером MySQL
  - mysql_create_db — Создаёт базу данных MySQL
  - mysql_data_seek — Перемещает внутренний указатель в результате запроса
  - mysql_db_name — Возвращает название базы данных из вызова к mysql_list_dbs
  - mysql_db_query — Переключается на указанную базу данных и посылает запрос
  - mysql_drop_db — Уничтожает базу данных MySQL
  - mysql_errno — Возвращает численный код ошибки выполнения последней операции с MySQL
  - mysql_error — Возвращает текст ошибки последней операции с MySQL
  - mysql_escape_string — Экранирует строку для использования в mysql_query
  - mysql_fetch_array — Обрабатывает ряд результата запроса, возвращая ассоциативный массив, численный массив или оба
  - mysql_fetch_assoc — Возвращает ряд результата запроса в качестве ассоциативного массива
  - mysql_fetch_field — Возвращает информацию о колонке из результата запроса в виде объекта
  - mysql_fetch_lengths — Возвращает длину каждого поля в результате
  - mysql_fetch_object — Обрабатывает ряд результата запроса и возвращает объект
  - mysql_fetch_row — Обрабатывает ряд результата запроса и возвращает массив с числовыми индексами
  - mysql_field_flags — Возвращает флаги, связанные с указанным полем результата запроса
  - mysql_field_len — Возвращает длину указанного поля
  - mysql_field_name — Возвращает название указанной колонки результата запроса
  - mysql_field_seek — Устанавливает внутренний указатель результата на переданное смещение поля
  - mysql_field_table — Возвращает название таблицы, которой принадлежит указанное поле
  - mysql_field_type — Возвращает тип указанного поля из результата запроса
  - mysql_free_result — Освобождает память от результата запроса
  - mysql_get_client_info — Возвращает данные о MySQL-клиенте
  - mysql_get_host_info — Возвращает информацию о соединении с MySQL
  - mysql_get_proto_info — Возвращает информацию о протоколе MySQL
  - mysql_get_server_info — Возвращает информацию о сервере MySQL
  - mysql_info — Возвращает информацию о последнем запросе
  - mysql_insert_id — Возвращает идентификатор, сгенерированный при последнем INSERT-запросе
  - mysql_list_dbs — Возвращает список баз данных, доступных на сервере
  - mysql_list_fields — Возвращает список колонок таблицы
  - mysql_list_processes — Возвращает список процессов MySQL
  - mysql_list_tables — Извлекает список таблиц базы данных MySQL
  - mysql_num_fields — Возвращает количество полей результата запроса
  - mysql_num_rows — Возвращает количество рядов результата запроса
  - mysql_pconnect — Устанавливает постоянное соединение с сервером MySQL
  - mysql_ping — Проверяет соединение с сервером и пересоединяется при необходимости
  - mysql_query — Посылает запрос MySQL
  - mysql_real_escape_string — Экранирует специальные символы в строках для использования в выражениях SQL
  - mysql_result — Возвращает данные результата запроса
  - mysql_select_db — Выбирает базу данных MySQL
  - mysql_set_charset — Устанавливает кодировку клиента
  - mysql_stat — Возвращает текущий статус сервера
  - mysql_tablename — Возвращает имя таблицы, содержащей указанное поле
  - mysql_thread_id — Возвращает идентификатор текущего потока
  - mysql_unbuffered_query — Посылает запрос MySQL без авто-обработки результата и его буферизации

# Встроенный драйвер MySQL

# Введение

MySQL Native Driver — драйвер, который включили в состав PHP как замену MySQL Client Library — клиентской MySQL-библиотеки libmysqlclient. MySQL Native Driver стал частью официальных исходных кодов PHP начиная с PHP 5.3.0.

PHP-модули для работы с базами данных MySQL — MySQL Original, `mysqli` и PDO — взаимодействуют с MySQL-сервером. В прошлом с MySQL-серверами взаимодействовали через модули, которые работали через библиотеку MySQL Client Library. Модули компилировались с библиотекой MySQL Client Library, чтобы взаимодействовать с серверами баз данных по клиент-серверному протоколу MySQL, который предоставляет библиотека.

С выпуском MySQL Native Driver появилась альтернатива, поскольку модули для работы с базами данных MySQL теперь компилируются для работы на основе встроенного драйвера MySQL Native Driver, а не внешней библиотеки MySQL Client Library.

Драйвер MySQL Native Driver написан на языке C как низкоуровневое PHP-расширение, на основе которого работают модули для взаимодействия с серверами баз данных MySQL.

# Обзор

Чем он не является

Хотя встроенный драйвер MySQL написан как модуль PHP, важно понимать, что он не предоставляет программисту PHP нового API. API к базе данных MySQL для программиста предоставляются модулями MySQL, `mysqli` и PDO MYSQL. Эти модули могут использовать возможности встроенного драйвера MySQL для общения с сервером MySQL. Таким образом, вы не должны думать о встроенном драйвере MySQL как об API.

Зачем его использовать?

Использование встроенного драйвера MySQL даёт некоторые плюсы относительно клиентской библиотеки MySQL.

Более старая клиентская библиотека MySQL была написана MySQL AB (сейчас Oracle Corporation) и выпускалась под лицензией MySQL. В конечном итоге это привело к тому, что поддержка MySQL в PHP была по умолчанию выключена. С другой стороны, встроенный драйвер MySQL был разработан как часть проекта PHP, и выпущен под лицензией PHP. Это снимает вопросы с лицензированием, бывшие проблемными в прошлом.

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

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

> Замечание: Контроль использования памяти
> Так как встроенный драйвер MySQL использует систему контроля памяти PHP, используемая им память может быть отслежена с помощью функции memory_get_usage(). Это нельзя сделать с помощью libmysqlclient, так как он использует функцию языка Си malloc().

Особые возможности

Встроенный драйвер MySQL также предоставляет некоторые особые возможности, недоступные при использовании расширениями клиентской библиотеки MySQL. Список этих возможностей приведён ниже:

- Улучшены постоянные соединения
- Особая функция mysqli_fetch_all()
- Вызов статистики производительности: mysqli_get_client_stats(), mysqli_get_connection_stats()

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

Встроенный драйвер MySQL также поддерживает постоянные соединения при использовании модуля `mysqli`.

Поддержка SSL

Встроенный драйвер MySQL поддерживает SSL.

Поддержка протокола с использованием сжатия

Встроенный драйвер MySQL поддерживает клиент-серверный протокол с использованием сжатия. Модули, например, `ext/mysql` или `ext/mysqli`, настроенные на использование встроенного драйвера MySQL, могут также воспользоваться этой возможностью. Обратите внимание, что `PDO_MYSQL` НЕ поддерживает сжатие при использовании совместно с mysqlnd.

Поддержка именованных каналов

Именованные каналы можно использовать для подключения в средах Windows.

# Установка

Установка в ОС Unix

Для работы со встроенным в БД MySQL драйвером при сборке PHP потребуется указать, что PHP-модули для работы с базой данных скомпилировали с поддержкой нативного драйвера MySQL. MySQL-драйвер, с которым будут взаимодействовать PHP-модули, определяют параметрами конфигурации перед сборкой PHP из исходного кода.

Следующая команда помогает собрать MySQL-модули `mysqli` и PDO MYSQL с поддержкой встроенного в MySQL драйвера:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [other options]

Установка в ОС Windows

В официальных Windows-дистрибутивах встроенный драйвер MySQL включён по умолчанию и поэтому работает без дополнительных настроек. В ОС Windows PHP-модули для работы с базой данных MySQL будут взаимодействовать со встроенным в MySQL драйвером.

Поддержка плагина аутентификации SHA-256

Для взаимодействия со встроенным драйвером MySQL требуется загрузить и включить поддержку функций PHP-модуля OpenSSL, чтобы подключаться к базе данных MySQL через учётные записи, пароли которых хранятся в зашифрованном виде и поддержку которых даёт MySQL-плагин аутентификации, который хеширует пароли по протоколу SHA-256. Пример настройки PHP, которая включит модуль OpenSSL в сборку:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [other options]

В инструменте автоконфигурации Autotools расширенная поддержка SSL-протокола в драйвере `mysqlnd` включается автоматически, если PHP собрали с параметром конфигурации --with-openssl, который включает модуль `openssl` в PHP-сборку. При сборке PHP без модуля `openssl` расширенную поддержку SSL-протокола включают вручную параметром конфигурации --with-mysqlnd-ssl.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавили Autotools-опцию конфигурации --with-mysqlnd-ssl, которая явно включает расширенную поддержку SSL-протокола при сборке PHP без модуля `openssl`.

# Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации встроенного драйвера MySQL
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mysqlnd.collect_statistics | "1" | `INI_SYSTEM` |
mysqlnd.collect_memory_statistics | "0" | `INI_SYSTEM` |
mysqlnd.debug | "" | `INI_SYSTEM` |
mysqlnd.log_mask | 0 | `INI_ALL` |
mysqlnd.mempool_default_size | 16000 | `INI_ALL` |
mysqlnd.net_read_timeout | "86400" | `INI_ALL` | До PHP 7.2.0 значением по умолчанию "31536000", а местом изменения было `INI_SYSTEM`
mysqlnd.net_cmd_buffer_size | 5.3.0 — "2048", 5.3.1 — "4096" | `INI_SYSTEM` |
mysqlnd.net_read_buffer_size | "32768" | `INI_SYSTEM` |
mysqlnd.sha256_server_public_key | "" | `INI_PERDIR` |
mysqlnd.trace_alloc | "" | `INI_SYSTEM` |
mysqlnd.fetch_data_copy | 0 | `INI_ALL` | Удалено с PHP 8.1.0

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`mysqlnd.collect_statistics` bool
  Включает сбор различной статистики клиента, доступ к которой можно получить с помощью mysqli_get_client_stats(), mysqli_get_connection_stats(), и которая отображается в разделе `mysqlnd` вывода функции phpinfo(). Этот параметр конфигурации включает всю статистику встроенного драйвера MySQL, кроме относящейся к работе с оперативной памятью.
`mysqlnd.collect_memory_statistics` bool
  Включает сбор различной статистики оперативной памяти, доступ к которой можно получить с помощью mysqli_get_client_stats(), mysqli_get_connection_stats(), и которая отображается в разделе `mysqlnd` вывода функции phpinfo(). Этот параметр конфигурации включает всю статистику, относящуюся к работе с оперативной памятью, в общий набор данных статистики встроенного драйвера MySQL.
`mysqlnd.debug` string
  Записывает команды из всех модулей, использующих `mysqlnd`, в указанный файл с логами. Формат параметра следующий: `mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"`. Возможны нижеуказанные значения для строки форматирования:
  - A[,file] - добавляет вывод трассировки в указанный файл. Также каждый раз проверяет успешность записи данных. Это реализовано путём закрытия и повторного открытия файла (что достаточно медленно). Даёт гарантию целостности файла с логами в случае возникновения ошибки приложения.
  - a[,file] - добавляет вывод трассировки в указанный файл.
  - d - Включает вывод из макроса DBUG_<N> для текущего состояния. Может быть дополнено списком ключевых слов, чтобы выбрать вывод только содержащего эти ключевые слова макросов DBUG. Пустой список ключевых слов подразумевает вывод всех для макросов.
  - f[,functions] - ограничивает действия отладчика указанным списком функций. Пустой список функций подразумевает выбор всех функций.
  - F - помечает вывод каждой строчки отладчика названием исходного файла, содержащего код, вызвавший вывод.
  - i - помечает вывод каждой строчки отладчика PID текущего процесса.
  - L - помечает вывод каждой строчки отладчика названием исходного файла, вызвавшего вывод, и номером строки в ней.
  - n - помечает вывод каждой строчки отладчика уровнем вложенности текущей функции.
  - o[,file] - сходно с a[,file], но перезаписывает старый файл, а не дописывает его.
  - O[,file] - сходно с A[,file] но перезаписывает старый файл, а не дописывает его.
  - t[,N] - включает контроль функций во время трассировки. Максимальный уровень вложенности определён N и по умолчанию равен 200.
  - x - этот параметр активирует профилирование.
  - m - отслеживать вызовы, связанные с выделениями и высвобождением памяти.
  Пример:

      d:t:x:O,/tmp/mysqlnd.trace

  > Замечание: Функция доступна только в отладочной сборке PHP.

`mysqlnd.log_mask` int
  Определяет, какие запросы будут журналироваться. Значение по умолчанию - 0, что отключает журналирование. Значение параметра - только целое число, константы PHP использовать нельзя. Например, при значении 48 (16 + 32) в журнал будут записываться медленные запросы, которые либо используют неподходящие индексы (SERVER_QUERY_NO_GOOD_INDEX_USED = 16), либо не используют их вообще SERVER_QUERY_NO_INDEX_USED = 32). При значении 2043 (1 + 2 + 8 + ... + 1024) в журнал будут записываться все типы медленных запросов. Используются следующие типы запросов: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, and SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Default size of the mysqlnd memory pool, which is used by result sets.
`mysqlnd.net_read_timeout` int
  `mysqlnd` и клиентская библиотека MySQL, `libmysqlclient`, используют разные сетевые API. `mysqlnd` использует потоки PHP, тогда как `libmysqlclient` - собственную обёртку над сетевыми вызовами операционной системы. В PHP по умолчанию выставлено 60-секундное время ожидания потоков. Этот параметр выставляется в php.ini директивой `default_socket_timeout`. По умолчанию это относится ко всем потокам, которым не установлено другое значение времени ожидания. `mysqlnd` не устанавливал других значений, поэтому подключения долго выполняющихся запросов могут быть отключены после `default_socket_timeout` секунд с ошибкой 2006 - MySQL Server has gone away. Клиентская библиотека MySQL устанавливает время ожидания по умолчанию равное 24 * 3600 секундам (1 день) и ждёт возникновения другого времени ожидания, такого как время ожидания TCP/IP. Теперь `mysqlnd` использует такой же очень долгое время ожидания. Это значение можно изменить через новую директиву php.ini - `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` будет использоваться любым модулем (`ext/mysql`, `ext/mysqli`, `PDO_MySQL`), использующим `mysqlnd`. `mysqlnd` указывает потокам PHP использовать `mysqlnd.net_read_timeout`. Пожалуйста, обратите внимание, что могут быть небольшие различия между `MYSQL_OPT_READ_TIMEOUT` в клиентской библиотеке MySQL и потоках PHP, например, судя по документации, `MYSQL_OPT_READ_TIMEOUT` работает только для TCP/IP-подключений и, вплоть до MySQL 5.1.2, только под Windows. Потоки PHP могут не иметь подобных ограничений. В случае сомнений просьба сверяться с документацией потоков.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` резервирует внутренний командно-сетевой буфер размером `mysqlnd.net_cmd_buffer_size` (в php.ini) байт для каждого соединения. Если команда клиент-серверного протокола MySQL, например, `COM_QUERY` (обычный запрос), не умещается в буфер, `mysqlnd` увеличит буфер до размера, необходимого для отправки команды. Каждый раз, когда буфер был увеличен, переменная статистики `command_buffer_too_small` будет увеличена на один. Если `mysqlnd` приходится увеличивать буфер сверх его заданного размера в `mysqlnd.net_cmd_buffer_size` байт для большинства соединений, вам следует обдумать необходимость увеличения размера по умолчанию, чтобы избежать повторных резерваций буфера. Размер буфера по умолчанию составляет 4096 байт, что является наименьшим возможным значением. Это значение также может быть установлено функцией `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)`.
`mysqlnd.net_read_buffer_size` int
  Максимальный размер части данных при считывании, в байтах, при обработке тела командного пакета MySQL. Клиент-серверный протокол MySQL оборачивает все свои команды в пакеты. Пакет состоит из небольшого заголовка и тела, содержащего непосредственно данные команды. Размер тела закодирован в заголовке. `mysqlnd` считывает тело частями по `MIN(header.size, mysqlnd.net_read_buffer_size)` байт. Если размер тела пакета больше, чем `mysqlnd.net_read_buffer_size` байт, `mysqlnd` будет вызывать `read()` несколько раз. Это значение также может быть установлено функцией `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)`.
`mysqlnd.sha256_server_public_key` string
  Данная опция относится к плагину аутентификации SHA-256 и содержит путь к файлу с публичным ключом RSA MySQL-сервера.. Клиент может как не указывать публичный ключ RSA, указать его с помощью данной опции, либо установить ключ во время выполнения с помощью функции mysqli_options(). Если публичный ключ RSA не был передан клиентом, то ключ будет получен в результате стандартной процедуры аутентификации плагина аутентификации SHA-256.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Принуждает копировать наборы из внутреннего буфера наборов в PHP переменные вместо использования логики с ссылками и "копированием при записи" по умолчанию. Смотрите реализация управления памятью для получения большей информации. Копирование результирующих наборов вместо PHP переменных ссылающихся на них позволяют выделять память для PHP переменных заранее. В зависимости от пользовательского кода, реальных запросов к базе данных и размеров их результатов, можно снизить потребление памяти mysqlnd. Не применяйте, если используется PDO_MySQL. В PDO_MySQL ещё не добавлена поддержка этого нового режима.

  > Замечание: Удалено с PHP 8.1.0

# Несовместимости

Встроенный драйвер MySQL (mysqlnd), в большинстве случаев, совместим с клиентской библиотекой MySQL `libmysql`. Этот раздел описывает несовместимости между этими библиотеками.

- Значения в полях данных типа `bit` в библиотеке `libmysql` возвращаются как бинарные строки (например, "\0" или "\x1F"), а в библиотеке `mysqlnd` - как десятичные строки (например, "0" или "31"). Если необходимо, чтобы код был совместим с обеими библиотеками, то всегда из MySQL возвращайте данные из полей типа `bit` в виде чисел, используя подобный запрос: `SELECT bit + 0 FROM table`.

# Постоянное соединение

Использование постоянных соединений

Если `mysqli` используется с `mysqlnd`,\ при создании постоянного соединения оно генерирует на сервере запрос `COM_CHANGE_USER` (`mysql_change_user()`). Это гарантирует, что при подключении будет повторно произведена авторизация.

Поскольку из-за вызовов `COM_CHANGE_USER` увеличиваются накладные расходы, возможно отключить такое поведение во время компиляции. В таком случае повторное использование постоянного соединения будет генерировать вызов `COM_PING` (`mysql_ping`), для проверки возможности повторного использования соединения.

Генерация вызова `COM_CHANGE_USER` может быть отключена флагом компиляции `MYSQLI_NO_CHANGE_USER_ON_PCONNECT`. Например:

    shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

Или альтернативный вариант:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Обратите внимание, что только `mysqli` совместно с `mysqlnd` используют `COM_CHANGE_USER`. Остальные комбинации модуль-драйвер используют `COM_PING` при первоначальном использовании постоянного соединения.

# Статистика

MySQL Native Driver поддерживает сбор статистики по взаимодействию клиента с сервером. Статистические данные собираются с двух основных точек:

- Клиентская статистика
- Статистика соединения

При работе с модулем mysqli эти статистические данные получают через два API-вызова:

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> Замечание: Статистика агрегируется по всем расширениям, которые работают через драйвер MySQL Native Driver. Например, при настройке модуля mysqli и MySQL-драйвера модуля PDO на работу с драйвером MySQLnd вызовы функций модуля mysqli и вызовы методов класса PDO влияют на статистику. Невозможно узнать, насколько конкретный API-вызов модуля, который скомпилировали с драйвером MySQL Native Driver, повлиял на конкретную статистику.

## Получение статистики

Клиентскую статистику получают через вызов функции mysqli_get_client_stats().

Статистику соединения получают через вызов функции mysqli_get_connection_stats().

Обе функции возвращают ассоциативный массив, в котором метрики статистики — ключи, которые соответствуют статистическим данным.

## Статистика драйвера MySQL Native Driver

Бо́льшая часть статистических данных связана с подключением, но отдельные данные связаны с процессом, и тогда это упоминается.

Следующая статистика выдается драйвером MySQL Native Driver:

Сетевая статистика
`bytes_sent`
  Количество байтов, которые PHP отправил MySQL-серверу.
`bytes_received`
  Количество байтов, которые PHP получил от MySQL-сервера.
`packets_sent`
  Количество пакетов, которые отправили по протоколу MySQL Client Server.
`packets_received`
  Количество пакетов, которые получили по протоколу MySQL Client Server.
`protocol_overhead_in`
  Накладные расходы протокола MySQL Client Server в байтах для входящего трафика. Пока накладными расходами признаётся только заголовок Packet Header (4 байта). `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  Накладные расходы протокола MySQL Client Server в байтах для исходящего трафика. Пока накладными расходами признаётся только заголовок Packet Header (4 байта). `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  Общий размер пакетов OK в байтах, которые драйвер получил по протоколу MySQL Client Server. Пакеты OK иногда содержат сообщение о статусе. Длина сообщения о статусе варьируется, поэтому размер пакета OK не фиксирован.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_ok`
  Количество полученных пакетов OK протокола MySQL Client Server.
`bytes_received_eof_packet`
  Общий размер пакетов EOF в байтах, которые драйвер получил по протоколу MySQL Client Server. Размер пакетов EOF варьируется и зависит от версии сервера. При ошибке в EOF-пакете также передаётся сообщение об ошибке.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_eof`
  Количество пакетов EOF протокола MySQL Client Server. Как и в случае с другой статистикой пакетов, количество пакетов будет увеличиваться, даже если PHP получит не ожидаемый пакет, а, например, сообщение об ошибке.
`bytes_received_rset_header_packet`
  Общий размер результирующего набора пакетов заголовков протокола MySQL Client Server в байтах. Размер пакетов варьируется в зависимости от полезной нагрузки (инструкции `LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, сообщение об ошибке).

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_rset_header`
  Количество пакетов заголовков результирующего набора протокола MySQL Client Server.
`bytes_received_rset_field_meta_packet`
  Общий размер пакетов метаданных (информации о столбце) результирующего набора протокола MySQL Client Server в байтах. Конечно, размер зависит от столбцов в наборе результатов. При выполнении команды COM_LIST_FIELDS вместо пакета с метаданными передаётся пакет с ошибкой или EOF-пакет.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_rset_field_meta`
  Количество пакетов метаданных (информации о столбце) результирующего набора протокола MySQL Client Server.
`bytes_received_rset_row_packet`
  Общий размер пакетов данных строки результирующего набора протокола MySQL Client Server в байтах. Пакет также может передавать ошибку или пакет EOF. Количество ошибок и пакетов EOF вычисляют путём вычитания метрик `rows_fetched_from_server_normal` и `rows_fetched_from_server_ps` из метрики `bytes_received_rset_row_packet`.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_rset_row`
  Количество пакетов данных строки результирующего набора протокола MySQL Client Server.
`bytes_received_prepare_response_packet`
  Общий размер пакетов OK протокола MySQL Client Server для инициализации подготовленного запроса (init-пакеты подготовленного запроса) в байтах. Пакет также может передавать сообщение об ошибке. Размер пакета зависит от версии MySQL-сервера.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_prepare_response`
  Количество пакетов OK протокола MySQL Client Server для инициализации подготовленного запроса (init-пакеты подготовленного запроса).
`bytes_received_change_user_packet`
  Общий размер пакетов COM_CHANGE_USER протокола MySQL Client Server protocol в байтах. Пакет также может передавать ошибку или состояние EOF.

  > Замечание: Общий размер в байтах включает размер пакета заголовка — 4 байта, см. накладные расходы протокола.

`packets_received_change_user`
  Количество пакетов COM_CHANGE_USER протокола MySQL Client Server.
`packets_sent_command`
  Количество команд протокола MySQL Client Server, которые отправил PHP на MySQL-сервер. Нет способа узнать, какие именно команды и сколько из них отправил PHP.
`bytes_received_real_data_normal`
  Количество байтов полезной нагрузки, которые получил PHP-клиент от драйвера `mysqlnd` по текстовому протоколу. Это размер фактических данных, которые содержатся в наборах результатов, которые не исходят из подготовленных запросов и которые получил PHP-клиент. Обратите внимание, даже при извлечении драйвером `mysqlnd` полного набора результатов с MySQL-сервера в статистике учитываются только фактические данные, которые PHP-клиент получил от дайвера `mysqlnd`.

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

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Каждая операция извлечения будет увеличивать значение.

  Однако значение метрики не увеличится, если результирующий набор только буферизуется на клиенте, но не извлекается, как, например, в следующем примере:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  Количество байтов полезной нагрузки, которую получил PHP-клиент от драйвера `mysqlnd` по протоколу подготовленного запроса. Это размер фактических данных, которые содержатся в наборах результатов, которые не исходят из подготовленных запросов и которые получил PHP-клиент. Модуль не увеличит значение, если PHP-клиент впоследствии не прочитает набор результатов. Обратите внимание, что, хотя полный результирующий набор мог быть получен от MySQL-сервера через драйвер `mysqlnd`, в этой статистике учитываются только фактические данные, которые PHP-клиент получил от драйвера `mysqlnd`. Смотрите также описание метрики `bytes_received_real_data_normal`.

Статистические данные результирующего набора
`result_set_queries`
  Количество запросов, которые сгенерировали набор результатов. Примеры запросов, которые генерируют результирующий набор: `SELECT`, `SHOW`. Модуль не увеличивает значение метрики, если произойдет ошибка при чтении пакета заголовка результирующего набора из строки.

  > Замечание: Этой статистикой пользуются как косвенным показателем количества запросов, которые PHP отправил на MySQL-сервер. Это помогает определить клиента, который вызывает высокую нагрузку на базу данных.

`non_result_set_queries`
  Количество запросов, которые не создали набор результатов. Примеры запросов, которые не генерируют набор результатов: `INSERT`, `UPDATE`, `LOAD DATA`. Модуль не увеличивает значение метрики, если произойдет ошибка при считывании пакета заголовка результирующего набора из строки.

  > Замечание: Этой статистикой пользуются как косвенным показателем количества запросов, которые PHP отправил на MySQL-сервер. Это помогает определить клиента, который вызывает высокую нагрузку на базу данных.

`no_index_used`
  Количество запросов, которые создали набор результатов, но не использовали индекс. (Смотрите также параметр запуска `--log-queries-not-using-indexes` команды mysqld).

  > Замечание: Об этих запросах сообщают через исключение, для чего вызывают `mysqli_report(MYSQLI_REPORT_INDEX);`. Вместо этого можно сообщить о них через предупреждения путём вызова `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`bad_index_used`
  Количество запросов, которые сгенерировали набор результатов без хорошего индекса. (Смотрите также параметр запуска `--log-slow-queries` команды mysqld).

  > Замечание: Об этих запросах сообщают через исключение, для чего вызывают `mysqli_report(MYSQLI_REPORT_INDEX);`. Вместо этого можно сообщить о них через предупреждения путём вызова `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);`.

`slow_queries`
  SQL-запросы, выполнение которых заняло больше секунд, чем значение параметра `long_query_time`, и для проверки которых требовало как минимум такое количество строк, которое задали в параметре `min_examined_row_limit`.
  Предостережение

  Не сообщается через функцию mysqli_report().

`buffered_sets`
  Количество буферизованных результирующих наборов, которые возвращают обычные неподготовленные запросы.

  Примеры вызовов API, которые буферизуют наборы результатов на клиенте: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  Количество небуферизованных результирующих наборов, которые возвращают обычные неподготовленные запросы.

  Примеры вызовов API, которые не буферизуют наборы результатов на клиенте: mysqli_use_result()

`ps_buffered_sets`
  Количество буферизованных наборов результатов, которые возвращают подготовленные запросы.

  Примеры вызовов API, которые буферизуют наборы результатов на клиенте: mysqli_stmt_store_result()

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

  > Замечание: Модуль сбрасывает только небуферизованные наборы результатов. Небуферизованные результирующие наборы должны быть полностью получены перед выполнением нового запроса по соединению, иначе MySQL-сервер выдаст ошибку. Если приложение не извлекает все строки из небуферизованного результирующего набора, команда mysqlnd неявно извлекает результирующий набор, чтобы очистить строку. Смотрите также описание метрик `rows_skipped_normal`, `rows_skipped_ps`.

  > Некоторые причины неявного сброса:

  > - Ошибка клиентского приложения
  > - Клиент прекратил чтение данных, когда нашёл то, что искал, но заставил MySQL-сервер вычислять больше записей, чем требуется
  > - Клиентское приложение неожиданно остановилось

`flushed_ps_sets`
  Количество результирующих наборов с непрочитанными данными, которые вернули подготовленные запросы и которые были без предупреждения сброшены.

  > Замечание: Модуль сбрасывает только небуферизованные наборы результатов. Небуферизованные результирующие наборы должны быть полностью получены перед выполнением нового запроса по соединению, иначе MySQL-сервер выдаст ошибку. Если приложение не извлекает все строки из небуферизованного результирующего набора, команда mysqlnd неявно извлекает результирующий набор, чтобы очистить строку. Смотрите также описание метрик `rows_skipped_normal`, `rows_skipped_ps`.

  > Некоторые причины неявного сброса:

  > - Ошибка клиентского приложения
  > - Клиент прекратил чтение данных, когда нашёл то, что искал, но заставил MySQL-сервер вычислять больше записей, чем требуется
  > - Клиентское приложение неожиданно остановилось

`ps_prepared_never_executed`
  Количество запросов, которые подготовили, но не выполнили.
`ps_prepared_once_executed`
  Количество подготовленных запросов, которые выполнили только один раз.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  Общее количество строк результирующего набора, которые вернул сервер. Сюда входят строки, которые клиент не прочитал, но неявно получил из-за сброшенных небуферизованных результирующих наборов. Смотрите также описание метрики `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  Общее количество буферизованных строк, которые получили в результате обычного запроса. Это количество строк, которые вернул MySQL-сервер и буферизовал клиент.

  Примеры запросов, которые буферизуют результаты:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  То же, что и метрика `rows_buffered_from_client_normal`, но для подготовленных запросов.
`rows_fetched_from_client_normal_buffered`
  Общее количество строк, которые извлёк клиент из буферизованного результирующего набора, который создал обычный запрос.
`rows_fetched_from_client_ps_buffered`
  Общее количество строк, которые извлёк клиент из буферизованного результирующего набора, который создал подготовленный запрос.
`rows_fetched_from_client_normal_unbuffered`
  Общее количество строк, которые извлёк клиент из небуферизованного результирующего набора, который создал обычный запрос.
`rows_fetched_from_client_ps_unbuffered`
  Общее количество строк, которые извлёк клиент из небуферизованного результирующего набора, который создал подготовленный запрос.
`rows_fetched_from_client_ps_cursor`
  Общее количество строк, которые клиент извлёк из курсора, который создал подготовленный запрос.
`rows_skipped_normal`
`rows_skipped_ps`
  Метрику зарезервировали для будущих нужд (пока не поддерживается).
`copy_on_write_saved`
`copy_on_write_performed`
  Это статистика уровня процесса. При запуске команды mysqlnd переменные, которые возвращает модуль, указывают на внутренние сетевые буферы результатов команды mysqlnd. Если данные не изменяются, извлеченные данные сохраняются в памяти только один раз. Однако для внесения изменений в данные потребуется, чтобы команда mysqlnd выполнила операцию копирования при записи.
`explicit_free_result`
`implicit_free_result`
  Это статистика уровня соединения и процесса. Общее количество высвобожденных результирующих наборов.
`proto_text_fetched_null`
  Общее количество столбцов типа `MYSQL_TYPE_NULL`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_null`
  Общее количество столбцов типа `MYSQL_TYPE_NULL`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_bit`
  Общее количество столбцов типа `MYSQL_TYPE_BIT`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_bit`
  Общее количество столбцов типа `MYSQL_TYPE_BIT`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_tinyint`
  Общее количество столбцов типа `MYSQL_TYPE_TINY`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_tinyint`
  Общее количество столбцов типа `MYSQL_TYPE_TINY`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_short`
  Общее количество столбцов типа `MYSQL_TYPE_SHORT`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_short`
  Общее количество столбцов типа `MYSQL_TYPE_SHORT`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_int24`
  Общее количество столбцов типа `MYSQL_TYPE_INT24`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_int24`
  Общее количество столбцов типа `MYSQL_TYPE_INT24`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_int`
  Общее количество столбцов типа `MYSQL_TYPE_LONG`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_int`
  Общее количество столбцов типа `MYSQL_TYPE_LONG`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_bigint`
  Общее количество столбцов типа `MYSQL_TYPE_LONGLONG`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_bigint`
  Общее количество столбцов типа `MYSQL_TYPE_LONGLONG`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_decimal`
  Общее количество столбцов типа `MYSQL_TYPE_DECIMAL` или `MYSQL_TYPE_NEWDECIMAL`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_decimal`
  Общее количество столбцов типа `MYSQL_TYPE_DECIMAL` или `MYSQL_TYPE_NEWDECIMAL`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_float`
  Общее количество столбцов типа `MYSQL_TYPE_FLOAT`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_float`
  Общее количество столбцов типа `MYSQL_TYPE_FLOAT`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_double`
  Общее количество столбцов типа `MYSQL_TYPE_DOUBLE`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_double`
  Общее количество столбцов типа `MYSQL_TYPE_DOUBLE`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_date`
  Общее количество столбцов типа `MYSQL_TYPE_DATE` или `MYSQL_TYPE_NEWDATE`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_date`
  Общее количество столбцов типа `MYSQL_TYPE_DATE` или `MYSQL_TYPE_NEWDATE`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_year`
  Общее количество столбцов типа `MYSQL_TYPE_YEAR`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_year`
  Общее количество столбцов типа `MYSQL_TYPE_YEAR`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_time`
  Общее количество столбцов типа `MYSQL_TYPE_TIME`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_time`
  Общее количество столбцов типа `MYSQL_TYPE_TIME`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_datetime`
  Общее количество столбцов типа `MYSQL_TYPE_DATETIME`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_datetime`
  Общее количество столбцов типа `MYSQL_TYPE_DATETIME`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_timestamp`
  Общее количество столбцов типа `MYSQL_TYPE_TIMESTAMP`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_timestamp`
  Общее количество столбцов типа `MYSQL_TYPE_TIMESTAMP`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_string`
  Общее количество столбцов типа `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` или `MYSQL_TYPE_VARCHAR`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_string`
  Общее количество столбцов типа `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` или `MYSQL_TYPE_VARCHAR`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_blob`
  Общее количество столбцов типа `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` или `MYSQL_TYPE_BLOB`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_blob`
  Общее количество столбцов типа `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` или `MYSQL_TYPE_BLOB`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_enum`
  Общее количество столбцов типа `MYSQL_TYPE_ENUM`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_enum`
  Общее количество столбцов типа `MYSQL_TYPE_ENUM`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_set`
  Общее количество столбцов типа `MYSQL_TYPE_SET`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_set`
  Общее количество столбцов типа `MYSQL_TYPE_SET`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_geometry`
  Общее количество столбцов типа `MYSQL_TYPE_GEOMETRY`, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).
`proto_binary_fetched_geometry`
  Общее количество столбцов типа `MYSQL_TYPE_GEOMETRY`, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).
`proto_text_fetched_other`
  Общее количество столбцов типов `MYSQL_TYPE_*`, не перечисленных ранее, которые модуль извлёк из обычного запроса (текстовый протокол MySQL-сервера).

  > Замечание: Теоретически значение всегда должно равняться `0`.

`proto_binary_fetched_other`
  Общее количество столбцов типа `MYSQL_TYPE_*`, не включённых ранее, которые модуль получил из подготовленного запроса (двоичный протокол MySQL-сервера).

  > Замечание: Теоретически, значение всегда должно равняться `0`.

Статистические данные соединения
`connect_success`
  Общее количество успешных попыток подключения.

  > Замечание: `connect_success` содержит сумму успешных постоянных и непостоянных попыток подключения. Следовательно, количество успешных попыток непостоянного подключения равно разности `connect_success - pconnect_success`.

`pconnect_success`
  Общее количество успешных попыток постоянного подключения.
`connect_failure`
  Общее количество неудачных попыток подключения.
`reconnect`
  Это статистика уровня процесса.
`active_connections`
  Это статистика уровня процесса. Общее количество активных постоянных и непостоянных подключений.

  > Замечание: Общее количество активных непостоянных соединений равно разности `active_connections - active_persistent_connections`.

`active_persistent_connections`
  Это статистика уровня процесса. Общее количество активных постоянных соединений.
`explicit_close`
  Общее количество явно закрытых соединений.

  Пример #1 Примеры фрагментов кода, которые вызывают явное закрытие

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  Общее количество неявно закрытых соединений.

  Пример #2 Примеры фрагментов кода, которые вызывают неявное закрытие

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Постоянное соединение: объединенное соединение создали методом real_connect, и, возможно, установили неизвестный набор опций, — закрывается неявно, чтобы избежать возврата соединения с неизвестными параметрами
  - Persistent connection: ping/change_user завершается неудачно, а ext/mysqli закрывает соединение
  - Окончание работы скрипта: закрываются соединения, которые пользователь не закрыл явно
`disconnect_close`
  Сбои подключения, на которые указывает вызов метода API-интерфейса языка C `mysql_real_connect` при попытке установить соединение.
`in_middle_of_command_close`
  Это статистика уровня процесса. Соединение прервалось в середине выполнения команды (не были получены выдающиеся результирующие наборы после отправки запроса и до получения ответа, во время получения данных, во время передачи данных через LOAD DATA).
  Внимание

  Если не выполняются асинхронные запросы, это должно произойти, только если PHP-приложение неожиданно завершилось, и PHP автоматически закрывает соединение.

`init_command_executed_count`
  Общее количество выполнений команды инициализации. Например: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. Количество успешных запусков — разность `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  Общее количество неудачных команд инициализации.

`Статистика команд COM_*`
`com_quit`
`com_init_db`
`com_query`
`com_field_list`
`com_create_db`
`com_drop_db`
`com_refresh`
`com_shutdown`
`com_statistics`
`com_process_info`
`com_connect`
`com_process_kill`
`com_debug`
`com_ping`
`com_time`
`com_delayed_insert`
`com_change_user`
`com_binlog_dump`
`com_table_dump`
`com_connect_out`
`com_register_slave`
`com_stmt_prepare`
`com_stmt_execute`
`com_stmt_send_long_data`
`com_stmt_close`
`com_stmt_reset`
`com_stmt_set_option`
`com_stmt_fetch`
`com_daemon`
  Общее количество попыток PHP отправить конкретную команду `COM_*` на MySQL-сервер. Значение метрики увеличивается после проверки строки и сразу перед отправкой соответствующего пакета клиент-серверного протокола MySQL.
  Предостережение

  Если драйвер MySQLnd не сможет отправить пакет по сети, значение метрики не будет уменьшаться. При сбое драйвер MySQLnd выдаёт PHP-предупреждение Error while sending %s packet. PID=%d.

  Пример #3 Примеры использования

  - Проверьте, отправляет ли PHP конкретные команды на MySQL-сервер, например: проверьте, отправляет ли клиент команду `COM_PROCESS_KILL`
  - Вычислите среднее количество выполнений подготовленных операторов путём сравнения команду `COM_EXECUTE` с командой `COM_PREPARE`
  - Выясните, не запускал ли PHP неподготовленные SQL-запросы путём проверки, равно ли значение команды `COM_QUERY` нулю
  - Определите PHP-скрипты, которые запускают чрезмерное количество SQL-запросов путём проверки команд `COM_QUERY` и `COM_EXECUTE`

Прочие статистические данные
`explicit_stmt_close`
`implicit_stmt_close`
  Это статистика уровня процесса. Общее количество закрытых подготовленных заявлений.

  > Замечание: Подготовленный запрос всегда явно закрыт. Единственный раз, когда он закрывается неявно, — когда подготовка не удалась.

`mem_emalloc_count`
`mem_emalloc_ammount`
`mem_ecalloc_count`
`mem_ecalloc_ammount`
`mem_realloc_count`
`mem_realloc_ammount`
`mem_efree_count`
`mem_malloc_count`
`mem_malloc_ammount`
`mem_calloc_count`
`mem_calloc_ammount`
`mem_ealloc_count`
`mem_ealloc_ammount`
`mem_free_count`
  Это статистика уровня процесса. Вызовы управления памятью.
`command_buffer_too_small`
  Количество модулей сетевого буфера команд при отправке команд из PHP на сервер MySQL. Драйвер mysqlnd выделяет для каждого подключения внутренний командный или сетевой буфер, размер которого задали в байтах в опции конфигурации mysqlnd.net_cmd_buffer_size. Драйвер MySQLnd увеличит размер буфера до размера, который требуется для отправки команды, если команда протокола MySQL Client Server наподобие `COM_QUERY` (обычный запрос) не помещается в буфер. Каждый раз при расширении буфера для одного соединения метрика `command_buffer_too_small` увеличивается на единицу. Если драйверу MySQLnd приходится увеличивать размер буфера сверх первоначального размера, который задали в байтах в опции mysqlnd.net_cmd_buffer_size, почти для каждого соединения, размер по умолчанию для буфера увеличивают, чтобы избежать перераспределения памяти.
`connection_reused`
  Общее количество переиспользований постоянного соединения.

# Замечания

Этот раздел содержит набор различных замечаний по поводу использования встроенного драйвера MySQL.

- Использование `mysqlnd` подразумевает использование потоков PHP как основу для подключений. При работе с `mysqlnd` следует обращаться к документации потоков PHP (Потоки), а не к документации клиентской библиотеки MySQL, по поводу таких вещей, как, например, настройка времени ожидания.

# Управление памятью

Введение

Встроенный драйвер MySQL (mysqlnd) управляет памятью по-другому, в отличие от клиентской библиотеки MySQL (libmysql). Библиотеки различаются способом выделения и освобождения памяти, тем, как память выделяется по кускам во время чтения результатов из MySQL, существующими опциями для отладки и разработки, и тем, как результаты, считанные из MySQL, связаны с пользовательскими переменными PHP.

Следующая информация предназначена в качестве введения и обобщения для пользователей, заинтересованных в понимании `mysqlnd` на уровне C-кода.

Используемые функции для управления памятью

Все операции выделения и освобождения памяти происходят используя PHP-функции, предназначенные для управления памятью. Поэтому, потребление памяти встроенного драйвера MySQL может быть отслежено при помощи вызовов PHP API, таких как memory_get_usage(). Из-за того, что память выделяется и освобождается при помощи системы управления памятью PHP, изменения на уровне операционной системы могут быть видны не мгновенно. Система управления памятью PHP ведёт себя как прокси, которая может вызывать задержку в освобождении памяти. Ввиду этого, сравнение использования памяти встроенного драйвера MySQL и клиентской библиотеки MySQL (libmysql) довольно сложно. Клиентская библиотека MySQL (libmysql) использует систему управления памятью операционной системы напрямую, следовательно, эффект на уровне операционной системы может быть виден незамедлительно.

Любое ограничение памяти, установленное в PHP, также влияет на встроенный драйвер MySQL. Это может вызвать ошибки переполнения памяти при извлечении больших массивов данных, которые превышают размер оставшейся памяти, предоставленных РНР. Из-за того, что клиентская библиотека MySQL не использует функций управления памяти PHP, она не подчиняется ограничению памяти, установленному в PHP. При использовании libmysql, в зависимости от модели развёртывания, объем памяти, занимаемый PHP-процессом, может вырасти за пределы ограничений, установленных в PHP. В тоже время, PHP-скрипты могут обрабатывать больший объем массивов данных, так как области памяти, выделенные для хранения данных, не находятся под управлением РНР.

Функции системы управления памятью PHP вызываются встроенным драйвером MySQL через легковесную обёртку. Среди прочего, обёртка делает отладку легче.

Обработка массивов полученных данных

Различные MySQL-сервера и различные клиентские API различают буферизированные и небуферизированные результаты. Небуферизированные результаты передаются строка за строкой от MySQL к клиенту и клиент читает их по порядку. Буферизированные результаты забираются клиентской библиотекой целиком до передачи их клиенту.

Встроенный драйвер MySQL использует PHP-потоки для сетевого общения с сервером MySQL. Результаты, посланные MySQL-сервером, выбираются из сетевых буферов PHP-потоков в результирующий буфер mysqlnd. Результирующий буфер состоит из zvals. На втором шаге результаты становятся доступными PHP-скрипту. Последняя передача из результирующего буфера в PHP-переменные вызывает потребление памяти и в большинстве случаев оно заметно при использовании буферизированных результатов.

По умолчанию встроенный драйвер MySQL пытается избежать двойного хранения буферного результата в памяти. Результаты хранятся только один раз во внутренних результирующих буферах и их zvals. Когда результаты забираются в РНР-переменные PHP-скриптом, переменные будут ссылаться на внутренние результаты буферов. Результаты запросов к базам данных не копируются и хранятся в памяти только один раз. Достаточно пользователю изменить содержимое переменной, содержащей результаты работы базы данных, как будет выполнен механизм копирования при записи (Copy-On-Write), для того, чтобы избежать изменения ссылающего внутреннего буфера результата. Содержимое буфера не должно быть изменено, так как пользователь может принять решение прочитать результат во второй раз. Механизм копирования при записи реализуется с помощью дополнительного управления списком ссылок и использования стандартных zval счётчиков ссылок. Копирование при записи также должно быть сделано, если пользователь читает данные результата в PHP переменных и освобождает данные результата прежде, чем переменные будут уничтожены.

В общем, этот шаблон работает хорошо для скриптов, которые читают наборы данных единожды и не изменяют переменных, содержащих результаты. Его главный недостаток в накладных расходах памяти, вызванных дополнительным управлением ссылками, причина которого в первую очередь связана с тем, что пользовательские переменные, удерживающие результаты, не могут быть полностью освобождены до того, как система управления ссылками mysqlnd содержит ссылки на них. Встроенный драйвер MySQL удаляет ссылку на на пользовательские переменные когда массив полученных данных освобождается или выполняется механизм копирования при записи. Наблюдатель увидит рост общего потребления памяти пока массив полученных данных не освободится. Используйте статистику, чтобы проверить, скрипт явно произвёл освобождение данных результата или же драйвер сделал это неявно и поэтому память используется в течение более долгого времени, чем это необходимо. Статистика также помогает увидеть количество операций копирования при записи.

PHP-скрипт, читающий множество небольших строк в буферизированном массиве данных, использующий код, подобный `while ($row = $res->fetch_assoc()) { ... }`, может оптимизировать потребление памяти, запросив копии вместо ссылок. Хотя и запрос копий означает хранение тех же результатов в памяти дважды, это позволяет PHP уничтожить копию, содержащую в `$row` в качестве итерируемого массива данных и перед уничтожением результат устанавливает сам себя. На загруженном сервере оптимизация использования памяти может помочь улучшить общую производительность системы, хотя для отдельного скрипта подход с копией вместо ссылок может быть медленнее в связи с дополнительным выделением памяти и дополнительными операциями копирования в памяти.

Контроль и отладка

Существует несколько методов отслеживания использования памяти во встроенном драйвере MySQL "mysqlnd". Если цель - получить быстрый высокоуровневый обзор или проверить эффективность PHP-скриптов при работе с памятью, то проверьте статистику, собранную библиотекой. Статистика позволит вам, например, поймать SQL-запрос, который генерирует больше результатов, чем обрабатываются PHP-скриптом.

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

В некоторых последних версиях встроенного драйвера MySQL "mysqlnd" присутствует возможность эмуляции случайных ситуаций нехватки памяти. Эта возможность была задумана для использования только C-разработчиками библиотеки или авторами плагина mysqlnd. Пожалуйста, используйте поиск по исходному коду для соответствующей настройки PHP и для дальнейшей информации. Это возможность является недокументированной и может быть изменена в любое время без дополнительного уведомления.

# API интеграции плагинов в драйвер MySQL Native Driver

## Содержание

- Сравнение плагинов mysqlnd с MySQL Proxy
- Получение API плагинов mysqlnd
- Архитектура плагинов MySQL Native Driver
- API плагинов mysqlnd
- Начинаем разработку плагина mysqlnd

Драйвер MySQL Native Driver, или `mysqlnd`, предоставляет API, через который плагины встраиваются в драйвер. Плагины драйвера `mysqlnd` работают на уровне между PHP-приложениями и MySQL-сервером, аналогично приложению MySQL Proxy, которое также работает между клиентскими приложениями и сервером MySQL. Плагины драйвера `mysqlnd` выполняют типовые задачи MySQL Proxy наподобие балансировки нагрузки, мониторинга и оптимизации быстродействия. Из-за другой архитектуры и места обработки запросов плагины драйвера `mysqlnd` не содержат недочётов MySQL Proxy наподобие единой точки отказа, не требуют установки отдельного прокси-сервера и изучения нового языка программирования Lua.

Плагин `mysqlnd` расширяет функции драйвера `mysqlnd`. Плагин умеет перехватывать вызовы функций драйвера `mysqlnd` из MySQL-модулей PHP наподобие `ext/mysql`, `ext/mysqli` и `PDO_MYSQL`. Поэтому плагинам драйвера `mysqlnd` доступен перехват каждого запроса, который модули выполнили из клиентского приложения.

Плагины умеют перехватывать или подменять вызовы внутренних функций драйвера `mysqlnd`. API не ограничивает модификацию таблиц внутренних функций драйвера `mysqlnd` и разрешает перенаправлять вызовы конкретных функций драйвера `mysqlnd` из `mysqlnd`-модулей на функции `mysqlnd`-плагина. Управление таблицей внутренних функций драйвера `mysqlnd` даёт плагинам максимум гибкости.

Плагины драйвера `mysqlnd` — фактически PHP-модули на языке C, которые работают через API интеграции `mysqlnd`-плагинов в PHP-драйвер MySQL Native Driver, или `mysqlnd`. Плагины на 100 % прозрачны для PHP-приложений. Приложение не требуется изменять, поскольку плагины работают на другом уровне. С точки зрения поведения, `mysqlnd`-плагин работает на уровень ниже `mysqlnd`-драйвера, поскольку переопределяет поведение драйвера.

Следующий список приводит примеры практических задач, которые решают посредством плагинов драйвера `mysqlnd`.

- Балансировка нагрузки
  - Разделение чтения и записи. Пример — модуль PECL/mysqlnd_ms (Master Slave). Модуль разделяет запросы на чтение и запись для настройки репликации.
  - Отказоустойчивость
  - Циклическое распределение запросов по принципу Round-Robin для равномерной нагрузки, распределение на наименее загруженный сервер
- Мониторинг
  - Логирование запросов
  - Анализ запросов
  - Аудит запросов. Пример — модуль PECL/mysqlnd_sip (SQL Injection Protection, защита от SQL-инъекций). Модуль инспектирует запросы и выполняет только те, которые соответствуют набору правил.
- Производительность.
  - Кеширование. Пример — модуль PECL/mysqlnd_qc (Query Cache, кеширование запросов).
  - Ограничение числа запросов
  - Шардирование. Пример — модуль PECL/mysqlnd_mc (Multi Connect). Модуль пытается разбить запрос SELECT на n частей через SELECT ... LIMIT part_1, SELECT LIMIT part_n. Модуль отправляет запросы на отдельные MySQL-серверы и объединяет результаты на клиенте.

Доступные плагины драйвера MySQL Native Driver

Репозитории PECL уже содержит ряд mysqlnd-плагинов, включая следующие:

- mysqlnd_mc — Multi Connect, разбивка запросов по шардам.
- mysqlnd_ms — Master Slave, разделение запросов на чтение и запросов на запись.
- mysqlnd_qc — Query Cache, кеширование результатов запросов.
- mysqlnd_pscache — Prepared Statement Handle Cache, обработка кеширования подготовленных запросов.
- mysqlnd_sip — SQL Injection Protection, защита от SQL-инъекций.
- mysqlnd_uh — User Handler, обработка пользователей.

## Сравнение плагинов mysqlnd с MySQL Proxy

Плагины `mysqlnd` и приложение MySQL Proxy — разные технологии с разными подходами. Оба инструмента решают стандартные задачи наподобие балансировки нагрузки, мониторинга и улучшения производительности. Важное отличие состоит в том, что приложение MySQL Proxy работает со всеми MySQL-клиентами, тогда как плагины `mysqlnd` работают только с PHP-приложениями.

Как PHP-модуль, плагин `mysqlnd` устанавливается на сервер PHP-приложений вместе с остальными компонентами PHP-дистрибутива. MySQL Proxy запускают на сервере приложений PHP или устанавливают на отдельной машине для поддержки множественных серверов PHP-приложений.

Установка MySQL Proxy на сервере приложений даёт два преимущества:

1. Отсутствие единой точки отказа
2. Лёгкость в горизонтальном масштабировании и масштабировании за счёт клиента

Приложение MySQL Proxy и плагины `mysqlnd` легко решают проблемы, которые иначе потребовали бы изменений в текущих приложениях.

Тем не менее, MySQL Proxy содержит и ряд недостатков:

- MySQL Proxy — новый элемент и технология, которую потребуется изучить и установить.
- MySQL Proxy требует знания скриптового языка Lua.

Приложения MySQL Proxy настраиваются под конкретные задачи средствами языков C и Lua. Lua — предпочтительный скриптовый язык для MySQL Proxy. Для большей части PHP-экспертов Lua новый язык, который потребуется изучать. Плагин драйвера `mysqlnd` пишут на C или на PHP через модуль » PECL/mysqlnd_uh.

MySQL Proxy работает как демон — фоновый процесс. MySQL Proxy может вспомнить ранее принятые решения, так как все состояние может быть сохранено. Однако плагины `mysqlnd` привязаны к жизненному циклу PHP, базирующемуся на запросах. Также MySQL Proxy может разделять единожды полученный результат между разными серверами приложений. Плагины `mysqlnd` для решения этой задачи должны использовать какое-нибудь постоянное хранилище, для сохранения результатов между запросами. Например, для этого может быть использован другой демон, такой как Memcache. Так что в этом случае MySQL Proxy работает явно лучше.

MySQL Proxy работает поверх сетевых протоколов. С помощью MySQL Proxy вы можете разобрать и подвергнуть инженерному анализу протокол MySQL Client Server. Что-либо поменять можно только манипулируя протоколом обмена. Если протокол вдруг поменяется (что бывает крайне редко), скрипты MySQL Proxy потребуется переписывать.

Плагины `Mysqlnd` работают поверх C API, который дублирует клиент `libmysqlclient`. Этот API-интерфейс языка C по сути обычная обёртка вокруг протокола MySQL Client Server. Вы можете перехватывать каждый вызов API-интерфейса C. PHP использует API-интерфейс C, фактически можно перехватывать вообще каждый вызов PHP, без программирования на уровне протокола обмена.

`Mysqlnd` реализует протокол обмена. Таким образом, плагины могут перехватывать, исследовать, менять и даже целиком заменять протокол связи. Хотя обычно ничего этого не требуется.

Плагины позволяют вам использовать два уровня (C API и протокол обмена), в этом они гораздо гибче, чем MySQL Proxy. Если плагин `mysqlnd` реализован с использованием C API, изменения протокола обмена не потребуют изменения плагина.

## Получение API плагинов mysqlnd

API плагинов `mysqlnd` является частью стандартного модуля `ext/mysqlnd`. API плагинов `mysqlnd` начали разрабатывать в декабре 2009 года. Он разрабатывался как часть репозитория исходных кодов PHP и, соответственно, доступен через публичный репозиторий Git либо через загрузку снапшота исходных кодов.

Разработчики плагинов узнают версию `mysqlnd` путём доступа к `MYSQLND_VERSION` — строка в формате mysqlnd 8.3.17, или через `MYSQLND_VERSION_ID` — числовое представление версии наподобие 50007. Разработчики вычисляют номер версии из этого числа следующим способом:

Таблица расчёта MYSQLND_VERSION_ID
Версия (часть) | Пример
--- | ---
Major*10000 | 5*10000 = 50000
Minor*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

Разработчики отслеживают версию драйвера `mysqlnd` на предмет совместимости и версионного тестирования, поскольку версии `mysqlnd` иногда изменяется в процессе работы над плагином.

## Архитектура плагинов MySQL Native Driver

В секции рассматривается архитектура плагинов драйвера `mysqlnd`.

Обзор MySQL Native Driver

Перед началом разработки плагинов для драйвера `mysqlnd` полезно узнать, как организован сам драйвер `mysqlnd`. `Mysqlnd` состоит из следующих модулей:

Организационная схема mysqlnd, помодульно
Модули статистики | mysqlnd_statistics.c
--- | ---
Соединение | mysqlnd.c
Результирующий набор | mysqlnd_result.c
Метаданные результирующего набора | mysqlnd_result_meta.c
Оператор | mysqlnd_ps.c
Сеть | mysqlnd_net.c
Протокол обмена | mysqlnd_wireprotocol.c

Объектно-ориентированная парадигма C

На уровне кода, `mysqlnd` использует паттерн C для реализации объектно-ориентированного подхода.

В C объекты описывают используя `struct`. Члены структуры являются свойствами объекта. Члены структуры, указывающие на функции, являются методами.

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

Жизненный цикл PHP

При рассмотрении жизненного цикла PHP существует два основных цикла:

- Цикл старта и остановки движка PHP
- Цикл обработки запроса

При старте движка PHP, первым делом вызывается функция инициализации модулей (MINIT) для каждого зарегистрированного модуля. Это позволяет каждому модулю установить переменные и выделить ресурсы, которые будут задействованы все время жизни процесса движка PHP. Когда движок PHP выключается, он вызывает функцию остановки модулей (MSHUTDOWN) для каждого модуля.

На протяжении жизненного цикла движка PHP, он принимает некоторое количество запросов. Каждый запрос порождает новый жизненный цикл. На каждый запрос, движок PHP вызывает функцию инициализации для каждого модуля. Модуль может предпринять выставление переменных и выделение ресурсов, требуемых для обслуживания запроса. По окончании жизни запроса, движок вызывает функцию остановки запроса (RSHUTDOWN) для каждого модуля, что позволяет им произвести необходимые чистки.

Как работает плагин

Плагин `mysqlnd` работает перехватывая вызовы модулей, использующих `mysqlnd`, к `mysqlnd`. Это достигается подменой таблицы функций `mysqlnd` на созданную плагином.

Следующий код демонстрирует замену таблицы функций `mysqlnd`:

    /* хранилище оригинальной таблицы */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* активная таблица функций */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* бэкап оригинальной таблицы */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods);

      /* установка новых методов */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

Манипуляцией с таблицей функций соединения необходимо заниматься на этапе инициализации модуля (MINIT). Таблица функций — глобальный разделяемый ресурс. В многопоточном окружении, со сборкой TSRM, манипуляция глобальным разделяемым ресурсом на этапе обработки запроса вызовет конфликты.

> Замечание: Не используйте логику, которая связана с фиксированным размером при манипуляции с таблицей функций `mysqlnd`. Всегда добавляйте новые методы в конец таблицы, так как сама таблица может в будущем в любой момент измениться.

Вызов родительских методов

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

В отдельных случаях, например, для `Connection::stmt_init()`, жизненно важно сначала вызвать родительский метод, и только потом делать что-либо в новом методе.

    MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
      const char *query, unsigned int query_len TSRMLS_DC) {

      php_printf("my_conn_class::query(query = %s)\n", query);

      query = "SELECT 'query rewritten' FROM DUAL";
      query_len = strlen(query);

      return org_methods.query(conn, query, query_len); /* возврат с вызовом родителя */
    }

Расширение свойств

Объекты `mysqlnd` представлены как C struct. Невозможно добавить члена в C struct во время исполнения. Пользователи объектов `mysqlnd` не могут просто добавить свойства объекту.

Произвольные данные (свойства) могут быть добавлены к объекту `mysqlnd` с использованием соответствующей функции из семейства `mysqlnd_plugin_get_plugin_<object>_data()`. При размещении объекта `mysqlnd` резервируется место в конце объекта для удержания `void *` указателя на произвольные данные. `mysqlnd` резервирует место для одного `void *` указателя на плагин.

В следующей таблице показано, как вычислить положение указателя для конкретного плагина:

Расчёт указателя для mysqlnd
Адрес памяти | Содержимое
--- | ---
0 | Начало объекта mysqlnd (C struct)
n | Конец объекта mysqlnd (C struct)
n + (m x sizeof(void*)) | void* для данных объекта плагина номер m

Если вы планируете делать подкласс от одного из конструкторов объекта `mysqlnd`, которые разрешены, имейте это в виду!

Следующий код демонстрирует расширение свойств:

    /* Любые данные, которые мы хотим добавить */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* идентификатор плагина */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* получаем уникальный идентификатор плагина */
      my_plugin_id = mysqlnd_plugin_register();
      /* snip - see Extending Connection: methods */
    }

    static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
      MY_CONN_PROPERTIES** props;
      props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
        conn, my_plugin_id);
      if (!props || !(*props)) {
        *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
        (*props)->query_counter = 0;
      }
      return props;
    }

Разработчик плагина отвечает за управление памятью данных плагина.

Рекомендуется использовать управление памятью `mysqlnd` для данных плагина. Эти функции именуются используя такие соглашения: `mnd_*loc()`. Управление памятью `mysqlnd` имеет ряд полезных свойств, таких как использование отладочного модуля управления памятью в неотладочных сборках.

Когда и как создавать подкласс
| Когда создавать подкласс? | Каждый экземпляр имеет свою собственную таблицу функций? | Как создавать подкласс?
--- | --- | --- | ---
Соединение (MYSQLND) | MINIT | Нет | mysqlnd_conn_get_methods()
Результирующий набор (MYSQLND_RES) | MINIT or later | Да | mysqlnd_result_get_methods() или методом объекта, манипулирующим таблицей функций
Результирующий набор (MYSQLND_RES_METADATA) | MINIT | Нет | mysqlnd_result_metadata_get_methods()
Оператор (MYSQLND_STMT) | MINIT | Нет | mysqlnd_stmt_get_methods()
Сеть (MYSQLND_NET) | MINIT или позже | Да | mysqlnd_net_get_methods() или методом объекта, манипулирующим таблицей функций
Протокол обмена (MYSQLND_PROTOCOL) | MINIT или позже | Да | mysqlnd_protocol_get_methods() или методом объекта, манипулирующим таблицей функций

Вы не должны манипулировать таблицей функций после MINIT, если это прямо не разрешено в таблице выше.

Некоторые классы содержат указатель на таблицу функций методов. Все экземпляры подобных классов должны делить одну и ту же таблицу функций. Для того, чтобы избежать хаоса, особенно в многопоточном окружении, управлять такими таблицами функций стоит только во время MINIT.

Прочие классы используют копии глобально разделённых таблиц функций. Таблица функций создаётся одновременно с объектом. Каждый объект использует свою таблицу. Это даёт вам две возможности: вы можете управлять таблицей функций по умолчанию для объекта во время MINIT, а также вы можете изменять методы объекта не затрагивая другие экземпляры этого же класса.

Преимущество разделяемой таблицы функций в производительности, так как нет нужды копировать таблицу функций отдельно для каждого объекта.

Статус конструктора
Тип | Размещение, создание, сброс | Может быть изменено? | Вызывающий
--- | --- | --- | ---
Connection (MYSQLND) | mysqlnd_init() | Нет | mysqlnd_connect()
Результирующий набор (MYSQLND_RES) | Размещение: Connection::result_init() Сброс и повторная инициализация во время: Result::use_result() Result::store_result | Да, но вызовите родителя! | Connection::list_fields() Statement::get_result() Statement::prepare() (Только метаданные) Statement::resultMetaData()
Метаданные результирующего набора (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Да, но вызовите родителя! | Result::read_result_metadata()
Оператор (MYSQLND_STMT) | Connection::stmt_init() | Да, но вызовите родителя! | Connection::stmt_init()
Сеть (MYSQLND_NET) | mysqlnd_net_init() | Нет | Connection::init()
Протокол обмена (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | Нет | Connection::init()

Настоятельно рекомендуется не заменять конструктор целиком. Конструкторы производят выделение памяти. Выделение памяти жизненно необходимо для API плагинов `mysqlnd` и для логики объекта `mysqlnd`. Если вам не страшны предупреждения и хотите сильно поменять конструктор, то хотя бы вызовите родительский конструктор прежде, чем что-либо делать.

Несмотря на предупреждения, это бывает полезным для конструктора подкласса. Конструкторы — отличное место для изменения таблицы функций для объектов, которые не работают с разделённой таблицу, например, результирующий набор, сеть, протокол обмена.

Статус уничтожения
| Производный метод должен вызвать родительский? | Деструктор
--- | --- | ---
Соединение | да, после выполнения метода | free_contents(), end_psession()
Результирующий набор | да, после выполнения метода | free_result()
Метаданные результирующего набора | да, после выполнения метода | free()
Оператор | да, после выполнения метода | dtor(), free_stmt_content()
Сеть | да, после выполнения метода | free()
Протокол обмена | да, после выполнения метода | free()

Деструкторы являются подходящим местом, чтобы освободить ресурсы, занимаемые свойствами `mysqlnd_plugin_get_plugin_<object>_data()`.

Перечисленные деструкторы могут не совпадать с актуальными методами `mysqlnd` для очистки самого объекта. Однако они являются самым лучшим местом, куда вы можете вклиниться для очистки данных своего плагина. Так же как и с конструкторами, вы можете полностью переопределить эти методы, но делать это не рекомендуется. Если вам необходимо вставить в каждый из перечисленных методов очистку данных своего плагина, то необходимо обеспечить запуск родительских методов `mysqlnd`.

Для плагинов рекомендуют метод — выполнить код очистки данных плагина и сразу после этого вызывать родительский метод.

## API плагинов mysqlnd

API-интерфейс плагинов `mysqlnd` поддерживает следующие функции:

- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()

Нет стандартных определений того, что такое плагин и как он работает.

Часто встречающиеся в плагинах компоненты:

- Менеджер плагина
- API плагина
- Сервисы приложения (или модули)
- API сервисов приложения (или API модулей)

Концепция плагина `mysqlnd` эксплуатирует эту функциональность и, кроме того, радует нас открытой архитектурой.

Нет запретов

Плагин имеет полный доступ ко всем внутренностям `mysqlnd`. Нет ограничений или запретов, связанных с безопасностью. Все что угодно можно переписать для реализации дружественных или враждебных алгоритмов, так что рекомендуется ставить плагины только из доверенных источников.

Как обсуждалось выше, плагины могут свободно использовать указатели. Эти указатели ничем не ограничены и могут указывать на данные другого плагина. Простейшая арифметическая операция позволит получить доступ к данным другого плагина.

Рекомендуется писать сотрудничающие плагины, которые могут работать сообща с другими плагинами и всегда вызывать родительские методы. Плагины никогда не должны вести себя враждебно к самому `mysqlnd`.

Проблемы: пример сотрудничества и построения цепочки
Модуль | Указатель mysqlnd.query() | Стек вызова, если вызывается родитель
--- | --- | ---
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache | mysqlnd_cache.query() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() mysqlnd.query

В этом сценарии загружены плагины кеша (`ext/mysqlnd_cache`) и мониторинга (`ext/mysqlnd_monitor`). Оба наследуют класс `Connection::query()`. регистрация плагинов происходит на этапе `MINIT` в соответствии с описанной выше логикой. PHP, по умолчанию, вызывает модули в алфавитном порядке. Плагины не знают друг о друге и не накладывают каких-либо зависимостей.

По умолчанию, плагины вызывают родительский метод query из своей, переопределённой, версии этого метода.

Резюме по модулю PHP

Повторение пройденного материала на примере поведения плагина `ext/mysqlnd_plugin`, использующего API плагинов `mysqlnd` для PHP:

- Любое приложение PHP, использующее MySQL пытается установить соединение по адресу 192.168.2.29
- Приложение использует одно из следующих модулей `ext/mysql`, `ext/mysqli` или `PDO_MYSQL`. Все три модуля используют `mysqlnd` для соединения с 192.168.2.29.
- `Mysqlnd` вызывает метод соединения, который наследуется плагином `ext/mysqlnd_plugin`.
- `ext/mysqlnd_plugin` вызывает зарегистрированный пользователем метод `proxy::connect()`.
- Этот метод подменяет IP адрес соединения с 192.168.2.29 на 127.0.0.1 и возвращает установленное `parent::connect()` соединение.
- `ext/mysqlnd_plugin` делает то же самое, что и `parent::connect(127.0.0.1)`, вызывая оригинальный метод `mysqlnd` для соединения.
- `ext/mysqlnd` устанавливает соединение и возвращает его `ext/mysqlnd_plugin`. `ext/mysqlnd_plugin`, в свою очередь, передаёт его дальше.
- Без разницы, какой модуль был использован, он всё равно получит соединение к 127.0.0.1. После этого, модуль возвращает это соединение приложению. Круг замкнулся.

## Начинаем разработку плагина mysqlnd

Важно помнить, что плагин `mysqlnd` сам по себе является модулем PHP.

Следующий пример показывает базовую структуру функции MINIT, использующуюся в типичном плагине `mysqlnd`:

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* глобальные переменные, ini-настройки, ресурсы, классы */

      /* регистрируем плагин mysqlnd */
      mysqlnd_plugin_id = mysqlnd_plugin_register();

      conn_m = mysqlnd_get_conn_methods();
      memcpy(org_conn_m, conn_m,
        sizeof(struct st_mysqlnd_conn_methods));

      conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
      conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
    }

    /* my_mysqlnd_plugin.c */

     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
      /* ... */
    }
    enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
      /* ... */
    }

Анализ задачи: от C до пользовательского пространства

     class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Процесс:

1. PHP: пользователь регистрирует callback-функцию плагина
2. PHP: пользователь вызывает PHP MySQL API для соединения с MySQL
3. C: ext/*mysql* вызывает метод mysqlnd
4. C: mysqlnd обрывается в ext/mysqlnd_plugin

5. C: ext/mysqlnd_plugin

   1. Вызывает пользовательскую callback-функцию
   2. Или оригинальный метод `mysqlnd`, если она не задана

Вам необходимо выполнить следующие действия:

1. Создайте в С класс "mysqlnd_plugin_connection"
2. Примите и зарегистрируйте прокси объект с помощью "mysqlnd_plugin_set_conn_proxy()"
3. Вызовите прокси методы пространства пользователя из C (оптимизация - zend_interfaces.h)

Методы объекта пространства пользователя должны быть вызваны с помощью `call_user_function()` или на уровень ниже, с помощью `zend_call_method()`.

Оптимизация: вызывайте методы из С с помощью zend_call_method

Следующий кусок кода демонстрирует прототип функции `zend_call_method`, взятый из zend_interfaces.h.

     ZEND_API zval* zend_call_method(
      zval **object_pp, zend_class_entry *obj_ce,
      zend_function **fn_proxy, char *function_name,
      int function_name_len, zval **retval_ptr_ptr,
      int param_count, zval* arg1, zval* arg2 TSRMLS_DC
    );

API движка Zend поддерживает только два аргумента. Иногда требуется больше. Например:

     enum_func_status (*func_mysqlnd_conn__connect)(
      MYSQLND *conn, const char *host,
      const char * user, const char * passwd,
      unsigned int passwd_len, const char * db,
      unsigned int db_len, unsigned int port,
      const char * socket, unsigned int mysql_flags TSRMLS_DC
    );

Для обхода этой проблемы вам необходимо сделать копию `zend_call_method()` и добавить необходимые параметры. Вы можете сделать это создав набор макросов `MY_ZEND_CALL_METHOD_WRAPPER`.

Обращение к пространству пользователя PHP

Этот кусок кода демонстрирует оптимизированный метод вызова функций пространства пользователя из С:

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)
    (
        MYSQLND *conn, const char *host /* ... */ TSRMLS_DC)
    {
        enum_func_status ret = FAIL;
        zval *global_user_conn_proxy = fetch_userspace_proxy();
        if (global_user_conn_proxy)
        {
            /* Вызов прокси пространства пользователя */
            ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
        }
        else
        {
            /* или оригинальный метод mysqlnd = ничего не делать, быть прозрачным */
            ret = org_methods.connect(conn, host, user, passwd,
                                      passwd_len, db, db_len, port,
                                      socket, mysql_flags TSRMLS_CC);
        }
        return ret;
    }

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

    /* my_mysqlnd_plugin.c */

     MYSQLND_METHOD(my_conn_class,connect)(
      /* ... */, const char *host, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_host;
        MAKE_STD_ZVAL(zv_host);
        ZVAL_STRING(zv_host, host, 1);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_host);
        /* ... */
      }
      /* ... */
    }

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

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)
    (
        MYSQLND *conn, /* ...*/)
    {
        /* ... */
        if (global_user_conn_proxy)
        {
            /* ... */
            zval *zv_conn;
            ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
            MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
            zval_ptr_dtor(&zv_conn);
            /* ... */
        }
        /* ... */
    }

первый аргумент многих методов `mysqlnd` — «объекты» С. Например, первый аргумент метода connect() — указатель на `MYSQLND`. Структура MYSQLND — объект соединения `mysqlnd`.

Указатель на объект соединения `mysqlnd` сравнивают со стандартным обработчиком файлового ввода-вывода. Так же как и он, объект соединения `mysqlnd` связывают с пространством пользователя через PHP-тип resource.

Из C в пространство пользователя и обратно

    <?php

    class proxy extends mysqlnd_plugin_connection
    {
        public function connect($conn, $host, ...)
        {
            /* До внедрения */
            printf("Подключение к = '%s'\n", $host);
            debug_print_backtrace();
            return parent::connect($conn);
        }

        public function query($conn, $query)
        {
            /* После внедрения */
            $ret = parent::query($conn, $query);
            printf("Запрос = '%s'\n", $query);
            return $ret;
        }
    }

    mysqlnd_plugin_set_conn_proxy(new proxy());

Пользователи PHP должны иметь возможность вызывать родительские реализации переопределённых методов.

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

Встроенный класс: mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

    PHP_METHOD("mysqlnd_plugin_connection", connect)
    {
        /* ... упрощённый! ... */
        zval *mysqlnd_rsrc;
        MYSQLND *conn;
        char *host;
        int host_len;
        if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
                                  &mysqlnd_rsrc, &host, &host_len) == FAILURE)
        {
            RETURN_NULL();
        }
        ZEND_FETCH_RESOURCE(conn, MYSQLND * conn, &mysqlnd_rsrc, -1,
                            "Mysqlnd Connection", le_mysqlnd_plugin_conn);
        if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))
            RETVAL_TRUE;
        else
            RETVAL_FALSE;
    }

- Обзор
- Установка
- Настройка во время выполнения
- Несовместимости
- Постоянное соединение
- Статистика
- Замечания
- Управление памятью
- API интеграции плагинов в драйвер MySQL Native Driver
  - Сравнение плагинов mysqlnd с MySQL Proxy
  - Получение API плагинов mysqlnd
  - Архитектура плагинов MySQL Native Driver
  - API плагинов mysqlnd
  - Начинаем разработку плагина mysqlnd

- Обзор PHP-драйверов MySQL
  - Обзор терминологии
  - Выбор API-интерфейса
  - Выбор библиотеки
  - Основные понятия
- MySQLi — Улучшенный модуль MySQL (MySQL Improved)
  - Краткий обзор
  - Краткое руководство
  - Установка и настройка
  - Модуль mysqli и постоянные соединения
  - Предопределённые константы
  - Основная информация о функциях модуля MySQLi
  - mysqli — Класс mysqli
  - mysqli_stmt — The mysqli_stmt class
  - mysqli_result — Класс mysqli_result
  - mysqli_driver — Класс mysqli_driver
  - mysqli_warning — Класс mysqli_warning
  - mysqli_sql_exception — Класс mysqli_sql_exception
  - Синонимы и устаревшие функции Mysqli
  - Список изменений
- Mysql_xdevapi
  - Установка и настройка
  - Предопределённые константы
  - Список изменений
  - Примеры
  - Функции Mysql_xdevapi
  - mysql_xdevapi\BaseResult — Интерфейс BaseResult
  - mysql_xdevapi\Client — Класс Client
  - mysql_xdevapi\Collection — Класс Collection
  - mysql_xdevapi\CollectionAdd — Класс CollectionAdd
  - mysql_xdevapi\CollectionFind — Класс CollectionFind
  - mysql_xdevapi\CollectionModify — Класс CollectionModify
  - mysql_xdevapi\CollectionRemove — Класс CollectionRemove
  - mysql_xdevapi\ColumnResult — Класс ColumnResult
  - mysql_xdevapi\CrudOperationBindable — Интерфейс CrudOperationBindable
  - mysql_xdevapi\CrudOperationLimitable — Интерфейс CrudOperationLimitable
  - mysql_xdevapi\CrudOperationSkippable — Интерфейс CrudOperationSkippable
  - mysql_xdevapi\CrudOperationSortable — Интерфейс CrudOperationSortable
  - mysql_xdevapi\DatabaseObject — Интерфейс DatabaseObject
  - mysql_xdevapi\DocResult — Класс DocResult
  - mysql_xdevapi\Exception — Класс Exception
  - mysql_xdevapi\Executable — Интерфейс Executable
  - mysql_xdevapi\ExecutionStatus — Класс ExecutionStatus
  - mysql_xdevapi\Expression — Класс Expression
  - mysql_xdevapi\Result — Класс Result
  - mysql_xdevapi\RowResult — Класс RowResult
  - mysql_xdevapi\Schema — Класс Schema
  - mysql_xdevapi\SchemaObject — Интерфейс SchemaObject
  - mysql_xdevapi\Session — Класс Session
  - mysql_xdevapi\SqlStatement — Класс SqlStatement
  - mysql_xdevapi\SqlStatementResult — Класс SqlStatementResult
  - mysql_xdevapi\Statement — Класс Statement
  - mysql_xdevapi\Table — Класс Table
  - mysql_xdevapi\TableDelete — Класс TableDelete
  - mysql_xdevapi\TableInsert — Класс TableInsert
  - mysql_xdevapi\TableSelect — Класс TableSelect
  - mysql_xdevapi\TableUpdate — Класс TableUpdate
  - mysql_xdevapi\Warning — Класс Warning
- Оригинальный MySQL — Оригинальный API-интерфейс доступа к MySQL-серверам
  - Установка и настройка
  - Список изменений
  - Предопределённые константы
  - Примеры
  - MySQL — Функции СУБД MySQL
- Mysqlnd — Встроенный драйвер MySQL
  - Обзор
  - Установка
  - Настройка во время выполнения
  - Несовместимости
  - Постоянное соединение
  - Статистика
  - Замечания
  - Управление памятью
  - API интеграции плагинов в драйвер MySQL Native Driver

# Oracle OCI8

# Введение

Внимание

Модуль УДАЛИЛИ из пакета PHP с версии 8.4.0.

Функции помогаеют работать с базой данных Oracle Database. Поддерживаются SQL и PL/SQL-выражения. Основной функционал представляет собой поддержку транзакций, привязку переменных PHP к соответствующим плейсхолдерам Oracle, расширенную поддержку больших объектов (LOB) и коллекций. Также поддерживаются кеширование результатов и такие возможности масштабирования Oracle как пул постоянных соединений базы данных (Database Resident Connection Pooling, DRCP).

# Установка и настройка

## Содержание

- Требования
- Установка
- Тестирование
- Настройка во время выполнения

## Требования

Модуль OCI8 3.0 включён в PHP 8. Также он доступен в » PECL. Для PHP 7, используйте OCI8 2.2 from » PECL. Для работы OCI8 требуются клиентские библиотеки Oracle 10g или выше.

Если база данных Oracle находится на той же машине, что и PHP, то все необходимые библиотеки и заголовочные файлы уже установлены. Если PHP установлен на другую машину, то используйте бесплатные библиотеки с » Oracle Instant Client.

Для использования Oracle Instant Client, установите `Basic` или `Basic Lite` zip-архив Oracle Instant Client или RPM или DMG пакет. При сборке PHP из исходного кода, также установите Instant Client `SDK`.

Необходимо использовать PHP с теми же или более свежими версиями библиотек Oracle, чем те, с которыми был собран модуль OCI8.

> Замечание:

> Принципы клиент-серверной сетевой совместимости Oracle, позволяют создавать соединения между различающимися версиями Oracle Client и Oracle Database. Подробности смотрите в документе совместимости ID 207303.1. В кратце, Oracle Client 19, 18 и 12.2 могут соединяться с Oracle Database 11.2 и выше. Oracle Client 12.1 может соединяться с Oracle Database 10.2 и выше. Oracle Client 11.2 может соединяться с Oracle Database 9.2 и выше.

> Замечание:

> Полный набор возможностей OCI8 возможен только при использовании новейших версий клиентских библиотек Oracle и базы данных.

## Установка

## Сборка PHP совместно с OCI8

Перед сборкой OCI8 изучите предыдущий раздел "Требования".

Перед стартом веб-сервера, OCI8 обычно требуется несколько переменных окружения Oracle (смотрите ниже) для обнаружения библиотек, конфигурационных файлов и установки некоторых базовых свойств, таких как кодировка, используемая библиотеками Oracle. Эти переменные должны быть установлены перед запуском любого PHP-процесса.

Бинарный файл PHP должен использовать ту же, или более свежую основную версию библиотек Oracle, чем ту, с которой он был собран. Например, если вы собрали OCI8 с библиотеками Oracle 19, то PHP также должен работать с библиотеками Oracle 19. Приложения PHP могут подключаться к другим версиям Oracle Database, так как Oracle имеет клиент-серверную совместимость разных версий.

## Установка OCI8 из PECL

Модуль OCI8 может быть включён в текущую установку PHP как автоматически, так и вручную с помощью » PECL.

- Если ваш компьютер находится за файерволом, установите прокси для PEAR, например:

      pear config-set http_proxy http://my-proxy.example.com:80/

- Запустите

      pecl install oci8

  Для PHP 7, используйте `pecl install oci8-2.2.0`

  При запросе введите либо значение `$ORACLE_HOME`, либо `instantclient,/path/to/instant/client/lib`.

  Обратите внимание: Не вводите имя переменной, такое как `$ORACLE_HOME` или `$HOME` т.к. она не будет развёрнута. Вместо этого, введите полный путь. Например `/opt/oracle/product/19c/dbhome_1` или `instantclient,/Users/myname/Downloads/instantclient_19_8`.

- Ошибка `oci8_dtrace_gen.h: No such file or directory` означает, что PHP был собран с поддержкой DTrace Dynamic Tracing. В таком случае устанавливайте так:

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- Добавьте в php.ini следующую строку:

      extension=oci8.so

  Убедитесь, что oci8.so установлен в директорию, заданную в директиве extension_dir файла php.ini.

## Установка OCI8 из PECL с помощью phpize

Если по каким-то причинам нет возможности воспользоваться командой `pecl`, можно самостоятельно загрузить пакет с сайта » PECL. Например oci8-3.0.0.tgz.

- Разархивируйте пакет:

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- Подготовьте его:

      phpize

- Сконфигурируйте используя `$ORACLE_HOME` или Instant Client

      ./configure -with-oci8=shared,$ORACLE_HOME

  or

      ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib

- Проинсталлируйте:

      make install

- Ошибка `oci8_dtrace_gen.h: No such file or directory` означает, что PHP был собран с поддержкой DTrace Dynamic Tracing. В таком случае перезапустите `configure` и `make`, предварительно установив переменную окружения:

      $ export PHP_DTRACE=yes

- Добавьте в php.ini следующую строку:

      extension=oci8.so

  Убедитесь, что oci8.so установлен в директорию, заданную в директиве extension_dir файла php.ini.

## Установка OCI8 в виде подгружаемого (shared) модуля во время сборки PHP

Указание опции конфигурации `shared` позволяет собрать OCI8 в виде динамически подгружаемой библиотеки. Сборка в виде подгружаемого модуля позволяет легко обновлять OCI8 без пересборки всего PHP.

Соберите OCI8 с помощью одной из следующих опций.

- При использовании бесплатных библиотек » Oracle Instant Client:

      ./configure --with-oci8=shared,instantclient,/путь/к/instant/client/lib

  Если Instant Client 12.2 (или более ранний) установлен из ZIP-архива, не забудьте в первую очередь создать символическую ссылку на библиотеку, например, так: `ln -s libclntsh.so.12.1 libclntsh.so`.

  Если Oracle Instant Client был установлен с помощью RPM, команда конфигурации будет выглядеть так:

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  Например, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- При использовании базы данных Oracle database или полной установке Oracle Client:

      ./configure --with-oci8=shared,$ORACLE_HOME

  Убедитесь, что пользователь, под которым запущен веб-сервер, (`nobody`, `www`) имеет доступ к библиотекам, файлам инициализации и tnsnames.ora (если используется) в папке `$ORACLE_HOME`. При использовании Oracle 10gR2, может понадобиться запуск утилиты $ORACLE_HOME/install/changePerm.sh для получения доступа к этой папке.

После настройки следуйте обычной процедуре сборки PHP, например, make install, после чего будет создано подгружаемая библиотека oci8.so. Возможно, вам потребуется вручную перенести её в папку модулей PHP, указанную опцией extension_dir вашего php.ini.

Для завершения установки OCI8 добавьте следующую строку в php.ini:

    extension=oci8.so

## Установка OCI8 в виде статически скомпилированного модуля

Сборка PHP со статическим подключением OCI8, используя одну из следующих конфигурационных опций.

- При использовании Oracle Instant Client:

      ./configure --with-oci8=instantclient,/путь/к/instant/client/lib

- При использовании базы данных Oracle или полной установке Oracle Client:

      ./configure --with-oci8=$ORACLE_HOME

После настройки следуйте обычной процедуре установки PHP, например, make install. После успешной сборки нет необходимости добавлять oci8.so в файл php.ini. Никаких дополнительных шагов сборки больше не требуется.

## Установка OCI8 в Windows

Модуль OCI8 можно добавить в PHP с помощью библиотек из репозитория » PECL или из директории `ext`, содержащейся в вашей инсталляции PHP.

Для библиотек Oracle 12c (и выше), раскомментируйте соответствующую строку в php.ini: `extension=php_oci8_12c.dll`, `extension=php_oci8_11g.dll` или `extension=php_oci8.dll`. Единовременно можно использовать только одну из этих библиотек. Более новые библиотеки могут содержать более продвинутый функционал. Состав доступных библиотек может меняться в зависимости от версии PHP. Убедитесь, что extension_dir указывает на директорию, содержащую библиотеки модулей PHP.

При использовании Instant Client, установите системную переменную окружения PATH на папку с библиотекой Oracle.

## Установка окружения Oracle

Перед использованием данного модуля, убедитесь, что переменные окружения Oracle правильно настроены для пользователя, под которым работает веб-сервер. Если ваш веб-сервер автоматически стартует при загрузке, то убедитесь, что окружение при загрузке также настроено корректно.

> Замечание:

> Не устанавливайте переменные окружения Oracle через putenv() в PHP-скрипте, потому что библиотеки Oracle могут быть загружены и проинициализированы до запуска вашего скрипта. Переменные, установленные через putenv() могут затем вызывать конфликты, падения и прочее непредсказуемое поведение. Некоторые функции могут работать, в то время как другие давать мелкие ошибки. Необходимо устанавливать эти переменные до запуска веб-сервера.

В Red Hat Linux и его вариантах, экспортируйте переменные в конце файла /etc/sysconfig/httpd. Другие системы с Apache 2 могут использовать скрипт envvars из папки bin в дистрибутиве Apache. Третьим вариантом является директива Apache `SetEnv` в файле httpd.conf, на каких-то системах она может работать, однако, известно, что на некоторых её недостаточно.

Чтобы удостовериться в корректной настройке переменных окружения, используйте функцию phpinfo() и проверьте, что раздел Environment (не Apache Environment) содержит ожидаемые переменные.

Следующая таблица содержит переменные, которые могут вам потребоваться. За подробностями обо всех доступных переменных обращайтесь к документации Oracle.

Общие переменные окружения Oracle
Название | Цель
--- | ---
ORACLE_HOME | Указывает на папку, с полностью установленной базой данных Oracle. Не устанавливайте эту переменную при использовании Oracle Instant Client, т.к. в этом нет необходимости и может вызвать проблемы при установке.
ORACLE_SID | Содержит имя базы данных на локальной машине, к которой идёт подключение. Нет необходимости устанавливать эту переменную при использовании Oracle Instant Client, или всегда передавать в параметрах соединения в функцию oci_connect().
LD_LIBRARY_PATH | Установите эту переменную (или её эквивалент на используемой платформе, например, `LIBPATH` или `SHLIB_PATH`) в местоположение библиотек Oracle, например, $ORACLE_HOME/lib или /usr/lib/oracle/18.5/client/lib. Обратите внимание, что для ZIP архивов Instant Client в Linux более надёжно использовать ldconfig. Обратитесь к инструкции по установке Instant Client. Для RPM пакетов Instant Client 19 (и старше), `ldconfig`, будет запущен автоматически. Кто-то использует `LD_PRELOAD` вместо `LD_LIBRARY_PATH`.
NLS_LANG | Это основная переменная, используемая для указания кодировки и настроек глобализации в библиотеках Oracle.
ORA_SDTZ | Устанавливает часовой пояс сессии Oracle.
TNS_ADMIN | Содержит папку, в которой хранятся конфигурационные файлы Oracle Net Services, такие как tnsnames.ora и sqlnet.ora. В ней нет необходимости, если строка соединения в функции oci_connect() использует синтаксис Easy Connect, такой как, например, `localhost/XE`. В ней также нет необходимости, если сетевые конфигурационные файлы содержатся в местах хранения по умолчанию, таких как /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin или /etc.

Менее используемые переменные окружения Oracle включают в себя `TWO_TASK`, `ORA_TZFILE`, а также различные установки глобализации Oracle наподобие переменных `NLS*` и `ORA_NLS_*`.

## Решение проблем

Самой частой проблемой при установке OCI8 является неправильная установка окружения Oracle. Обычно это выражается в проблеме при использовании функций oci_connect() или oci_pconnect(). Ошибка может проявляться в виде ошибок PHP, например, Call to undefined function oci_connect(), ошибок Oracle, таких как ORA-12705, или даже крушения Apache. Проверьте лог-файлы Apache на наличие ошибок запуска и вышеописанные разделы для разрешения этой проблемы.

Несмотря на то, что сетевые ошибки, наподобие ORA-12154 или ORA-12514 сигнализируют об ошибке в именовании или конфигурации сети Oracle, реальной причиной может быть некорректно установленное окружение PHP, из-за чего библиотеки Oracle не могут найти конфигурационный файл tnsnames.ora.

В Windows, использование нескольких версий Oracle на одной машине может легко вызвать их конфликты, которых можно избежать при соблюдении особых мер предосторожности, предусматривающих, что PHP использует корректную версию Oracle.

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

> Замечание: Если веб-сервер не стартует или падает при старте

> Проверьте, что Apache собран с библиотекой pthread:

>     # ldd /www/apache/bin/httpd
>       libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
>       libm.so.6 => /lib/libm.so.6 (0x4002f000)
>       libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
>       libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
>       libc.so.6 => /lib/libc.so.6 (0x4007e000)
>       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

> Если libpthread нет в списке, переустановите Apache:

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> Имейте в виду, что на некоторых системах, наподобие UnixWare, libpthread называется libthread. Таким образом, PHP и Apache должны быть настроены с помощью EXTRA_LIBS=-lthread.

## Тестирование

Набор тестов для модуля OCI8 располагается в директории ext/oci8/tests. После запуска тестов модуля OCI8 этот каталог также будет содержать журналы сбоев.

Перед запуском тестов PHP необходимо отредактировать файл details.inc и задать значения переменным $user, $password и строке соединения $dbase. Набор тестов OCI8 был разработан с учётной записью `SYSTEM`. Некоторые тесты не будут выполняться, если у тестирующего пользователя нет аналогичных разрешений.

Если тестируется пул резидентных подключений к базе данных Oracle (Database Resident Connection Pooling), необходимо установить для переменной $test_drcp значение `true` и проверить, что в строке соединения установили сервер, который соответствует пулу DRCP.

В качестве альтернативы редактированию файла details.inc выступает установка переменных окружения, например:

        $ export PHP_OCI8_TEST_USER=system
        $ export PHP_OCI8_TEST_PASS=oracle
        $ export PHP_OCI8_TEST_DB=localhost/XE
        $ export PHP_OCI8_TEST_DRCP=FALSE

Обратите внимание, в ряде оболочек эти переменные транслируются в PHP-процесс неправильно, и через этот метод тесты не смогут подключиться.

Затем необходимо установить необходимое окружение для базы данных Oracle. Если PHP запускается на тех же машинах, что и база данных Orcale, можно запустить:

        $ . /usr/local/bin/oraenv

В Oracle 11gR2 XE выполняют:

        $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

Отдельные оболочки требуют, чтобы в файле php.ini параметр variables_order содержал литеру `E`, например:

        variables_order = "EGPCS"

Запуск всех PHP-тестов выполняют командой:

        $ cd your_php_src_directory
        $ make test

или запускают только OCI8-тесты:

        $ cd your_php_src_directory
        $ make test TESTS=ext/oci8

После завершения тестов просмотрите журналы на наличие ошибок. На медленных системах отдельные тесты выполняются дольше, чем время ожидания теста по умолчанию, которое указали в файле run-tests.php. Чтобы это исправить, переменной окружения `TEST_TIMEOUT` устанавливают большее количество секунд.

На быстрых машинах с локальной базой данных, которую настроили на небольшую нагрузку (например, Oracle 11gR2 XE), часть тестов завершится неудачно с ошибками ORA-12516 или ORA-12520. Чтобы предотвратить это, значение параметра базы данных `PROCESSES` увеличивают следующими действиями:

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

        $ su - oracle

Установить необходимое окружение Oracle через сценарии oracle_env.sh или oraenv, как описали предыдущие параграфы.

Запустить утилиту командной строки SQL*Plus и увеличить значение параметра `PROCESSES`

        $ sqlplus / as sysdba
        SQL> alter system set processes=100 scope=spfile

Перезапустить базу данных:

        SQL> startup force

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации OCI8
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
oci8.connection_class | "" | `INI_ALL` |
oci8.default_prefetch | "100" | `INI_SYSTEM` |
oci8.events | Off | `INI_SYSTEM` |
oci8.max_persistent | "-1" | `INI_SYSTEM` | Объявлена устаревшей, начиная с PHP 8.1.0.
oci8.old_oci_close_semantics | Off | `INI_SYSTEM` |
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Доступна начиная с версии PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

Краткое разъяснение конфигурационных директив.

`oci8.connection_class` string

  Этот определяемый пользователем текст обязательно должен быть задан при использовании резидентного пула соединений базы данных Oracle (Database Resident Connection Pooling (DRCP)). Это позволяет суб-партиционирование пула соединений DRCP, что позволяет постоянным соединениям OCI8 из приложения заново использовать сессии базы данных от предыдущего PHP-скрипта, улучшая масштабируемость. Если приложение использует процесс из пула базы данных, ранее используемый с другим классом соединений, настройки сессии, такие как формат даты Oracle, будут сброшены. Это предотвращает случайный обмен информацией между различными приложениями.

  Значение может быть установлено во время выполнения скрипта с помощью ini_set() до установки соединения.

  Для использования DRCP, OCI8 должна быть собрана с библиотеками Oracle 11g или новее и база данных должна быть Oracle 11g или новее. Пул соединений DRCP в базе данных должен быть включён, `oci8.connection_class` должно быть установлено в одно и то же строковое значение для всех веб-серверов, выполняющих одно и то же приложение, а строка соединения OCI8 должна указывать на сервер из пула. Приложение должно использовать постоянные соединения.

`oci8.default_prefetch` int

  Эта опция устанавливает значение по умолчанию для количества экстра рядов, которые будут возвращены и автоматически закешированы при низкоуровневом запросе данных из базы данных. Установка значения в `0` выключает предварительную выборку (prefetching).

  Значение предварительной выборки не меняет количество возвращаемых пользователю рядов такими функциями как oci_fetch_array(); OCI8 внутренне обрабатывает предварительную выборку и кеширование рядов.

  Значение может быть установлено отдельно для каждого выражения (per-statement) с помощью oci_set_prefetch() до выполнения самого выражения.

  При использовании Oracle Database 12c или новее, предварительное значение, заданное PHP, может быть переопределено клиентским конфигурационным файлом Oracle `oraaccess.xml`. Обратитесь к документации Oracle.

  > Замечание: Большая предварительная выборка может улучшить производительность за счёт некоторого увеличенного использования памяти. Для запросов, возвращающих большие массивы данных, выгода в производительности будет значительной.

`oci8.events` bool

  Включение (`On`) позволяет уведомить PHP о событиях Быстрого Уведомления Приложений базы данных (Fast Application Notification (FAN)).

  Без FAN, если экземпляр базы данных или узел машины неожиданно даст сбой, PHP приложения могут быть заблокированы, ожидая ответа от базы данных до превышения времени ожидания TCP. С помощью событий FAN PHP приложения быстро будут уведомлены о сбоях, которые влияют на установленные ими соединения к базе данных. Модуль OCI8 подчистит неиспользуемые соединения в кеше постоянных соединений.

  При использовании директивы (`On`), база данных также должна быть настроена на отправку FAN событий.

  Поддержка FAN доступна, если OCI8 была слинкована с библиотеками Oracle 10gR2 (или более поздними) и соединение было осуществлено к Oracle Database 10gR2 (или более поздней версии).

`oci8.max_persistent` int

  Максимальное количество постоянных соединений OCI8 на один PHP процесс. Установка этой опции в -1 означает отсутствие лимита.

`oci8.old_oci_close_semantics` bool

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

`oci8.persistent_timeout` int

  Максимальное количество секунд, которое разрешается PHP-процессу держать неиспользуемое постоянное соединение открытым. Установка этой опции в -1 означает, что неиспользуемые соединения будут удержаны, пока PHP-процесс не завершит своё выполнение или соединение не будет принудительно закрыто с помощью функции oci_close().

  > Замечание: В PHP истечение срока действия неиспользуемых ресурсов не основано на уведомлениях. Оно случается когда PHP завершает обработку скрипта и проверяет отметку времени последних использованных ресурсов. Отсюда возникает следующий парадокс: неиспользуемые соединения могут быть закрыты только когда есть некоторая активность (хотя и не обязательно связанная с OCI8) в PHP-процессе. Если присутствует более одного PHP-процесса, то каждый из них в отдельности должен быть приведён в действие для того, чтобы инициировать истечение срока действия простаивающих ресурсов. Введение резидентного пула соединений базы данных (DRCP) в Oracle 11g разрешает проблемы с памятью и ресурсами, которые ранее пытались решить `oci8.max_persistent` и `oci8.persistent_timeout`.

`oci8.ping_interval` int

  Количество секунд, которое должно пройти до совершения пинга в течение выполнения oci_pconnect(). Пинг обеспечивает корректность соединения базы данных. Если установлена в 0, постоянные соединения будут пинговаться при каждом вызове oci_pconnect(). Для полного отключения пингов установите эту опцию в -1.

  > Замечание: Отключение пингов позволяет oci_pconnect() действовать с максимальной эффективностью, но PHP может быть неспособен определить непригодные соединения, например, при обрыве сети или при отключении базы данных Oracle после того, как PHP установил соединение, пока соединение вновь не будет использовано в скрипте. Проконсультируйтесь с документацией функции oci_pconnect() для более подробной информации.

`oci8.prefetch_lob_size` int

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

  Значение влияет на LOB, возвращаемые как экземпляры OCILob, а также на те, которые возвращаются с использованием `OCI_RETURN_LOBS`.

  Значение может быть установлено для каждого оператора с помощью функции oci_set_prefetch_lob() до выполнения оператора.

  > Замечание: Используйте с Oracle Database 12.2 или новее.

`oci8.privileged_connect` bool

  Эта опция позволяет соединениям использовать привилегированные внешние учётные записи `OCI_SYSOPER` или `OCI_SYSDBA`.

  > Замечание: Установка этой директивы в `On` позволит скриптам, запущенных с соответствующими пользовательскими привилегиями операционной системы, соединяться с базой данных в качестве привилегированных пользователей базы данных без требования пароля. Это может быть брешью системы безопасности.

`oci8.statement_cache_size` int

  Эта опция включает кеширование выражений, а также указывает сколько выражений необходимо кешировать. Для отключения кеширования выражений просто установите значение этой опции в 0.

  Кеширование выражений убирает необходимость передавать текст выражения к базе данных, а также обратную передачу различных метаданных об этом выражении обратно к PHP. Это может значительно улучшить общую производительность системы в приложениях, повторно использующих выражения в течение жизни одного соединения. Некоторые дополнительные "курсоры" баз данных могут остаться открытыми, подразумевая, что данные выражения будут использованы повторно.

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

  Эта опция чаще всего используется с постоянными соединениями.

  При использовании Oracle Database 12c или выше, предварительное значение, заданное PHP, можно переопределить клиентским конфигурационным файлом Oracle `oraaccess.xml`. Обратитесь к документации Oracle.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Функции и методы модуля OCI8
Константа | Описание
--- | ---
`OCI_ASSOC` | Флаг передают в функции oci_fetch_all() и oci_fetch_array(), чтобы получить результаты в виде ассоциативного массива.
`OCI_BOTH` | Флаг передают в функции oci_fetch_all() и oci_fetch_array(), чтобы получить результаты в виде массива с ассоциативными и числовыми индексами.
`OCI_COMMIT_ON_SUCCESS` | Режим выполнения запросов для функции oci_execute(). Автоматически фиксирует изменения в случае успешного выполнения запроса.
`OCI_CRED_EXT` | Флаг передают в функцию oci_connect() для выбора режима внешней или системной аутентификации.
`OCI_DEFAULT` | Смотрите описание константы `OCI_NO_AUTO_COMMIT`.
`OCI_DESCRIBE_ONLY` | Режим выполнения запросов для функции oci_execute(). Этот режим устанавливают, когда необходимо получить данные о выполнении запроса, а не выполнить сам запрос.
`OCI_EXACT_FETCH` | Константа устарела. Режим получения результатов запроса. Этот режим устанавливают, если приложение заранее знает, сколько строк вернёт результат. БД Oracle 8 и более поздние версии не выбирают результаты с упреждением в этом режиме, а курсоры уничтожаются автоматически после выборки ожидаемого количества строк, что может уменьшить требования сервера к ресурсам.
`OCI_FETCHSTATEMENT_BY_COLUMN` | Режим oci_fetch_all() по умолчанию.
`OCI_FETCHSTATEMENT_BY_ROW` | Альтернативный режим функции oci_fetch_all().
`OCI_LOB_BUFFER_FREE` | Флаг передают в метод OCILob::flush для перевода в режим освобождения буферов.
`OCI_NO_AUTO_COMMIT` | Режим выполнения запросов для функции oci_execute(). В этом режиме транзакция не завершается автоматически оператором COMMIT. Для повышения читаемости в новом коде вместо старой эквивалентной константы `OCI_DEFAULT` указывают эту константу.
`OCI_NUM` | Флаг передают в функции oci_fetch_all() и oci_fetch_array(), чтобы получить результаты в виде перечислимого массива — с числовыми индексами.
`OCI_RETURN_LOBS` | Флаг передают в функцию oci_fetch_array() для получения значения данных объекта LOB вместо дескриптора.
`OCI_RETURN_NULLS` | Флаг передают в функцию oci_fetch_array(), чтобы получить пустые элементы массива, если значение элемента строки равно `null`.
`OCI_SEEK_CUR` | Флаг передают в метод OCILob::seek, чтобы установить позицию для перемещения.
`OCI_SEEK_END` | Флаг передают в метод OCILob::seek, чтобы установить позицию для перемещения.
`OCI_SEEK_SET` | Флаг передают в метод OCILob::seek, чтобы установить позицию для перемещения.
`OCI_SYSDATE` | Устарела.
`OCI_SYSDBA` | Флаг передают в функцию oci_connect() для соединения с привилегиями SYSOPER. В файле php.ini потребуется включить опцию oci8.privileged_connect.
`OCI_SYSOPER` | Флаг передают в функцию oci_connect() для соединения с привилегиями SYSOPER. В файле php.ini потребуется включить опцию oci8.privileged_connect.
`OCI_TEMP_BLOB` | Флаг передают в метод OCILob::writeTemporary, чтобы указать, что требуется создать временный BLOB-объект.
`OCI_TEMP_CLOB` | Флаг передают в метод OCILob::writeTemporary, чтобы указать, что требуется создать временный CLOB-объект.

OCI8 привязка переменных и определение типов
Константа | Описание
--- | ---
`OCI_B_BFILE` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом BFILE.
`OCI_B_BIN` | Флаг передают в функцию oci_bind_by_name() для привязки необработанных данных.
`OCI_B_BLOB` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом BLOB.
`OCI_B_BOL` | Флаг передают в функцию oci_bind_by_name() для привязки BOOLEAN-переменной PL/SQL-запроса.
`OCI_B_CFILEE` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом CFILE.
`OCI_B_CLOB` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом CLOB.
`OCI_B_CURSOR` | Флаг передают в функцию oci_bind_by_name() для привязки курсоров, которые ранее получили из функции oci_new_descriptor().
`OCI_B_INT` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом INTEGER.
`OCI_B_NTY` | Флаг передают в функцию oci_bind_by_name() для привязки именованных типов данных.
`OCI_B_NUM` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом NUMBER.
`OCI_B_ROWID` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом ROWID.
`SQLT_AFC` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом CHAR.
`SQLT_AVC` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом VARCHAR2.
`SQLT_BDOUBLE` | Не поддерживается.
`SQLT_BFILEE` | То же, что и `OCI_B_BFILE`.
`SQLT_BFLOAT` | Не поддерживается.
`SQLT_BIN` | То же, что и `OCI_B_BIN`.
`SQLT_BLOB` | То же, что и `OCI_B_BLOB`.
`SQLT_BOL` | То же, что и `OCI_B_BOL`.
`SQLT_CFILEE` | То же, что и `OCI_B_CFILEE`.
`SQLT_CHR` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом VARCHAR2. Константа также работает с функцией oci_bind_by_name().
`SQLT_CLOB` | То же, что и `OCI_B_CLOB`.
`SQLT_FLT` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом FLOAT.
`SQLT_INT` | То же, что и `OCI_B_INT`.
`SQLT_LBI` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом LONG RAW.
`SQLT_LNG` | Флаг передают в функцию oci_bind_by_name() для привязки переменных с типом LONG.
`SQLT_LVC` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом LONG VARCHAR.
`SQLT_NTY` | То же, что и `OCI_B_NTY`.
`SQLT_NUM` | То же, что и `OCI_B_NUM`.
`SQLT_ODT` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом LONG.
`SQLT_RDD` | То же, что и `OCI_B_ROWID`.
`SQLT_RSET` | То же, что и `OCI_B_CURSOR`.
`SQLT_STR` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом STRING.
`SQLT_UIN` | Не поддерживается.
`SQLT_VCS` | Флаг передают в функцию oci_bind_array_by_name() для привязки массивов элементов с типом VARCHAR.

Типы дескрипторов OCI8
Константа | Описание
--- | ---
`OCI_DTYPE_FILE` | Флаг указывает функции oci_new_descriptor(), что требуется инициализация дескриптора с типом FILE.
`OCI_DTYPE_LOB` | Флаг указывает функции oci_new_descriptor(), что требуется инициализация дескриптора с типом LOB.
`OCI_DTYPE_ROWID` | Флаг указывает функции oci_new_descriptor(), что требуется инициализация дескриптора с типом ROWID.
`OCI_D_FILE` | То же, что и `OCI_DTYPE_FILE`.
`OCI_D_LOB` | То же, что и `OCI_DTYPE_LOB`.
`OCI_D_ROWID` | То же, что и `OCI_DTYPE_ROWID`.

Константы | Описание
--- | ---
Константы прозрачной для приложений обработки отказов (TAF) модуля OCI8
`OCI_FO_ABORT` (int) | Обработка отказа не удалась и невозможно повторить попытку.
`OCI_FO_BEGIN` (int) | Драйвер механизма отказоустойчивости обнаружил потерянное соединение и начал аварийное переключение.
`OCI_FO_END` (int) | Обработка отказа завершилась успешно.
`OCI_FO_ERROR` (int) | Переключение при отказе не удалось, но это удобный для приложения случай обработать ошибку и вернуть флаг `OCI_FO_RETRY`, чтобы повторить попытку обработки отказа.
`OCI_FO_NONE` (int) | Пользователь не запросил тип аварийного переключения.
`OCI_FO_REAUTH` (int) | Пользователь БД Oracle прошёл повторную аутентификацию.
`OCI_FO_RETRY` (int) | БД Oracle должна повторить попытку обработать отказ. Механизм TAF, если требуется, повторяет попытку обработки отказа, если при переключении на новое соединение возникла ошибка. Обычно коду приложения требуется выдержать паузу, прежде чем вернуть флаг `OCI_FO_RETRY`.
`OCI_FO_SELECT` (int) | Пользователь также запросил отработку отказа при выполнении инструкции SELECT. Это разрешает пользователям с открытыми курсорами продолжать извлечение данных из курсоров после сбоя.
`OCI_FO_SESSION` (int) | Пользователь запросил только обработку отказа сессии. Например, если произошла потеря пользовательского соединения, в резервной копии для пользователя автоматически создаётся новая сессия. Этот тип аварийного переключения не пытается восстановить SELECT-запросы.
`OCI_FO_TXNAL` (int) | Пользователь запросил обработку отказа транзакции.

# Примеры

Эти примеры выполняются под пользователем `HR`, который является образцом из "Human Resources" схемы, поставляемой вместе с базой данных Oracle. Возможно потребуется разблокировать этот аккаунт и переустановить для него пароль, чтобы использовать его.

Примеры подключаются к базе данных `XE` на вашем компьютере. Вы можете заменить строки с подключением для использования своих баз данных.

Пример #1 Простой запрос

Данный пример показывает запрос и результат. Выражения в OCI8 используют последовательность из шагов подготовка-выполнение-выборка.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Подготовка выражения
    $stid = oci_parse($conn, 'SELECT * FROM departments');
    if (!$stid) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Выполним логику запроса
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Получим результат запроса
    print "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        print "<tr>\n";
        foreach ($row as $item) {
            print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        print "</tr>\n";
    }
    print "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Вставка с использованием привязанных переменных

Привязывание переменных повышают производительность за счёт повторного использования контекста запроса и кеширования. Также они повышают безопасность блокируя некоторые типы SQL-инъекций.

    <?php

    // Создайте таблицу перед выполнением:
    //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

    $id = 60;
    $data = 'Some data';

    oci_bind_by_name($stid, ':myid', $id);
    oci_bind_by_name($stid, ':mydata', $data);

    $r = oci_execute($stid);  // выполнение и фиксация

    if ($r) {
        print "Была вставлена одна строка";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Привязка в WHERE выражении запроса

Пример единичной привязки скаляра.

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Выведет
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #4 Вставка данных в поле типа CLOB

Для больших данных используйте длинные двоичные объекты (BLOB) или длинные символьные объекты (CLOB). Данный пример использует тип данных CLOB.

    <?php

    // Создайте таблицу перед выполнением:
    //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $mykey = 12343;  // произвольный ключ для данного примера;

    $sql = "INSERT INTO mytable (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Получение CLOB данных

    $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // В цикле, очищение больших переменных перед повторным получением данных, уменьшает пиковое потребление памяти PHP
        unset($row);
    }
    print '</table>';

    ?>

Пример #5 Использование PL/SQL хранимых процедур

Вы должны привязывать переменную для каждого возвращаемого значения и опционально для каждого аргумента функции.

    <?php

    /*
      До выполнения PHP-скрипта сойздайте хранимую процедуру в
      SQL*Plus или SQL Developer:

      CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
      BEGIN
          RETURN p * 3;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // выведет 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #6 Использование PL/SQL хранимых процедур

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

    <?php

    /*
      До выполнения PHP-скрипта сойздайте хранимую процедуру в
      SQL*Plus или SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // выведет 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #7 Вызов PL/SQL процедур, возвращающих `REF CURSOR`

Каждое возвращаемое значение из запроса является `REF CURSOR`.

    <?php
    /*
      Создайте PL/SQL хранимую процедуру:

      CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
          rc SYS_REFCURSOR;
      BEGIN
          OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
          RETURN rc;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
        echo "<tr>\n";
        $rc = $row['MFRC'];
        oci_execute($rc);  // возвращает значение поля из запроса в виде указателя
        while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
            echo "    <td>" . $rc_row['CITY'] . "</td>\n";
        }
        oci_free_statement($rc);
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Выведет:
    //   Beijing
    //   Bern
    //   Bombay
    //   Geneva

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# Работа с соединениями OCI8 и Connection Pooling

## Функции подключения

Модуль OCI8 предоставляет три различных функции для подключения к серверу Oracle. Стандартная функция соединения — oci_connect(). Она создаёт соединение к базе данных Oracle и возвращает ресурс, который используется при последующих обращениях к БД.

Подключение к серверу Oracle является достаточно дорогостоящей операцией с точки зрения времени, которое требуется для выполнения. Функция oci_pconnect() использует постоянный кеш соединений, которые могут быть повторно использованы различными запросами скриптов. Это означает, что затраты на установку соединения, как правило, происходят только единожды на один процесс PHP (или на потомка Apache).

Если приложение соединяется к серверу Oracle, используя особый набор данных для каждого веб-пользователя, то постоянный кеш соединений, используемый функцией oci_pconnect() будет менее полезным, поскольку количество одновременных пользователей вырастает до того уровня, где он может начать оказывать негативное влияние на общую производительность сервера Oracle из-за поддержания слишком большого количества простаивающих соединений. Если приложение настроено таким образом, то рекомендуется либо настроить его с помощью параметров конфигурации oci8.max_persistent и oci8.persistent_timeout (это даст возможность управления размером кеша постоянных соединений и их время жизни), либо использовать Oracle Database Resident Connection Pooling (в Oracle Database 11g и новее), либо использовать функцию oci_connect() вместо неё.

Вместе oci_connect() и oci_pconnect() используют кеш подключений; если множество вызовов oci_connect() использует одинаковые параметры в данном скрипте, второй и последующие вызовы вернут существующий дескриптор соединения. Кеш, который использует функция oci_connect(), очищается по завершению выполнения скрипта, или когда соединение неявно закрывается. У функции oci_pconnect() похожее поведение, хотя её кеш обрабатывается отдельно и остаётся действующим между HTTP-запросами.

Эта возможность кеширования означает, что два дескриптора не изолированы транзакционно (они на самом деле являются одним и тем же дескриптором, поэтому здесь нет никакой изоляции). Если приложению необходимы два отдельных транзакционно изолированных соединения, то необходимо использовать функцию oci_new_connect().

Кеш функции oci_pconnect() очищается и закрываются все соединения к БД, когда завершается процесс PHP. Поэтому эффективное использование постоянных соединений требует, чтобы PHP был модулем Apache или использовался с FPM или подобным. Постоянные соединения не будут иметь никаких преимуществ перед oci_connect(), когда PHP используется с CGI или через командную строку.

Функция oci_new_connect() каждый раз создаёт новое соединение с сервером Oracle, несмотря на то, что другие соединения могут уже существовать. Высоконагруженным веб-приложениям следует избегать использования oci_new_connect(), особенно в самых загруженных частях приложения.

Постоянные соединения могут быть закрыты пользователем, что даёт более полный контроль над использованием ресурсов. Также постоянные соединения могут быть закрыты автоматически, если не осталось переменных PHP указывающих на них, например при завершении выполнения пользовательской функции. Закрытие соединения откатит все не подтверждённые транзакции. Эти изменения в постоянных подключениях делают их поведение аналогичным не постоянным соединениям. Чтобы включить старое поведение, задайте опцию oci8.old_oci_close_semantics значением On.

Автоматическое пересоздание постоянных соединений после перезапуска процессов Apache или FPM, означает, что Oracle Database `LOGON` рекомендуется только для настройки атрибутов сеанса, а не для запросов на подключение пользователей для отдельных приложений.

## Создание пула соединений DRCP

PHP поддерживает постоянный пул соединений Oracle 11g (DRCP). DRCP позволяет более эффективно использовать память СУБД и предоставляет высокую масштабируемость. Изменять код приложения для использования DRCP либо нет необходимости, либо требуются минимальные изменения.

DRCP подходит для приложений, которые подключаются используя несколько схем БД и сохраняют соединения к БД открытыми короткий промежуток времени. Другим приложениям следует использовать доступные по умолчанию `Dedicated` серверные процессы или использовать `Shared` сервера.

DRCP приносит пользу всем трём функциям подключения, однако предоставляет самую высокую масштабируемость, когда соединения создаются с помощью функции oci_pconnect().

Чтобы функциональность DRCP была доступна в OCI8, клиентские библиотеки Oracle, используемые в PHP, и версия сервера баз данных должны быть 11g и новее.

Документация по DRCP находится в нескольких руководствах Oracle. К примеру, смотрите » Конфигурирование пула постоянных соединений базы данных в документации Oracle для информации по использованию. Документ » техническое описание DRCP содержит дополнительную информацию по DRCP.

Для использования DRCP, установите модуль OCI8 и библиотеки Oracle 11g (или новее) и затем выполните следующие действия:

- Как привилегированный администратор БД воспользуйтесь программой наподобие SQL*Plus, чтобы запустить пул соединений в СУБД:

          SQL> execute dbms_connection_pool.start_pool;

- Дополнительно можно использовать `dbms_connection_pool.alter_param()`, чтобы конфигурировать параметры DRPC. Текущие настройки пула могут быть получены из представления `DBA_CPOOL_INFO`.

- Обновите используемую строку соединения. К примеру, для приложений PHP, которые сейчас соединяются, используя Network Connect Name `MYDB`:

          $c = oci_pconnect("myuser", "mypassword", "MYDB");

  измените файл tnsnames.ora и добавьте оператор `(SERVER=POOLED)`, например:

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
                 (SERVER=POOLED)))

  В качестве альтернативы можно изменить синтаксис упрощённого соединения в PHP и добавить туда `:POOLED` после имени сервиса:

          $c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");

- Отредактируйте php.ini и выберите имя класса соединения. Это имя устанавливает логическое разделение пула соединений и может использоваться, чтобы изолировать пул для отдельных приложений. Любое PHP-приложение с одинаковым именем пользователя и классом для соединения будет иметь возможность совместно использовать соединения в пуле, получая бОльшую масштабируемость.

          oci8.connection_class = "MY_APPLICATION_NAME"

- Запустите приложение, соединяющееся с базой 11g и новее.

> Замечание:

> Приложения, использующие Oracle 10g, которые требуют производительности от постоянных соединений, могут уменьшить количество памяти сервера БД, которое используется `Shared`-серверами Oracle (ранее известные как многопоточные сервера). Обратитесь к документации Oracle для более подробной информации.

> Замечание:

> При изменении пароля через DRCP-соединение будет выдаваться ошибка ORA-56609: Usage not supported with DRCP. Это документированное ограничение of Oracle Database 11g.

# Поддержка OCI8 Fast Application Notification (FAN)

Поддержка FAN обеспечивает быстрое переподключение в случае сбоев, что обеспечивает высокую доступность базы данных Oracle. Эта функциональность позволяет PHP OCI8 скрипту получать оповещения в случае если база данных или сервер, на котором она запущена, становятся недоступны. Без FAN, OCI8 может подвиснуть, пока не будет превышено время ожидания подключения и возвращена ошибка, что может занять несколько минут. Разрешение FAN в OCI8 позволяет приложениям определять такие ошибки и переподключаться к доступному экземпляру базы данных без ожидания ответа от недоступной базы.

Поддержка FAN доступна если клиентские библиотеки Oracle, с которыми собран PHP, и база данных Oracle имеют версию 10gR2 или более позднюю.

FAN даёт преимущества пользователям кластерной технологии Oracle (RAC), так как подключение к доступной базе данных может быть произведено мгновенно. Пользователи Oracle Data Guard с брокером могут наблюдать события FAN создаваемые при переходе резервной базы в режим основной. Отдельные установленные экземпляры базы данных будут посылать события FAN при своём перезапуске.

Для активных соединений, когда сервер или экземпляр базы становятся недоступны, будет возвращена ошибка соединения для текущей запущенной функции модуля OCI8. При последующем переподключении PHP-скрипта будет установлено соединение с работающим экземпляром базы данных. Также модуль OCI8 прозрачно зачищает все ожидающие соединения, затронутые падением сервера или базы данных, так что новые соединения будут нормально устанавливаться без оглядки на какие-либо проблемы с сервисом.

Если oci8.events установлено как `On`, то предполагается, что oci8.ping_interval установлено в значение -1, так как включение событий FAN предоставляет проактивное управление ожидающими соединениями.

Для включения поддержки FAN в PHP OCI8, соберите PHP OCI8 с библиотеками Oracle 10gR2 или более поздними и выполните следующие шаги:

- Под аккаунтом привилегированного администратора баз данных, с помощью программ типа SQL*Plus разрешите сервису базы отправлять оповещения FAN, к примеру:

          SQL> execute dbms_service.modify_service(
                         SERVICE_NAME        => 'sales',
                         AQ_HA_NOTIFICATIONS => TRUE);

- Добавьте в php.ini

          oci8.events = On

- Если приложение не обрабатывает ошибки соединения OCI8, модифицируйте его таким образом, чтобы обрабатывало и производило, например, переподключение и перезапуск запросов.
- Запустите приложение соединяясь с базой данных Oracle версии 10gR2 или выше.

# Поддержка прозрачного для приложений восстановления после отказа (Transparent Application Failover или TAF) для OCI8

TAF — функция базы данных Oracle, которая обеспечивает высокую доступность. TAF помогает OCI8-приложениям PHP автоматически переподключаться к предварительно настроенной базе данных при сбое подключения к базе данных из-за сбоя экземпляра или сети.

В сконфигурированной системе базы данных Oracle TAF-обработка происходит, когда PHP-приложение обнаруживает, что экземпляр базы данных не работает или недоступен. Он устанавливает соединение с другим узлом в конфигурации Oracle » RAC, базой данных горячего резерва или самим экземпляром базы данных. Подробнее об OCI TAF рассказывает краткое руководство » Oracle Call Interface Programmer's Guide.

Callback-функцию приложения регистрируют функцией oci_register_taf_callback(). В процессе восстановления после отказа исполнение приложения приостанавливается и вызывается зарегистрированная callback-функция. Эта функция будет оповещать приложение о событиях процесса восстановления. Если восстановление завершилось успешно, управление возвращается приложению. Если восстановление завершилось неудачно, то очередные обращения к базе данных завершаются с ошибкой, поскольку отсутствует подключение.

Когда соединение переходит к другой базе данных, обратный вызов может сбросить любое необходимое состояние соединения, например, перевыполнить необходимую команду ALTER SESSION, если для сервиса базы данных не включили параметр -failover_restore.

Регистрацию callback-функции приложения удаляют вызовом функции oci_unregister_taf_callback().

## настройка TAF

TAF настраивают на стороне PHP-модуля OCI8 или в конфигурации базы данных. Если настроено и там, и там, предпочтение отдаётся настройкам на стороне базы данных.

Настроить TAF в PHP-модуле OCI8 (на стороне клиента) можно через параметр FAILOVER_MODE в части CONNECT_DATA дескриптора соединения. Подробнее о настройке TAF на стороне клиента рассказывает секция «Настройка прозрачного переключения приложений при отказе» (Configuring Transparent Application Failover) краткого руководства » Oracle Database Net Services Administrator's Guide.

Пример настройки TAF в файле tnsnames.ora для переподключения к той же самой БД:

        ORCL =
          (DESCRIPTION =
            (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
            (CONNECT_DATA =
              (SERVICE_NAME = orclpdb1)
              (FAILOVER_MODE =
                (TYPE = SELECT)
                (METHOD = BASIC)
                (RETRIES = 20)
                (DELAY = 15))))

TAF также настраивается на стороне базы данных путём изменения целевой службы утилитой » srvctl (для RAC) или через пакетную процедуру » DBMS_SERVICE.MODIFY_SERVICE (для одиночных экземпляров баз данных).

## Callback-функции TAF в модуле OCI8

Callback-функция TAF — функция приложения, которую можно зарегистрировать для вызова во время аварийного переключения. При восстановлении соединения функция вызывается несколько раз.

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

Интерфейс callback-функции модуля TAF:

function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

`connection`

  Идентификатор соединения Oracle, на котором функцией oci_register_taf_callback() зарегистрировали callback-функцию TAF. Соединение недействительно, пока восстановление не завершится успешно.

`event`

  Событие восстановления означает текущий статус восстановления.

  - `OCI_FO_BEGIN` означает, что произошла потеря соединения и процесс восстановления начат.

  - `OCI_FO_END` означает удачное восстановление соединения.

  - `OCI_FO_ABORT` означает, что восстановление завершилось неудачно и попыток восстановления больше не будет.

  - `OCI_FO_ERROR` также означает, что восстановление завершилось с ошибкой, но приложению даётся возможность обработать ошибку и вернуть OCI_FO_RETRY для ещё одной попытки восстановления.

  - `OCI_FO_REAUTH` означает, что пользователь Oracle был повторно аутентифицирован.

`type`

  Тип восстановления после отказа. Это позволяет функции понять, какой тип восстановления запрошен приложением. Допустимы такие значения:

  - `OCI_FO_SESSION` означает, что пользователь запросил только восстановление сессии. К примеру, если соединение пропало, то будет создана новая сессия на резервном сервере. Этот тип восстановления не будет пытаться восстановить запросы типа SELECT.

  - `OCI_FO_SELECT` означает, что запрошено восстановление запросов SELECT. Это позволит использовать открытый курсор для извлечения значений после восстановления.

`return value`

  - `0` означает, что шаги восстановления после отказа должны продолжаться нормально.

  - `OCI_FO_RETRY` означает, что необходимо попробовать восстановиться ещё раз. В случае возникновения ошибки при переходе на новое соединение TAF может повторить переход на другой ресурс. Обычно перед возвращением кода OCI_FO_RETRY рекомендуется некоторое время подождать.

Пример #1 Регистрация callback-функции TAF

    <?php

    // Определяем callback-функцию в пространстве пользователя
    class MyClass
    {
        public static $retry_count;

        public static function TAFCallback($conn, $event, $type)
        {
            switch ($event) {
                case OCI_FO_BEGIN:
                    printf(" Failing Over ... Please stand by\n");
                    printf(" Failover type was found to be %s \n",
                           (($type==OCI_FO_SESSION) ? "SESSION"
                            :(($type==OCI_FO_SELECT) ? "SELECT" : "UNKNOWN!")));
                    self::$retry_count = 0;
                    break;
                case OCI_FO_ABORT:
                    // Приложение больше не может использовать базу данных
                    printf(" Восстановление невозможно.\n");
                    break;
                case OCI_FO_END:
                    // Восстановление завершилось успешно. Оповестим пользователей, что была проблема.
                    printf(" Восстановление завершено ... восстанавливаю работу\n");
                    break;
                case OCI_FO_REAUTH:
                    printf(" Пользователь переавторизован ... восстанавливаю работу\n");
                    // Заново выполняем все необходимые ALTER SESSION
                    // т.е. oci_parse($conn, ‘ALTER SESSION …’) ;
                    break;
                case OCI_FO_ERROR:
                    // Прекращаем попытки соединения, если их было более 20.
                    if (self::$retry_count >= 20)
                        return 0;
                    printf(" Ошибка восстановления. Повторная попытка через 10 секунд...\n");
                    sleep(10);
                    self::$retry_count++;
                    return OCI_FO_RETRY; // retry failover
                    break;
                default:
                    printf("Неизвестное событие восстановления: %d.\n", $event);
                    break;
            }
            return 0;
        }
    }

    $fn_name = 'MyClass::TAFCallback';

    $conn = oci_connect('hr', 'welcome', 'orcl');
    $sysconn = oci_connect('system', 'oracle', 'orcl');

    // Используйте привилегированное соединение для создания SQL-запроса, который инициирует отработку отказа
    $sql = <<< 'END'
    select unique 'alter system disconnect session '''||sid||','||serial#||''''
    from v$session_connect_info
    where sid = sys_context('USERENV', 'SID')
    END;

    $s = oci_parse($conn, $sql);
    oci_execute($s);
    $r = oci_fetch_array($s);
    $disconnectssql = $r[0];

    oci_register_taf_callback($conn, $fn_name); // Зарегистрируйте TAFCallback для Oracle TAF

    print "Разбор пользовательского запроса\n";
    $sql = "select systimestamp from dual";
    $stmt = oci_parse($conn, $sql);

    // Например, если соединение было потеряно на этом шаге, функция oci_execute()
    // определит это и запустит процедуру восстановления. В процессе восстановления
    // функция oci_execute() будет вызывать зарегистрированную callback-функцию
    // несколько раз. Если восстановление пройдёт успешно, callback-функция создаст новое соединение
    // и выполнение функции oci_execute() продолжится в нормальном режиме.
    // Настройки сессии могут быть сброшены в callback-функции.
    // Если восстановление завершится неудачно, функция oci_execute() вернёт ошибку,
    // поскольку будет отсутствовать соединение.

    // Отключите пользователя, который инициирует аварийное переключение
    print "Отключение пользователя\n";
    $discsql = oci_parse($sysconn, $disconnectssql);
    oci_execute($discsql);

    print "Выполнение пользовательского запроса\n";
    $e = oci_execute($stmt);
    if (!$e) {
        $m = oci_error($stmt);
        trigger_error('Не удалось выполнить условие:'. $m['message'], E_USER_ERROR);
    }
    $row = oci_fetch_array($stmt);
    print $row[0] . "\n";

    // Выполняем другие SQL-запросы на новом подключении
    // $stmt = oci_parse($conn,  . . .);

    ?>

## Смотрите также

- oci_register_taf_callback()
- oci_unregister_taf_callback()

# OCI8 и динамическая трассировка DTrace

OCI8 2.0 содержит статические зонды DTrace, которые можно использовать в операционных системах, которые поддерживают DTrace. Более подробно взаимоотношения PHP и DTrace описывает раздел Динамическая трассировка DTrace.

## Установка OCI8 с поддержкой DTrace

Для включения поддержки DTrace в PHP OCI8, соберите OCI8 как разделяемый модуль после установки переменной окружения `PHP_DTRACE`.

    $ export PHP_DTRACE=yes
    $ pecl install oci8

Отредактируйте php.ini, задав extension_dir равным директории, в которой создался oci8.so, а также включите модуль следующим образом:

    extension=oci8.so

Если вы установили PHP OCI8 из PECL с использованием phpize и configure (вместо pecl), вам все ещё будет необходимо установить `PHP_DTRACE=yes`. Это потому, что опция `--enable-dtrace` будет проигнорирована ограниченным скриптом configure модуля PECL.

Более подробно об установке PECL модулей читайте в разделе Установка модулей PECL.

## Статические зонды DTrace в PHP OCI8

Следующие статические зонды доступны в PHP OCI8
Имя зонда | Описание зонда | Аргументы зонда
--- | --- | ---
`oci8-connect-entry` | Инициируется oci_connect(), oci_pconnect() и oci_new_connect(). Срабатывает до того, как соединение было установлено. | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
`oci8-connect-return` | Срабатывает после установки соединения. | void *connection
`oci8-check-connection` | Срабатывает, если ошибка Oracle может привести к порче соединения. | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
`oci8-sqltext` | Срабатывает при запуске oci_parse(). | void *connection, char *client_id, void *statement, char *sql
`oci8-connection-close` | Срабатывает, когда соединение окончательно уничтожено. | void *connection
`oci8-error` | Срабатывает, если произошла ошибка Oracle. | int status, long errcode
`oci8-execute-mode` | Срабатывает при oci_execute() для выявления режима запуска. | void *connection, char *client_id, void *statement, unsigned int mode

Эти зонды полезны при отладке скриптов OCI8.

Параметры connection и statement являются указателями на внутренние структуры, используемые для отслеживания соединений и запущенных запросов.

Параметр client_id устанавливается функцией oci_set_client_identifier().

Ядро PHP также содержит статические зонды. Смотрите раздел Статические зонды DTrace в ядре PHP.

Внутренние отладочные зонды DTrace в OCI8
Имя зонда
`oci8-connect-expiry`
`oci8-connect-lookup`
`oci8-connect-p-dtor-close`
`oci8-connect-p-dtor-release`
`oci8-connect-type`
`oci8-sesspool-create`
`oci8-sesspool-stats`
`oci8-sesspool-type`

Эти зонды полезны для разработчиков модуля OCI8. Для более детальной информации изучайте исходные коды OCI8.

## Получение списка статических зондов DTrace в PHP OCI8

Для получения списка доступных зондов, запустите процесс PHP и, затем, запустите:

    # dtrace -l

Вывод будет примерно следующим:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
       17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
       18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
       19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
       20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
       21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
       22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
       23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
       24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
       25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
       26 phpoci22116           oci8.so                     php_oci_error oci8-error
       27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
       28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
       29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
       30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
       31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

Столбец "Provider" состоит из `phpoci` и идентификатора запущенного процесса PHP.

Столбец "Function" содержит имена внутренних, написанных на C, функций PHP, в которых содержатся соответствующие провайдеры (Provider).

Если процесс PHP не запущен, то никаких зондов PHP показано не будет.

## Пример использования DTrace с PHP OCI8

В этом примере продемонстрированы основы скриптового языка DTrace D.

Пример #1 user_oci8_probes.d для трассировки всех статических зондов PHP OCI8 с помощью DTrace на пользовательском уровне

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::oci8-connect-entry
    {
        printf("%lld: PHP connect-entry\n", walltimestamp);
        printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
        printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
        printf("  session_mode=%ld\n", (long)arg3);
        printf("  persistent=%d\n", (int)arg4);
        printf("  exclusive=%d\n", (int)arg5);
    }

    php*:::oci8-connect-return
    {
        printf("%lld: PHP oci8-connect-return\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-connection-close
    {
        printf("%lld: PHP oci8-connect-close\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-error
    {
        printf("%lld: PHP oci8-error\n", walltimestamp);
        printf("  status=%d\n", (int)arg0);
        printf("  errcode=%ld\n", (long)arg1);
    }

    php*:::oci8-check-connection
    {
        printf("%lld: PHP oci8-check-connection\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  is_open=%d\n", arg2);
        printf("  errcode=%ld\n", (long)arg3);
        printf("  server_status=%lu\n", (unsigned long)arg4);
    }

    php*:::oci8-sqltext
    {
        printf("%lld: PHP oci8-sqltext\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
    }

    php*:::oci8-execute-mode
    {
        printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  mode=0x%x\n", arg3);
    }

В этом скрипте с dtrace используется опция `-Z`, позволяющая ему запускаться даже если никаких процессов PHP не запущено. Если не задать данную опцию, то скрипт сразу же прекратит свою работу, так как отсутствуют зонды для отслеживания.

На многопроцессорных машинах порядок зондов может быть не последовательным. Это зависит от того, на каких ядрах работают зонды и каким образом потоки мигрируют между ядрами. В такой ситуации имеет смысл ориентироваться на временные метки зондов.

Скрипт отслеживает все сообщения статических зондов PHP OCI8 уровня пользователя на протяжении работы скрипта PHP. Запускаем скрипт D:

    # ./user_oci8_probes.d

Запускаем скрипт PHP или своё приложение. D-скрипт будет выводить все аргументы зондов при их срабатывании. К примеру, простой скрипт PHP, выполняющий запрос к базе данных может создавать следующие сообщения:

    1381794982092854582: PHP connect-entry
      credentials="hr@localhost/pdborcl"
      charset=""
      session_mode=0
      persistent=0
      exclusive=0
    1381794982183158766: PHP oci8-connect-return
      connection=0x7f4a7907bfb8
    1381794982183594576: PHP oci8-sqltext
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      sql="select * from employees"
    1381794982183783706: PHP oci8-execute-mode
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      mode=0x20
    1381794982444344390: PHP oci8-connect-close
      connection=0x7f4a7907bfb8

После завершения диагностики D-скрипт можно прервать с помощью нажатия ``CTRL`+`C``.

## Смотрите также

- Динамическая трассировка DTrace

# Поддерживаемые типы данных

Данный драйвер поддерживает следующие типы данных при использовании функции oci_bind_by_name() для связки параметров:
Тип | Отображение
--- | ---
`SQLT_NTY` | Связывает оригинальный тип коллекции из объекта коллекции PHP, например, создаваемых функцией oci_new_collection().
`SQLT_BFILEE` | Связывает оригинальный дескриптор, например, полученный с помощью функции oci_new_descriptor().
`SQLT_CFILEE` | Связывает оригинальный дескриптор, например, полученный с помощью функции oci_new_descriptor().
`SQLT_CLOB` | Связывает оригинальный дескриптор, например, полученный с помощью функции oci_new_descriptor().
`SQLT_BLOB` | Связывает оригинальный дескриптор, например, полученный с помощью функции oci_new_descriptor().
`SQLT_RDD` | Связывает оригинальный дескриптор, например, полученный с помощью функции oci_new_descriptor().
`SQLT_NUM` | Конвертирует параметр PHP в тип long языка 'C', и привязывает к этому значению.
`SQLT_RSET` | Связывает оригинальный дескриптор выражения, например, полученный из функции oci_parse() или из других запросов OCI.
`SQLT_BOL` | Связывает PHP параметр с PL/SQL BOOLEAN
`SQLT_CHR` и любой другой тип | Преобразовывает параметр PHP к строковому типу и привязывает его в виде строки.

Поддерживаются следующие типы при извлечении столбцов из набора данных:
Тип | Отображение
--- | ---
`SQLT_RSET` | Создаёт ресурс выражения oci для представления курсора.
`SQLT_RDD` | Создаёт объект ROWID.
`SQLT_BLOB` | Создаёт объект LOB.
`SQLT_CLOB` | Создаёт объект LOB.
`SQLT_BFILE` | Создаёт объект LOB.
`SQLT_LNG` | Связывает в виде SQLT_CHR, возвращается в виде строки
`SQLT_LBI` | Связывает в виде `SQLT_BIN`, возвращается в виде строки
Любой другой тип | Связывает в виде `SQLT_CHR`, возвращается в виде строки

# OCI8 Функции

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Связывает PHP массив с массивом Oracle PL/SQL

### Описание

function oci_bind_array_by_name(
resource `$statement`,
string `$param`,
array `&$var`,
int `$max_array_length`,
int `$max_item_length` = -1,
int `$type` = `SQLT_AFC`
): bool

Связывает PHP массив `var` с указателем Oracle `param` на массив Oracle PL/SQL. Направление, ввод или вывод, для которого будет использоваться массив будет определяться во время выполнения.

### Список параметров

`statement`

  Идентификатор допустимого OCI выражения.

`param`

  Указатель на массив Oracle.

`var`

  Массив.

`max_array_length`

  Задаёт максимальный размер для исходного и результирующего массивов.

`max_item_length`

  Задаёт максимальный размер значений массива. Если не задано или равно -1, oci_bind_array_by_name() найдёт самый большой элемент в исходном массиве и использует его размер в качестве этой настройки.

`type`

  Используется для задания типа значений PL/SQL массива. Смотрите список ниже:

  - `SQLT_NUM` - для массивов с элементами типа NUMBER.

  - `SQLT_INT` - для массивов с элементами типа INTEGER (Замечание: INTEGER - синоним для типа NUMBER(38), однако тип `SQLT_NUM` в этом случае не будет работать, даже несмотря на то, что они синонимичны).

  - `SQLT_FLT` - для массивов с элементами типа FLOAT.

  - `SQLT_AFC` - для массивов с элементами типа CHAR.

  - `SQLT_CHR` - для массивов с элементами типа VARCHAR2.

  - `SQLT_VCS` - для массивов с элементами типа VARCHAR.

  - `SQLT_AVC` - для массивов с элементами типа CHARZ.

  - `SQLT_STR` - для массивов с элементами типа STRING.

  - `SQLT_LVC` - для массивов с элементами типа LONG VARCHAR.

  - `SQLT_ODT` - для массивов с элементами типа DATE.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_bind_array_by_name()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $create = "CREATE TABLE bind_example(name VARCHAR(20))";
    $stid = oci_parse($conn, $create);
    oci_execute($stid);

    $create_pkg = "
    CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
      TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
      PROCEDURE iobind(c1 IN OUT ARRTYPE);
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg);
    oci_execute($stid);

    $create_pkg_body = "
    CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
      CURSOR CUR IS SELECT name FROM bind_example;
      PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
        BEGIN
        -- Bulk Insert
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Fetch and reverse
        IF NOT CUR%ISOPEN THEN
          OPEN CUR;
        END IF;
        FOR i IN REVERSE 1..5 LOOP
          FETCH CUR INTO c1(i);
          IF CUR%NOTFOUND THEN
            CLOSE CUR;
            EXIT;
          END IF;
        END LOOP;
      END iobind;
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg_body);
    oci_execute($stid);

    $stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
    $array = array("one", "two", "three", "four", "five");
    oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
    oci_execute($stid);

    var_dump($array);

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Прикрепляет переменную PHP к соответствующей метке в SQL-выражении

### Описание

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

Прикрепляет переменную `var` к метке `param`. Такое прикрепление позволяет повысить производительность и избежать SQL-инъекций.

Прикрепление переменной позволяет базе данных повторно использовать кешированные контекстные выражения от предыдущих запросов, даже если они первоначально были запущены другим пользователем или процессом. Это также снижает риск SQL-инъекций, поскольку данные в таком случае никогда не рассматриваются как инструкции SQL. Данные не требуется экранировать или заключать в кавычки.

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

В Oracle, прикрепление переменных обычно разделяют на `IN` (прикрепляет значения, передаваемые в базу данных) и `OUT` (прикрепляет значения, возвращаемые PHP). Переменная может быть одновременно `IN` и `OUT`. Независимо от этого, характер прикрепления переменных будет определён во время выполнения.

Необходимо указать `max_length` при использовании `OUT`-привязки, что позволяет PHP зарезервировать больше памяти для хранения возвращаемого значения

Для `IN`-привязки рекомендуется также указать параметр `max_length`, если выражение выполняется несколько раз с различными значениями PHP-переменной. В противном случае, Oracle может урезать размер данных до размера первоначального значения переменной PHP. Если максимальная длина значения неизвестна, рекомендуется вызывать oci_bind_by_name() перед каждым вызовом oci_execute(). Прикрепление неоправданно большой переменной повлияет на процесс сохранения базы данных.

Вид прикрепления указывает Oracle как работать с памятью при чтении данных. Для `IN`-прикрепления адрес в памяти должен содержать допустимые данные при вызове oci_execute(). Это значит, что значение переменной должно находиться в памяти во время исполнения. Если это не так, возможны некорректные результаты или ошибки наподобие "ORA-01460: unimplemented or unreasonable conversion requested" (запрошены невыполнимые или некорректные преобразования) Для `OUT`-прикрепления основным признаком является установка значения в переменную PHP.

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

### Список параметров

`statement`

  Допустимый идентификатор выражения OCI8.

`param`

  Метка с префиксом в виде двоеточия, используемая в выражении. Двоеточие опционально в `param`. Oracle не использует знак вопроса для меток.

`var`

  Переменная PHP, ассоциированная с `param`

`max_length`

  Устанавливает максимальный размер данных. Если указать -1, функция будет использовать текущий размер переменной `var` в качестве максимального. При этом переменная `var` должна существовать и содержать данные во время вызова oci_bind_by_name().

`type`

  Тип данных, к которому Oracle будет приводить значения. По умолчанию `type` имеет значение `SQLT_CHR`. Oracle приводит данные от данного типа к типу поля (или типу переменной PL/SQL), если это возможно.

  Если необходимо прикрепить переменную абстрактного типа (LOB/ROWID/BFILE), следует предварительно использовать oci_new_descriptor(). Параметр `length` не используется для абстрактных типов и должен быть установлен в -1.

  Допустимые значения параметра `type`:

  - `SQLT_BFILEE` или `OCI_B_BFILE` - для BFILE-объектов;

  - `SQLT_CFILEE` или `OCI_B_CFILEE` - для CFILE-объектов;

  - `SQLT_CLOB` или `OCI_B_CLOB` - для CLOB-объектов;

  - `SQLT_BLOB` или `OCI_B_BLOB` - для BLOB-объектов;

  - `SQLT_RDD` или `OCI_B_ROWID` - для ROWID-объектов;

  - `SQLT_NTY` или `OCI_B_NTY` - для именованных типов даты;

  - `SQLT_INT` или `OCI_B_INT` - для целых чисел;

  - `SQLT_CHR` - для символов VARCHAR;

  - `SQLT_BIN` или `OCI_B_BIN` - для RAW-полей;

  - `SQLT_LNG` - для LONG-полей;

  - `SQLT_LBI` - для LONG RAW полей;

  - `SQLT_RSET` - для курсоров, созданных функцией oci_new_cursor();

  - `SQLT_BOL` или `OCI_B_BOL` - для PL/SQL BOOLEAN (Требуется Oracle Database 12c)

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Добавление данных с использованием oci_bind_by_name()

    <?php

    // Создание таблицы:
    //   CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

    $id = 1;
    $text = "Data to insert     ";
    oci_bind_by_name($stid, ":id_bv", $id);
    oci_bind_by_name($stid, ":text_bv", $text);
    oci_execute($stid);

    // В таблице содержится: 1, 'Data to insert     '

    ?>

Пример #2 Одна привязка для многократного использования

    <?php

    // Создание таблицы:
    //   CREATE TABLE mytab (id NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $a = array(1,3,5,7,11);  // данные для вставки

    $stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $v, 20);
    foreach ($a as $v) {
        $r = oci_execute($stid, OCI_DEFAULT);  // не использовать автоматическое завершение транзакции
    }
    oci_commit($conn); // завершение транзакции

    // Таблица содержит пять записей: 1, 3, 5, 7, 11

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Прикрепление в цикле `foreach`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
    $stid = oci_parse($conn, $sql);

    $ba = array(':dname' => 'IT Support', ':loc' => 1700);

    foreach ($ba as $key => $val) {

        // oci_bind_by_name($stid, $key, $val) не работает,
        // потому что прикрепляет каждое значение в одно место: $val
        // Вместо этого следует указывать конкретное место: $ba[$key]
        oci_bind_by_name($stid, $key, $ba[$key]);
    }

    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    foreach ($row as $item) {
        print $item."<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #4 Прикрепление в выражение WHERE

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Выводом будет
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #5 Прикрепление в выражение LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Поиск всех городов, начинающихся на 'South'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
    $city = 'South%';  // '%' - это знак шаблона SQL
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Выводом будет:
    //   South Brunswick
    //   South San Francisco
    //   Southlake

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #6 Прикрепление в выражение REGEXP_LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Поиск названий городов, содержащих 'ing'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
    $city = '.*ing.*';
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Выводом будет:
    //   Beijing
    //   Singapore

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Для небольшого, фиксированного количества условий в выражении IN, используются индивидуальные имена переменных. Неизвестные значения при исполнении могут быть установлены в NULL. Это позволяет использовать одно выражение нескольким пользователям, что повышает эффективность кеширования Oracle DB.

Пример #7 Прикрепление нескольких значений в выражение IN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
    $stid = oci_parse($conn, $sql);
    $mye1 = 103;
    $mye2 = 104;
    $mye3 = NULL; // притворимся, что не получили это значение
    oci_bind_by_name($stid, ':e1', $mye1);
    oci_bind_by_name($stid, ':e2', $mye2);
    oci_bind_by_name($stid, ':e3', $mye3);
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    foreach ($res['LAST_NAME'] as $name) {
        print $name ."<br>\n";
    }

    // Выводом будет:
    //   Ernst
    //   Hunold

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #8 Прикрепление ROWID, возвращаемое запросом

    <?php

    // Создадим и наполним таблицу:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //   INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
    //   COMMIT;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
    $id = 1;
    oci_bind_by_name($stid, ':id_bv', $id);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    $rid = $row['ROWID'];
    $name = $row['NAME'];

    // Переведём имя в верхний регистр и зафиксируем изменения
    $name = strtoupper($name);
    $stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
    oci_bind_by_name($stid, ':n_bv', $name);
    oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
    oci_execute($stid);

    // Теперь таблица содержит: 1, 100, CHRIS

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #9 OUT-прикрепление ROWID, возвращаемое при INSERT

    <?php

    // В данном примере добавляется запись с идентификатором и именем,
    // после чего увеличивается заработная плата
    // Создание таблицы:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //
    // На основе собственных ROWID на примере thies[at]thieso.net (980221)

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
            RETURNING ROWID INTO :rid";

    $ins_stid = oci_parse($conn, $sql);

    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_bind_by_name($ins_stid, ":id_bv",   $id,    10);
    oci_bind_by_name($ins_stid, ":name_bv", $name,  32);
    oci_bind_by_name($ins_stid, ":rid",     $rowid, -1, OCI_B_ROWID);

    $sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
    $upd_stid = oci_parse($conn, $sql);
    oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
    oci_bind_by_name($upd_stid, ":salary", $salary,   32);

    // идентификаторы и имена для вставки
    $data = array(1111 => "Larry",
                  2222 => "Bill",
                  3333 => "Jim");

    // Заработная плата для каждого сотрудника
    $salary = 10000;

    // Вставка и немедленное обновление каждой строки
    foreach ($data as $id => $name) {
        oci_execute($ins_stid);
        oci_execute($upd_stid);
    }

    $rowid->free();
    oci_free_statement($upd_stid);
    oci_free_statement($ins_stid);

    // Показать новые записи
    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        var_dump($row);
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #10 Прикрепление для хранимой функции PL/SQL

    <?php

    //  Перед запуском PHP-сценария, создайте хранимую функцию в
    //  SQL*Plus или SQL Developer:
    //
    //  CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
    //  BEGIN
    //      RETURN p * 3;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);

    // Возвращаемое значение OUT-прикреплено. По умолчаннию типом данных будет строка.
    // Прикрепление со значением 40 означает, что будет возвращено 40 символов.
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // выведет 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #11 Прикрепление параметров для PL/SQL хранимой процедуры

    <?php

    //  Перед запуском PHP-сценария, создайте хранимую процедуру в
    //  SQL*Plus или SQL Developer:
    //
    //  CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
    //  BEGIN
    //      p2 := p1 * 2;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);

    // Второй параметр процедуры OUT-прикреплён. По умолчаннию типом данных будет строка.
    // Прикрепление со значением 40 означает, что будет возвращено 40 символов.
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // выведет 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #12 Прикрепление CLOB-объекта

    <?php

    // Перед запуском создаём таблицу:
    //     CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $mykey = 12343;  // произвольный ключ для примера

    $sql = "INSERT INTO mytab (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_DEFAULT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Получение CLOB-данных

    $query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // В цикле, очищение больших переменных перед повторным получением данных, уменьшает пиковое потребление памяти PHP
        unset($row);
    }
    print '</table>';

    ?>

Пример #13 Прикрепление PL/SQL BOOLEAN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $plsql =
      "begin
        :output1 := true;
        :output2 := false;
       end;";

    $s = oci_parse($c, $plsql);
    oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
    oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
    oci_execute($s);
    var_dump($output1);  // true
    var_dump($output2);  // false

    ?>

### Примечания

Внимание

Не используйте addslashes() одновременно с oci_bind_by_name(), так как кавычек быть не должно. Все указанные кавычки будут записаны в базу данных, потому что oci_bind_by_name() вставляет данные дословно и не удаляет кавычки или символы экранирования.

> Замечание:

> Если прикрепляется строка к `CHAR`-полю в выражении `WHERE`, помните, что Oracle использует при сравнении значения `CHAR`, дополненные пробелами. Переменная PHP должна быть дополнена пробелами до того же размера, что и поле, чтобы выражение `WHERE` выполнялось верно.

> Замечание:

> Переменная PHP `var` является ссылкой. Некоторые виды циклов могут работать не так, как ожидается:

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> В этом случае каждый ключ прикрепляется к $value, поэтому все прикреплённые переменные указывают на значение в последней итерации цикла. Вместо этого следует использовать:

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### Смотрите также

- oci_bind_array_by_name() - Связывает PHP массив с массивом Oracle PL/SQL
- oci_parse() - Подготавливает запрос к выполнению

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — Заканчивает процесс чтения из курсора

### Описание

function oci_cancel(resource `$statement`): bool

Сбрасывает курсор, освобождая все связанные ресурсы и отменяет возможность читать из него.

### Список параметров

`statement`

  Запрос OCI.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Возвращает версию клиентской библиотеки

### Описание

function oci_client_version(): string

Возвращает номер версии в виде строки клиентской C-библиотеки Oracle, с которой связан PHP.

### Список параметров

Отсутствуют.

### Возвращаемые значения

Возвращает номер версии в виде строки (string).

### Примеры

Пример #1 Пример использования oci_client_version()

    <?php
        echo "Версия клиента: " . oci_client_version(); // Версия клиента: 19.9.0.0.0
    ?>

### Примечания

> Замечание:

> Библиотеки Oracle версий до 10gR2 не имеют необходимого функционала, чтобы выдать номер версии. В этих случаях функция вернёт строку "Unknown".

### Смотрите также

- oci_server_version() - Возвращает версию сервера Oracle

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Закрывает соединение с сервером Oracle

### Описание

function oci_close(resource `$connection`): ?bool

Освобождает `connection`. Соответствующее ему соединение с базой данных будет закрыто при отсутствии использующих его ресурсов и если оно было получено из функции oci_connect() или oci_new_connect().

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

### Список параметров

`connection`

  Идентификатор соединения Oracle, полученный из функций oci_connect(), oci_pconnect() или oci_new_connect().

### Возвращаемые значения

Возвращает `null` если oci8.old_oci_close_semantics включён или `true` в противном случае.

### Примеры

Пример #1 Закрытие соединения

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

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');
    $r = oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    // Освобождаем идентификатор выражения при закрытии соединения
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Соединение базы данных не закрывается до тех пор, пока не будут закрыты все ссылки на него

Внутренний счётчик ссылок (refcount) идентификатора соединения должен равняться нулю перед непосредственным закрытием соединения к базе данных.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');  // это увеличивает refcount на $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn больше не может использоваться в данном скрипте, но реальное
    // соединение с базой данных будет открыто, пока не будет освобождена $stid.
    var_dump($conn);  // выводит NULL

    // Пока PHP спит, запрос к виду Oracle V$SESSION в окне терминала
    // покажет, что пользователь базы данных всё ещё подключён.
    sleep(10);

    // Как только $stid освобождается, соединение к базе данных физически закрывается
    oci_free_statement($stid);

    // Пока PHP спит, запрос к виду Oracle V$SESSION в окне терминала
    // покажет, что пользователь базы данных уже отключился.
    sleep(10);

    ?>

Пример #3 Закрытие соединения, открытого несколько раз

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

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Использование тех же учётных данных повторно использует одно и то же
    // соединение с базой данных. Любые незафиксированные изменения в
    // $conn1 будут видны в $conn2
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Пока PHP спит, запрос к виду Oracle V$SESSION в окне терминала
    // покажет, что подключён только один пользователь базы данных.
    sleep(10);

    oci_close($conn1); // не закрывает реальное соединение с базой данных
    var_dump($conn1);  // выводит NULL, т.к. $conn1 теперь бесполезна
    var_dump($conn2);  // показывает, что $conn2 всё ещё является корректным ресурсом соединения

    ?>

Пример #4 Соединение закрывается при уходе переменных из области видимости

Когда все переменные, ссылающиеся на соединение, уходят из области видимости и освобождаются PHP, происходит откат транзакции (если необходимо) и соединение с базой закрывается.

    <?php

    function myfunc() {
        $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
        if (!$conn) {
            $e = oci_error();
            trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
        }

        $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
        return "Закончили!";
    }

    $r = myfunc();
    // В этой точке происходит откат транзакции и закрывается соответствующее
    // соединение с базой данных

    print $r;  // отображает возвращённое функцией значение "Закончили!"

    ?>

### Примечания

> Замечание:

> Переменные, зависящие от идентификатора соединений, такие как идентификаторы выражений, полученные из oci_parse(), должны быть также освобождены до закрытия соединения с базой данных.

> Замечание:

> Функция oci_close() не закрывает соединения с базой данных, созданные функцией oci_pconnect().

### Смотрите также

- oci_connect() - Устанавливает соединение с базой данных Oracle
- oci_free_statement() - Освобождает ресурсы, занимаемые курсором или SQL-выражением

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — Подтверждает транзакцию базы данных

### Описание

function oci_commit(resource `$connection`): bool

Подтверждает транзакцию соединения `connection`. Подтверждение завершает текущую транзакцию и делает все изменения постоянными. Она также освобождает все установленные блокировки.

Транзакция начинается при первом SQL-запросе, изменяющим данные, который был запущен с помощью функции oci_execute() и флага `OCI_NO_AUTO_COMMIT`. Последующие изменения данных от других запросов также становятся частью данной транзакции. Изменения, сделанные в транзакции, являются временными до тех пор, пока транзакция не будет зафиксирована или пока не будет произведён её откат. Другие пользователи базы данных не смогут увидеть изменения до их подтверждения.

При вставке или обновлении данных рекомендуется использовать транзакции для сохранения целостности данных и увеличения производительности.

### Список параметров

`connection`

  Идентификатор соединения Oracle, полученный из функций oci_connect(), oci_pconnect() или oci_new_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_commit()

    <?php

    // Вставка в несколько таблиц, откат изменений в случае возникновения ошибки

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // Флаг OCI_NO_AUTO_COMMIT сообщает Oracle не фиксировать запрос INSERT при его поступлении
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // откат изменений из обоих таблиц
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Фиксация изменений в обоих таблицах
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

### Примечания

> Замечание:

> Транзакции будут автоматически откачены при закрытии соединения или окончании скрипта (в зависимости от того, что случится раньше). Для подтверждения транзакции необходимо явно вызвать функцию oci_commit().

> Все вызовы oci_execute(), явно или по умолчанию использующие режим `OCI_COMMIT_ON_SUCCESS` зафиксируют любую предыдущую незафиксированную транзакцию.

> Любой DDL-запрос Oracle, такой как `CREATE` или `DROP` автоматически подтверждает любую незавершённую транзакцию.

### Смотрите также

- oci_execute() - Выполняет подготовленное выражение
- oci_rollback() - Откатывает транзакции, ожидающие обработки

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Устанавливает соединение с базой данных Oracle

### Описание

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

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

Для повышения производительности большинство приложений должны использовать постоянные соединения с помощью oci_pconnect() вместо oci_connect(). Смотрите Управление соединением для более детальной информации по управлению соединениями и создании пулов подключений.

Второй и последующие вызовы функции oci_connect() с теми же параметрами вернут идентификатор уже открытого соединения. Это означает, что транзакции используют одно и то же базовое соединение с базой данных. При необходимости разделения транзакций рекомендуется использовать функцию oci_new_connect().

### Список параметров

`username`

  Имя пользователя Oracle.

`password`

  Пароль `username`.

`connection_string`
  Содержит `экземпляр Oracle` для подключения. Это может быть » Easy Connect string, или Connect Name из файла tnsnames.ora, или имя локального экземпляра Oracle. Если не указано отдельно или `null`, PHP использует переменные окружения, такие как `TWO_TASK` (на Linux) или `LOCAL` (на Windows) и `ORACLE_SID` для определения `экземпляра Oracle` для соединения. Для использования метода Easy Connect, PHP должен быть слинкован с клиентскими библиотеками версии Oracle 10g или старше. Easy Connect string для Oracle 10g принимает следующую форму: [//]host_name[:port][/service_name]. Начиная с Oracle 11g синтаксис таков: [//]host_name[:port][/service_name][:server_type][/instance_name]. В Oracle 19c были введены дополнительные параметры, включая настройки времени ожидания и проверки активности. Обратитесь к документации Oracle. Названия служб могут быть определены с помощью запуска Oracle утилиты `lsnrctl status` на сервере базы данных. Файл tnsnames.ora может находиться в поисковом пути Oracle Net, который включает /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin и /etc. В качестве альтернативного варианта можно установить `TNS_ADMIN` таким образом, чтобы путь $TNS_ADMIN/tnsnames.ora был читаемым. Убедитесь, что веб-сервер имеет доступ к этому файлу.
`encoding`
  Определяет кодировку, которую будут использовать клиентские библиотеки Oracle. Кодировка не обязательно должна совпадать с кодировкой самой базы данных. Oracle сделает всё возможное, чтобы преобразовать данные из или в эту кодировку, если кодировка не совпадает. В зависимости от кодировок это не всегда даёт приемлемые результаты. Преобразование также занимает некоторое время. Клиентские библиотеки Oracle будут определять кодировку из переменной окружения `NLS_LANG`, если кодировку не указали. Передача аргумента часто уменьшает время, которое тратится на соединение.
`session_mode`
  Параметр доступен с PHP 5 (PECL OCI8 1.1) и принимает следующие значения: `OCI_DEFAULT`, `OCI_SYSOPER` и `OCI_SYSDBA`. Если указали `OCI_SYSOPER` или `OCI_SYSDBA`, функция попытается установить привилегированное соединение через внешние данные авторизации. По умолчанию привилегированные соединения отключены. Чтобы их включить, устанавливают oci8.privileged_connect в `On`. В версии PHP 5.3 (PECL OCI8 1.3.4) появилась константа `OCI_CRED_EXT` как значение режима. Этот режим говорит Oracle использовать внешнюю аутентификацию или аутентификацию операционной системы, которую требуется настроить в базе данных. Флаг `OCI_CRED_EXT` разрешается использовать только с именем пользователя "/" и пустым паролем. Опиция oci8.privileged_connect принимает значение `On` или `Off`. Режим `OCI_CRED_EXT` разрешается объединять с режимами `OCI_SYSOPER` и `OCI_SYSDBA`. Режим `OCI_CRED_EXT` не поддерживается в Windows по соображениям безопасности.

### Возвращаемые значения

Возвращает идентификатор соединения или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` теперь допускает значение null.

### Примеры

Пример #1 Пример использования oci_connect() с синтаксисом Easy Connect

    <?php

    // Подключается к XE сервису (т.е. к базе данных) на "localhost"
    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Пример #2 Пример использования oci_connect() используя имя Network Connect

    <?php

    // Соединяется с базой данных MYDB описанной в файле tnsnames.ora,
    // Пример записи в tnsnames.ora для MYDB:
    //   MYDB =
    //     (DESCRIPTION =
    //       (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
    //       (CONNECT_DATA =
    //         (SERVER = DEDICATED)
    //         (SERVICE_NAME = XE)
    //       )
    //     )

    $conn = oci_connect('hr', 'welcome', 'MYDB');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Пример #3 Пример использования oci_connect() с использованием определённого набора символов

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Пример #4 Пример использования многократных вызовов oci_connect()

    <?php

    $c1 = oci_connect("hr", "welcome", 'localhost/XE');
    $c2 = oci_connect("hr", "welcome", 'localhost/XE');

    // $c1 и $c2 содержат одинаковый PHP id ресурса, что означает, что
    // они используют одинаковое базовое соединение
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    function create_table($conn)
    {
        $stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
        oci_execute($stmt);
        echo "Created table<br>\n";
    }

    function drop_table($conn)
    {
        $stmt = oci_parse($conn, "drop table hallo");
        oci_execute($stmt);
        echo "Dropped table<br>\n";
    }

    function insert_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "insert into hallo
                  values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname inserted row without committing<br>\n";
    }

    function rollback($connname, $conn)
    {
        oci_rollback($conn);
        echo "$connname rollback<br>\n";
    }

    function select_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "select * from hallo");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname ----selecting<br>\n";
        while (oci_fetch($stmt)) {
            echo "    " . oci_result($stmt, "TEST") . "<br>\n";
        }
        echo "$connname ----done<br>\n";
    }

    create_table($c1);

    insert_data('c1', $c1);   // Вставить строку используя c1
    sleep(2);                 // остановиться для записи другой временной метки для следующей строки
    insert_data('c2', $c2);   // Вставить строку используя c2

    select_data('c1', $c1);   // Возврат результата обоих вставок
    select_data('c2', $c2);   // Возврат результата обоих вставок

    rollback('c1', $c1);      // Откат используя c1

    select_data('c1', $c1);   // Откат был произведён для обоих вставок
    select_data('c2', $c2);

    drop_table($c1);

    // Закрытие одного из соединений делает переменную PHP недоступной, но
    // другие могут быть использованы
    oci_close($c1);
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    // Вывод is:
    //    c1 is Resource id #5
    //    c2 is Resource id #5
    //    Created table
    //    c1 inserted row without committing
    //    c2 inserted row without committing
    //    c1 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c1 ----done
    //    c2 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c2 ----done
    //    c1 rollback
    //    c1 ----selecting
    //    c1 ----done
    //    c2 ----selecting
    //    c2 ----done
    //    Dropped table
    //    c1 is
    //    c2 is Resource id #5

    ?>

### Примечания

> Замечание:

> Некорректно установленный или настроенный модуль OCI8 будет часто сообщать о проблемах соединения или ошибках. Смотрите Установка/Настройка для решения проблем.

### Смотрите также

- oci_pconnect() - Устанавливает постоянное соединение с сервером Oracle
- oci_new_connect() - Устанавливает новое соединение с сервером Oracle
- oci_close() - Закрывает соединение с сервером Oracle

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — Сопоставляет переменную PHP столбцу результата запроса

### Описание

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

Сопоставляет переменную PHP столбцу результата запроса, полученного с помощью oci_fetch().

Вызов oci_define_by_name() должен производиться до запуска oci_execute().

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.
`column`

  Имя столбца использованного в запросе.

  Используйте верхний регистр для стандартных регистронезависимых имён столбцов Oracle. Используйте точное написание имени столбца для регистрозависимых имён.

`var`

  Переменная PHP, предназначенная для хранения возвращённого значения.

`type`

  Тип возвращаемых данных. Обычно не требуется. Имейте ввиду, что преобразования Oracle-данных не производятся. К примеру, `SQLT_INT` будет проигнорировано и возвращённые данные будут по-прежнему в виде `SQLT_CHR`.

  Если требуется назначить переменную абстрактного типа данных (LOB/ROWID/BFILE), то переменную сначала необходимо создать функцией oci_new_descriptor().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции oci_define_by_name()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // Переменные ДОЛЖНЫ быть определены перед запуском
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    //  Каждый результат запроса помещает в заранее определённую переменную следующую строку данных
    while (oci_fetch($stid)) {
        echo "ID местоположения $locid - $city<br>\n";
    }

    // Выведет:
    //   ID местоположения 1000 - Roma
    //   ID местоположения 1100 - Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Пример использования oci_define_by_name() с регистрозависимыми именами столбцов

    <?php

    /*
      До запуска, создаётся таблица со столбцом, имеющим регистрозависимое имя
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Используется верхний регистр для регистронезависимых имён столбцов
    oci_define_by_name($stid, 'ID', $id);

    // Используется точное написание для регистрозависимых имён столбцов
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "Идентификатор $id - $mydesc<br>\n";
    }

    // Выведет:
    //   Идентификатор 1 - Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Пример использования oci_define_by_name() со столбцами типа LOB

    <?php

    /*
      Перед запуском создаются таблицы:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Переменные ДОЛЖНЫ быть определены перед запуском
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit станет дескриптором LOB

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " - " . $fruit->load(100) . "<br>\n";
    }

    // Выведет:
    //   1 - apple
    //   2 - orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #4 Пример использования oci_define_by_name() с приведёнными типами

    <?php

    /*
      Перед запуском создаётся таблица:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Переменные ДОЛЖНЫ быть определены перед запуском
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " - " . $fruit->load(100) . "<br>\n";
    }

    // Выведет:
    //   1 - apple
    //   2 - orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_new_descriptor() - Инициализирует новый дескриптор объекта LOB или FILE

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — Возвращает последнюю ошибку

### Описание

function oci_error(?resource `$connection_or_statement` = `null`): array|false

Возвращает последнюю найденную ошибку.

Функция должна вызваться сразу же после появления ошибки. Ошибки очищаются при произведении правильного запроса.

### Список параметров

`connection_or_statement`

  Для большинства ошибок параметром `connection_or_statement` является соответствующий идентификатор соединения или выражения. Для ошибок во время выполнения функций oci_connect(), oci_new_connect() или oci_pconnect() следует передавать `null`.

### Возвращаемые значения

Если ошибок не найдено, то oci_error() возвращает `false`. В противном случае, oci_error() возвращает информацию об ошибке в виде ассоциативного массива.

Описание массива вывода oci_error()
Ключ массива | Тип | Описание
--- | --- | ---
`code` | int | Номер ошибки Oracle.
`message` | string | Текст ошибки Oracle.
`offset` | int | Позиция ошибки в запросе SQL. Если нет запроса, то равна `0`
`sqltext` | string | Текст запроса SQL. Если нет запроса, то строка пуста.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_or_statement` теперь допускает значение null.

### Примеры

Пример #1 Вывод сообщения об ошибке Oracle после ошибки соединения

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // Для обработки ошибок oci_connect
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Пример #2 Вывод сообщения об ошибке Oracle после ошибки разбора

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // пропущенные кавычки
    if (!$stid) {
        $e = oci_error($conn);  // Для обработки ошибок oci_parse
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Пример #3 Вывод сообщения об ошибке Oracle, ошибочного запроса и позиции ошибки запуска запроса

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);  // Для обработки ошибок oci_execute
        print htmlentities($e['message']);
        print "\n<pre>\n";
        print htmlentities($e['sqltext']);
        printf("\n%".($e['offset']+1)."s", "^");
        print  "\n</pre>\n";
    }
    ?>

# oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — Выполняет подготовленное выражение

### Описание

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

Выполняет подготовленное выражение `statement`, созданное с помощью функции oci_parse().

Сразу после выполнения выражения подобного `INSERT`, по умолчанию все данные сразу будут сохранены в базе данных. Для выражений подобных `SELECT`, выполняется только логика запроса. Результат же запроса можно получить позже в PHP с помощью функций подобных oci_fetch_array().

Каждое подготовленное выражение может быть выполнено несколько раз для экономии на издержках от повторной подготовки запроса. Это чаще всего применяется для выражений `INSERT`, когда к ним привязаны данные с помощью oci_bind_by_name().

### Список параметров

`statement`

  Правильное подготовленное выражение OCI.

`mode`

  Необязательный второй параметр с одним из следующих значений:

  Режим выполнения
  Константа | Описание
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | Автоматически сохранять все несохраненные изменения, произведённые за текущую сессию в случае успешного выполнения выражения. Этот режим установлен по умолчанию.
  `OCI_DESCRIBE_ONLY` | Делает доступными метаданные запроса для функций подобных oci_field_name(), но не создаёт результат выполнения выражения. Любое последующее получение данных, например с помощью oci_fetch_array() не будет произведено.
  `OCI_NO_AUTO_COMMIT` | Не сохранять автоматически изменения.

  Использование режима `OCI_NO_AUTO_COMMIT` открывает или продолжает транзакцию. Эта транзакция автоматически откатывается при закрытии соединения или завершении скрипта. Используйте oci_commit() для завершения транзакции и oci_rollback() для её отмены.

  При вставке и обновлении данных рекомендуется использование транзакций для реляционной целостности данных и для улучшения производительности.

  Если для какого-нибудь выражения используется режим `OCI_NO_AUTO_COMMIT`, и впоследствии не используются oci_commit() или oci_rollback(), то OCI8 будет выполнять откат при завершении скрипта даже если данные не были изменены. Для избежания ненужных откатов большинство скриптов не используют режим `OCI_NO_AUTO_COMMIT` для запросов или PL/SQL. Будьте внимательны, чтобы обеспечить надлежащую согласованность транзакций при использовании oci_execute() с различными режимами в одном скрипте.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 oci_execute() при выполнении запросов

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Пример #2 oci_execute() без указания определённого режима

    <?php

    // Перед выполнением создайте таблицу:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

    oci_execute($stid); // Строка сохранена и становится видимой для других пользователей

    ?>

Пример #3 oci_execute() с `OCI_NO_AUTO_COMMIT`

    <?php

    // Перед выполнением создайте таблицу:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $i, 10);
    for ($i = 1; $i <= 5; ++$i) {
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
    }
    oci_commit($conn);  // сохранение все новых значений: 1, 2, 3, 4, 5

    ?>

Пример #4 oci_execute() с различными режимами

    <?php

    // Перед выполнением создайте таблицу:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // data not committed

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
    oci_execute($stid);  // commits both 123 and 456 values

    ?>

Пример #5 oci_execute() с `OCI_DESCRIBE_ONLY`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM locations');
    oci_execute($s, OCI_DESCRIBE_ONLY);
    for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
        echo oci_field_name($stid, $i) . "<br>\n";
    }

    ?>

### Примечания

> Замечание:

> Транзакции автоматически откатываются при закрытии соединения или завершении выполнения скрипта. Принудительно вызывайте oci_commit() для завершения транзакции.

> Любой вызов oci_execute(), который принудительно использует `OCI_COMMIT_ON_SUCCESS` или по умолчанию будет завершать любую предыдущую незакрытую транзакцию.

> Любое выражение Oracle DDL подобное `CREATE` или `DROP` будет автоматически завершать любую. незакрытую транзакцию.

> Замечание:

> Так как функция oci_execute() обычно отправляет выражения в базу данных, то oci_execute() может найти некоторые незначительные синтаксические ошибки, когда локальная oci_parse() их не находит.

### Смотрите также

- oci_parse() - Подготавливает запрос к выполнению

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — Выбирает следующую строку из результата в буфер

### Описание

function oci_fetch(resource `$statement`): bool

Выбирает следующую строку из результата запроса во внутренний буфер, доступный с помощью oci_result() или через переменные, заранее определённые с помощью oci_define_by_name().

Смотрите oci_fetch_array() для более детальной информации о выборе данных.

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если в результате `statement` больше нет рядов.

### Примеры

Пример #1 Пример использования oci_fetch() с определёнными переменными

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // Определение переменных ДОЛЖНО быть произведено до запуска
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // С каждой выборкой переменные заполняются данными следующего ряда
    while (oci_fetch($stid)) {
        echo "Идентификатор местоположения $city = $locid<br>\n";
    }

    // Выведет:
    //   Идентификатор местоположения Roma = 1000
    //   Идентификатор местоположения Venice = 1100

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Пример использования oci_fetch() с oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " = ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Выведет:
    //   1000 = Roma
    //   1100 = Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Не возвращает строки для неявных результирующих наборов в Oracle Database. Используйте вместо данной функции функцию oci_fetch_array().

### Смотрите также

- oci_define_by_name() - Сопоставляет переменную PHP столбцу результата запроса
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива
- oci_result() - Возвращает значение поля из результата запроса

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — Выбирает все строки из результата запроса в двумерный массив

### Описание

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

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

Эта функция может быть вызваться только один раз для каждого запроса запущенного с помощью oci_execute().

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.
`output`

  Переменная, содержащая возвращённые строки.

  LOB столбцы возвращаются в виде строк, для которых поддерживается Oracle преобразования.

  Смотрите oci_fetch_array() для более детальной информации о том, как производится выборка данных и типов.

`offset`

  Число строк, которых необходимо исключить из выборки. По умолчанию равно 0, выборка возвращается со следующего за первым ряда.

`limit`

  Число возвращаемых строк. По умолчанию равно -1, что означает возврат всех строк, начиная с указанных в `offset` + 1 предыдущая строка.

`flags`

  Параметр `flags` содержит структуру массива отражает необходимость использования ассоциативных массивов.

  Структура массива oci_fetch_all()
  Константа | Описание
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | Массив будет содержать по одному под-массиву на каждую строку запроса.
  `OCI_FETCHSTATEMENT_BY_COLUMN` | Массив будет содержать по одному под-массиву на каждый столбец. Используется по умолчанию.

  Массивы могут быть проиндексированы или заголовками столбцов или пронумерованы. Будет возвращён только один режим индексации.

  Индексация массива oci_fetch_all()
  Константа | Описание
  --- | ---
  `OCI_NUM` | Для массива каждого столбца используются числовые индексы.
  `OCI_ASSOC` | Для массива каждого столбца используется ассоциативные индексы. По умолчанию.

  Используйте оператор сложения "+" для выбора определённой комбинации структуры и индексации массива.

  Регистронезависимые (по умолчанию в Oracle) имена полей в результирующем массиве будут иметь ассоциативные индексы в верхнем регистре. Регистрозависимые имена полей будут иметь индексы с теми же регистрами символов, что и само поле. Используйте var_dump() на `output`, чтобы проверить соответствие регистров символов для каждого запроса.

  В запросах в которых имеется несколько столбцов с одинаковыми именами необходимо использовать псевдонимы. Иначе только один из столбцов появится в ассоциативном массиве.

### Возвращаемые значения

Возвращает число столбцов в `output`, который может принимать значение 0 или более.

### Примеры

Пример #1 Пример использования oci_fetch_all()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res);

    echo "$nrows строк получено<br>\n";
    var_dump($res);

    // Вывод var_dump:
    //    2 строк получено
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Roma"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    // Форматирование результатов
    echo "<table border='1'>\n";
    foreach ($res as $col) {
        echo "<tr>\n";
        foreach ($col as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Пример использования oci_fetch_all() с `OCI_FETCHSTATEMENT_BY_ROW`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

    echo "$nrows строк получено<br>\n";
    var_dump($res);

    // Выведет:
    //    2 строк получено
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Пример использования oci_fetch_all() с `OCI_NUM`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

    echo "$nrows строк получено<br>\n";
    var_dump($res);

    // Выведет:
    //    2 строк получено
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Roma"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venice"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Использование `offset` неэффективно. Все пропускаемые ряды включаются в результат запроса возвращаемый базой данных к PHP. После этого они исключаются. Более эффективно использовать SQL для отступа и ограничения рядов в запросе. Смотрите oci_fetch_array() для примеров.

> Замечание:

> Запросы, возвращающие большое число рядов, могут быть более эффективными если используется однорядная функция выборки, такая как oci_fetch_array().

> Замечание: Для запросов, которые возвращают большое количество рядов, производительность может быть значительно увеличена за счёт увеличения значения опции oci8.default_prefetch или вызова функции oci_set_prefetch().

> Замечание:

> Не возвращает ряды для неявных результирующих наборов в Oracle Database 12c. Используйте вместо данной функции функцию oci_fetch_array().

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива
- oci_set_prefetch() - Устанавливает количество строк, которые будут автоматически выбраны в буфер

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива

### Описание

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Возвращает массив, содержащий следующую строку результата запроса. Каждый элемент массива соответствует одному полю из строки. Эта функция обычно вызывается в цикле, пока она не вернёт `false`, который указывает на отсутствие последующих строк.

Если `statement` соответствует PL/SQL блоку, возвращаемому Oracle Database Implicit Result Sets, тогда будут последовательно извлечены ряды из всех наборов. Если `statement` возвращается из oci_get_implicit_resultset(), тогда вернётся только часть рядов для одного дочернего запроса.

За подробностями по операции отображения типов данных, осуществляемой модулем OCI8, обратитесь к типам данных, поддерживаемых драйвером

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.

  Также может быть идентификатором, возвращаемым функцией oci_get_implicit_resultset().

`mode`

  Необязательный второй параметр может состоять из любой комбинации следующих констант:

  oci_fetch_array() Modes
  Константа | Описание
  --- | ---
  `OCI_BOTH` | Возвращает массив как с ассоциативными и числовыми индексами. Эта константа то же самое что и `OCI_ASSOC` + `OCI_NUM`, и она используется по умолчанию.
  `OCI_ASSOC` | Возвращает ассоциативный массив.
  `OCI_NUM` | Возвращает нумерованный массив.
  `OCI_RETURN_NULLS` | Создаёт элементы для полей равных `null`. Значение элемента будет равно PHP `null`.
  `OCI_RETURN_LOBS` | Возвращает содержимое полей типа LOB, вместо LOB указателя.

  По умолчанию `mode` равен `OCI_BOTH`.

  Используйте оператор сложения "+" для указания более одного режима.

### Возвращаемые значения

Возвращает массив с ассоциативными и/или числовыми ключами. Если больше нет строк в `statement`, то возвращается `false`.

По умолчанию, поля `LOB` возвращаются как указатели LOB.

Поля типа `DATE` возвращаются в формате строк, соответствующем текущему формату даты. Формат по умолчанию может быть изменён с помощью переменных окружения Oracle, таких как `NLS_LANG`, или предварительным выполнением команды `ALTER SESSION SET NLS_DATE_FORMAT`.

Регистронезависимые (по умолчанию в Oracle) имена полей будут иметь ассоциативные индексы в верхнем регистре в результирующем массиве. Регистрозависимые имена полей будут иметь индексы с теми же регистрами символов, что и само поле. Используйте var_dump() для результирующего массива, чтобы проверить соответствие регистров символов для каждого запроса.

Имя таблицы не входит в ассоциативны индекс. Если ваш запрос содержит два разных поля с одинаковым именем, используйте `OCI_NUM` или добавьте алиас для поля в запрос, так чтобы имена стали уникальными (смотрите пример #7). Иначе будет возвращено только одно поле.

### Примеры

Пример #1 oci_fetch_array() с `OCI_BOTH`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_BOTH))) {
        // Используйте название полей в верхнем регистре для ассоциативных индексов
        echo $row[0] . " и " . $row['DEPARTMENT_ID']   . " идентичны<br>\n";
        echo $row[1] . " и " . $row['DEPARTMENT_NAME'] . " идентичны<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 oci_fetch_array() с `OCI_NUM`

    <?php

    /*
      Перед выполнением создайте таблицу:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
        echo $row[0] . "<br>\n";
        echo $row[1]->read(11) . "<br>\n"; // это выведет первые 11 байт DESCRIPTION
    }

    // Выведет:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 oci_fetch_array() с `OCI_ASSOC`

    <?php

    /*
      Перед выполнением создайте таблицу:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION']->read(11) . "<br>\n"; // это выведет первые 11 байт DESCRIPTION
    }

    // Выведет:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #4 oci_fetch_array() с `OCI_RETURN_NULLS`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // Игнорирует NULL значения
        var_dump($row);
    }

    /*
    Вышеуказанный код выведет:
      array(1) {
        [1]=>
        string(1) "1"
      }
    */

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // Получает NULL значения
        var_dump($row);
    }

    /*
    Вышеуказанный код выведет:
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

Пример #5 oci_fetch_array() с `OCI_RETURN_LOBS`

    <?php

    /*
      Перед выполнением создайте таблицу:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'A very long string');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS))) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION'] . "<br>\n"; // содержит весь DESCRIPTION
        // В цикле, очищение больших переменных перед повторным получением данных, уменьшает пиковое потребление памяти PHP
        unset($row);
    }

    // Выведет:
    //    1
    //    A very long string

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #6 oci_fetch_array() с регистрозависимыми названиями полей

    <?php

    /*
       Перед выполнением создайте таблицу:
          CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
          INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

    // Так как 'Name' было создан как регистрозависимое поле, то
    // те же регисты символов используются для индексов массива.
    // Тем не менее для 'CITY' должен использоваться индекс в верхнем регистре.
    print $row['Name'] . "<br>\n";   //  выведет Chris
    print $row['CITY'] . "<br>\n";   //  выведет Melbourne

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #7 oci_fetch_array() с полями с одинаковыми названиями

    <?php

    /*
      Перед выполнением создайте таблицу:
          CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycity (id, name) values (1, 'Melbourne');
          CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycountry (id, name) values (1, 'Australia');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT mycity.name, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // Выведет только одну записаь "NAME":
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    // Для получения полей с повторяющимся названием используйте SQL псевдонимы (alias) для полей. Например "AS ctnm":
    $sql = 'SELECT mycity.name AS ctnm, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // Выведет записи из обоих полей:
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australia"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #8 oci_fetch_array() с полями `DATE`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Устанавливаем формат даты для данного соединения.
    // Для повышения производительности вместо этого
    // используйте изменение формата в триггере или переменной окружения.
    $stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
    oci_execute($stid);

    $stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    echo $row['HIRE_DATE'] . "<br>\n";  // выведет 1997-06-14

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #9 oci_fetch_array() с `REF CURSOR`

    <?php
    /*
      Создайте PL/SQL хранимую процедуру:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Выполняет вовзращенный REF CURSOR и получает его в виде идентификатора выражения
    oci_execute($refcur);
    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #10 Постраничный вывод с помощью oci_fetch_array() используя `LIMIT`-подобный запрос

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Определяем версию базы данных
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // Запрос, который необходимо сделать "постраничным"
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // Используем Oracle 12c OFFSET / FETCH NEXT синтаксис
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Cтарые версии Oracle нуждаются в выборке с помощью подзапроса в $sql.
        // Или, если SQL выражение известно на стадии разработки, то с помощью
        // функции row_number(). Будьте осторожны и избегайте возможности
        // SQL-инъекции при объединении строк в боевом окружении.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // skip this many rows
    $numrows = 5;  // return 5 rows
    $stid = oci_parse($conn, $sql);
    oci_bind_by_name($stid, ':numrows', $numrows);
    oci_bind_by_name($stid, ':offset', $offset);
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
        echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
    }

    // Выведет:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #11 oci_fetch_array() c Oracle Database Implicit Result Sets

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Требует OCI8 2.0 (или новее) и Oracle Database 12c (или новее)
    // также смотрите oci_get_implicit_resultset()
    $sql = 'DECLARE
               c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Обратите внимание: oci_fetch_all и oci_fetch() нельзя неприменимы здесь
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Выведет:
    //    Beijing 190518
    //    Bern    3095
    //    Bombay  490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Индексы ассоциативного массива необходимо приводить в верхний регистр для стандартных полей Oracle, созданных с регистронезависимыми названиями.

> Замечание: Для запросов, которые возвращают большое количество рядов, производительность может быть значительно увеличена за счёт увеличения значения опции oci8.default_prefetch или вызова функции oci_set_prefetch().

> Замечание:

> Функция oci_fetch_array() немного медленней oci_fetch_assoc() или oci_fetch_row(), но более гибкая.

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива
- oci_set_prefetch() - Устанавливает количество строк, которые будут автоматически выбраны в буфер

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Возвращает следующую строку из результата запроса в виде ассоциативного массива

### Описание

function oci_fetch_assoc(resource `$statement`): array|false

Возвращает ассоциативный массив, содержащий следующую строку из результата выполнения запроса. Каждый элемент массива соответствует столбцу текущей строки. Эта функция обычно вызывается в цикле, пока не возвращает `false`, если больше нет строк.

Результат выполнения oci_fetch_assoc() идентичен выполнению oci_fetch_array() с флагом `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.

### Возвращаемые значения

Возвращает ассоциативный массив. Если в результате запроса строк больше нет, возвращает `false`.

### Примеры

Пример #1 Пример использования oci_fetch_assoc()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_assoc($stid)) != false) {
        echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Смотрите дополнительные примеры получения строк в oci_fetch_array().

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Возвращает следующую строку из результата запроса в виде объекта

### Описание

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Возвращает объект, содержащий следующую строку из результата запроса. Имена свойств объекта соответствуют именам столбцов в строке. Эта функция обычно вызывается в цикле пока не возвращает `false` когда больше нет рядов.

За подробностями по операции отображения типов данных, осуществляемой модулем OCI8, обратитесь к типам данных, поддерживаемых драйвером

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.

### Возвращаемые значения

Возвращает объект. Каждое свойство объекта соответствуют именам столбцов в строке. Если в результате `запроса` больше нет рядов, то возвращает `false`.

Любой столбец `LOB` возвращается как дескриптор LOB.

Столбцы `DATE` возвращаются в виде строк, форматированных в соответствии с текущим форматов даты. Стандартный формат может быть изменён с помощью переменных окружения Oracle, таких как `NLS_LANG` или с помощью предварительно запущенной `ALTER SESSION SET NLS_DATE_FORMAT` команды.

Вам не следует забывать о том, что Oracle возвращает имена полей в ВЕРХНЕМ регистре, поэтому имена атрибутов объекта будут также в ВЕРХНЕМ регистре. Используйте функцию var_dump() по отношению к полученному объекту для доступа к атрибутам.

Значения атрибутов соответствуют `null` для любых `NULL` полей.

### Примеры

Пример #1 Пример использования oci_fetch_object()

    <?php

    /*
      Перед запуском создайте таблицу:
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Используйте имена атрибутов в верхнем регистре для каждого столбца Oracle
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // Выведет:
    //    1
    //    Fish and Chips

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Пример использования oci_fetch_object() с названиями столбцов в различных регистрах

    <?php

    /*
    Перед запуском создайте таблицу с именем столбца в различных регистрах:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // Использование имён атрибутов в верхнем регистре для каждого столбца Oracle
        echo $row->ID . "<br>\n";
        // Использование точного написания для имени столбца с различными регистрами
        echo $row->MyDescription . "<br>\n";
    }

    // Выведет:
    //    1
    //    Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Пример использования oci_fetch_object() с LOB

    <?php

    /*
      Перед запуском создайте таблицу
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'A very long string');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        echo $row->ID . "<br>\n";
        // Таким образом будет выведено первые 11 байт из DESCRIPTION
        echo $row->DESCRIPTION->read(11) . "<br>\n";
    }

    // Выведет:
    //    1
    //    A very long

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Возвращает следующую строку из результата запроса в виде нумерованного массива

### Описание

function oci_fetch_row(resource `$statement`): array|false

Возвращает нумерованный массив, содержащий следующую строку из результата запроса. Каждый массив соответствует столбцу строки. Эта функция обычно вызывается в цикле пока не возвращает `false`, если в результате запроса больше нет строк.

Вызов oci_fetch_row() аналогичен вызову oci_fetch_array() с флагом `OCI_NUM` + `OCI_RETURN_NULLS`.

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.

### Возвращаемые значения

Возвращает нумерованный массив. Если в `statement` больше нет срок возвращает `false`.

### Примеры

Пример #1 Пример использования oci_fetch_row()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_row($stid)) != false) {
        echo $row[0] . " " . $row[1] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Смотрите oci_fetch_array() для дополнительных примеров результатов запросов.

### Смотрите также

- oci_fetch() - Выбирает следующую строку из результата в буфер
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — Проверяет, равняется ли поле в текущем полученном ряду равным `null`

### Описание

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

Проверяет, является ли значение, переданное в поле `column` из текущего ряда `statement` равным `null`.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть порядковый номер поля (начиная с 1) или имя поля.

### Возвращаемые значения

Возвращает `true`, если `column` равен `null`, и `false` если нет.

### Примеры

Пример #1 Пример использования oci_field_name()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (c1 NUMBER);
    //   INSERT INTO mytab VALUES (1);
    //   INSERT INTO mytab VALUES (NULL);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
        $ncols = oci_num_fields($stid);
        for ($col = 1; $col <= $ncols; $col++) {
            var_dump(oci_field_is_null($stid, $col));
        }
    }

    // Выведет:
    //    bool(false)
    //    bool(true)

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — Возвращает имя поля из результата запроса

### Описание

function oci_field_name(resource `$statement`, string|int `$column`): string|false

Возвращает имя поля `column` из результата запроса.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть номером поля (нумерация начинается с 1) или именем.

### Возвращаемые значения

Возвращает имя в виде строки или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_field_name()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Выведет:
    //    Name           Type
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_num_fields() - Возвращает количество полей в результате запроса
- oci_field_type() - Возвращает имя типа поля
- oci_field_size() - Возвращает размер поля

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — Возвращает точность поля

### Описание

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

Возвращает точность поля `column`.

Для полей типа FLOAT точность больше нуля, а масштаб равен -127. Если точность поля равна нулю, то тип поля - NUMBER. Иначе же, тип поля может быть описан как NUMBER(precision, scale).

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть номером поля (нумерация начинается с 1) или именем.

### Возвращаемые значения

Возвращает точность в виде числа или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_field_precision()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Выведет:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_field_scale() - Возвращает масштаб поля
- oci_field_type() - Возвращает имя типа поля

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — Возвращает масштаб поля

### Описание

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

Возвращает масштаб поля под номером `column`.

Для полей типа FLOAT точность, получаемая с помощью oci_field_precision(), больше нуля, а масштаб равен -127. Если точность поля равна нулю, то тип поля - NUMBER. Иначе же, тип поля может быть описан как NUMBER(precision, scale).

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть номером поля (нумерация начинается с 1) или именем.

### Возвращаемые значения

Функция возвращает масштаб в виде числа или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции oci_field_scale()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Выведет:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_field_precision() - Возвращает точность поля
- oci_field_type() - Возвращает имя типа поля

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — Возвращает размер поля

### Описание

function oci_field_size(resource `$statement`, string|int `$column`): int|false

Возвращает размер поля `column`.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть номером поля (нумерация начинается с 1) или именем.

### Возвращаемые значения

Возвращает размер поля `column` в байтах или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_field_size()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Выведет:
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_num_fields() - Возвращает количество полей в результате запроса
- oci_field_name() - Возвращает имя поля из результата запроса

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — Возвращает имя типа поля

### Описание

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

Возвращает имя типа поля.

### Список параметров

`statement`

  Допустимый идентификатор OCI-выражения.

`column`

  Может быть задано индексом (начиная с 1) или по имени.

### Возвращаемые значения

Возвращает тип поля как строку (string) или как целое число (int) или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_field_type()

    <?php

    // Создайте таблицу:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Имя</th>";
    echo "<th>Тип</th>";
    echo "<th>Длина</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Выведет:
    //    Имя           Тип       Длина
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_num_fields() - Возвращает количество полей в результате запроса
- oci_field_name() - Возвращает имя поля из результата запроса
- oci_field_size() - Возвращает размер поля

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Возвращает исходный тип поля Oracle

### Описание

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

Возвращает тип "SQLT" Oracle поля `column`.

Если вы хотите получить тип поля, то oci_field_type() подойдёт вам больше.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

`column`

  Может быть номером поля (нумерация начинается с 1) или именем.

### Возвращаемые значения

Возвращает исходный тип Oracle в виде числа или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_field_type_raw()

    <?php

    // Создать таблицу:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid, OCI_DESCRIBE_ONLY);  // используйте OCI_DESCRIBE_ONLY, если не получаете данных
    $n = oci_num_fields($stid);
    for ($i = 1; $i <= $n; ++$i) {
        echo oci_field_name($stid, $i) . " - исходный тип: " . oci_field_type_raw($stid, $i) . "<br>\n";
    }

    // Выведет:
    //    NUMBER_COL - исходный тип: 2
    //    VARCHAR2_COL - исходный тип: 1
    //    CLOB_COL - исходный тип: 112
    //    DATE_COL - исходный тип: 12

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — Освобождает дескриптор

### Описание

function oci_free_descriptor(OCILob `$lob`): bool

Освобождает дескриптор, созданный с помощью oci_new_descriptor().

### Список параметров

`lob`

  Дескриптор, созданный с помощью oci_new_descriptor().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание:

> Функция обычно используется как метод OCILOB::free.

### Смотрите также

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — Освобождает ресурсы, занимаемые курсором или SQL-выражением

### Описание

function oci_free_statement(resource `$statement`): bool

Освобождает все ресурсы, занимаемые курсором или SQL-выражением, которое было возвращено функцией oci_parse() или получено от сервера Oracle.

### Список параметров

`statement`

  Допустимый идентификатор OCI-выражения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Возвращает следующий ресурс дочернего запроса из ресурса родительского запроса, имеющего неявные результирующие наборы Oracle Database

### Описание

function oci_get_implicit_resultset(resource `$statement`): resource|false

Используется для выборки последовательных наборов результатов запроса после выполнения хранимого или анонимного блока Oracle PL / SQL, когда этот блок возвращает результаты запроса Oracle Database 12 (или новее) с помощью PL/SQL функции DBMS_SQL.RETURN_RESULT. Это позволят блокам PL/SQL возвращать результаты запроса.

Дочерний запрос может быть использован с любой извлекающей функцией OCI8: oci_fetch(), oci_fetch_all(), oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() или oci_fetch_row()

Дочерний запрос наследует родительское значение предвыборки, либо можно указать его явно с помощью oci_set_prefetch().

### Список параметров

`statement`

  Корректный идентификатор запроса OCI8, созданный с помощью oci_parse() и запущенный с помощью oci_execute(). Идентификатор запроса может быть, а может и не быть связан с SQL-запросом, который возвращает неявные результирующие наборы (Implicit Result Set).

### Возвращаемые значения

Возвращает обработчик запроса для следующего доступного для `statement` дочернего запроса. Возвращает `false` если такового нет или все дочерние запросы уже были возвращены предыдущими вызовами oci_get_implicit_resultset().

### Примеры

Пример #1 Извлечение неявных результирующих наборов в цикле

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (($stid_c = oci_get_implicit_resultset($stid))) {
        echo "<h2>Новый неявный результирующий набор:</h2>\n";
        echo "<table>\n";
        while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
            echo "<tr>\n";
            foreach ($row as $item) {
                echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
            }
            echo "</tr>\n";
        }
        echo "</table>\n";
    }

    // Вывод:
    //    Новый неявный результирующий набор:
    //     Beijing 190518
    //     Bern    3095
    //     Bombay  490231
    //    New Implicit Result Set:
    //     CN
    //     CH
    //     IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Извлечение обработчиков дочерних запросов в индивидуальном порядке

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_1 = oci_get_implicit_resultset($stid);
    $stid_2 = oci_get_implicit_resultset($stid);

    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);

    // Вывод:
    //    array(2) {
    //      ["CITY"]=>
    //      string(7) "Beijing"
    //      ["POSTAL_CODE"]=>
    //      string(6) "190518"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CN"
    //    }
    //    array(2) {
    //      ["CITY"]=>
    //      string(4) "Bern"
    //      ["POSTAL_CODE"]=>
    //      string(4) "3095"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CH"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #3 Явное указание величины предвыборки

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_c = oci_get_implicit_resultset($stid);
    oci_set_prefetch($stid_c, 200);   // Устанавливаем величину предвыборки до того как начинаем извлекать пезультаты из дочернего запроса
    echo "<table>\n";
    while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #4 Пример неявного результирующего набора без использования oci_get_implicit_resultset()

Все результаты всех запросов возвращаются последовательно.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Обратите внимание: oci_fetch_all and oci_fetch() нельзя использовать таким образом
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Вывод:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание: Для запросов, которые возвращают большое количество рядов, производительность может быть значительно увеличена за счёт увеличения значения опции oci8.default_prefetch или вызова функции oci_set_prefetch().

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Копирует объект LOB

### Описание

function oci_lob_copy(OCILob `$to`, OCILob `$from`, ?int `$length` = `null`): bool

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

Если необходимо скопировать определённую часть объекта, то для этого можно использовать OCILob::seek(), чтобы передвинуть внутренние указатели объектов на нужные позиции.

### Список параметров

`to`

  LOB объект назначения.

`from`

  Копируемый объект LOB.

`length`

  Длина участка содержимого для копирования.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` теперь допускает значение null.

### Примечания

> Замечание:

> Класс OCILob назывался OCI-Lob до PHP 8 и PECL OCI8 3.0.0.

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — Сравнивает два объекта LOB/FILE

### Описание

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Сравнивает два объекта LOB/FILE.

### Список параметров

`lob1`

  Идентификатор LOB.

`lob2`

  Идентификатор LOB.

### Возвращаемые значения

Возвращает `true`, если объекты идентичны, и `false` в обратном случае или в случае возникновения ошибки.

### Примечания

> Замечание:

> Класс OCILob назывался OCI-Lob до PHP 8 и PECL OCI8 3.0.0.

# oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — Создаёт новый объект коллекции

### Описание

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

Создаёт новый объект коллекции.

### Список параметров

`connection`

  Идентификатор соединения с сервером Oracle, возвращаемый функцией oci_connect() или oci_pconnect().

`type_name`

  Должен быть корректным именем типа (в верхнем регистре).

`schema`

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

### Возвращаемые значения

Возвращает новый объект OCICollection или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `schema` теперь допускает значение null.

### Примечания

> Замечание:

> Класс OCICollection назывался OCI-Collection до PHP 8 и OCI8 3.0.0.

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — Устанавливает новое соединение с сервером Oracle

### Описание

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Создаёт новое соединение с сервером Oracle и выполняет вход.

В отличие от oci_connect() и oci_pconnect(), функция oci_new_connect() не кеширует соединения и при каждом вызове устанавливает новое соединение. Это полезно, если приложению необходима транзакционная изоляция двух наборов запросов.

### Список параметров

`username`

  Имя пользователя Oracle.

`password`

  Пароль пользователя `username`.

`connection_string`
  Содержит `экземпляр Oracle` для подключения. Это может быть » Easy Connect string, или Connect Name из файла tnsnames.ora, или имя локального экземпляра Oracle. Если не указано отдельно или `null`, PHP использует переменные окружения, такие как `TWO_TASK` (на Linux) или `LOCAL` (на Windows) и `ORACLE_SID` для определения `экземпляра Oracle` для соединения. Для использования метода Easy Connect, PHP должен быть слинкован с клиентскими библиотеками версии Oracle 10g или старше. Easy Connect string для Oracle 10g принимает следующую форму: [//]host_name[:port][/service_name]. Начиная с Oracle 11g синтаксис таков: [//]host_name[:port][/service_name][:server_type][/instance_name]. В Oracle 19c были введены дополнительные параметры, включая настройки времени ожидания и проверки активности. Обратитесь к документации Oracle. Названия служб могут быть определены с помощью запуска Oracle утилиты `lsnrctl status` на сервере базы данных. Файл tnsnames.ora может находиться в поисковом пути Oracle Net, который включает /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin и /etc. В качестве альтернативного варианта можно установить `TNS_ADMIN` таким образом, чтобы путь $TNS_ADMIN/tnsnames.ora был читаемым. Убедитесь, что веб-сервер имеет доступ к этому файлу.
`encoding`
  Определяет кодировку, которую будут использовать клиентские библиотеки Oracle. Кодировка не обязательно должна совпадать с кодировкой самой базы данных. Oracle сделает всё возможное, чтобы преобразовать данные из или в эту кодировку, если кодировка не совпадает. В зависимости от кодировок это не всегда даёт приемлемые результаты. Преобразование также занимает некоторое время. Клиентские библиотеки Oracle будут определять кодировку из переменной окружения `NLS_LANG`, если кодировку не указали. Передача аргумента часто уменьшает время, которое тратится на соединение.
`session_mode`
  Параметр доступен с PHP 5 (PECL OCI8 1.1) и принимает следующие значения: `OCI_DEFAULT`, `OCI_SYSOPER` и `OCI_SYSDBA`. Если указали `OCI_SYSOPER` или `OCI_SYSDBA`, функция попытается установить привилегированное соединение через внешние данные авторизации. По умолчанию привилегированные соединения отключены. Чтобы их включить, устанавливают oci8.privileged_connect в `On`. В версии PHP 5.3 (PECL OCI8 1.3.4) появилась константа `OCI_CRED_EXT` как значение режима. Этот режим говорит Oracle использовать внешнюю аутентификацию или аутентификацию операционной системы, которую требуется настроить в базе данных. Флаг `OCI_CRED_EXT` разрешается использовать только с именем пользователя "/" и пустым паролем. Опиция oci8.privileged_connect принимает значение `On` или `Off`. Режим `OCI_CRED_EXT` разрешается объединять с режимами `OCI_SYSOPER` и `OCI_SYSDBA`. Режим `OCI_CRED_EXT` не поддерживается в Windows по соображениям безопасности.

### Возвращаемые значения

Возвращает идентификатор соединения или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` теперь допускает значение null.

### Примеры

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

Пример #1 Пример использования oci_new_connect()

    <?php

    // создайте таблицу mytab (mycol number);

    function query($name, $c)
    {
        echo "Выполнение $name\n";
        $s = oci_parse($c, "select * from mytab");
        oci_execute($s, OCI_NO_AUTO_COMMIT);
        $row = oci_fetch_array($s, OCI_ASSOC);
        if (!$row) {
            echo "Нет данных\n";
        } else {
            do {
                foreach ($row as $item)
                    echo $item . " ";
                echo "\n";
            } while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
        }
    }

    $c1 = oci_connect("hr", "welcome", "localhost/orcl");
    $c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

    $s = oci_parse($c1, "insert into mytab values(1234)");
    oci_execute($s, OCI_NO_AUTO_COMMIT);

    query("основного соединения", $c1);
    query("нового соединения", $c2);
    oci_commit($c1);
    query("нового соединения после commit", $c2);

    // Выведет:
    //   Выполнение основного соединения
    //   1234
    //   Выполнение нового соединения
    //   Нет данных
    //   Выполнение нового соединения после commit
    //   1234

    ?>

Дополнительные примеры можно найти в описании функции oci_connect().

### Смотрите также

- oci_connect() - Устанавливает соединение с базой данных Oracle
- oci_pconnect() - Устанавливает постоянное соединение с сервером Oracle

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — Возвращает идентификатор созданного курсора

### Описание

function oci_new_cursor(resource `$connection`): resource|false

Создаёт новый курсор для указанного соединения и возвращает его идентификатор.

### Список параметров

`connection`

  Идентификатор соединения с сервером Oracle, возвращаемый функцией oci_connect() или oci_pconnect().

### Возвращаемые значения

Возвращает указатель на новое выражение или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Привязка REF CURSOR в вызове хранимых процедур Oracle

    <?php

    // Предварительная подготовка:
    //   создайте или замените процедуру myproc(myrc out sys_refcursor) как
    //   begin
    //     open myrc for select first_name from employees;
    //   end;

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $curs = oci_new_cursor($conn);
    $stid = oci_parse($conn, "begin myproc(:cursbv); end;");
    oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
    oci_execute($stid);

    oci_execute($curs);  // Выполняет REF CURSOR как обычный идентификатор выражения
    while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo $row['FIRST_NAME'] . "<br />\n";
    }

    oci_free_statement($stid);
    oci_free_statement($curs);
    oci_close($conn);

    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — Инициализирует новый дескриптор объекта LOB или FILE

### Описание

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

Резервирует ресурсы, необходимые для хранения дескриптора объекта или LOB-локатора.

### Список параметров

`connection`

  Идентификатор соединения с сервером Oracle, возвращаемый функцией oci_connect() или oci_pconnect().

`type`

  Допустимые значения параметра `type`: `OCI_DTYPE_FILE`, `OCI_DTYPE_LOB` и `OCI_DTYPE_ROWID`.

### Возвращаемые значения

Возвращает новый LOB или дескриптор FILE в случае успешного выполнения или `null` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования oci_new_descriptor()

    <?php
    /* Приведённый скрипт разработан для использования с HTML формами.
     * Это подразумевает, что $user, $password, $table, $where, и $commitsize
     * получены из формы. Скрипт удаляет записи с использованием
     * ROWID и закрывает транзакцию после каждого
     * $commitsize записей. (Используйте осторожно, откат изменений невозможен)
     */
    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "select rowid from $table $where");
    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_define_by_name($stmt, "ROWID", $rowid);
    oci_execute($stmt);
    while (oci_fetch($stmt)) {
        $nrows = oci_num_rows($stmt);
        $delete = oci_parse($conn, "delete from $table where ROWID = :rid");
        oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
        oci_execute($delete);
        echo "$nrows\n";
        if (($nrows % $commitsize) == 0) {
            oci_commit($conn);
        }
    }
    $nrows = oci_num_rows($stmt);
    echo "$nrows deleted...\n";
    oci_free_statement($stmt);
    oci_close($conn);
    ?>

    <?php
        /* Данный скрипт реализует загрузку файлов в LOB-столбцы
         * HTML-форма для скрипта выглядит примерно так:
         * <form action="upload.php" method="post" enctype="multipart/form-data">
         * <input type="file" name="lob_upload" />
         * ...
         */
      if (!isset($lob_upload) || $lob_upload == 'none'){
    ?>
    <form action="upload.php" method="post" enctype="multipart/form-data">
    Загрузить файл: <input type="file" name="lob_upload" /><br />
    <input type="submit" value="Загрузить" /> - <input type="reset" value="Сбросить" />
    </form>
    <?php
      } else {

         // $lob_upload содержит временное имя загруженного файла

         // смотрите также раздел особенностей загрузки файлов,
         // если необходимо реализовать безопасную загрузку

         $conn = oci_connect($user, $password);
         $lob = oci_new_descriptor($conn, OCI_D_LOB);
         $stmt = oci_parse($conn, "insert into $table (id, the_blob)
                   values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
         oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
         oci_execute($stmt, OCI_DEFAULT);
         if ($lob->savefile($lob_upload)){
            oci_commit($conn);
            echo "Blob успешно загружен\n";
         }else{
            echo "Не удалось загрузить Blob\n";
         }
         $lob->free();
         oci_free_statement($stmt);
         oci_close($conn);
      }
    ?>

Пример #2 Пример использования oci_new_descriptor()

    <?php
    /* Вызов хранимой процедуры PL/SQL, параметрами которой являются объекты CLOB
     * Пример PL/SQL процедуры:
     *
     * PROCEDURE save_data
     *   Имя аргумента                    Тип                     In/Out По умолчанию?
     *   ------------------------------ ----------------------- ------ ------------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stmt, ':key', $key);
    oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
    $clob->write($data);
    oci_execute($stmt, OCI_DEFAULT);
    oci_commit($conn);
    $clob->free();
    oci_free_statement($stmt);
    ?>

### Смотрите также

- oci_bind_by_name() - Прикрепляет переменную PHP к соответствующей метке в SQL-выражении

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — Возвращает количество полей в результате запроса

### Описание

function oci_num_fields(resource `$statement`): int

Получает число столбцов в запросе, заданном в `statement`.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

### Возвращаемые значения

Возвращает число столбцов в виде целого числа (int).

### Примеры

Пример #1 Пример использования oci_num_fields()

    <?php

    // Создате таблицу:
    //   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // используйте OCI_DESCRIBE_ONLY, если не получаете данных

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
    }

    // Выведет:
    //    ID NUMBER
    //    QUANTITY NUMBER

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — Возвращает количество строк, изменённых в процессе выполнения запроса

### Описание

function oci_num_rows(resource `$statement`): int|false

Возвращает число строк, затронутых в процессе выполнения запроса.

### Список параметров

`statement`

  Идентификатор допустимого OCI запроса.

### Возвращаемые значения

Возвращает число затронутых строк в виде integer или `false`, если возникла ошибка

### Примеры

Пример #1 Пример использования oci_num_rows()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "create table emp2 as select * from employees");
    oci_execute($stid);
    echo oci_num_rows($stid) . " строк вставлено.<br />\n";
    oci_free_statement($stid);

    $stid = oci_parse($conn, "delete from emp2");
    oci_execute($stid, OCI_DEFAULT);
    echo oci_num_rows($stid) . " строк удалено.<br />\n";
    oci_commit($conn);
    oci_free_statement($stid);

    $stid = oci_parse($conn, "drop table emp2");
    oci_execute($stid);
    oci_free_statement($stid);

    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Функция не возвращает количество строк в результате выражения SELECT! Для запросов SELECT oci_num_rows() вернёт количество строк, которые были считаны в буфер с помощью функций oci_fetch*().

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — Подготавливает запрос к выполнению

### Описание

function oci_parse(resource `$connection`, string `$sql`): resource|false

Функция подготавливает `sql`-запрос к выполнению через соединение `connection` и возвращает идентификатор запроса, который передают в oci_bind_by_name(), oci_execute() и другие функции.

Идентификаторы запросов освобождают функцией oci_free_statement() или установкой для переменной значения `null`.

### Список параметров

`connection`

  Идентификатор соединения Oracle, который получили из функций oci_connect(), oci_pconnect() или oci_new_connect().

`sql`

  SQL- или PL/SQL-запрос.

  SQL-запросы не должны заканчиваться точкой с запятой (";"). PL/SQL-запросы должны заканчиваться точкой с запятой (";").

### Возвращаемые значения

Функция возвращает дескриптор запроса в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции oci_parse() с SQL-запросами

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    // Парсим запрос. Обратите внимание на отсутствие точки запятой в конце SQL-запроса
    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Пример #2 Пример использования функции oci_parse() с PL/SQL-запросами

    <?php

    /*
      Перед запуском PHP-скрипта, создайте хранимую процедуру
      в SQL*Plus или SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    // При парсинге PL/SQL-запросов требуется наличие точки с запятой в конце строки
    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // prints 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Примечания

> Замечание:

> Функция не проверяет синтаксис запроса `sql`. Единственный способ проверить правильность SQL- или PL/SQL-запроса `sql` — выполнить запрос.

### Смотрите также

- oci_execute() - Выполняет подготовленное выражение
- oci_free_statement() - Освобождает ресурсы, занимаемые курсором или SQL-выражением

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Изменяет пароль пользователя Oracle

### Описание

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function oci_password_change(
string `$database_name`,
string `$username`,
string `$old_password`,
string `$new_password`
): resource

Изменяет пароль пользователя, указанного в `username`.

Функция oci_password_change() особенно полезна для скриптов PHP командной строки или при использовании непостоянных соединений во всем приложении PHP.

### Список параметров

`connection`

  Идентификатор соединения, возвращаемый функцией oci_connect() или oci_pconnect().

`username`

  Имя пользователя Oracle.

`old_password`

  Старый пароль.

`new_password`

  Новый пароль.

`database_name`

  Имя базы данных.

### Возвращаемые значения

Если указан параметр `database_name`, oci_password_change() возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка. Если указан параметр `connection`, oci_password_change() возвращает ресурс соединения в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_password_change() с изменением пароля уже подключённого пользователя

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    oci_password_change($c, $user, $current_pw, $new_pw);
    echo "Новый пароль : " . $new_pw . "\n";

    ?>

Пример #2 Пример использования oci_password_change() с подключением и изменением пароля одновременно

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    if (!$c) {
        $m = oci_error();
        if ($m['code'] == 28001) { // "ORA-28001: the password has expired"
            // Подключение и сброс пароля одновременно
            $c = oci_password_change($dbase, $user, $current_pw, $new_pw);
            if ($c) {
                echo "Новый пароль : " . $new_pw . "\n";
            }
        }
    }

    if (!$c) {  // Ошибка не совпадала с 28001, или не получилось изменить пароль
        $m = oci_error();
        trigger_error('Не удалось подключиться к базе данных: '. $m['message'], E_USER_ERROR);
    }

    // Использование подключения $c
    // ...

    ?>

### Примечания

> Замечание:

> Изменение пароля с помощью этой функции или непосредственно в Oracle должно выполняться аккуратно, поскольку PHP-приложение может продолжать использовать в постоянных соединениях данные аутентификации последнего удачного подключения, которые уже устарели. Наилучшим решением может быть перезапуск всех веб-серверов после смены пароля.

> Замечание:

> При обновлении библиотеки клиента Oracle или базы данных от версии установки до версии 11.2.0.3 и выше функция oci_password_change() может вернуть ошибку "ORA-1017: invalid username/password" (Неверные имя пользователя/пароль), если версии и клиента и сервера обновлены в одно время.

> Замечание:

> Второй набор параметров функции oci_password_change() доступен начиная с версии OCI8 1.1.

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Устанавливает постоянное соединение с сервером Oracle

### Описание

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Создаёт постоянное соединение с сервером Oracle и выполняет аутентификацию.

Постоянные соединения кешируются и повторно используются при следующих запросах, в результате снижаются накладные расходы при каждой загрузке страницы; типичное приложение PHP имеет одно постоянное подключение к серверу PHP, реализованное дочерним процессом Apache (или процессом PHP FPM). Дополнительную информацию смотрите в разделе Работа с соединениями OCI8 и Connection Pooling.

### Список параметров

`username`

  Имя пользователя Oracle.

`password`

  Пароль пользователя `username`.

`connection_string`
  Содержит `экземпляр Oracle` для подключения. Это может быть » Easy Connect string, или Connect Name из файла tnsnames.ora, или имя локального экземпляра Oracle. Если не указано отдельно или `null`, PHP использует переменные окружения, такие как `TWO_TASK` (на Linux) или `LOCAL` (на Windows) и `ORACLE_SID` для определения `экземпляра Oracle` для соединения. Для использования метода Easy Connect, PHP должен быть слинкован с клиентскими библиотеками версии Oracle 10g или старше. Easy Connect string для Oracle 10g принимает следующую форму: [//]host_name[:port][/service_name]. Начиная с Oracle 11g синтаксис таков: [//]host_name[:port][/service_name][:server_type][/instance_name]. В Oracle 19c были введены дополнительные параметры, включая настройки времени ожидания и проверки активности. Обратитесь к документации Oracle. Названия служб могут быть определены с помощью запуска Oracle утилиты `lsnrctl status` на сервере базы данных. Файл tnsnames.ora может находиться в поисковом пути Oracle Net, который включает /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin и /etc. В качестве альтернативного варианта можно установить `TNS_ADMIN` таким образом, чтобы путь $TNS_ADMIN/tnsnames.ora был читаемым. Убедитесь, что веб-сервер имеет доступ к этому файлу.
`encoding`
  Определяет кодировку, которую будут использовать клиентские библиотеки Oracle. Кодировка не обязательно должна совпадать с кодировкой самой базы данных. Oracle сделает всё возможное, чтобы преобразовать данные из или в эту кодировку, если кодировка не совпадает. В зависимости от кодировок это не всегда даёт приемлемые результаты. Преобразование также занимает некоторое время. Клиентские библиотеки Oracle будут определять кодировку из переменной окружения `NLS_LANG`, если кодировку не указали. Передача аргумента часто уменьшает время, которое тратится на соединение.
`session_mode`
  Параметр доступен с PHP 5 (PECL OCI8 1.1) и принимает следующие значения: `OCI_DEFAULT`, `OCI_SYSOPER` и `OCI_SYSDBA`. Если указали `OCI_SYSOPER` или `OCI_SYSDBA`, функция попытается установить привилегированное соединение через внешние данные авторизации. По умолчанию привилегированные соединения отключены. Чтобы их включить, устанавливают oci8.privileged_connect в `On`. В версии PHP 5.3 (PECL OCI8 1.3.4) появилась константа `OCI_CRED_EXT` как значение режима. Этот режим говорит Oracle использовать внешнюю аутентификацию или аутентификацию операционной системы, которую требуется настроить в базе данных. Флаг `OCI_CRED_EXT` разрешается использовать только с именем пользователя "/" и пустым паролем. Опиция oci8.privileged_connect принимает значение `On` или `Off`. Режим `OCI_CRED_EXT` разрешается объединять с режимами `OCI_SYSOPER` и `OCI_SYSDBA`. Режим `OCI_CRED_EXT` не поддерживается в Windows по соображениям безопасности.

### Возвращаемые значения

Возвращает идентификатор подключения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Простой пример для oci_pconnect() с использованием упрощённого синтаксиса подключения

    <?php

    // Подключение к XE сервису (т.е. базе данных) на локальной машине
    $conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Дополнительные примеры можно найти в описании функции oci_connect().

### Примечания

> Замечание: Продолжительность и максимальное количество постоянных соединений к серверу Oracle на каждый процесс PHP может быть изменено в следующих директивах: oci8.persistent_timeout, oci8.ping_interval и oci8.max_persistent.

### Смотрите также

- oci_connect() - Устанавливает соединение с базой данных Oracle
- oci_new_connect() - Устанавливает новое соединение с сервером Oracle

# oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Регистрирует пользовательскую функцию обратного вызова для Oracle Database TAF

### Описание

function oci_register_taf_callback(resource `$connection`, ?callable `$callback`): bool

Регистрирует пользовательскую функцию обратного вызова для соединения `connection`. Если соединение `connection` оборвалось из-за проблем с БД или сетью, будет произведено несколько запусков зарегистрированной функции в процессе восстановления. Более подробно читайте OCI8 Transparent Application Failover (TAF) Support .

Каждый новый вызов oci_register_taf_callback() будет затирать предыдущие регистрации.

Для явного удаления регистрации используйте функцию oci_unregister_taf_callback().

Регистрация функции обратного вызова НЕ сохраняется для постоянных соединений, следовательно при каждом новом постоянном соединении её необходимо перерегистрировать.

### Список параметров

`connection`

  Идентификатор соединения Oracle.

`callback`

  Пользовательская функция для регистрации для Oracle TAF. Может быть как строкой с именем функции, так и замыканием (анонимной функцией).

  Интерфейс функции следующий:

  function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

  Описание параметров и примеры смотрите на странице OCI8 Transparent Application Failover (TAF) Support.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- oci_unregister_taf_callback() - Удалить регистрацию пользовательской callback-функции для Oracle Database TAF

# oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — Возвращает значение поля из результата запроса

### Описание

function oci_result(resource `$statement`, string|int `$column`): mixed

Возвращает данные поля `column` текущей строки, возвращаемой функцией oci_fetch().

За подробностями по операции отображения типов данных, осуществляемой модулем OCI8, обратитесь к типам данных, поддерживаемых драйвером

### Список параметров

`statement`

`column`

  Может быть задано номером поля (начиная с 1), либо по имени. Регистр имени поля должен быть таким же, как и у поля, описанного в метаданных Oracle, которое всегда в верхнем регистре для полей, созданных регистронезависимыми.

### Возвращаемые значения

Возвращает все значения в виде строки за исключением абстрактных типов (ROWIDs, LOBs и FILEs). Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования oci_fetch() с oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " - это ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Выведет:
    //   1000 - это Roma
    //   1100 - это Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- oci_fetch_array() - Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_assoc() - Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object() - Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row() - Возвращает следующую строку из результата запроса в виде нумерованного массива
- oci_fetch_all() - Выбирает все строки из результата запроса в двумерный массив

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — Откатывает транзакции, ожидающие обработки

### Описание

function oci_rollback(resource `$connection`): bool

Данная функция откатывает все незафиксированные изменения соединения Oracle `connection` и завершает транзакцию. Она также освобождает все установленные блокировки. Удаляются все Oracle `SAVEPOINTS`.

Транзакция начинается при первом SQL-запросе, изменяющим данные, который был запущен с помощью функции oci_execute() и флага `OCI_NO_AUTO_COMMIT`. Последующие изменения данных от других запросов также становятся частью данной транзакции. Изменения, сделанные в транзакции, являются временными до тех пор, пока транзакция не будет зафиксирована или будет произведён её откат. Другие пользователи базы данных не смогут увидеть изменения до их фиксации.

При вставке или обновлении данных рекомендуется использовать транзакции для сохранения целостности данных и увеличения производительности.

### Список параметров

`connection`

  Идентификатор соединения Oracle, полученный из функций oci_connect(), oci_pconnect() или oci_new_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования oci_rollback()

    <?php

    // Вставка в несколько таблиц, откат изменений в случае возникновения ошибки

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // Флаг OCI_NO_AUTO_COMMIT сообщает Oracle не фиксировать запрос INSERT при его поступлении
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // откат изменений из обоих таблиц
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Фиксация изменений в обоих таблицах
    $r = oci_commit($conn);
    if (!r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

Пример #2 Пример использования отката до `SAVEPOINT`

    <?php
    $stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Создаём точку сохранения
    $stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    $stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Явно используем SQL-запрос для отката к точке сохранения
    $stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    oci_commit($conn);  // mytab теперь содержит id равные 1111
    ?>

### Примечания

> Замечание:

> Транзакции будут автоматически откачены при закрытии соединения или окончании скрипта (в зависимости от того, что случится раньше). Для фиксации транзакции необходимо явно вызвать функцию oci_commit().

> Все вызовы oci_execute(), явно или по умолчанию использующие режим `OCI_COMMIT_ON_SUCCESS` зафиксируют любую предыдущую незафиксированную транзакцию.

> Любой DDL-запрос Oracle, такой как `CREATE` или `DROP` автоматически фиксирует любую незафиксированную транзакцию.

### Смотрите также

- oci_commit() - Подтверждает транзакцию базы данных
- oci_execute() - Выполняет подготовленное выражение

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Возвращает версию сервера Oracle

### Описание

function oci_server_version(resource `$connection`): string|false

Возвращает строку с информацией о версии сервера Oracle и доступных опциях

### Список параметров

`connection`

### Возвращаемые значения

Возвращает в виде строки информацию о версии или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования oci_server_version()

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    echo "Версия сервера: " . oci_server_version($conn);

    // Выведет:
    // Версия сервера: Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
    // With the Partitioning, OLAP, Data Mining and Real Application Testing option

    oci_close($conn);

    ?>

### Смотрите также

- oci_client_version() - Возвращает версию клиентской библиотеки

# oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — Задаёт имя для действия

### Описание

function oci_set_action(resource `$connection`, string `$action`): bool

Присваивает имя действию для трассировки Oracle.

Присвоенное имя регистрируется в базе данных во время очередного запроса от PHP, например, когда запускается SQL выражение.

Имя действия может быть извлечено из административных представлений (view) базы данных, таких как `V$SESSION`. Его можно использовать для трассировки и мониторинга, например, с помощью `V$SQLAREA` и `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

Значение можно устанавливать и через постоянные соединения.

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`action`

  Задаваемая пользователем строка до 32 байт.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка действия

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Запись действия
    oci_set_action($c, 'Friend Lookup');

    // Код, осуществляющий запрос к БД, например выборка:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Пока скрипт выполняется, администратор может наблюдать выполнение действий:

    sqlplus system/welcome
    SQL> select action from v$session;

### Примечания

> Замечание: Требование к версии Oracle
> Эта функция доступна, если PHP слинкован с библиотеками Oracle Database начиная с версии 10g и выше.

Подсказка

# Производительность

В старых версиях модуля OCI8 или базы данных Oracle была доступна установка информации о клиенте средствами пакета `DBMS_APPLICATION_INFO`. Для этого более эффективен вызов функции oci_set_client_info().

Предостережение

# Совет по полному сканированию таблицы (roundtrip)

Ряд OCI8-функции вызывают полное сканирование таблицы (roundtrip). Функции не сканируют таблицы полностью для тех запросов, в которых включено кеширование результатов в базе данных.

### Смотрите также

- oci_set_module_name() - Задаёт имя модулю
- oci_set_client_info() - Задаёт информацию о клиенте
- oci_set_client_identifier() - Задаёт идентификатор клиента
- oci_set_db_operation() - Задаёт операцию базы данных

# oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Устанавливает время ожидания в миллисекундах для вызовов базы данных

### Описание

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

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

Каждая операция OCI8 выполняется ноль или более вызовов к клиентской библиотеки Oracle. Затем эти внутренние вызовы приводят к нулевому или большему количеству обращений к базе данных Oracle. Если какой-либо из этих циклических обходов занимает больше миллисекунд, чем указали в параметре `time_out`, операция отменяется и приложению возвращается ошибка.

Значение `time_out` применяется к каждому циклу по отдельности, а не к сумме всех циклов в оба конца. Время, затраченное на обработку в PHP-модуле OCI8 до или после завершения каждого циклического пути, не учитывается.

При прерывании вызова БД Oracle попытается очистить соединение для переиспользования. Эту операцию разрешается запускать в течение другого периода `time_out`. Будет ли соединение многоразовым, зависит от результатов очистки.

В постоянных соединениях значение времени ожидания сохраняется для каждого PHP-запроса.

Функция oci_set_call_timeout() доступна, когда модуль OCI8 использует клиентские библиотеки Oracle 18 или более поздних версий.

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`timeout`

  Максимальное время одного обмена данными между PHP и базой данных Oracle в миллисекундах.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример установки времени ожидания

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    oci_set_call_timeout($conn, 5000);

    ?>

# oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — Задаёт идентификатор клиента

### Описание

function oci_set_client_identifier(resource `$connection`, string `$client_id`): bool

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

Идентификатор клиента регистрируется в базе данных во время очередного запроса от PHP, например, когда запускается SQL выражение.

Идентификатор может быть извлечён, например с помощью `SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL`. Административное представление базы данных, такое как `V$SESSION`, также содержит это значение. Его можно использовать совместно с `DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE` для трассировки и аудита.

Значение может сохраняться между запросами страниц, которые используют одно и то же постоянное соединение.

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`client_id`

  Задаваемая пользователем строка до 64 байт.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка идентификатора клиента для пользователя

    <?php

    // Найдём логин пользователя
    session_start();
    $un = my_validate_session($_SESSION['username']);
    $c = oci_connect('myschema', 'welcome', 'localhost/XE');

    // Сообщим его базе данных
    oci_set_client_identifier($c, $un);

    // Следующий запрос к БД заодно установит идентификатор
    $s = oci_parse($c, 'select mydata from mytable');
    oci_execute($s);

    // ...

    ?>

### Примечания

Предостережение

# Совет по полному сканированию таблицы (roundtrip)

Ряд OCI8-функции вызывают полное сканирование таблицы (roundtrip). Функции не сканируют таблицы полностью для тех запросов, в которых включено кеширование результатов в базе данных.

### Смотрите также

- oci_set_module_name() - Задаёт имя модулю
- oci_set_action() - Задаёт имя для действия
- oci_set_client_info() - Задаёт информацию о клиенте
- oci_set_db_operation() - Задаёт операцию базы данных

# oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — Задаёт информацию о клиенте

### Описание

function oci_set_client_info(resource `$connection`, string `$client_info`): bool

Задет информацию о клиенте для трассировки Oracle.

Информация о клиенте регистрируется в базе данных во время очередного запроса от PHP, например, когда запускается SQL выражение.

Клиентская информация может быть извлечена из административных представлений (view) базы данных, таких как `V$SESSION`.

Значение можно устанавливать и через постоянные соединения.

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`client_info`

  Задаваемая пользователем строка до 64 байт.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка клиентской информации

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Запись информации о клиенте
    oci_set_client_info($c, 'My Application Version 2');

    // Код, осуществляющий запрос к БД, например выборка:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Пока скрипт выполняется, администратор может увидеть клиентскую
    // информацию:

    sqlplus system/welcome
    SQL> select client_info from v$session;

### Примечания

> Замечание: Требование к версии Oracle
> Эта функция доступна, если PHP слинкован с библиотеками Oracle Database начиная с версии 10g и выше.

Подсказка

# Производительность

В старых версиях модуля OCI8 или базы данных Oracle была доступна установка информации о клиенте средствами пакета `DBMS_APPLICATION_INFO`. Для этого более эффективен вызов функции oci_set_client_info().

Предостережение

# Совет по полному сканированию таблицы (roundtrip)

Ряд OCI8-функции вызывают полное сканирование таблицы (roundtrip). Функции не сканируют таблицы полностью для тех запросов, в которых включено кеширование результатов в базе данных.

### Смотрите также

- oci_set_module_name() - Задаёт имя модулю
- oci_set_action() - Задаёт имя для действия
- oci_set_client_identifier() - Задаёт идентификатор клиента
- oci_set_db_operation() - Задаёт операцию базы данных

# oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Задаёт операцию базы данных

### Описание

function oci_set_db_operation(resource `$connection`, string `$action`): bool

Устанавливает DBOP для трассировки Oracle.

Имя операции базы данных регистрируется в базе данных при следующем "циклическом пути" (round-trip) из PHP в базу данных, как правило, при выполнении выражения SQL.

Операция базы данных может впоследствии запрашиваться из представлений администрирования базы данных, таких как `V$SQL_MONITOR`.

Функция oci_set_db_operation() доступна, если oci8 использует клиентские библиотеки Oracle версии 12 (или новее) и базу данных Oracle 12 (или новее).

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`action`

  Пользовательская строка.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка DBOP

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Записать операцию
    oci_set_db_operation($c, 'main query');

    // Код, вызывающий циклический путь, например запрос:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // Во время выполнения скрипта администратор может видеть выполняемые операции
    // с базой данных.

    sqlplus system/welcome
    SQL> select dbop_name from v$sql_monitor;

### Примечания

Предостережение

# Совет по полному сканированию таблицы (roundtrip)

Ряд OCI8-функции вызывают полное сканирование таблицы (roundtrip). Функции не сканируют таблицы полностью для тех запросов, в которых включено кеширование результатов в базе данных.

### Смотрите также

- oci_set_action() - Задаёт имя для действия
- oci_set_module_name() - Задаёт имя модулю
- oci_set_client_info() - Задаёт информацию о клиенте
- oci_set_client_identifier() - Задаёт идентификатор клиента

# oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — Задаёт выпуск (edition) базы данных

### Описание

function oci_set_edition(string `$edition`): bool

Задаёт "серию" объектов для использования на нижестоящих соединениях.

Подобные "выпуски" Oracle позволяют запускать приложения, использующие одинаковые схемы и имена объектов в конкурентном режиме. Это может быть полезным при модернизации работающих систем без их отключения.

Вызывайте oci_set_edition() до вызова oci_connect(), oci_pconnect() или oci_new_connect().

Если заданный выпуск является недопустимым в базе данных, соединение не будет устанавливаться, даже если функция oci_set_edition() успешно выполнится.

При использовании постоянных соединений, если соединение с данным значением серии уже существует, оно будет использовано повторно. В остальных случаях будет создаваться новое соединение.

### Список параметров

`edition`

  Имя "выпуска" базы данных Oracle, ранее созданное SQL командой "`CREATE EDITION`".

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Два скрипта могут использовать различные версии функции myfunc() одновременно

    <?php

    // Файл 1

    echo "Версия приложения 1\n";

    oci_set_edition('ORA$BASE');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "Результат: $r\n";

    ?>

    <?php

    // Файл 2

    echo "Версия приложения 2\n";

    oci_set_edition('E1');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "Результат: $r\n";

    ?>

### Примечания

> Замечание: Требование к версии Oracle

> Эта функция доступна, начиная с Oracle 11gR2.

Предостережение

# Постоянные соединения

Во избежание несовместимости и случайных ошибок не используйте команду "ALTER SESSION SET EDITION" для изменения "серии" на постоянных соединениях.

Предостережение

# DRCP объединение соединений в пул

Во избежание несовместимости и случайных ошибок при использовании серий и DRCP в Oracle 11.2.0.1 придерживайтесь однозначного соответствия между oci8.connection_class и именем "выпуска", которым пользуются приложения. Каждый сервер, входящий в состав пула с заданным классом соединений, должен использоваться только с одним "выпуском". Это ограничение устранено в версии Oracle 11.2.0.2.

# oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — Задаёт имя модулю

### Описание

function oci_set_module_name(resource `$connection`, string `$name`): bool

Задаёт имя модуля для трассировки Oracle.

Имя модуля регистрируется в базе данных во время очередного запроса от PHP, например, когда запускается SQL выражение.

Имя может быть извлечено из административных представлений (view) базы данных, таких как `V$SESSION`. Оно может использоваться для трассировки и мониторинга также, как `V$SQLAREA` and `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

Значение можно устанавливать и через постоянные соединения.

### Список параметров

`connection`
  Идентификатор соединения Oracle, который возвращают функции oci_connect(), oci_pconnect() или oci_new_connect().
`name`

  Задаваемая пользователем строка string длиной до 48 байт.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установка имени модуля

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Запись модуля
    oci_set_module_name($c, 'Home Page');

    // Код, осуществляющий запрос к БД, например выборка:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);
    ?>

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

    sqlplus system/welcome
    SQL> select module from v$session;

### Примечания

> Замечание: Требование к версии Oracle
> Эта функция доступна, если PHP слинкован с библиотеками Oracle Database начиная с версии 10g и выше.

Подсказка

# Производительность

В старых версиях модуля OCI8 или базы данных Oracle была доступна установка информации о клиенте средствами пакета `DBMS_APPLICATION_INFO`. Для этого более эффективен вызов функции oci_set_client_info().

Предостережение

# Совет по полному сканированию таблицы (roundtrip)

Ряд OCI8-функции вызывают полное сканирование таблицы (roundtrip). Функции не сканируют таблицы полностью для тех запросов, в которых включено кеширование результатов в базе данных.

### Смотрите также

- oci_set_action() - Задаёт имя для действия
- oci_set_client_info() - Задаёт информацию о клиенте
- oci_set_client_identifier() - Задаёт идентификатор клиента
- oci_set_db_operation() - Задаёт операцию базы данных

# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Устанавливает количество строк, которые будут автоматически выбраны в буфер

### Описание

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

Устанавливает количество строк, которые будут выбраны в буфер клиентскими библиотеками Oracle сразу после удачного вызова oci_execute() и для каждого последующего внутреннего запроса данных к базе. Производительность может быть значительно увеличена для запросов, возвращающих большое количество строк, с помощью установки значения предварительной выборки больше значения по умолчанию oci8.default_prefetch.

Предварительная выборка - это эффективный механизм Oracle, позволяющий возвращать больше одной строки результата из базы данных за каждый сетевой запрос. Это даёт более рациональное использование сети и процессора. Буферизация строк происходит внутри OCI8, поэтому поведение функций выборки OCI8 никак не зависит от размера предварительной выборки. Например, oci_fetch_row() всегда возвращает одну строку. Буфер предварительной выборки резервируется отдельно на каждый запрос и не используется второй раз в повторно запущенных запросах или в других соединениях.

Перед вызовом oci_execute() вызовите oci_set_prefetch().

Смысл настройки размера предварительной выборки состоит в подборе удобного значения для передачи в сети и обработки в базе данных. Для запросов, возвращающих очень большое количество строк, общая производительность системы может быть лучше, если строки будут возвращаться в несколько приёмов (т.е. установить размер предварительной выборки меньше количества строк). Это позволит базе данных обрабатывать запросы других пользователей в течение обработки PHP-скриптом текущего результата запроса.

Предварительная выборка запросов появилась в Oracle 8i. Предварительная выборка REF CURSOR появилась в Oracle 11gR2 и может быть применена в случае, если PHP слинкован с клиентскими библиотеками Oracle 11gR2 и старше. Предварительная выборка вложенных курсоров была добавлена в Oracle 11gR2 и требует наличия версии 11gR2 и старше как для клиентских библиотек Oracle, так и для используемой базы данных.

Предварительная выборка не поддерживается, если запросы содержат LONG или LOB столбцы. Значение предварительной выборки игнорируется и, во всех ситуациях не поддерживающих предварительную выборку, будет использована построчная выборка.

При использовании Oracle Database 12c, предварительная выборка заданная PHP может быть изменена конфигурационным файлом `oraaccess.xml` клиента Oracle. Обратитесь к документации Oracle за дополнительной информацией.

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.
`rows`

  Количество строк предварительной выборки, >= 0

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Смена значения предварительной выборки по умолчанию для запроса

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // Устанавливаем перед вызовом oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Пример #2 Смена значения предварительной выборки по умолчанию для выборки REF CURSOR

    <?php
    /*
      Создайте хранимую процедуру PL/SQL следующим образом:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Меняем размер предварительной выборки перед запуском курсора.
    // Предварительная выборка REF CURSOR работает в случае линковки PHP
    // с клиентскими библиотеками Oracle 11gR2 и старше
    oci_set_prefetch($refcur, 200);
    oci_execute($refcur);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Если PHP OCI8 производит выборку из REF CURSOR, а затем передаёт REF CURSOR обратно в другую PL/SQL-процедуру для дальнейшей обработки, необходимо установить размер предварительной выборки REF CURSOR в `0`, чтобы избежать "потери" рядов из результата. Значение предварительной выборки - это количество "лишних" рядов, полученных каждым внутренним запросом OCI8 к базе данных, поэтому установка его в `0` означает выборку только одного ряда за один раз.

Пример #3 Установка значения предварительной выборки при передаче REF CURSOR обратно в Oracle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/orcl');

    // получение REF CURSOR
    $stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Отображаем два ряда, но больше не предвыбираем других рядов, иначе
    // эти ряды не будут переданы обратно в  myproc_use_rc().
    oci_set_prefetch($refcur, 0);
    oci_execute($refcur);
    $row = oci_fetch_array($refcur);
    var_dump($row);
    $row = oci_fetch_array($refcur);
    var_dump($row);

    // передаём REF CURSOR в myproc_use_rc() для дальнейшей обработки результата
    $stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
    oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    ?>

### Смотрите также

- Директива oci8.default_prefetch

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — Устанавливает объём данных, предварительно выбираемых для каждого CLOB или BLOB

### Описание

function oci_set_prefetch_lob(resource `$statement`, int `$prefetch_lob_size`): bool

Устанавливает размер внутреннего буфера, используемого для выборки каждого значения CLOB или BLOB, когда реализация получает внутренний локатор LOB Oracle из базы данных после успешного вызова запроса к функции oci_execute() и для каждого последующего внутреннего запроса выборки в базу данных. Увеличение этого значения может улучшить производительность выборки меньших LOB за счёт сокращения круговых обходов между PHP и базой данных. Использование памяти изменится.

Значение влияет на большие объекты, возвращаемые как экземпляры OCILob, а также на те, которые возвращаются с использованием `OCI_RETURN_LOBS`.

Функция oci_set_prefetch_lob() вызывается до вызова oci_execute(). Если функция не была вызвана, используется значение oci8.prefetch_lob_size.

Значение предварительной выборки LOB следует устанавливать только в Oracle Database 12.2 или новее.

### Список параметров

`statement`
  Корректный идентификатор выражения OCI8, полученный из функции oci_parse() и исполненный функцией oci_execute(), или идентификатор выражения `REF CURSOR`.
`prefetch_lob_size`

  Число байтов каждого LOB, которое нужно предварительно выбрать, >= 0.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Изменение значения предварительной выборки LOB для запроса

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myclob FROM mytable');
    oci_set_prefetch_lob($stid, 100000);  // Установка значения перед вызовом oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Смотрите также

- INI-опция oci8.prefetch_lob_size

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — Возвращает тип выражения

### Описание

function oci_statement_type(resource `$statement`): string|false

Возвращает выражение, соответствующее одному из типов параметра `statement` OCI8.

### Список параметров

`statement`

  Допустимый идентификатор оператора OCI8, возвращаемый oci_parse().

### Возвращаемые значения

Возвращает тип параметра `statement`, который может быть одним из нижеследующих значений:

Тип оператора
Возвращаемое значение | Примечание
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования oci_statement_type()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
    if (oci_statement_type($stid) == "DELETE") {
        trigger_error('Вы не имеете прав для удаления записей из таблицы', E_USER_ERROR);
    }
    else {
        oci_execute($stid);  // удалить запись
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Удалить регистрацию пользовательской callback-функции для Oracle Database TAF

### Описание

function oci_unregister_taf_callback(resource `$connection`): bool

Удаляет регистрацию пользовательской callback-функции, зарегистрированную для соединения `connection` с помощью oci_register_taf_callback(). Более подробно читайте OCI8 Transparent Application Failover (TAF) Support .

### Список параметров

`connection`

  Идентификатор соединения Oracle.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- oci_register_taf_callback() - Регистрирует пользовательскую функцию обратного вызова для Oracle Database TAF

## Содержание

- oci_bind_array_by_name — Связывает PHP массив с массивом Oracle PL/SQL
- oci_bind_by_name — Прикрепляет переменную PHP к соответствующей метке в SQL-выражении
- oci_cancel — Заканчивает процесс чтения из курсора
- oci_client_version — Возвращает версию клиентской библиотеки
- oci_close — Закрывает соединение с сервером Oracle
- oci_commit — Подтверждает транзакцию базы данных
- oci_connect — Устанавливает соединение с базой данных Oracle
- oci_define_by_name — Сопоставляет переменную PHP столбцу результата запроса
- oci_error — Возвращает последнюю ошибку
- oci_execute — Выполняет подготовленное выражение
- oci_fetch — Выбирает следующую строку из результата в буфер
- oci_fetch_all — Выбирает все строки из результата запроса в двумерный массив
- oci_fetch_array — Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
- oci_fetch_assoc — Возвращает следующую строку из результата запроса в виде ассоциативного массива
- oci_fetch_object — Возвращает следующую строку из результата запроса в виде объекта
- oci_fetch_row — Возвращает следующую строку из результата запроса в виде нумерованного массива
- oci_field_is_null — Проверяет, равняется ли поле в текущем полученном ряду равным null
- oci_field_name — Возвращает имя поля из результата запроса
- oci_field_precision — Возвращает точность поля
- oci_field_scale — Возвращает масштаб поля
- oci_field_size — Возвращает размер поля
- oci_field_type — Возвращает имя типа поля
- oci_field_type_raw — Возвращает исходный тип поля Oracle
- oci_free_descriptor — Освобождает дескриптор
- oci_free_statement — Освобождает ресурсы, занимаемые курсором или SQL-выражением
- oci_get_implicit_resultset — Возвращает следующий ресурс дочернего запроса из ресурса родительского запроса, имеющего неявные результирующие наборы Oracle Database
- oci_lob_copy — Копирует объект LOB
- oci_lob_is_equal — Сравнивает два объекта LOB/FILE
- oci_new_collection — Создаёт новый объект коллекции
- oci_new_connect — Устанавливает новое соединение с сервером Oracle
- oci_new_cursor — Возвращает идентификатор созданного курсора
- oci_new_descriptor — Инициализирует новый дескриптор объекта LOB или FILE
- oci_num_fields — Возвращает количество полей в результате запроса
- oci_num_rows — Возвращает количество строк, изменённых в процессе выполнения запроса
- oci_parse — Подготавливает запрос к выполнению
- oci_password_change — Изменяет пароль пользователя Oracle
- oci_pconnect — Устанавливает постоянное соединение с сервером Oracle
- oci_register_taf_callback — Регистрирует пользовательскую функцию обратного вызова для Oracle Database TAF
- oci_result — Возвращает значение поля из результата запроса
- oci_rollback — Откатывает транзакции, ожидающие обработки
- oci_server_version — Возвращает версию сервера Oracle
- oci_set_action — Задаёт имя для действия
- oci_set_call_timeout — Устанавливает время ожидания в миллисекундах для вызовов базы данных
- oci_set_client_identifier — Задаёт идентификатор клиента
- oci_set_client_info — Задаёт информацию о клиенте
- oci_set_db_operation — Задаёт операцию базы данных
- oci_set_edition — Задаёт выпуск (edition) базы данных
- oci_set_module_name — Задаёт имя модулю
- oci_set_prefetch — Устанавливает количество строк, которые будут автоматически выбраны в буфер
- oci_set_prefetch_lob — Устанавливает объём данных, предварительно выбираемых для каждого CLOB или BLOB
- oci_statement_type — Возвращает тип выражения
- oci_unregister_taf_callback — Удалить регистрацию пользовательской callback-функции для Oracle Database TAF

# Класс OCICollection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Введение

Функционал коллекций OCI8.

> Замечание:

> Класс OCI-Collection был переименован в OCICollection в PHP 8 OCI8 3.0.0 в соответствии со стандартами именования PHP.

## Обзор класса

class OCICollection {
/* Методы */
public function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — Добавляет элемент в коллекцию

### Описание

public function OCICollection::append(string `$value`): bool

Добавляет элемент в конец коллекции.

### Список параметров

`value`

  Значение, добавляемое в конец коллекции.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Присваивает коллекции значение другой, уже существующей коллекции

### Описание

public function OCICollection::assign(OCICollection `$from`): bool

Присваивает коллекции значение другой, ранее созданной коллекции. Обе коллекции должны быть созданы ранее с помощью oci_new_collection().

### Список параметров

`from`

  Экземпляр OCI-Collection.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Присваивает значение элементу коллекции

### Описание

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Присваивает значение элементу коллекции с индексом `index`.

### Список параметров

`index`

  Индекс элемента. Первый индекс - ноль.

`value`

  Может быть строкой или числом.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Освобождает ресурсы, занимаемые объектом коллекции

### Описание

public function OCICollection::free(): bool

Освобождает ресурсы, занимаемые объектом коллекции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Возвращает значение элемента

### Описание

public function OCICollection::getElem(int `$index`): string|float|null|false

Возвращает значение элемента с индексом `index` (начиная с нуля).

### Список параметров

`index`

  Индекс элемента. Первый индекс - ноль.

### Возвращаемые значения

Djpdhfoftn `false`, если такого элемента нет; `null`, если элемент равен `null`; строку, если элемент относится к строковому столбцу, и число, если элемент является числовым полем.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Возвращает максимальное количество элементов в коллекции

### Описание

public function OCICollection::max(): int|false

Возвращает максимальное количество элементов в коллекции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает максимальное количество как целое число или `false` в случае возникновения ошибки.

Если будет возвращён 0, то количество элементов не ограничено.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Возвращает количество элементов в коллекции

### Описание

public function OCICollection::size(): int|false

Возвращает количество элементов в коллекции.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество элементов в коллекции или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Отсекает элементы с конца коллекции

### Описание

public function OCICollection::trim(int `$num`): bool

Отсекает `num` элементов с конца коллекции.

### Список параметров

`num`

  Количество элементов для отсечения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Collection переименован в OCICollection в соответствии со стандартами именования PHP.

### Смотрите также

- OCICollection::size

## Содержание

- OCICollection::append — Добавляет элемент в коллекцию
- OCICollection::assign — Присваивает коллекции значение другой, уже существующей коллекции
- OCICollection::assignElem — Присваивает значение элементу коллекции
- OCICollection::free — Освобождает ресурсы, занимаемые объектом коллекции
- OCICollection::getElem — Возвращает значение элемента
- OCICollection::max — Возвращает максимальное количество элементов в коллекции
- OCICollection::size — Возвращает количество элементов в коллекции
- OCICollection::trim — Отсекает элементы с конца коллекции

# Класс OCILob

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Введение

Функциональность OCI8 LOB для больших бинарных (BLOB) и символьных (CLOB) объектов.

> Замечание:

> Класс OCI-Lob был переименован в OCILob в PHP 8 OCI8 3.0.0 в соответствии со стандартами именования PHP.

## Обзор класса

class OCILob {
/* Методы */
public function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — Добавляет данные из объекта LOB в конец другого объекта

### Описание

public function OCILob::append(OCILob `$from`): bool

Добавляет в конец объекта LOB данные из другого объекта LOB.

Запись в LOB с помощью этого метода вызовет ошибку, если у объекта ранее был включён режим буферизации. Поэтому вы должны выключить буферизацию перед её применением. Перед выключением буферизации вам может понадобиться метод OCILob::flush для очистки буфера.

### Список параметров

`from`

  Копируемый LOB.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Закрывает дескриптор объекта LOB

### Описание

public function OCILob::close(): bool

Закрывает дескриптор объекта LOB или FILE. Функцию следует использовать только вместе с OCILob::writeTemporary.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — Проверяет, находится ли указатель LOB на конце объекта

### Описание

public function OCILob::eof(): bool

Сообщает о достижении внутренним указателем конца объекта LOB.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если внутренний указатель объекта находится на конце LOB. Иначе возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Примечания

> Замечание:

> Функция возвращает Oracle ошибку в случае, если OCILob::setBuffering включена для LOB.

### Смотрите также

- OCILob::size

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — Очищает указанную часть объекта LOB

### Описание

public function OCILob::erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false

Очищает конкретную часть объекта LOB, начиная с позиции, определённой в параметре `offset`. По умолчанию LOB очищается полностью.

Для объектов типа BLOB очищение означает заполнение нулевыми байтами. Объекты типа CLOB заполняются пробелами.

### Список параметров

`offset`

`length`

### Возвращаемые значения

Возвращает число очищенных символов/байт или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` и `length` теперь допускают значение null.
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Сохраняет содержимое объекта LOB в файл

### Описание

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Сохраняет содержимое объекта LOB в файл.

### Список параметров

`filename`

  Путь к файлу.

`offset`

  Начальная позиция экспорта.

`length`

  Длина экспортируемой части LOB.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` и `length` теперь допускают значение null.
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::import

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — Очищает и записывает буфер объекта LOB на сервер

### Описание

public function OCILob::flush(int `$flag` = 0): bool

OCILob::flush() непосредственно записывает данные на сервер.

### Список параметров

`flag`

  По умолчанию ресурсы не освобождаются, но используя флаг `OCI_LOB_BUFFER_FREE` вы можете сделать это принудительно. Однако, вы должны быть точно уверены в том, что вы делаете, так как следующее чтение из объекта будет более ресурсоемко, чем предыдущие из-за необходимости обращения к серверу. Поэтому использовать флаг `OCI_LOB_BUFFER_FREE` рекомендуется только после того, как работа с объектом уже закончена.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Возвращает `false` в случае возникновения ошибки или если буферизация объекта не была включена.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::getBuffering
- OCILob::setBuffering

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — Освобождает ресурсы, связанные с дескриптором LOB

### Описание

public function OCILob::free(): bool

Освобождает ресурсы, связанные с дескриптором LOB, изначально выделенные функцией oci_new_descriptor().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — Возвращает текущее состояние буферизации большого объекта (LOB)

### Описание

public function OCILob::getBuffering(): bool

Сообщает, включена ли буферизация для большого объекта (LOB).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `false`, если буферизация отключена, и `true`, если включена.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Записывает содержимое файла в объект LOB

### Описание

public function OCILob::import(string `$filename`): bool

Записывает содержимое файла `filename` в текущую позицию объекта LOB.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Возвращает содержимое объекта LOB

### Описание

public function OCILob::load(): string|false

Возвращает содержимое объекта LOB. Так как выполнение скрипта прекратится при превышении memory_limit, необходимо убедиться, что LOB не превышает этого ограничения. Поэтому, в большинстве случаев этот метод рекомендуется заменять на OCILob::read.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает содержимое объекта или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Возвращает часть объекта LOB

### Описание

public function OCILob::read(int `$length`): string|false

Читает `length` байтов (BLOB) или символов (CLOB) с текущей позиции объекта LOB.

Чтение останавливается, когда прочитано `length` байтов для BLOB, `length` символов для CLOB или когда достигнут конец объекта. Внутренний указатель объекта будет сдвинут на количество прочитанных байт/символов.

### Список параметров

`length`

  Длина считываемых данных, в байтах (BLOB) или символах (CLOB). Большие значения округляются вниз до 1 MB.

### Возвращаемые значения

Возвращает содержимое в виде строки или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::load
- OCILob::write

# OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — Переводит указатель объекта в начало большого объекта

### Описание

public function OCILob::rewind(): bool

Устанавливает внутренний указатель в начало объекта LOB.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — Сохраняет данные в LOB

### Описание

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Сохраняет данные из параметра `data` в объект LOB.

### Список параметров

`data`

  Данные для сохранения.

`offset`

  Может использоваться для указания смещения от начала LOB.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — Псевдоним OCILob::import()

### Описание

Псевдоним функции OCILob::import().

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Устанавливает позицию внутреннего указателя LOB

### Описание

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Устанавливает позицию внутреннего указателя объекта LOB.

### Список параметров

`offset`

  Указывает количество байтов, на которые следует переместиться от позиции, определяемой параметром `whence`:

`whence`

  Может быть одним из значений:

  - `OCI_SEEK_SET` - установить позицию, равную `offset`
  - `OCI_SEEK_CUR` - прибавить к текущей позиции `offset` байт
  - `OCI_SEEK_END` - прибавить к концу файла `offset` байт (чтобы переместить указатель в начало - укажите отрицательный `offset`)

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::rewind
- OCILob::tell
- OCILob::eof

# OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — Изменяет текущее состояние буферизации большого объекта (LOB)

### Описание

public function OCILob::setBuffering(bool `$mode`): bool

Устанавливает буферизацию для большого объекта исходя из значения параметра `mode`.

Использование этой функции может привести к улучшению производительности путём буферизации мелких операций чтения и записи в LOB за счёт уменьшения количества сетевых обращений и версий LOB. Необходимо обязательно использовать OCILob::flush() после завершения всех работ с LOB.

### Список параметров

`mode`

  `true` для включения и `false` для отключения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Повторные вызовы этого метода с тем же флагом будет возвращать `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Возвращает размер объекта LOB

### Описание

public function OCILob::size(): int|false

Возвращает размер объекта LOB

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает длину объекта LOB или `false`, если возникла ошибка. Для пустых объектов длина равняется нулю.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — Возвращает текущую позицию внутреннего указателя объекта LOB

### Описание

public function OCILob::tell(): int|false

Метод возвращает текущую позицию внутреннего указателя объекта LOB.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает текущую позицию внутреннего указателя объекта LOB или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Обрезает большой объект

### Описание

public function OCILob::truncate(int `$length` = 0): bool

Обрезает объект LOB.

### Список параметров

`length`

  Если указан, то LOB обрезается до указанной в `length` длины в байтах. Иначе LOB очищается полностью.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Записывает данные в объект LOB

### Описание

public function OCILob::write(string `$data`, ?int `$length` = `null`): int|false

Записывает данные из параметра `data` в текущую позицию внутреннего указателя объекта.

### Список параметров

`data`

  Записываемые в LOB данные.

`length`

  Если параметр является числом, то запись остановится после того, как `length` байт будет записано или закончатся данные из параметра `data`.

### Возвращаемые значения

Возвращает количество записанных байт или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` теперь допускает значение null.
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Записывает временный большой объект (LOB)

### Описание

public function OCILob::writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool

Создаёт временный большой объект и записывает в него данные `data`.

После завершения работы с этим объектом его желательно закрыть функцией OCILob::close.

### Список параметров

`data`

  Данные для записи.

`type`

  Один из следующих вариантов:

  - `OCI_TEMP_BLOB` для создания временных BLOB
  - `OCI_TEMP_CLOB` для создания временных CLOB

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

### Смотрите также

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — Псевдоним OCILob::export()

### Описание

Псевдоним функции OCILob::export().

### Список изменений

Версия | Описание
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` и `length` теперь допускают значение null.
8.0.0, PECL OCI8 3.0.0 | Класс OCI-Lob переименован в OCILob в соответствии со стандартами именования PHP.

## Содержание

- OCILob::append — Добавляет данные из объекта LOB в конец другого объекта
- OCILob::close — Закрывает дескриптор объекта LOB
- OCILob::eof — Проверяет, находится ли указатель LOB на конце объекта
- OCILob::erase — Очищает указанную часть объекта LOB
- OCILob::export — Сохраняет содержимое объекта LOB в файл
- OCILob::flush — Очищает и записывает буфер объекта LOB на сервер
- OCILob::free — Освобождает ресурсы, связанные с дескриптором LOB
- OCILob::getBuffering — Возвращает текущее состояние буферизации большого объекта (LOB)
- OCILob::import — Записывает содержимое файла в объект LOB
- OCILob::load — Возвращает содержимое объекта LOB
- OCILob::read — Возвращает часть объекта LOB
- OCILob::rewind — Переводит указатель объекта в начало большого объекта
- OCILob::save — Сохраняет данные в LOB
- OCILob::saveFile — Псевдоним OCILob::import
- OCILob::seek — Устанавливает позицию внутреннего указателя LOB
- OCILob::setBuffering — Изменяет текущее состояние буферизации большого объекта (LOB)
- OCILob::size — Возвращает размер объекта LOB
- OCILob::tell — Возвращает текущую позицию внутреннего указателя объекта LOB
- OCILob::truncate — Обрезает большой объект
- OCILob::write — Записывает данные в объект LOB
- OCILob::writeTemporary — Записывает временный большой объект (LOB)
- OCILob::writeToFile — Псевдоним OCILob::export

# Устаревшие наименования и функции OCI8

# oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — Включает или отключает внутренний вывод отладки

### Описание

function oci_internal_debug(bool `$onoff`): void

Функция включает или отключает внутренний вывод отладки.

### Список параметров

`onoff`

  Чтобы отключить вывод отладки, устанавливают значение `false`, чтобы включить — `true`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примечания

> Замечание:

> Функцию удалили в PHP 8 и PECL OCI8 3.0.

# ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — Псевдоним функции oci_bind_by_name()

### Описание

Псевдоним функции oci_bind_by_name().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — Псевдоним oci_cancel()

### Описание

Псевдоним функции oci_cancel().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — Псевдоним OCILob::close()

### Описание

Псевдоним метода OCILob::close().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — Псевдоним OCICollection::append()

### Описание

Псевдоним метода OCICollection::append().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — Псевдоним метода OCICollection::assign()

### Описание

Псевдоним метода OCICollection::assign().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — Псевдоним метода OCICollection::assignElem()

### Описание

Псевдоним метода OCICollection::assignElem().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — Псевдоним метода OCICollection::getElem()

### Описание

Псевдоним метода OCICollection::getElem().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — Псевдоним метода OCICollection::max()

### Описание

Псевдоним метода OCICollection::max().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — Псевдоним метода OCICollection::size()

### Описание

Псевдоним метода OCICollection::size().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — Псевдоним метода OCICollection::trim()

### Описание

Псевдоним метода OCICollection::trim().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — Псевдоним функции oci_field_is_null()

### Описание

Псевдоним функции oci_field_is_null().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — Псевдоним функции oci_field_name()

### Описание

Псевдоним функции oci_field_name().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — Псевдоним функции oci_field_precision()

### Описание

Псевдоним функции oci_field_precision().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — Псевдоним функции oci_field_scale()

### Описание

Псевдоним функции oci_field_scale().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — Псевдоним функции oci_field_size()

### Описание

Псевдоним функции oci_field_size().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — Псевдоним функции oci_field_type()

### Описание

Псевдоним функции oci_field_type().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — Псевдоним функции oci_field_type_raw()

### Описание

Псевдоним функции oci_field_type_raw().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — Псевдоним функции oci_commit()

### Описание

Псевдоним функции oci_commit().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — Псевдоним функции oci_define_by_name()

### Описание

Псевдоним функции oci_define_by_name().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — Псевдоним функции oci_error()

### Описание

Псевдоним функции oci_error().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — Псевдоним функции oci_execute()

### Описание

Псевдоним функции oci_execute().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — Псевдоним функции oci_fetch()

### Описание

Псевдоним функции oci_fetch().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Устаревший вариант функций oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() и oci_fetch_row()

### Описание

Устаревший вариант функций oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() и oci_fetch_row().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — Псевдоним функции oci_fetch_all()

### Описание

Псевдоним функции oci_fetch_all().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — Псевдоним метода OCICollection::free()

### Описание

Псевдоним метода OCICollection::free().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — Псевдоним функции oci_free_statement()

### Описание

Псевдоним функции oci_free_statement().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — Псевдоним метода OCILob::free()

### Описание

Псевдоним метода OCILob::free().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — Псевдоним функции oci_free_statement()

### Описание

Псевдоним функции oci_free_statement().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — Псевдоним функции oci_internal_debug()

### Описание

Псевдоним функции oci_internal_debug().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — Псевдоним метода OCILob::load()

### Описание

Псевдоним метода OCILob::load().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — Псевдоним функции oci_close()

### Описание

Псевдоним функции oci_close().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — Псевдоним функции oci_connect()

### Описание

Псевдоним функции oci_connect().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — Псевдоним функции oci_new_collection()

### Описание

Псевдоним функции oci_new_collection().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — Псевдоним функции oci_new_cursor()

### Описание

Псевдоним функции oci_new_cursor().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — Псевдоним функции oci_new_descriptor()

### Описание

Псевдоним функции oci_new_descriptor().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — Псевдоним функции oci_new_connect()

### Описание

Псевдоним функции oci_new_connect().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — Псевдоним функции oci_num_fields()

### Описание

Псевдоним функции oci_num_fields().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — Псевдоним функции oci_parse()

### Описание

Псевдоним функции oci_parse().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — Псевдоним функции oci_pconnect()

### Описание

Псевдоним функции oci_pconnect().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — Псевдоним функции oci_result()

### Описание

Псевдоним функции oci_result().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — Псевдоним функции oci_rollback()

### Описание

Псевдоним функции oci_rollback().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — Псевдоним функции oci_num_rows()

### Описание

Псевдоним функции oci_num_rows().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — Псевдоним метода OCILob::save()

### Описание

Псевдоним метода OCILob::save().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — Псевдоним метода OCILob::import()

### Описание

Псевдоним метода OCILob::import().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — Псевдоним функции oci_server_version()

### Описание

Псевдоним функции oci_server_version().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — Псевдоним функции oci_set_prefetch()

### Описание

Псевдоним функции oci_set_prefetch().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — Псевдоним функции oci_statement_type()

### Описание

Псевдоним функции oci_statement_type().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — Псевдоним метода OCILob::export()

### Описание

Псевдоним метода OCILob::export().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — Псевдоним метода OCILob::writeTemporary()

### Описание

Псевдоним метода OCILob::writeTemporary().

Внимание

Начиная с PHP 5.4.0 псевдоним УСТАРЕЛ. Полагаться на псевдоним настоятельно не рекомендуют.

## Содержание

- oci_internal_debug — Включает или отключает внутренний вывод отладки
- ocibindbyname — Псевдоним функции oci_bind_by_name
- ocicancel — Псевдоним oci_cancel
- ocicloselob — Псевдоним OCILob::close
- ocicollappend — Псевдоним OCICollection::append
- ocicollassign — Псевдоним метода OCICollection::assign
- ocicollassignelem — Псевдоним метода OCICollection::assignElem
- ocicollgetelem — Псевдоним метода OCICollection::getElem
- ocicollmax — Псевдоним метода OCICollection::max
- ocicollsize — Псевдоним метода OCICollection::size
- ocicolltrim — Псевдоним метода OCICollection::trim
- ocicolumnisnull — Псевдоним функции oci_field_is_null
- ocicolumnname — Псевдоним функции oci_field_name
- ocicolumnprecision — Псевдоним функции oci_field_precision
- ocicolumnscale — Псевдоним функции oci_field_scale
- ocicolumnsize — Псевдоним функции oci_field_size
- ocicolumntype — Псевдоним функции oci_field_type
- ocicolumntyperaw — Псевдоним функции oci_field_type_raw
- ocicommit — Псевдоним функции oci_commit
- ocidefinebyname — Псевдоним функции oci_define_by_name
- ocierror — Псевдоним функции oci_error
- ociexecute — Псевдоним функции oci_execute
- ocifetch — Псевдоним функции oci_fetch
- ocifetchinto — Устаревший вариант функций oci_fetch_array, oci_fetch_object, oci_fetch_assoc и oci_fetch_row
- ocifetchstatement — Псевдоним функции oci_fetch_all
- ocifreecollection — Псевдоним метода OCICollection::free
- ocifreecursor — Псевдоним функции oci_free_statement
- ocifreedesc — Псевдоним метода OCILob::free
- ocifreestatement — Псевдоним функции oci_free_statement
- ociinternaldebug — Псевдоним функции oci_internal_debug
- ociloadlob — Псевдоним метода OCILob::load
- ocilogoff — Псевдоним функции oci_close
- ocilogon — Псевдоним функции oci_connect
- ocinewcollection — Псевдоним функции oci_new_collection
- ocinewcursor — Псевдоним функции oci_new_cursor
- ocinewdescriptor — Псевдоним функции oci_new_descriptor
- ocinlogon — Псевдоним функции oci_new_connect
- ocinumcols — Псевдоним функции oci_num_fields
- ociparse — Псевдоним функции oci_parse
- ociplogon — Псевдоним функции oci_pconnect
- ociresult — Псевдоним функции oci_result
- ocirollback — Псевдоним функции oci_rollback
- ocirowcount — Псевдоним функции oci_num_rows
- ocisavelob — Псевдоним метода OCILob::save
- ocisavelobfile — Псевдоним метода OCILob::import
- ociserverversion — Псевдоним функции oci_server_version
- ocisetprefetch — Псевдоним функции oci_set_prefetch
- ocistatementtype — Псевдоним функции oci_statement_type
- ociwritelobtofile — Псевдоним метода OCILob::export
- ociwritetemporarylob — Псевдоним метода OCILob::writeTemporary

- Установка и настройка
  - Требования
  - Установка
  - Тестирование
  - Настройка во время выполнения
- Предопределённые константы
- Примеры
- Работа с соединениями OCI8 и Connection Pooling
- Поддержка OCI8 Fast Application Notification (FAN)
- Поддержка прозрачного для приложений восстановления после отказа (Transparent Application Failover или TAF) для OCI8
- OCI8 и динамическая трассировка DTrace
- Поддерживаемые типы данных
- OCI8 Функции
  - oci_bind_array_by_name — Связывает PHP массив с массивом Oracle PL/SQL
  - oci_bind_by_name — Прикрепляет переменную PHP к соответствующей метке в SQL-выражении
  - oci_cancel — Заканчивает процесс чтения из курсора
  - oci_client_version — Возвращает версию клиентской библиотеки
  - oci_close — Закрывает соединение с сервером Oracle
  - oci_commit — Подтверждает транзакцию базы данных
  - oci_connect — Устанавливает соединение с базой данных Oracle
  - oci_define_by_name — Сопоставляет переменную PHP столбцу результата запроса
  - oci_error — Возвращает последнюю ошибку
  - oci_execute — Выполняет подготовленное выражение
  - oci_fetch — Выбирает следующую строку из результата в буфер
  - oci_fetch_all — Выбирает все строки из результата запроса в двумерный массив
  - oci_fetch_array — Возвращает следующую строку из результата запроса в виде ассоциативного или нумерованного массива
  - oci_fetch_assoc — Возвращает следующую строку из результата запроса в виде ассоциативного массива
  - oci_fetch_object — Возвращает следующую строку из результата запроса в виде объекта
  - oci_fetch_row — Возвращает следующую строку из результата запроса в виде нумерованного массива
  - oci_field_is_null — Проверяет, равняется ли поле в текущем полученном ряду равным null
  - oci_field_name — Возвращает имя поля из результата запроса
  - oci_field_precision — Возвращает точность поля
  - oci_field_scale — Возвращает масштаб поля
  - oci_field_size — Возвращает размер поля
  - oci_field_type — Возвращает имя типа поля
  - oci_field_type_raw — Возвращает исходный тип поля Oracle
  - oci_free_descriptor — Освобождает дескриптор
  - oci_free_statement — Освобождает ресурсы, занимаемые курсором или SQL-выражением
  - oci_get_implicit_resultset — Возвращает следующий ресурс дочернего запроса из ресурса родительского запроса, имеющего неявные результирующие наборы Oracle Database
  - oci_lob_copy — Копирует объект LOB
  - oci_lob_is_equal — Сравнивает два объекта LOB/FILE
  - oci_new_collection — Создаёт новый объект коллекции
  - oci_new_connect — Устанавливает новое соединение с сервером Oracle
  - oci_new_cursor — Возвращает идентификатор созданного курсора
  - oci_new_descriptor — Инициализирует новый дескриптор объекта LOB или FILE
  - oci_num_fields — Возвращает количество полей в результате запроса
  - oci_num_rows — Возвращает количество строк, изменённых в процессе выполнения запроса
  - oci_parse — Подготавливает запрос к выполнению
  - oci_password_change — Изменяет пароль пользователя Oracle
  - oci_pconnect — Устанавливает постоянное соединение с сервером Oracle
  - oci_register_taf_callback — Регистрирует пользовательскую функцию обратного вызова для Oracle Database TAF
  - oci_result — Возвращает значение поля из результата запроса
  - oci_rollback — Откатывает транзакции, ожидающие обработки
  - oci_server_version — Возвращает версию сервера Oracle
  - oci_set_action — Задаёт имя для действия
  - oci_set_call_timeout — Устанавливает время ожидания в миллисекундах для вызовов базы данных
  - oci_set_client_identifier — Задаёт идентификатор клиента
  - oci_set_client_info — Задаёт информацию о клиенте
  - oci_set_db_operation — Задаёт операцию базы данных
  - oci_set_edition — Задаёт выпуск (edition) базы данных
  - oci_set_module_name — Задаёт имя модулю
  - oci_set_prefetch — Устанавливает количество строк, которые будут автоматически выбраны в буфер
  - oci_set_prefetch_lob — Устанавливает объём данных, предварительно выбираемых для каждого CLOB или BLOB
  - oci_statement_type — Возвращает тип выражения
  - oci_unregister_taf_callback — Удалить регистрацию пользовательской callback-функции для Oracle Database TAF
- OCICollection — Класс OCICollection
  - OCICollection::append — Добавляет элемент в коллекцию
  - OCICollection::assign — Присваивает коллекции значение другой, уже существующей коллекции
  - OCICollection::assignElem — Присваивает значение элементу коллекции
  - OCICollection::free — Освобождает ресурсы, занимаемые объектом коллекции
  - OCICollection::getElem — Возвращает значение элемента
  - OCICollection::max — Возвращает максимальное количество элементов в коллекции
  - OCICollection::size — Возвращает количество элементов в коллекции
  - OCICollection::trim — Отсекает элементы с конца коллекции
- OCILob — Класс OCILob
  - OCILob::append — Добавляет данные из объекта LOB в конец другого объекта
  - OCILob::close — Закрывает дескриптор объекта LOB
  - OCILob::eof — Проверяет, находится ли указатель LOB на конце объекта
  - OCILob::erase — Очищает указанную часть объекта LOB
  - OCILob::export — Сохраняет содержимое объекта LOB в файл
  - OCILob::flush — Очищает и записывает буфер объекта LOB на сервер
  - OCILob::free — Освобождает ресурсы, связанные с дескриптором LOB
  - OCILob::getBuffering — Возвращает текущее состояние буферизации большого объекта (LOB)
  - OCILob::import — Записывает содержимое файла в объект LOB
  - OCILob::load — Возвращает содержимое объекта LOB
  - OCILob::read — Возвращает часть объекта LOB
  - OCILob::rewind — Переводит указатель объекта в начало большого объекта
  - OCILob::save — Сохраняет данные в LOB
  - OCILob::saveFile — Псевдоним OCILob::import
  - OCILob::seek — Устанавливает позицию внутреннего указателя LOB
  - OCILob::setBuffering — Изменяет текущее состояние буферизации большого объекта (LOB)
  - OCILob::size — Возвращает размер объекта LOB
  - OCILob::tell — Возвращает текущую позицию внутреннего указателя объекта LOB
  - OCILob::truncate — Обрезает большой объект
  - OCILob::write — Записывает данные в объект LOB
  - OCILob::writeTemporary — Записывает временный большой объект (LOB)
  - OCILob::writeToFile — Псевдоним OCILob::export
- Устаревшие наименования и функции OCI8
  - oci_internal_debug — Включает или отключает внутренний вывод отладки
  - ocibindbyname — Псевдоним функции oci_bind_by_name
  - ocicancel — Псевдоним oci_cancel
  - ocicloselob — Псевдоним OCILob::close
  - ocicollappend — Псевдоним OCICollection::append
  - ocicollassign — Псевдоним метода OCICollection::assign
  - ocicollassignelem — Псевдоним метода OCICollection::assignElem
  - ocicollgetelem — Псевдоним метода OCICollection::getElem
  - ocicollmax — Псевдоним метода OCICollection::max
  - ocicollsize — Псевдоним метода OCICollection::size
  - ocicolltrim — Псевдоним метода OCICollection::trim
  - ocicolumnisnull — Псевдоним функции oci_field_is_null
  - ocicolumnname — Псевдоним функции oci_field_name
  - ocicolumnprecision — Псевдоним функции oci_field_precision
  - ocicolumnscale — Псевдоним функции oci_field_scale
  - ocicolumnsize — Псевдоним функции oci_field_size
  - ocicolumntype — Псевдоним функции oci_field_type
  - ocicolumntyperaw — Псевдоним функции oci_field_type_raw
  - ocicommit — Псевдоним функции oci_commit
  - ocidefinebyname — Псевдоним функции oci_define_by_name
  - ocierror — Псевдоним функции oci_error
  - ociexecute — Псевдоним функции oci_execute
  - ocifetch — Псевдоним функции oci_fetch
  - ocifetchinto — Устаревший вариант функций oci_fetch_array, oci_fetch_object, oci_fetch_assoc и oci_fetch_row
  - ocifetchstatement — Псевдоним функции oci_fetch_all
  - ocifreecollection — Псевдоним метода OCICollection::free
  - ocifreecursor — Псевдоним функции oci_free_statement
  - ocifreedesc — Псевдоним метода OCILob::free
  - ocifreestatement — Псевдоним функции oci_free_statement
  - ociinternaldebug — Псевдоним функции oci_internal_debug
  - ociloadlob — Псевдоним метода OCILob::load
  - ocilogoff — Псевдоним функции oci_close
  - ocilogon — Псевдоним функции oci_connect
  - ocinewcollection — Псевдоним функции oci_new_collection
  - ocinewcursor — Псевдоним функции oci_new_cursor
  - ocinewdescriptor — Псевдоним функции oci_new_descriptor
  - ocinlogon — Псевдоним функции oci_new_connect
  - ocinumcols — Псевдоним функции oci_num_fields
  - ociparse — Псевдоним функции oci_parse
  - ociplogon — Псевдоним функции oci_pconnect
  - ociresult — Псевдоним функции oci_result
  - ocirollback — Псевдоним функции oci_rollback
  - ocirowcount — Псевдоним функции oci_num_rows
  - ocisavelob — Псевдоним метода OCILob::save
  - ocisavelobfile — Псевдоним метода OCILob::import
  - ociserverversion — Псевдоним функции oci_server_version
  - ocisetprefetch — Псевдоним функции oci_set_prefetch
  - ocistatementtype — Псевдоним функции oci_statement_type
  - ociwritelobtofile — Псевдоним метода OCILob::export
  - ociwritetemporarylob — Псевдоним метода OCILob::writeTemporary

# PostgreSQL

# Введение

База данных PostgreSQL - это свободно доступный продукт с открытым исходным кодом. Изначально Postgres разрабатывался в Университете Компьютерных Наук Беркли и инициировал многие объектно-реляционные идеи, которые на данный момент доступны в некоторых коммерческих базах данных. В частности, это поддержка языка SQL92/SQL99, транзакции, ссылочная целостность, хранимые процедуры и расширение типов. PostgreSQL - это потомок своего первоисточника из Беркли с открытым исходным кодом.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Для использования поддержки PostgreSQL в PHP необходима библиотека libpq (клиентская библиотека PostgreSQL на языке C). Начиная с PHP 8.0.0 требуется libpq 9.1 или новее. Начиная с PHP 8.4.0 требуется libpq 10.0 или новее. В PostgreSQL есть поддержка различных кодировок символов, включая многобайтовую кодировку. Последняя версия и полная информация о PostgreSQL доступна на » http://www.postgresql.org/ и в » документации PostgreSQL.

## Установка

Для того, чтобы включить поддержку PostgreSQL необходимо скомпилировать PHP с директивой --with-pgsql[=DIR]. Параметр `DIR` определяет путь к установочной директории PostgreSQL, по умолчанию это /usr/local/pgsql. Если доступен динамический модуль, то он может быть включён директивой extension в php.ini, либо функцией dl().

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Параметры конфигурации PostgreSQL
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
pgsql.allow_persistent | "1" | `INI_SYSTEM` |
pgsql.max_persistent | "-1" | `INI_SYSTEM` |
pgsql.max_links | "-1" | `INI_SYSTEM` |
pgsql.auto_reset_persistent | "0" | `INI_SYSTEM` |
pgsql.ignore_notice | "0" | `INI_ALL` |
pgsql.log_notice | "0" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`pgsql.allow_persistent` bool

  Следует ли разрешить постоянное соединение с Postgres.

`pgsql.max_persistent` int

  Максимальное количество постоянных соединений на один процесс.

`pgsql.max_links` int

  Максимальное количество соединений Postgres на один процесс, включая постоянные соединения.

`pgsql.auto_reset_persistent` int

  Определять разорванные постоянные ссылки с pg_pconnect(). Требуются небольшие дополнительные ресурсы.

`pgsql.ignore_notice` int

  Игнорировать или нет уведомления от PostgreSQL.

`pgsql.log_notice` int

  Записывать ли в лог уведомления от PostgreSQL. Для записи в лог уведомлений также необходимо отключить PHP-директиву pgsql.ignore_notice.

## Типы ресурсов

До PHP 8.1.0 существовало два типа ресурсов используемых в модуле PostgreSQL. Первый из них представляет собой идентификатор соединения с базой данных, а второй - ресурс необходимый для хранения результата запроса.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`PGSQL_LIBPQ_VERSION` (string)
  Короткое обозначение версии модуля libpq, содержащее только цифры и точки.
`PGSQL_LIBPQ_VERSION_STR` (string)
  До PHP 8.0.0 — длинное обозначение версии модуля libpq, которое включает информацию о компиляторе. Начиная с PHP 8.0.0, значение идентично `PGSQL_LIBPQ_VERSION`, а использование `PGSQL_LIBPQ_VERSION_STR` устарело.
`PGSQL_ASSOC` (int)
  Передаётся в функцию pg_fetch_array(). Возвращает ассоциативный массив 'имя поля' => 'значение поля'.
`PGSQL_NUM` (int)
  Передаётся в функцию pg_fetch_array(). Возвращает нумерованный массив 'номер поля' => 'значение поля'.
`PGSQL_BOTH` (int)
  Передаётся в функцию pg_fetch_array(). Возвращает массив значений поля, нумерованный (по номеру поля) и ассоциативный (по имени поля).
`PGSQL_CONNECT_FORCE_NEW` (int)
  Передаётся в функцию pg_connect() для принудительного создания нового подключения вместо использования идентичного существующего.
`PGSQL_CONNECT_ASYNC` (int)
  Передаётся в функцию pg_connect() для создания асинхронного соединения.
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  Возвращается функцией pg_connection_status(), указывает на неработоспособность соединения с базой данных.
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  Возвращается функцией pg_connection_status(), указывает на нормальное (рабочее) состояние соединения с базой данных.
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  Передаётся в функцию pg_lo_seek(). Операция поиска начнёт работу с начала объекта.
`PGSQL_SEEK_CUR` (int)
  Передаётся в функцию pg_lo_seek(). Операция поиска начнёт работу с текущей позиции.
`PGSQL_SEEK_END` (int)
  Передаётся в функцию pg_lo_seek(). Операция поиска начнёт работу с конца объекта.
`PGSQL_EMPTY_QUERY` (int)
  Возвращается функцией pg_result_status(). Означает, что отправленная на сервер строка была пустой.
`PGSQL_COMMAND_OK` (int)
  Возвращается функцией pg_result_status(). Означает успешное завершение команды, не возвращающей данных.
`PGSQL_TUPLES_OK` (int)
  Возвращается функцией pg_result_status(). Означает успешное завершение команды, возвращающей какие-либо данные (например, `SELECT` или `SHOW`).
`PGSQL_TUPLES_CHUNK` (int)
  Возвращается функцией pg_result_status(). Указывает на успешное выполнение команды, которая возвращает данные в режиме извлечения результов по частям. Возвращается для команд `SELECT`, когда режим извлечения результатов по частям установили функцией pg_set_chunked_rows_size() Результирующий набор делится на несколько фрагментов, каждый из которых содержит предопределённое количество строк. Константа доступна с PHP 8.4.0 и libpq 17.
`PGSQL_COPY_OUT` (int)
  Возвращается функцией pg_result_status(). Сообщает, что началось копирование данных с сервера.
`PGSQL_COPY_IN` (int)
  Возвращается функцией pg_result_status(). Сообщает, чтобы начато копирование данных на сервер.
`PGSQL_BAD_RESPONSE` (int)
  Возвращается функцией pg_result_status(). Сообщает, что ответ от сервера не был распознан.
`PGSQL_NONFATAL_ERROR` (int)
  Возвращается функцией pg_result_status(). Сообщает, что произошла некритическая (уведомление или предупреждение) ошибка.
`PGSQL_FATAL_ERROR` (int)
  Возвращается функцией pg_result_status(). Сообщает, что произошла критическая ошибка.
`PGSQL_TRANSACTION_IDLE` (int)
  Возвращается функцией pg_transaction_status(). Означает, что соединение на данный момент бездействует и не находится в рамках транзакции.
`PGSQL_TRANSACTION_ACTIVE` (int)
  Возвращается функцией pg_transaction_status(). Означает состояние, когда команда находится в процессе выполнения. Запрос через соединение отправлен, но выполнение ещё не завершено.
`PGSQL_TRANSACTION_INTRANS` (int)
  Возвращается функцией pg_transaction_status(). Означает, что соединение простаивает и находится в рамках транзакции.
`PGSQL_TRANSACTION_INERROR` (int)
  Возвращается функцией pg_transaction_status(). Означает, что соединение простаивает и находится в рамках транзакции потерпевшей неудачу при выполнении.
`PGSQL_TRANSACTION_UNKNOWN` (int)
  Возвращается функцией pg_transaction_status(). Означает, что соединение разорвано.
`PGSQL_DIAG_SEVERITY` (int)
  Передаётся в функцию pg_result_error_field(). Сообщает о затруднении. Возможны лишь перечисленные значения: `ERROR`, `FATAL`, или `PANIC` (в сообщении об ошибке), либо `WARNING`, `NOTICE`, `DEBUG`, `INFO`, или `LOG` (в уведомлении), либо перевод перечисленных значений в соответствии с текущей локализацией. Поле всегда определено.
`PGSQL_DIAG_SQLSTATE` (int)
  Передаётся в функцию pg_result_error_field(). Код ошибки SQLSTATE. Код SQLSTATE определяет тип произошедшей ошибки; он может быть использован прикладной программой при выполнении специфических операций (таких как обработка ошибки) в ответ на ошибку базы данных. Это поле всегда определено и его значение не зависит от локализации.
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  Передаётся в функцию pg_result_error_field(). Основное удобочитаемое сообщение об ошибке (обычно одна строка). Поле всегда определено.
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  Передаётся в функцию pg_result_error_field(). Детализация: дополнительное сообщение об ошибке, содержащее более подробную информацию о проблеме. Может содержать несколько строк.
`PGSQL_DIAG_MESSAGE_HINT` (int)
  Передаётся в функцию pg_result_error_field(). Подсказка: указание на возможные пути устранения ошибки. Отличается от детализации ошибки тем, что это просто предложения (возможно ошибочные), а не точная информация. Может содержать несколько строк.
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  Передаётся в функцию pg_result_error_field(). Строка, содержащая целое десятичное число, указывающее на позицию курсора в исходном выражении, в котором произошла ошибка. Первый символ имеет индекс 1, позиции измеряются в символах, а не в байтах.
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  Передаётся в функцию pg_result_error_field(). Эта константа определена так же, как поле `PG_DIAG_STATEMENT_POSITION`, но эту константу применяют, когда позиция курсора указывает на команду, сгенерированную сервером БД. Поле `PG_DIAG_INTERNAL_QUERY` появляетс каждый раз, когда появляется это поле.
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  Передаётся в функцию pg_result_error_field(). Текст ошибки, сгенерированной внутренней командой СУБД, в которой произошла ошибка. Это может быть, например, SQL-запрос, сформированный функцией PL/pgSQL.
`PGSQL_DIAG_CONTEXT` (int)
  Передаётся в функцию pg_result_error_field(). Указание на контекст, где произошла ошибка. В основном содержит трассировку запрограммированных функций и автоматически сгенерированных запросов. Трассировка выводится построчно, начиная с последней строки.
`PGSQL_DIAG_SOURCE_FILE` (int)
  Передаётся в функцию pg_result_error_field(). Имя файла исходного кода PostgreSQL, в котором отмечена ошибка.
`PGSQL_DIAG_SOURCE_LINE` (int)
  Передаётся в функцию pg_result_error_field(). Номер строки файла исходного кода PostgreSQL, где отмечена ошибка.
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  Передаётся в функцию pg_result_error_field(). Имя функции в исходном коде PostgreSQL, сообщающей об ошибке.
`PGSQL_DIAG_SCHEMA_NAME` (int)
  Добавлено в PHP 7.3.0.
`PGSQL_DIAG_TABLE_NAME` (int)
  Добавлено в PHP 7.3.0.
`PGSQL_DIAG_COLUMN_NAME` (int)
  Добавлено в PHP 7.3.0.
`PGSQL_DIAG_DATATYPE_NAME` (int)
  Добавлено в PHP 7.3.0.
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  Добавлено в PHP 7.3.0.
`PGSQL_ERRORS_TERSE` (int)
  Передаётся в функцию pg_set_error_verbosity(). Константа предписывает, что выдаваемые сообщения содержат только важность ошибки, основной текст и указатель на место, в котором возникла ошибка; эта информация обычно помещается в одну строку.
`PGSQL_ERRORS_DEFAULT` (int)
  Передаётся в функцию pg_set_error_verbosity(). В режиме по умолчанию сообщения об ошибках содержат описанную выше информацию, а также детализацию, подсказку или поля с контекстом ошибки (могут занимать несколько строк).
`PGSQL_ERRORS_VERBOSE` (int)
  Передаётся в функцию pg_set_error_verbosity(). Константа задаёт режим, при котором в сообщения включаются все возможные поля.
`PGSQL_ERRORS_SQLSTATE` (int)
  Константа передаётся в функцию pg_set_error_verbosity(). На этом уровне детализации сообщение содержит только серьёзность ошибки и код ошибки `SQLSTATE`. При недоступности кода ошибки возвращается вывод, аналогичный выводу в режиме `PGSQL_ERRORS_TERSE`. До PostgreSQL 11.1 вывод в этом режиме совпадал с выводом в режиме `PGSQL_ERRORS_TERSE`.
`PGSQL_NOTICE_LAST` (int)
  Указывается в функции pg_last_notice(). Доступно с PHP 7.1.0.
`PGSQL_NOTICE_ALL` (int)
  Используется pg_last_notice(). Доступно с PHP 7.1.0.
`PGSQL_NOTICE_CLEAR` (int)
  Используется pg_last_notice(). Доступно с PHP 7.1.0.
`PGSQL_STATUS_LONG` (int)
  Передаётся в функцию pg_result_status(). Указывает на то, что в качестве возвращаемого значения ожидается числовой код.
`PGSQL_STATUS_STRING` (int)
  Передаётся в функцию pg_result_status(). Указывает на то, что в качестве возвращаемого значения ожидается текстовое представление статуса.
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  Передаётся в функцию pg_convert(). Игнорировать значения по умолчанию в таблице в процессе преобразования.
`PGSQL_CONV_FORCE_NULL` (int)
  Передаётся в функцию pg_convert(). Заменять пустые строки string на SQL `NULL` при преобразовании.
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  Передаётся в функцию pg_convert(). Указывает, что не нужно конвертировать `null` в столбцы SQL `NOT NULL`.
`PGSQL_DML_NO_CONV` (int)
  Передаётся в функцию pg_insert(), pg_select(), pg_update() и pg_delete(). Все параметры передаются в исходном виде. Ручное экранирование обязательно, если параметры содержат пользовательские данные. Используйте для этих целей pg_escape_string().
`PGSQL_DML_EXEC` (int)
  Передаётся в функцию pg_insert(), pg_select(), pg_update() и pg_delete(). Выполнить запрос с помощью этих функций.
`PGSQL_DML_ASYNC` (int)
  Передаётся в функцию pg_insert(), pg_select(), pg_update() и pg_delete(). Выполнить асинхронный запрос с помощью этих функций.
`PGSQL_DML_STRING` (int)
  Передаётся в функцию pg_insert(), pg_select(), pg_update() и pg_delete(). Вернуть строку с выполненным запросом.
`PGSQL_DML_ESCAPE` (int)
  Передаётся в функции pg_insert(), pg_select(), pg_update() и pg_delete(). Применить экранирование ко всем параметрам вместо внутреннего вызова функции pg_convert(). Опция пропускает просмотр метаданных. По скорости запрос теоретически аналогичен функциям pg_query() и pg_send_query().
`PGSQL_POLLING_FAILED` (int)
  Возвращается функцией pg_connect_poll() и указывает на ошибку при попытке соединения с БД.
`PGSQL_POLLING_READING` (int)
  Возвращается функцией pg_connect_poll() и указывает на то, что соединение ожидает, когда сокет PostgreSQL станет доступным для чтения.
`PGSQL_POLLING_WRITING` (int)
  Возвращается функцией pg_connect_poll() и указывает на то, что соединение ожидает, когда сокет PostgreSQL станет доступным для записи.
`PGSQL_POLLING_OK` (int)
  Возвращается функцией pg_connect_poll() и указывает на готовность соединения к работе.
`PGSQL_POLLING_ACTIVE` (int)
  Возвращается функцией pg_connect_poll() и указывает на то, что соединение сейчас активно.
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  Важность; Возможны следующие значения: ERROR, FATAL или PANIC (в сообщении ошибке), либо WARNING, NOTICE, DEBUG, INFO или LOG (в сообщении предупреждении). Это идентично полю PG_DIAG_SEVERITY за исключением того, содержимое не локализовано. Доступно только в версии 9.6 или новее / PHP 7.3.0 или новее.
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  Константу указывают при вызове функции pg_set_error_context_visibility(), скрывает показ контекста. Доступна с PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  Константу указывают при вызове функции pg_set_error_context_visibility(), поля контекста включаются только в сообщения об ошибках. Это поведение по умолчанию. Доступна с PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  Константу указывают при вызове функции pg_set_error_context_visibility(), поля контекста включаются в сообщения об ошибках, уведомления и предупреждения. Доступна с PHP 8.3.0.
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  Константу указывают при вызове функции pg_trace(), метка времени не включается в сообщения трассировки. Доступна с PHP 8.4.20.
`PGSQL_TRACE_REGRESS_MODE` (int)
  Константу указывают при вызове функции pg_trace(), поля наподобие OIDs включаются в сообщение трассировки. Доступна с PHP 8.3.0.

# Примеры

## Содержание

- Основы взаимодействия с БД PostgreSQL
- Пользовательские функции взаимодействия с БД PostgreSQL

## Основы взаимодействия с БД PostgreSQL

Простой пример, который показывает, как подключиться к БД, выполнить запрос, вывести строки с результатами запроса и закрыть соединение с БД PostgreSQL.

Пример #1 Пример работы с модулем PostgreSQL

    <?php

    // Подключение к СУБД и выбор базы данных
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Не удалось соединиться: ' . pg_last_error())
    ;

    // Выполнение SQL-запроса
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('Ошибка запроса: ' . pg_last_error());

    // Вывод результатов в виде HTML-разметки
    echo "<table>\n";
    while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Очистка результата
    pg_free_result($result);

    // Закрытие соединения
    pg_close($dbconn);

    ?>

## Пользовательские функции взаимодействия с БД PostgreSQL

Пример содержит пользовательские функции, аналогичные устаревшим функциям БД MySQL.

Пример #1 Пример пользовательских функций для работы с БД PostgreSQL

    <?php

    // Функция потребуется, поскольку PostgreSQL-соединение связывает базу данных
    function pg_list_dbs($db)
    {
        assert(is_resource($db));

        $query = '
    SELECT
       d.datname as "Name",
       u.usename as "Owner",
       pg_encoding_to_char(d.encoding) as "Encoding"
    FROM
       pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
    ORDER BY 1;
    ';
        return pg_query($db, $query);
    }

    // Список таблиц
    function pg_list_tables($db)
    {
        assert(is_resource($db));

        $query = "
    SELECT
       c.relname as \"Name\",
       CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
       u.usename as \"Owner\"
    FROM
       pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
    WHERE
       c.relkind IN ('r','v','S','')
       AND c.relname !~ '^pg_'
    ORDER BY 1;
    ";
        return pg_query($db, $query);
    }

    // Смотрите также описание функции pg_meta_data(). Функция возвращает определение поля в виде массива
    function pg_list_fields($db, $table)
    {
        assert(is_resource($db));
        $query = "
    SELECT
       a.attname,
       format_type(a.atttypid, a.atttypmod),
       a.attnotnull,
       a.atthasdef,
       a.attnum
    FROM
       pg_class c,
       pg_attribute a
    WHERE
       c.relname = '".$table."'
       AND a.attnum > 0 AND a.attrelid = c.oid
    ORDER BY a.attnum;
    ";
        return pg_query($db, $query);
    }

    ?>

# Функции PostgreSQL

## Примечания

> Замечание:

> Не все функции могут поддерживаться в собранном модуле. Это зависит от версии вашей libpq (клиентская библиотека PostgreSQL) и как libpq была собрана. Если модуль PostgreSQL для PHP отсутствует, то это значит, что версия вашей libpq не поддерживается.

> Замечание:

> Большинство функций PostgreSQL принимают `connection` в качестве первого необязательного параметра. Если параметр отсутствует, то используется последнее открытое соединение. Если же такого не существует, то функция возвращает `false`.

> Замечание:

> PostgreSQL автоматически переводит все идентификаторы (такие как имена таблиц/столбцов) в нижний регистр во время создания объекта и выполнения запроса. Для того, чтобы заставить использовать идентификаторы в обоих или только в верхнем регистрах, вы должны экранировать идентификатор с помощью двойных кавычек ("").

> Замечание:

> В PostgreSQL нет специальных команд для получения информации о схеме БД (к примеру, всех таблиц выбранной базы данных). Но вместо этого существует стандартная схема, которая называется `information_schema`. Она содержит системные представления (view) со всей необходимой информацией в легкодоступной форме. Для дополнительной информации смотрите » документацию PostgreSQL

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — Возвращает количество затронутых запросом записей (кортежей)

### Описание

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() возвращает количество кортежей (сущностей/записей/рядов) затронутых запросом `INSERT`, `UPDATE`, и `DELETE` queries.

Сервер также возвращает число выбранных рядов для запроса SELECT.

> Замечание:

> Ранее данная функция называлась pg_cmdtuples().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Количество записей, затронутых запросом. Если ни один кортеж не был затронут, функция вернёт `0`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_affected_rows()

    <?php
    $result = pg_query($conn, "INSERT INTO authors VALUES ('Orwell', 2002, 'Animal Farm')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " кортежей затронуто.\n";
    ?>

Результат выполнения приведённого примера:

    1 кортежей затронуто.

### Смотрите также

- pg_query() - Выполняет запрос
- pg_query_params() - Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса
- pg_execute() - Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
- pg_num_rows() - Возвращает количество строк в выборке

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — Остановка асинхронного запроса.

### Описание

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() отменяет выполнение асинхронного запроса, отправленного функциями pg_send_query(), pg_send_query_params() или pg_send_execute(). Невозможно завершить выполнение запроса, запущенное функцией pg_query().

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_cancel_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Первый запрос к pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 получил $rows1 записей\n\n";

      // Остановка выполняющегося в данный момент запроса.
      // Последует второй запрос, если, конечно, он ещё выполняется.
      pg_cancel_query($dbconn);
    ?>

Результат выполнения приведённого примера:

    Первый запрос к pg_get_result(): Resource id #3
    Resource id #3 получил 3 записей

### Смотрите также

- pg_send_query() - Отправляет асинхронный запрос
- pg_connection_busy() - Проверяет, занято ли соединение в данный момент.

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Изменяет пароль пользователя PostgreSQL

### Описание

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

Функция pg_change_password() изменяет пароль пользователя PostgreSQL. Функция использует функцию `PQchangePassword` библиотеки libpq, которая автоматически выполняет шифрование пароля на основе настроек сервера.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`user`
  Имя пользователя PostgreSQL, пароль которого требуется изменить.
`password`
  Новый пароль.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — Получение кодировки клиента.

### Описание

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL поддерживает автоматическое преобразование наборов символов между сервером и клиентом для некоторых кодировок. pg_client_encoding() возвращает клиентскую кодировку в виде строки, представляющей собой стандартный идентификатор кодировки PostgreSQL.

> Замечание:

> В случае, если libpg скомпилирована без поддержки многобайтовых кодировок, pg_client_encoding() всегда возвращает `SQL_ASCII`. Набор поддерживаемых кодировок зависит от версии сервера БД и описан в документации PostgreSQL.

> Функция, используемая для вызова: pg_clientencoding().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Клиентская кодировка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_client_encoding()

    <?php
    // Допустим, что $conn - соединение с базой данных, поддерживающей стандарт ISO-8859-1
    $encoding = pg_client_encoding($conn);

    echo "Кодировка клиента: ", $encoding, "\n";
    ?>

Результат выполнения приведённого примера:

    Кодировка клиента: ISO-8859-1

### Смотрите также

- pg_set_client_encoding() - Устанавливает клиентскую кодировку

# pg_close

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

pg_close — Закрывает соединение с базой данных PostgreSQL

### Описание

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() закрывает обычное (непостоянное) соединение с базой данных PostgreSQL, соответствующее экземпляру `connection`.

> Замечание:

> Использование pg_close(), как правило, необязательно, так как непостоянные соединения закрываются автоматически при завершении работы скрипта.

Если с соединением работают экземпляры PgSql\Lob, то перед закрытием соединения необходимо закрыть все экземпляры PgSql\Lob.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_close()

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
       or die("Невозможно подключиться к БД");
    echo "Успешно подключено к БД";
    pg_close($dbconn);
    ?>

Результат выполнения приведённого примера:

    Успешно подключено к БД

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL

# pg_connect

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

pg_connect — Открывает соединение с базой данных PostgreSQL

### Описание

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

Функция pg_connect() открывает соединение с базой данных PostgreSQL на основе параметров, которые указали в строке `connection_string`.

При повторном вызове функции pg_connect() с теми же параметрами в строке `connection_string` функция вернёт подключение, которое уже установили, если только в параметр `flags` не передали флаг `PGSQL_CONNECT_FORCE_NEW`.

Прежний синтаксис с набором параметров — $conn = pg_connect("host", "port", "options", "tty", "dbname") — устарел.

### Список параметров

`connection_string`

  Параметр `connection_string` принимает пустую строку или настройки параметров через пробел. Каждую настройку параметра передают в форме `keyword = value`. Пробелы вокруг знака равенства необязательны. Пустые значения или значения с пробелами записывают в одинарных кавычках: `keyword = 'a value'`. Одинарные кавычки и обратные слеши внутри значения экранируют обратным слешем: \' и \\.

  Функция распознаёт следующие параметры: `host`, `hostaddr`, `port`, `dbname` (значение по умолчанию для параметра `user`), `user`, `password`, `connect_timeout`, `options`, `tty` (игнорируется), `sslmode`, `requiressl` (устарело в связи с использованием параметра `sslmode`) и `service`. Поддержка параметров зависит от версии СУБД PostgreSQL.

  Параметр `options` устанавливает параметры командной строки, которые вызовет сервер.

`flags`

  При передаче флага `PGSQL_CONNECT_FORCE_NEW` функция создаёт новое соединение, даже если строка подключения `connection_string` идентична строке подключения, которое уже установили.

  При передаче флага `PGSQL_CONNECT_ASYNC` функция устанавливает асинхронное соединение. Состояние соединения проверяют функцией pg_connect_poll() или pg_connection_status().

### Возвращаемые значения

Функция возвращает экземпляр класса PgSql\Connection, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция теперь возвращает экземпляр класса PgSql\Connection; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример установки соединения функцией pg_connect()

    <?php

    // Подключение к базе данных "mary"
    $dbconn = pg_connect("dbname=mary");

    // Подключение к базе "mary" на хосте "localhost" и порте "5432"
    $dbconn2 = pg_connect("host=localhost port=5432 dbname=mary");

    // Подключение к базе "mary" на хосте "sheep" с именем пользователя и паролем
    $dbconn3 = pg_connect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // Подключение к базе "test" на хосте "sheep" с именем пользователя и паролем
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_connect($conn_string);

    // Подключение к базе на хосте "localhost" с передачей параметра командной строки,
    // который устанавливает кодировку UTF-8
    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");

    ?>

### Смотрите также

- pg_pconnect() - Открывает постоянное соединение с сервером PostgreSQL
- pg_close() - Закрывает соединение с базой данных PostgreSQL
- pg_host() - Возвращает имя хоста, соответствующего подключению
- pg_port() - Возвращает номер порта, соответствующий заданному соединению
- pg_tty() - Возвращает имя терминала TTY, связанное с соединением
- pg_options() - Получение параметров соединения с сервером баз данных
- pg_dbname() - Определяет имя базы данных

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — Опросить статус попытки асинхронного соединения PostgreSQL.

### Описание

function pg_connect_poll(PgSql\Connection `$connection`): int

pg_connect_poll() опрашивает статус соединения PostgreSQL, созданного вызовом функции pg_connect() с параметром `PGSQL_CONNECT_ASYNC`.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Возвращает `PGSQL_POLLING_FAILED`, `PGSQL_POLLING_READING`, `PGSQL_POLLING_WRITING`, `PGSQL_POLLING_OK` или `PGSQL_POLLING_ACTIVE`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — Проверяет, занято ли соединение в данный момент.

### Описание

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() определяет, занято соединение в данный момент или нет. Соединение занято, когда предыдущий запрос ещё выполняется. Функция pg_get_result() также блокирует соединение на время своего выполнения.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Возвращает `true`, если соединение занято, в противном случае `false`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_connection_busy()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединится");
      $bs = pg_connection_busy($dbconn);
      if ($bs) {
          echo 'Соединение занято';
      } else {
         echo 'Соединение не занято';
      }
    ?>

### Смотрите также

- pg_connection_status() - Определяет состояние подключения
- pg_get_result() - Получает результат асинхронного запроса

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — Сброс подключения (переподключение)

### Описание

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() сбрасывает подключение. Может быть использована для устранения ошибок.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_connection_reset()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться");
      $dbconn2 = pg_connection_reset($dbconn);
      if ($dbconn2) {
          echo "Успешный сброс\n";
      } else {
          echo "Неудачный сброс\n";
      }
    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL
- pg_pconnect() - Открывает постоянное соединение с сервером PostgreSQL
- pg_connection_status() - Определяет состояние подключения

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — Определяет состояние подключения

### Описание

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() возвращает состояние переданного в качестве аргумента соединения `connection`.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

`PGSQL_CONNECTION_OK` либо `PGSQL_CONNECTION_BAD`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_connection_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Статус соединения: доступно';
      } else {
          echo 'Статус соединения: разорвано';
      }
    ?>

### Смотрите также

- pg_connection_busy() - Проверяет, занято ли соединение в данный момент.

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Читает вводные данные на соединении

### Описание

function pg_consume_input(PgSql\Connection `$connection`): bool

pg_consume_input() принимает любые входные данные, ожидающие чтения с сервера базы данных.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

`true`, если ошибки не возникло, или `false`, если произошла ошибка. Обратите внимание, что `true` не обязательно указывает, что входные данные ожидали чтения.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

### Описание

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

Функция pg_convert() проверяет и преобразовывает значения массива `values` в значения, которые соответствуют формату SQL-выражения. Предварительное условие функции pg_convert() — таблица `table_name` должна существовать, а количество колонок в таблице должно быть не меньше количества значений в массиве `values`. Имена колонок в таблице `table_name` должны совпадать с ключами массива `values`, типы данных значений массива также должны совпадать с типами данных колонок. В случае удачной конвертации функция возвращает массив преобразованных значений, иначе возвращает `false`.

> Замечание:

> Логические значения преобразовываются в логический тип СУБД PostgreSQL. Поддерживаются также строковые представления логического значения. Значение `null` преобразовывается в значения NULL СУБД PostgreSQL.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы базы данных.

`values`

  Данные для преобразования.

`flags`

  Одна или комбинация констант `PGSQL_CONV_IGNORE_DEFAULT`, `PGSQL_CONV_FORCE_NULL` или `PGSQL_CONV_IGNORE_NOT_NULL`.

### Возвращаемые значения

Функция возвращает массив (array), который содержит преобразованные данные или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает исключение ValueError или TypeError, если значение или тип поля не соответствует правильному типу СУБД PostgreSQL.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция теперь выбрасывает исключение ValueError или TypeError, если значение или тип поля не соответствуют правильному типу СУБД PostgreSQL; раньше функция выдавала ошибку уровня `E_WARNING`.
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_convert()

    <?php

    $dbconn = pg_connect('dbname=foo');

    $tmp = array(
        'author' => 'Joe Thackery',
        'year' => 2005,
        'title' => 'My Life, by Joe Thackery'
    );

    $vals = pg_convert($dbconn, 'authors', $tmp);

    ?>

### Смотрите также

- pg_meta_data() - Получение метаданных таблицы
- pg_insert() - Заносит данные массива в таблицу базы данных
- pg_select() - Выбирает записи из базы данных
- pg_update() - Обновление данных в таблице
- pg_delete() - Удаляет записи

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — Вставляет записи из массива в таблицу

### Описание

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() вставляет записи в таблицу из массива `rows`. В ходе выполнения вызывает SQL-команду `COPY FROM` для вставки записей.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы, в которую копируются значения из `rows`.

`rows`

  Итерируемое значение (iterable) данных для копирования в `table_name`. Каждое значение в `rows` становится строкой в `table_name`. Каждое значение должно быть строкой с разделителем, содержащей значения для вставки в каждое поле таблицы. Значения должны заканчиваться символом перевода строки.

`separator`

  Символ, отделяющий значения друг от друга в каждом элементе массива `rows`. По умолчанию `\t`.

`null_as`

  Определяет, каким образом значения SQL `NULL` представлены в массиве `rows`. По умолчанию `\\N` (`"\\\\N"`).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Значение параметра `rows` теперь является итерируемым значением (iterable). Ранее оно было массивом (array).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_copy_from()

    <?php
       $db = pg_connect("dbname=publisher") or die("Не удалось подключиться");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Смотрите также

- pg_copy_to() - Копирует данные из таблицы в массив

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — Копирует данные из таблицы в массив

### Описание

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() копирует данные из таблицы в массив. Для получения записей посылает серверу команду SQL `COPY TO`.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы, из которой данные копируются в массив `rows`.

`separator`

  Символ-разделитель, отделяющий значения полей в элементах массива `rows`. По умолчанию `\t`.

`null_as`

  Этот параметр отвечает за то, как значения SQL `NULL` будут представлены в массиве `rows`. По умолчанию `\\N` (`"\\\\N"`).

### Возвращаемые значения

Массив (array), в котором каждый элемент - строка, полученная с помощью `COPY` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_copy_to()

    <?php
       $db = pg_connect("dbname=publisher") or die("Невозможно подключиться");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Смотрите также

- pg_copy_from() - Вставляет записи из массива в таблицу

# pg_dbname

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

pg_dbname — Определяет имя базы данных

### Описание

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() возвращает имя базы данных, соответствующей экземпляру PostgreSQL `connection`.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Строка, содержащая имя базы данных, соответствующей ресурсу `connection`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_dbname()

    <?php
      error_reporting(E_ALL);

      pg_connect("host=localhost port=5432 dbname=mary");
      echo pg_dbname(); // mary
    ?>

# pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — Удаляет записи

### Описание

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() удаляет из таблицы записи, соответствующие ключам и значениям массива `conditions`.

Если `flags` указан, pg_convert() применяется к `conditions` с указанными флагами.

По умолчанию pg_delete() передаёт необработанные значения. Значения должны быть экранированы или опция `PGSQL_DML_ESCAPE` должна быть указана. `PGSQL_DML_ESCAPE` заключает в кавычки и экранирует параметры/идентификаторы. Поэтому имена таблиц/столбцов становятся чувствительными к регистру.

Обратите внимание, что ни экранирование, ни подготовленный запрос не защитят запрос LIKE, JSON, массив, регулярные выражения и т.д. Эти параметры должны обрабатываться в соответствии с их контекстами, т.е. следует экранировать/проверять значения.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы, из которой удаляются записи.

`conditions`

  Ассоциативный массив, ключи которого соответствуют именам полей таблицы `table_name`, а значения соответствуют удаляемым значениям в этих колонках.

`flags`

  Комбинация констант `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` или `PGSQL_DML_STRING`. Если константа `PGSQL_DML_STRING` присутствует в аргументе `flags`, то функция вернёт строку, содержащую запрос. Если установлены `PGSQL_DML_NO_CONV` или `PGSQL_DML_ESCAPE`, то функция pg_convert() внутренне не вызывается.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Возвращает строку, если в аргументе `flags` передана константа `PGSQL_DML_STRING`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_delete()

    <?php
      $db = pg_connect('dbname=foo');
      // Это безопасно в некоторой степени, поскольку все значения экранируются.
      // Однако PostgreSQL поддерживает JSON/массив. Для этих значений это не безопасно
      // ни с через экранирование, ни с помощью подготовленного запроса.
      $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($res) {
          echo "Данные из POST удалены: $res\n";
      } else {
          echo "Пользователь отправил неверные входные данные\n";
      }
    ?>

### Смотрите также

- pg_convert() - Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — Синхронизирует с бэкендом PostgreSQL

### Описание

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() синхронизирует данные между фронтендом PostgreSQL (обычно процессом веб-сервера) и сервером PostgreSQL после завершения копирования данных, совершенных с помощью функции pg_put_line(). Использование pg_end_copy() необходимо, чтобы избежать рассинхронизации сервера PostgreSQL с фронтендом и сообщений об ошибках.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_end_copy()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Смотрите также

- pg_put_line() - Передаёт на PostgreSQL сервер строку с завершающим нулём

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — Экранирует спецсимволы в строке для вставки в поле типа bytea

### Описание

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() экранирует спецсимволы в строке с данными типа bytea. Возвращает экранированную строку.

> Замечание:

> При выборке SQL-функцией `SELECT` данных типа bytea PostgreSQL возвращает значения в восьмеричной системе счисления с префиксом '\' (такие как \032). Пользователю необходимо вручную преобразовывать их в двоичный формат.

> Функция поддерживается PostgreSQL версии 7.2 и выше. Для версий 7.2.0 и 7.2.1 значения должны быть преобразованы к типу bytea, когда включена мультибайтовая поддержка. Тогда как `INSERT INTO test_table (image)VALUES ('$image_escaped'::bytea);` в PostgreSQL 7.2.2 и выше не требует каких-либо преобразований. Исключение составляет случай, когда клиентская (frontend) кодировка не соответствует серверной (backend). При этом возникает ошибка мультибайтового потока, и пользователь должен привести данные к типу bytea, чтобы её избежать.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`string`

  Строка, содержащая двоичные данные в виде текста, которые требуется поместить в поле типа bytea.

### Возвращаемые значения

Возвращает строку, в которой экранированы все необходимые символы.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_escape_bytea()

    <?php
      // Подключение к базе данных
      $dbconn = pg_connect('dbname=foo');

      // Чтение бинарного файла
      $data = file_get_contents('image1.jpg');

      // Экранирование спецсимволов в строке с двоичными данными
      $escaped = pg_escape_bytea($data);

      // Вставка в таблицу базы данных
      pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### Смотрите также

- pg_unescape_bytea() - Убирает экранирование двоичных данных типа bytea
- pg_escape_string() - Экранирование спецсимволов в строке запроса

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Экранирует идентификатор перед вставкой в текст SQL-инструкции

### Описание

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

Функция pg_escape_identifier() экранирует названия таблиц, полей и других идентификаторов в SQL-инструкциях перед отправкой запроса к базе данных. Функция pg_escape_identifier() экранирует идентификаторы по правилам PostgreSQL-сервера — обрамляет двойными кавычками — и возвращает заэкранированную строку. Оставлять в SQL-инструкции незаэкранированные идентификаторы или добавлять двойные кавычки вручную — небезопасно. Строковые, числовые, логические и другие SQL-литералы внутри инструкции, кроме типа bytea, экранируют функцией pg_escape_literal() или pg_escape_string(). Поля с типом bytea экранируют функцией pg_escape_bytea().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`string`

  Текстовая строка (string), которую требуется заэкранировать.

### Возвращаемые значения

Функция возвращает строку (string) с заэкранированными данными или `false` в случае ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример экранирования идентификатора функцией pg_escape_identifier()

    <?php

    // Устанавливаем соединение с базой данных
    $dbconn = pg_connect('dbname=foo');

    // Экранируем название таблицы
    $escaped = pg_escape_identifier($table_name);

    // Выбираем строки из таблицы $table_name
    pg_query("SELECT * FROM {$escaped};");

### Смотрите также

- pg_escape_literal() - Экранировать литерал при вставке в текстовое поле
- pg_escape_bytea() - Экранирует спецсимволы в строке для вставки в поле типа bytea
- pg_escape_string() - Экранирование спецсимволов в строке запроса

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Экранировать литерал при вставке в текстовое поле

### Описание

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

Функция pg_escape_literal() экранирует литерал для запроса базы данных PostgreSQL. Она возвращает экранированный литерал в формате PostgreSQL. pg_escape_literal() добавляет кавычки до и после данных. Пользователи не должны добавлять кавычки. Рекомендуется использовать эту функцию вместо pg_escape_string(). Если тип столбца - bytea, вместо него следует использовать pg_escape_bytea(). Для экранирования идентификаторов (например, таблицы, имён полей) необходимо использовать pg_escape_identifier().

> Замечание:

> Эта функция имеет внутренний код экранирования и может также использоваться с PostgreSQL 8.4 или младшей версии.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`string`

  Строка (string), содержащая текст для экранирования.

### Возвращаемые значения

Строка (string), содержащая экранированный текст, или `false` в случае ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_escape_literal()

    <?php
      // Подключение к базе данных
      $dbconn = pg_connect('dbname=foo');

      // Чтение из текстового файла (содержащий апострофы и обратные косые черты)
      $data = file_get_contents('letter.txt');

      // Экранирование текстовых данных
      $escaped = pg_escape_literal($data);

      // Вставка их в базу данных. Обратите внимание, что вокруг {$escaped} нет кавычек
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
    ?>

### Смотрите также

- pg_escape_identifier() - Экранирует идентификатор перед вставкой в текст SQL-инструкции
- pg_escape_bytea() - Экранирует спецсимволы в строке для вставки в поле типа bytea
- pg_escape_string() - Экранирование спецсимволов в строке запроса

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — Экранирование спецсимволов в строке запроса

### Описание

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

Функция pg_escape_string() экранирует спецсимволы в строке запроса для базы данных. Она возвращает экранированную строку в формате PostgreSQL. Функция pg_escape_string() является наиболее предпочтительным способом экранирования SQL параметров для PostgreSQL, в то время как addslashes() не должна использоваться с PostgreSQL. Если тип столбца bytea, то должна использоваться функция pg_escape_bytea() вместо pg_escape_string. Функция pg_escape_identifier() должна использоваться для экранирования идентификаторов (например, имена таблиц или полей).

> Замечание:

> Функция поддерживается PostgreSQL версии 7.2 и выше.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`string`

  Исходная экранируемая строка.

### Возвращаемые значения

Возвращает строку, в которой экранированы все необходимые символы.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_escape_string()

    <?php
      // Подключение к базе данных
      $dbconn = pg_connect('dbname=foo');

      // Чтение текстового файла (содержащего апострофы и обратные слеши)
      $data = file_get_contents('letter.txt');

      // Экранирование спецсимволов в строке
      $escaped = pg_escape_string($data);

      // Вставка в таблицу базы данных
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', '{$escaped}')");
    ?>

### Смотрите также

- pg_escape_bytea() - Экранирует спецсимволы в строке для вставки в поле типа bytea

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат

### Описание

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

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

pg_execute() аналог функции pg_query_params(), только вместо строки с запросом принимает имя предварительно подготовленного SQL-запроса. Это позволяет многократно выполнять единожды созданные запросы с различными параметрами. Сам запрос должен быть заранее подготовлен в текущей сессии. pg_execute() поддерживается PostgreSQL версии 7.4 и выше. Функция не будет работать на соединениях с сервером ранних версий.

Аргументы функции те же, что и у pg_query_params(), за исключением имени предварительно составленного запроса, который передаётся вместо строки с запросом.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`statement_name`

  Имя подготовленного к исполнению запроса. Если передана пустая строка "", будет выполнен безымянный запрос. Имя и содержимое запроса должны быть подготовлены функцией pg_prepare(), pg_send_prepare() либо с помощью SQL-команды `PREPARE`.

`params`

  Массив значений параметров запроса для замены псевдопеременных $1, $2 и т.д. в исходной строке запроса. Количество элементов массива должно точно совпадать с количеством псевдопеременных.

  Внимание

  Элементы массива будут преобразованы в строки.

### Возвращаемые значения

Экземпляр PgSql\Result в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_execute()

    <?php
    // Подключение к базе данных "mary"
    $dbconn = pg_connect("dbname=mary");

    // Подготовка запроса
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Запуск запроса на выполнение. Стоит отметить, что нет необходимости экранировать
    // спецсимволы в строке "Joe's Widgets"
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Запуск на выполнение того же запроса, но с другим параметром
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Смотрите также

- pg_prepare() - Отправляет на сервер запрос на подготовку SQL-запроса с параметрами-заполнителями и ждёт, пока завершится подготовка запроса
- pg_send_prepare() - Посылает запрос на создание параметризованного SQL-выражения, не дожидаясь его завершения
- pg_query_params() - Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — Выбирает все данные из результата запроса и помещает их в массив

### Описание

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() возвращает массив содержащий все записи экземпляра PgSql\Result.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`mode`
  Необязательный параметр, который управляет индексированием массив (array), который возвращает функция. Параметр `mode` — константа и принимает следующие значения: `PGSQL_ASSOC`, `PGSQL_NUM` и `PGSQL_BOTH`. С константой `PGSQL_NUM` функция возвращает массив с числовыми индексами, с константой `PGSQL_ASSOC` функция вернёт только ассоциативные индексы, а с `PGSQL_BOTH` — вернёт как числовые, так и ассоциативные индексы.

### Возвращаемые значения

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

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.
8.0.0 | Функция pg_fetch_all() теперь возвращает пустой массив (array) вместо значения `false` для наборов результатов без строк.
7.1.0 | Добавлен параметр `mode`.

### Примеры

Пример #1 Пример использования

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
        echo "Произошла ошибка.\n";
        exit;
    }

    $result = pg_query($conn, "SELECT * FROM authors");
    if (!$result) {
        echo "Произошла ошибка.\n";
        exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### Смотрите также

- pg_fetch_row() - Выбирает строку результата запроса и помещает данные в массив
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Выбирает все записи из одной колонки результата запроса и помещает их в массив

### Описание

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() возвращает массив, содержащий все записи одной колонки экземпляра PgSql\Result.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Номер колонки. Если параметр не задан, будет обработана первая (нулевая) колонка.

### Возвращаемые значения

Массив значений колонки результата запроса.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_fetch_all_columns()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    // Получить массив имён всех авторов
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### Смотрите также

- pg_fetch_all() - Выбирает все данные из результата запроса и помещает их в массив

# pg_fetch_array

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

pg_fetch_array — Возвращает строку результата в виде массива

### Описание

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

Функция pg_fetch_array() возвращает массив, который соответствует выбранной строке (записи).

Функция pg_fetch_array() — расширенный вариант функции pg_fetch_row(). Эта функция умеет сохранять данные не только с числовыми индексами (номерами полей), но и с ассоциативными (именами полей). По умолчанию функция хранит и те, и другие.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

Функция pg_fetch_array() выполняется немного медленнее, чем функция pg_fetch_row(), но значительно проще в работе.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер строки в result для выборки. Строки пронумерованы с 0 по возрастанию. Если параметр опустили или передали `null`, функция выберет следующую строку.

`mode`
  Необязательный параметр, который управляет индексированием массив (array), который возвращает функция. Параметр `mode` — константа и принимает следующие значения: `PGSQL_ASSOC`, `PGSQL_NUM` и `PGSQL_BOTH`. С константой `PGSQL_NUM` функция возвращает массив с числовыми индексами, с константой `PGSQL_ASSOC` функция вернёт только ассоциативные индексы, а с `PGSQL_BOTH` — вернёт как числовые, так и ассоциативные индексы.

### Возвращаемые значения

Функция возвращает массив (array) с числовыми индексами (начиная с 0), либо ассоциативными (по имени поля), либо с обеими типами индексов. Функция представляет каждое значение в массиве (array) в виде строки (string). Значение `NULL` возвращается как `null`.

Функция возвращает `false`, если значение `row` выходит за рамки количества строк в выборке, или отсутствия строк, или если возникла любая другая ошибка. Выборка из результата запроса, который отличается от SELECT, также вернёт `false`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_fetch_array()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $arr = pg_fetch_array($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Row 1 Author\n";
    echo $arr[1] . " <- Row 1 E-mail\n";

    // Параметр row необязателен,
    // для передечи result_type вместо row можно передать NULL.
    // Успешные вызовы pg_fetch_array вернут следующий ряд.

    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["author"] . " <- Row 2 Author\n";
    echo $arr["email"] . " <- Row 2 E-mail\n";

    $arr = pg_fetch_array($result);
    echo $arr["author"] . " <- Row 3 Author\n";
    echo $arr[1] . " <- Row 3 E-mail\n";

    ?>

### Смотрите также

- pg_fetch_row() - Выбирает строку результата запроса и помещает данные в массив
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — Выбирает строку результата запроса и помещает данные в ассоциативный массив

### Описание

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() возвращает ассоциативный массив, содержащий записи из строки результата запроса.

Результат выполнения pg_fetch_assoc() тот же, что и у pg_fetch_array() с параметром `PGSQL_ASSOC`. Функция возвращает только ассоциативный массив. Если нужен численно-индексированный массив, используйте функцию pg_fetch_row().

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

pg_fetch_assoc() не намного медленней и значительно проще в использовании, чем pg_fetch_row().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер выбираемой из результата запроса строки. Нумерация начинается с нуля. Если аргумент опущен или равен `null`, берётся следующая по очереди строка.

### Возвращаемые значения

Ассоциативный массив, индексированный именами полей выборки. Значения массива представляются в виде текстовых строк. Значения `NULL` базы данных преобразуются в PHP `null`.

`false`, если `row` превышает число строк в результате запроса, когда строк в результате не осталось, и при прочих ошибках.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_fetch_assoc()

    <?php
    $conn = pg_connect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT id, author, email FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['author'];
      echo $row['email'];
    }
    ?>

### Смотрите также

- pg_fetch_row() - Выбирает строку результата запроса и помещает данные в массив
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_fetch_object

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

pg_fetch_object — Выбирает строку результата запроса и возвращает данные в виде объекта

### Описание

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

Функция pg_fetch_object() возвращает объект, свойства которого соответствуют именам полей выборки. Функция опционально создаёт экземпляр конкретного класса и передаёт параметры конструктору этого класса.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

По скорости функция идентична функции pg_fetch_array() и немного медленней функции pg_fetch_row(); разница незначительна.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер строки, которую функция выбирает из результата запроса. Нумерация начинается с нуля. Функция берёт следующую по очереди строку, если аргумент опущен или равен `null`.

`class`

  Имя класса объекта, который создаст и вернёт функция. Если не задано, функция создаст экземпляр класса stdClass.

`constructor_args`

  Необязательный массив (array) параметров для передачи в конструктор объекта `class`.

### Возвращаемые значения

Функция возвращает объект (object), имена и значения свойств которого соответствуют именам и значениям полей результата запроса. Функция преобразовывает значения `NULL` базы данных в значения PHP `null`.

Функция возвращает значение `false`, если значение параметра `row` превышает число строк в результате запроса, когда строк в результате не осталось, и при прочих ошибках.

### Ошибки

Функция выбросит исключение ValueError, если в параметр `constructor_args` передали не пустой массив, а у класса нет конструктора.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция теперь выбрасывает исключение a ValueError, если в параметр `constructor_args` передали не пустой массив, а у класса нет конструктора; раньше функция выбрасывала исключение Exception.
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_fetch_object()

    <?php

    $database = "store";

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "Невозможно соединиться с базой postgres $database\n";
      exit;
    }

    $qu = pg_query($db_conn, "SELECT * FROM books ORDER BY author");

    while ($data = pg_fetch_object($qu)) {
      echo $data->author . " (";
      echo $data->year . "): ";
      echo $data->title . "<br />";
    }

    pg_free_result($qu);
    pg_close($db_conn);

    ?>

### Смотрите также

- pg_query() - Выполняет запрос
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_assoc() - Выбирает строку результата запроса и помещает данные в ассоциативный массив
- pg_fetch_row() - Выбирает строку результата запроса и помещает данные в массив
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — Возвращает запись из результата запроса

### Описание

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): string|false|null
function pg_fetch_result(PgSql\Result `$result`, mixed `$field`): string|false|null

Функция pg_fetch_result() возвращает значение ячейки таблицы экземпляра класса PgSql\Result.

> Замечание:

> Прежнее название функции: pg_result().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер строки, которую функция выбирает из результата запроса. Нумерация начинается с нуля. Функция берёт следующую по очереди строку, если аргумент опущен.

`field`

  Имя или номер поля выбираемого значения. Поля нумеруются с нуля.

### Возвращаемые значения

Функция возвращает логические значения как "t" или "f". Остальные типы, включая массивы, функция возвращает в виде строк в стандартном формате СУБД PostgreSQL, аналогично выводу команды psql. Функция преобразовывает значения `NULL` базы данных в значения PHP `null`.

Функция возвращает значение `false`, если значение параметра `row` превышает число строк в результате запроса, и при прочих ошибках.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Параметр `row` теперь принимает значение `null`.
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_fetch_result()

    <?php

    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Первое поле во второй строчке результата это: ", $val, "\n";

    ?>

Результат выполнения приведённого примера:

    Первое поле во второй строчке результата это: 2

### Смотрите также

- pg_query() - Выполняет запрос
- pg_fetch_array() - Возвращает строку результата в виде массива

# pg_fetch_row

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

pg_fetch_row — Выбирает строку результата запроса и помещает данные в массив

### Описание

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() выбирает одну строку из результата запроса `result`.

> Замечание: Эта функция устанавливает NULL-поля в значение `null` PHP.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер выбираемой из результата запроса строки. Нумерация начинается с нуля. Если аргумент опущен или равен `null`, берётся следующая по очереди строка.

`mode`
  Необязательный параметр, который управляет индексированием массив (array), который возвращает функция. Параметр `mode` — константа и принимает следующие значения: `PGSQL_ASSOC`, `PGSQL_NUM` и `PGSQL_BOTH`. С константой `PGSQL_NUM` функция возвращает массив с числовыми индексами, с константой `PGSQL_ASSOC` функция вернёт только ассоциативные индексы, а с `PGSQL_BOTH` — вернёт как числовые, так и ассоциативные индексы.

### Возвращаемые значения

Численно индексированный массив значений из строки результата запроса. Индексация начинается с нуля. Значения представляются в виде строк. Значения `NULL` базы данных преобразуются в PHP `null`.

`false`, если `row` превышает число строк в результате запроса, когда строк в результате не осталось, и при прочих ошибках.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_fetch_row()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Автор: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Смотрите также

- pg_query() - Выполняет запрос
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — Проверяет поля на значение SQL `NULL`

### Описание

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): int
function pg_field_is_null(PgSql\Result `$result`, mixed `$field`): int

Функция pg_field_is_null() проверяет, содержит ли ячейка экземпляра класса PgSql\Result значение SQL `NULL`.

> Замечание:

> Прежнее название функции: pg_fieldisnull().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер строки результата запроса с нужным полем. Нумерация строк начинается с нуля. Функция выбирает текущую строку, если аргумент не задали.

`field`

  Номер поля в виде целого числа (int), начиная с нуля, или имя поля в виде строки (string).

### Возвращаемые значения

Функция возвращает значение `1`, если выбранное значение SQL — `NULL`, `0` для других значений. Функция вернёт значение `false`, если номер строки будет вне допустимого диапазона, и при прочих ошибках.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Параметр `row` теперь принимает значение `null`.
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_field_is_null()

    <?php

    $dbconn = pg_connect("dbname=publisher") or die ("Не удалось соединиться с базой");
    $res = pg_query($dbconn, "SELECT * FROM authors WHERE author = 'Orwell'");

    if ($res) {
        if (pg_field_is_null($res, 0, "year") == 1) {
            echo "Значение поля year — null.\n";
        }
        if (pg_field_is_null($res, 0, "year") == 0) {
            echo "Значение поля year не null.\n";
        }
    }

    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — Возвращает наименование поля

### Описание

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() возвращает имя поля результата запроса `result` с порядковым номером `field`. Нумерация полей начинается с нуля.

> Замечание:

> Прежнее название функции: pg_fieldname().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Номер поля, начиная с нуля.

### Возвращаемые значения

Наименование поля.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о полях выборки

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с базой");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

Результат выполнения приведённого примера:

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### Смотрите также

- pg_field_num() - Возвращает порядковый номер именованного поля

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — Возвращает порядковый номер именованного поля

### Описание

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() вернёт порядковый номер поля с именем `field` в результате запроса `result`.

> Замечание:

> Прежнее название функции: pg_fieldnum().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Наименование поля. Данное имя обрабатывается как идентификатор в SQL-команде, то есть оно переводится в нижний регистр, если оно не заключено в двойные кавычки.

### Возвращаемые значения

Номер поля (начиная с нуля), либо -1 в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о полях выборки

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с базой");

      $res = pg_query($dbconn, "select author, year, title from authors where author = 'Orwell'");

      echo "Столбец 'title' - это поле с номером: ", pg_field_num($res, 'title');
    ?>

Результат выполнения приведённого примера:

    Столбец 'title' - это поле с номером: 2

### Смотрите также

- pg_field_name() - Возвращает наименование поля

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — Возвращает количество печатаемых символов

### Описание

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row`, mixed `$field_name_or_number`): int
function pg_field_prtlen(PgSql\Result `$result`, mixed `$field_name_or_number`): int

Функция pg_field_prtlen() возвращает длину строки, количество символов, значения поля при выводе результата `result`. Строки нумеруются с нуля. Функция вернёт `false` в случае возникновения ошибки.

`field_name_or_number` Номер или имя выбранного поля. Может передаваться либо как int, либо как string. Если передаётся значение типа int, PHP распознает его как номер, в противном случае как наименование поля.

Ознакомьтесь с примерами на странице с описанием функции pg_field_name().

> Замечание:

> Прежнее название функции: pg_fieldprtlen().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Номер строки в результате. Нумерация строк начинается с нуля. Функция выбирает текущую строку, если аргумент не задан.

### Возвращаемые значения

Функция возвращает длину строки при выводе значения поля.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Параметр `row` теперь принимает значение `null`.
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о полях выборки

    <?php

    $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с базой");
    $res = pg_query($dbconn, "SELECT * FROM authors WHERE author = 'Orwell'");

    $i = pg_num_fields($res);
    for ($j = 0; $j < $i; $j++) {
        echo "column $j\n";
        $fieldname = pg_field_name($res, $j);
        echo "fieldname: $fieldname\n";
        echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
        echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
        echo "field type: " . pg_field_type($res, $j) . " \n\n";
    }

    ?>

Результат выполнения приведённого примера:

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### Смотрите также

- pg_field_size() - Возвращает размер поля

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — Возвращает размер поля

### Описание

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() возвращает объем памяти (в байтах), занимаемый значением поля результата запроса PostgreSQL `result`.

> Замечание:

> Прежнее название функции: pg_fieldsize().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Порядковый номер поля результата запроса, начиная с нуля.

### Возвращаемые значения

Требуемый объем памяти (в байтах) для хранения значения поля. -1 указывает на переменный размер поля.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о полях выборки

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Невозможно соединиться с базой");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "column $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "fieldname: $fieldname\n";
          echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
          echo "field type: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

Результат выполнения приведённого примера:

    column 0
    fieldname: author
    printed length: 6 characters
    storage length: -1 bytes
    field type: varchar

    column 1
    fieldname: year
    printed length: 4 characters
    storage length: 2 bytes
    field type: int2

    column 2
    fieldname: title
    printed length: 24 characters
    storage length: -1 bytes
    field type: varchar

### Смотрите также

- pg_field_prtlen() - Возвращает количество печатаемых символов
- pg_field_type() - Возвращает имя типа заданного поля

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Возвращает наименование или идентификатор таблицы, содержащей заданное поле

### Описание

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() возвращает имя таблицы, которой принадлежит заданное поле. Если в качестве аргумента `oid_only` передаётся `true`, функция вернёт oid-идентификатор таблицы.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Порядковый номер поля результата запроса, начиная с нуля.

`oid_only`

  По умолчанию функция возвращает название таблицы, содержащей заданное поле. Если параметр `oid_only` равен `true`, то функция вернёт oid таблицы.

### Возвращаемые значения

При успешном завершении название таблицы или её oid или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о поле выборки

    <?php
    $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с базой");

    $res = pg_query($dbconn, "SELECT bar FROM foo");

    echo pg_field_table($res, 0);
    echo pg_field_table($res, 0, true);

    $res = pg_query($dbconn, "SELECT version()");
    var_dump(pg_field_table($res, 0));
    ?>

Вывод приведённого примера будет похож на:

    foo
    14379580

    bool(false)

### Примечания

> Замечание:

> Возврат oid таблицы значительно быстрее, чем её названия, потому как определение названия требует выполнения дополнительного запроса к системной таблице базы данных.

### Смотрите также

- pg_field_name() - Возвращает наименование поля
- pg_field_type() - Возвращает имя типа заданного поля

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — Возвращает имя типа заданного поля

### Описание

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() возвращает строку, содержащую имя базового типа значений колонки результата запроса `result` с номером `field`.

> Замечание:

> Если в качестве типа значений используется PostgreSQL домен (вместо базового типа), функция вернёт имя типа внутри домена, а не имя самого домена.

> Замечание:

> Прежнее название функции: pg_fieldtype().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Порядковый номер поля, начиная с нуля.

### Возвращаемые значения

Строка, содержащая имя базового типа значений поля.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о поле выборки

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с базой");

      // Положим, 'title' имеет тип varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Title field type: ", pg_field_type($res, 0);
    ?>

Результат выполнения приведённого примера:

    Title field type: varchar

### Смотрите также

- pg_field_prtlen() - Возвращает количество печатаемых символов
- pg_field_name() - Возвращает наименование поля
- pg_field_type_oid() - Возвращает идентификатор типа заданного поля

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Возвращает идентификатор типа заданного поля

### Описание

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() возвращает целочисленный идентификатор базового типа (OID) значений колонки результата запроса `result` с номером `field`.

Более подробную информацию о типе значений можно получить, отправив запрос с полученным OID к системной таблице PostgreSQL `pg_type`. Функция PostgreSQL format_type() преобразовывает OID в стандартное имя типа SQL.

> Замечание:

> Если в качестве типа значений используется PostgreSQL домен (вместо базового типа), функция вернёт OID типа внутри домена, а не OID самого домена.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field`

  Порядковый номер поля, начиная с нуля.

### Возвращаемые значения

Возвращает OID базового типа значений поля.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение информации о полях выборки

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Невозможно соединиться с базой");

      // Допустим, 'title' имеет тип varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Title field type OID: ", pg_field_type_oid($res, 0);
    ?>

Результат выполнения приведённого примера:

    Title field type OID: 1043

### Смотрите также

- pg_field_type() - Возвращает имя типа заданного поля
- pg_field_prtlen() - Возвращает количество печатаемых символов
- pg_field_name() - Возвращает наименование поля

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — Сбросить данные исходящего запроса на соединении

### Описание

function pg_flush(PgSql\Connection `$connection`): int|bool

pg_flush() сбрасывает любые данные исходящего запроса, ожидающие отправки на соединении.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Возвращает `true`, если сброс был успешный или данные не ожидали сброса, либо `0`, если часть ожидающих данных была сброшена, однако остались ещё или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — Очищает результат запроса и освобождает память

### Описание

function pg_free_result(PgSql\Result `$result`): bool

Функция pg_free_result() освобождает память, которую занимает экземпляр класса PgSql\Result.

Функцию вызывают, только если при выполнении скрипта недостаточно памяти. Память так или иначе освободится автоматически, когда скрипт завершит работу.

> Замечание:

> Раньше функция называлась pg_freeresult().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример очистки результата запроса и освобождения памяти функцией pg_free_result()

    <?php

    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Первое поле во второй строчке: ", $val, "\n";

    pg_free_result($res);

    ?>

Результат выполнения приведённого примера:

    Первое поле во второй строчке: 2

### Смотрите также

- pg_query() - Выполняет запрос
- pg_query_params() - Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса
- pg_execute() - Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
- pg_result_memory_size() - Возвращает объём памяти, выделенный для результата запроса

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — Получение SQL NOTIFY сообщения

### Описание

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() получает уведомления, сгенерированные командой SQL `NOTIFY`. Для получения уведомлений используйте команду SQL `LISTEN`.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`mode`
  Необязательный параметр, который управляет индексированием массив (array), который возвращает функция. Параметр `mode` — константа и принимает следующие значения: `PGSQL_ASSOC`, `PGSQL_NUM` и `PGSQL_BOTH`. С константой `PGSQL_NUM` функция возвращает массив с числовыми индексами, с константой `PGSQL_ASSOC` функция вернёт только ассоциативные индексы, а с `PGSQL_BOTH` — вернёт как числовые, так и ассоциативные индексы.

### Возвращаемые значения

Массив (array), содержащий сообщение `NOTIFY` и PID сервера БД. Если поддерживается сервером, массив также содержит версию сервера и полезную нагрузку. Если никаких уведомлений не ожидается, функция вернёт `false`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Сообщение PostgreSQL NOTIFY

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    // Слушаем сообщение 'author_updated' из другого процесса
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "Нет сообщений\n";
    } else {
      print_r($notify);
    }
    ?>

### Смотрите также

- pg_get_pid() - Получает ID процесса сервера БД

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — Получает ID процесса сервера БД

### Описание

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() получает PID сервера базы данных. PID полезен, когда требуется определить, какой процесс отправил `NOTIFY` сообщение, принятое функцией pg_get_notify() (точнее узнать, сервер его отправил или какой-то другой процесс).

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

ID процесса сервера баз данных.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 PID сервера PostgreSQL

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    // PID сервера БД. Сравните его с PID возвращаемым pg_get_notify()
    $pid = pg_get_pid($conn);
    ?>

### Смотрите также

- pg_get_notify() - Получение SQL NOTIFY сообщения

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — Получает результат асинхронного запроса

### Описание

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

Функция pg_get_result() получает экземпляр класса PgSql\Result из асинхронного запроса, который выполняют функциями pg_send_query(), pg_send_query_params() или pg_send_execute().

Функция pg_send_query() и другие функции, которые отправляют асинхронные запросы, умеет отправлять на сервер серию запросов один за другим, а функция pg_get_result() получает результаты каждого запроса по очереди.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Функция возвращает экземпляр класса PgSql\Result, или `false`, если доступных результатов не осталось.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример получения результата асинхронного запроса функцией pg_get_result()

    <?php

    $dbconn = pg_connect("dbname=publisher") or die("Невозможно соединиться с сервером");

    if (!pg_connection_busy($dbconn)) {
        pg_send_query($dbconn, "SELECT * FROM authors; SELECT count(*) FROM authors;");
    }

    $res1 = pg_get_result($dbconn);
    echo "Первый вызов функции pg_get_result(): $res1\n";
    $rows1 = pg_num_rows($res1);
    echo "$res1 содержит $rows1 записей\n\n";

    $res2 = pg_get_result($dbconn);
    echo "Второй вызов функции pg_get_result(): $res2\n";
    $rows2 = pg_num_rows($res2);
    echo "$res2 содержит $rows2 записей\n";

    ?>

Результат выполнения приведённого примера:

    Первый вызов функции pg_get_result(): Resource id #3
    Resource id #3 содержит 3 записей

    Второй вызов функции pg_get_result(): Resource id #4
    Resource id #4 содержит 1 записей

### Смотрите также

- pg_send_query() - Отправляет асинхронный запрос

# pg_host

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

pg_host — Возвращает имя хоста, соответствующего подключению

### Описание

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() возвращает имя хоста, с которым установлено заданное соединение PostgreSQL `connection`.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Строка, содержащая имя подключённого через `connection` хоста, либо пустая строка в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_host()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Успешно подключились к : " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL
- pg_pconnect() - Открывает постоянное соединение с сервером PostgreSQL

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — Заносит данные массива в таблицу базы данных

### Описание

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

Функция pg_insert() вставляет записи из массива `values` в таблицу `table_name`.

Функция pg_convert() обработает значения массива `values` с заданными флагами, если установлен параметр `flags`.

По умолчанию функция pg_insert() передаёт необработанные значения. Значения нужно экранировать или передавать в параметр `flags` флаг `PGSQL_DML_ESCAPE`. Опиция `PGSQL_DML_ESCAPE` закавычивает и экранирует параметры и идентификаторы. Поэтому имена таблиц и столбцов становятся чувствительными к регистру.

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

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы для вставки данных. Количество колонок в таблице `table_name` должно быть не меньше, чем элементов в массиве `values`.

`values`

  Ассоциативный массив (array), в котором ключи — названия столбцов таблицы `table_name`, а значения — записи, которые нужно вставить в эти колонки.

`flags`

  Комбинация констант `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` и `PGSQL_DML_STRING`. Функция возвращает строку запроса, если в числе прочих в параметр `flags` передают флаг `PGSQL_DML_STRING`. Функция не вызывает функцию pg_convert() внутренне, если установлены флаги `PGSQL_DML_NO_CONV` или `PGSQL_DML_ESCAPE`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.. Или возвращает строку (string), если флаг `PGSQL_DML_STRING` включён в список аргументов параметра `flags`.

### Ошибки

Функция выбрасывает исключение ValueError, если заданная таблица недопустима.

Функция выбрасывает исключения ValueError или TypeError, если значение или тип поля не соответствуют правильному типу СУБД PostgreSQL.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция теперь выбрасывает исключение ValueError, если заданная таблица недопустима; раньше функция выдавала ошибку уровня `E_WARNING`.
8.3.0 | Функция теперь выбрасывает исключения ValueError или TypeError, если значение или тип поля не соответствуют правильному типу СУБД PostgreSQL; раньше функция выдавала ошибку уровня `E_WARNING`.
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_insert()

    <?php

    $dbconn = pg_connect('dbname=foo');

    // Это безопасно в некоторой степени, поскольку все значения экранируются.
    // Однако СУБД PostgreSQL поддерживает JSON или массив. Для этих значений это не безопасно
    // ни через экранирование, ни с через подготовленный запрос.
    $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);

    if ($res) {
        echo "Данные из POST-запроса успешно внесены в журнал\n";
    } else {
        echo "Пользователь прислал неверные данные\n";
    }

    ?>

### Смотрите также

- pg_convert() - Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Возвращает информацию о JIT сервера

### Описание

function pg_jit(?PgSql\Connection `$connection` = `null`): array

Функция pg_jit() возвращает массив с информацией о JIT (компиляции Just-In-Time) сервера PostgreSQL.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает массив (array) с информацией о JIT сервера.

### Смотрите также

- pg_version() - Возвращает массив, содержащий версии клиента, протокола клиент-серверного взаимодействия и сервера (если доступно)

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — Получает сообщение о последней произошедшей ошибке на соединении с базой данных

### Описание

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() возвращает сообщение о последней ошибке на заданном соединении `connection`.

Сообщения об ошибках могут перезаписываться при внутренних вызовах функций PostgreSQL (libpq). Если внутри модуля PostgreSQL произойдёт несколько ошибок, сообщение может оказаться неинформативным.

Для обработки ошибок лучше использовать функции pg_result_error(), pg_result_error_field(), pg_result_status() и pg_connection_status().

> Замечание:

> Прежнее название функции: pg_errormessage().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает строку, которая содержит сообщение о последней ошибке соединения `connection`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_last_error()

    <?php

    $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с сервером");

    // Неудачный запрос
    $res = pg_query($dbconn, "SELECT * FROM doesnotexist");

    echo pg_last_error($dbconn);

    ?>

### Смотрите также

- pg_result_error() - Возвращает сообщение об ошибке, связанное с запросом результата
- pg_result_error_field() - Возвращает конкретное поле из отчёта об ошибках

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — Возвращает последнее уведомление от сервера PostgreSQL

### Описание

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() возвращает последнее уведомление, сгенерированное сервером PostgreSQL на заданном соединении `connection`. В некоторых случаях сервер посылает уведомления, например при создании в таблице колонки типа `SERIAL`.

Благодаря pg_last_notice() не требуется делать лишних запросов, чтобы узнать посылала ваша транзакция уведомления или нет.

Можно отключить отслеживание уведомлений установкой в значение 1 параметра `pgsql.ignore_notice` в файле php.ini.

Можно отключить журналирование уведомлений установкой в значение 0 параметра `pgsql.log_notice` в файле php.ini. Пока этот параметр установлен в значение 0, уведомления невозможно записать в журнал выполнения.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`mode`

  Одна из констант `PGSQL_NOTICE_LAST` (для возврата последнего уведомления), `PGSQL_NOTICE_ALL` (для возврата всех уведомлений) или `PGSQL_NOTICE_CLEAR` (для очистки уведомлений).

### Возвращаемые значения

Строка, содержащая последнее уведомление на заданном соединении, если задана опция `PGSQL_NOTICE_LAST`, массив (array), если опция `PGSQL_NOTICE_ALL` и значение типа bool в случае опции `PGSQL_NOTICE_CLEAR`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
7.1.0 | Добавлен параметр `mode`.

### Примеры

Пример #1 Пример использования pg_last_notice()

    <?php
      $pgsql_conn = pg_connect("dbname=mark host=localhost");

      $res = pg_query("CREATE TABLE test (id SERIAL)");

      $notice = pg_last_notice($pgsql_conn);

      echo $notice;
    ?>

Результат выполнения приведённого примера:

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### Смотрите также

- pg_query() - Выполняет запрос
- pg_last_error() - Получает сообщение о последней произошедшей ошибке на соединении с базой данных

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — Возвращает OID последней добавленной в базу строки

### Описание

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() используется для определения OID, соответствующего вставленной в таблицу строке.

Поле OID таблиц баз данных стало необязательным, начиная с версии PostgreSQL 7.2, а с версии 8.1 перестанет добавляться в таблицы по умолчанию. Если поле OID таблицы не задано, используйте функцию pg_result_status() для проверки успешности вставки записей в таблицу.

Чтобы получить значение `SERIAL` поля после вставки строки в таблицу, используйте функцию PostgreSQL `CURRVAL`, передав ей имя последовательности, значение которой нужно получить. Чтобы узнать имя последовательности, необходимо использовать функцию `pg_get_serial_sequence` (PostgreSQL 8.0).

В PostgreSQL 8.1 есть функция `LASTVAL`, возвращающая значение наиболее часто используемой за сессию последовательности. Так можно избежать необходимость задавать название последовательности, таблицы или колонки.

> Замечание:

> Прежнее название функции: pg_getlastoid().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Целое число (int) или строка (string), содержащая OID последней вставленной строки на соединении `connection`, либо `false`, если произошла ошибка или поле OID недоступно.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_last_oid()

    <?php
      // Подключение к базе данных
      pg_connect("dbname=mark host=localhost");

      // Создание тестовой таблицы
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // Вставка данных в таблицу
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### Смотрите также

- pg_query() - Выполняет запрос
- pg_result_status() - Возвращает статус результата запроса

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — Закрывает большой объект

### Описание

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() закрывает большой объект.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_loclose().

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_close()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_open() - Открывает большой объект базы данных
- pg_lo_create() - Создаёт большой объект
- pg_lo_import() - Импортирует большой объект из файла

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — Создаёт большой объект

### Описание

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() создаёт большой объект и возвращает его OID. Режимы доступа Константы PostgreSQL `INV_READ` и `INV_WRITE` не поддерживаются, объект всегда создаётся с доступом на чтение и запись.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

Вместо использования интерфейса больших объектов (который не имеет контроля доступа и весьма громоздкий сам по себе) пользуйтесь полями PostgreSQL типа bytea для хранения двоичных данных и функцией pg_escape_bytea() для их экранирования.

> Замечание:

> Прежнее название функции: pg_locreate().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`object_id`

  Если задан аргумент `object_id`, функция попытается создать объект с этим идентификатором, в противном случае будет использован свободный идентификатор, назначенный сервером.

### Возвращаемые значения

OID большого объекта или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_create()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

# pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — Вывод большого объекта в файл

### Описание

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() выбирает большой объект из базы данных и сохраняет его данные локально в файловой системе.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_loexport().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`oid`

  OID большого объекта в базе данных.

`filename`

  Полный путь и имя файла в клиентской файловой системе для записи данных большого объекта.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_export()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       $handle = pg_lo_open($database, $oid, "w");
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_import() - Импортирует большой объект из файла

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — Импортирует большой объект из файла

### Описание

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

Функция pg_lo_import() создаёт большой объект в базе данных из локального файла.

Методы интерфейса больших объектов работают только внутри блока транзакций.

> Замечание:

> Раньше функция называлась pg_loimport().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`filename`

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

`oid`

  При установке параметра `oid` функция попытается создать объект с этим идентификатором, иначе сервер назначит объекту свободный идентификатор. Параметр работает на основе механизма, который впервые появился в PostgreSQL 8.1.

### Возвращаемые значения

Функция возвращает OID вновь созданного большого объекта или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример импорта большого объекта из файла функцией pg_lo_import()

    <?php

    $database = pg_connect("dbname=jacarta");
    pg_query($database, "begin");
    $oid = pg_lo_import($database, '/tmp/lob.dat');
    pg_query($database, "commit");

    ?>

### Смотрите также

- pg_lo_export() - Вывод большого объекта в файл
- pg_lo_open() - Открывает большой объект базы данных

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — Открывает большой объект базы данных

### Описание

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() открывает большой объект базы данных и возвращает экземпляр PgSql\Lob.

Внимание

Не следует закрывать соединение с базой данных до того, как завершится работа с экземпляром PgSql\Lob.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_loopen().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`oid`

  OID большого объекта в базе данных.

`mode`

  Режим доступа к объекту. Возможные значения: "r" - только для чтения, "w" - только для записи, "rw" - для чтения и записи.

### Возвращаемые значения

Экземпляр PgSql\Lob или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Возвращает экземпляр PgSql\Lob; ранее возвращался ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_open()

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "large object data");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_close() - Закрывает большой объект
- pg_lo_create() - Создаёт большой объект

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — Читает данные большого объекта

### Описание

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() читает `length` байт большого объекта и возвращает их в виде строки.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_loread().

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().
`length`

  Необязательный аргумент. Количество байт, которые необходимо прочитать.

### Возвращаемые значения

Строка(string), содержащая `length` байт большого объекта, либо `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_read()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       $data = pg_lo_read($handle, 50000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Смотрите также

- pg_lo_read_all() - Читает содержимое большого объекта и посылает напрямую в браузер

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — Читает содержимое большого объекта и посылает напрямую в браузер

### Описание

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() читает большой объект и посылает данные напрямую в браузер после отправки всех необходимых заголовков. Используется в основном для пересылки двоичных данных, таких как изображения или звук.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_loreadall().

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().

### Возвращаемые значения

Количество прочитанных байт.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_read_all()

    <?php
       header('Content-type: image/jpeg');
       $image_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $image_oid, "r");
       pg_lo_read_all($handle);
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_read() - Читает данные большого объекта

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — Перемещает внутренний указатель большого объекта

### Описание

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() перемещает внутренний указатель экземпляра PgSql\Lob.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().
`offset`

  Количество байт, на сколько требуется переместить указатель.

`whence`

  Одна из констант: `PGSQL_SEEK_SET` (перемещать от начала объекта), `PGSQL_SEEK_CUR` (перемещать с текущей позиции) или `PGSQL_SEEK_END` (отступать от конца объекта).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_seek()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Пропустить первые 50000 байт
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Прочитать следующие 10000 байт
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Смотрите также

- pg_lo_tell() - Возвращает текущее положение внутреннего указателя большого объекта

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — Возвращает текущее положение внутреннего указателя большого объекта

### Описание

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() возвращает текущую позицию (отступ от начала) внутреннего указателя большого объекта.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().

### Возвращаемые значения

Текущая позиция внутреннего указателя (количество байт от начала) большого объекта. В случае возникновения ошибки функция вернёт отрицательное значение.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_tell()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Пропустить первые 50000 байт
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Проверим, на сколько мы отступили
       $offset = pg_lo_tell($handle);
       echo "Текущее положение внутреннего указателя: $offset";
       pg_query($database, "commit");
    ?>

Результат выполнения приведённого примера:

    Текущее положение внутреннего указателя: 50000

### Смотрите также

- pg_lo_seek() - Перемещает внутренний указатель большого объекта

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Обрезает большой объект

### Описание

function pg_lo_truncate(PgSql\Lob `$lob`, int `$size`): bool

pg_lo_truncate() обрезает экземпляр PgSql\Lob.

Для использования интерфейса большого объекта, необходимо заключить его в блок транзакций.

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().
`size`

  Количество байтов для обрезания.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_truncate()

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Обрезать до 0
       pg_lo_truncate($handle, 0);
       pg_query($database, "commit");
       echo $data;
    ?>

### Смотрите также

- pg_lo_tell() - Возвращает текущее положение внутреннего указателя большого объекта

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — Удаление большого объекта

### Описание

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() удаляет большой объект с идентификатором `oid`.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_lounlink().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`oid`

  OID большого объекта в базе данных.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_lo_unlink()

    <?php
       // OID удаляемого объекта
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_create() - Создаёт большой объект
- pg_lo_import() - Импортирует большой объект из файла

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — Записывает данные в большой объект

### Описание

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() записывает данные в большой объект, начиная с текущей позиции внутреннего указателя.

Операции с использованием интерфейса больших объектов необходимо заключать в блок транзакции.

> Замечание:

> Прежнее название функции: pg_lowrite().

### Список параметров

`lob`
  Экземпляр класса PgSql\Lob, который вернула функция pg_lo_open().
`data`

  Данные для записи в большой объект. Если аргумент `length` задан и меньше размера `data`, то записаны будут только `length` байт.

`length`

  Необязательный аргумент. Максимальное количество записываемых байт. Должен быть больше нуля и не превышать размер `data`. По умолчанию принимается равным размеру `data`.

### Возвращаемые значения

Количество записанных в большой объект байт, либо `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `lob` теперь принимает объект PgSql\Lob; раньше параметр принимал тип resource.
8.0.0 | `length` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_lo_write()

    <?php
       $doc_oid = 189762345;
       $data = "This will overwrite the start of the large object.";
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "w");
       $data = pg_lo_write($handle, $data);
       pg_query($database, "commit");
    ?>

### Смотрите также

- pg_lo_create() - Создаёт большой объект
- pg_lo_open() - Открывает большой объект базы данных

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — Получение метаданных таблицы

### Описание

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_meta_data() возвращает определение таблицы `table_name` в виде массива.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Название таблицы.

`extended`

  Флаг, который указывает, что нужно вернуть расширенные метаданные. Значение по умолчанию — `false`.

### Возвращаемые значения

Массив, который содержит определение таблицы или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Получение метаданных таблицы

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось соединиться с сервером");

      $meta = pg_meta_data($dbconn, 'authors');
      if (is_array($meta)) {
          echo '<pre>';
          var_dump($meta);
          echo '</pre>';
      }
    ?>

Результат выполнения приведённого примера:

    array(3) {
    ["author"]=>
    array(5) {
      ["num"]=>
      int(1)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["year"]=>
    array(5) {
      ["num"]=>
      int(2)
      ["type"]=>
      string(4) "int2"
      ["len"]=>
      int(2)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["title"]=>
    array(5) {
      ["num"]=>
      int(3)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    }

### Смотрите также

- pg_convert() - Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — Возвращает количество полей в выборке

### Описание

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() возвращает количество полей (столбцов) в экземпляре PgSql\Result.

> Замечание:

> Ранее функция называлась pg_numfields().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Количество полей (столбцов) в выборке. В случае возникновения ошибки возвращает -1.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_num_fields()

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo "Возвращено полей: " . $num . ".\n";
    ?>

Результат выполнения приведённого примера:

    Возвращено полей: 2.

### Смотрите также

- pg_num_rows() - Возвращает количество строк в выборке
- pg_affected_rows() - Возвращает количество затронутых запросом записей (кортежей)

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — Возвращает количество строк в выборке

### Описание

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() возвращает количество строк в экземпляре PgSql\Result.

> Замечание:

> Ранее функция называлась pg_numrows().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Количество строк в выборке. В случае возникновения ошибки возвращает `-1`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_num_rows()

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo "Возвращено строк: " . $rows . ".\n";
    ?>

Результат выполнения приведённого примера:

    Возвращено строк: 1.

### Смотрите также

- pg_num_fields() - Возвращает количество полей в выборке
- pg_affected_rows() - Возвращает количество затронутых запросом записей (кортежей)

# pg_options

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

pg_options — Получение параметров соединения с сервером баз данных

### Описание

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() возвращает строку, содержащую параметры соединения PostgreSQL `connection`.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Строка, содержащая параметры соединения `connection`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_options()

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Просмотр текущих значений параметров сервера

### Описание

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

Получает текущее значение заданного параметра сервера.

Значения некоторых параметров сервер сообщает автоматически при установлении подключения или при изменении данных значений. Функция pg_parameter_status() может запрашивать подобные значения. Она возвращает значение параметра, если оно определено, либо `false` в случае возникновения ошибки.

Список параметров серверов PostgreSQL версий 8.0 и выше: `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone`, и `integer_datetimes`. (`server_encoding`, `TimeZone`, и `integer_datetimes` не определяются для версий ниже 8.0.) Стоит отметить, что значения `server_version`, `server_encoding` и `integer_datetimes` нельзя изменить после запуска PostgreSQL.

Несмотря на то, что PostgreSQL версий 7.3 и ниже не сообщают значений своих параметров, pg_parameter_status() позволяет определить значения параметров `server_version` и `client_encoding`. Для определения значений этих параметров предпочтительней использовать pg_parameter_status(), нежели специально разрабатывать другие функции.

Предостережение

Если при использовании сервера PostgreSQL версий 7.4 и ниже изменить параметр `client_encoding` посредством команды сервера `SET` уже после установки соединения, функция pg_parameter_status() не сможет отразить этот факт.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`name`

  Допустимые значения аргумента: `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` и `integer_datetimes`. Обратите внимание, что это значение чувствительно к регистру.

### Возвращаемые значения

Значение запрашиваемого параметра в виде строки, либо `false`, если передан недопустимый параметр.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_parameter_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Невозможно соединиться с сервером");

      echo "Кодировка сервера: ", pg_parameter_status($dbconn, "server_encoding");
    ?>

Результат выполнения приведённого примера:

    Кодировка сервера: SQL_ASCII

# pg_pconnect

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

pg_pconnect — Открывает постоянное соединение с сервером PostgreSQL

### Описание

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

Функция pg_pconnect() устанавливает соединение с базой данных PostgreSQL и возвращает экземпляр класса PgSql\Connection, который требуется другим функциям взаимодействия с СУБД PostgreSQL.

При повторном вызове функции pg_pconnect() с теми же параметрами в строке `connection_string` функция вернёт подключение, которое уже установили, если только в параметр `flags` не передали флаг `PGSQL_CONNECT_FORCE_NEW`.

Постоянные соединения включают в файле php.ini путём установки в директиве pgsql.allow_persistent значения по умолчанию — `"On"`. Максимальное количество постоянных подключений определяют в файле php.ini через директиву pgsql.max_persistent. Стандартное значение директивы равняется `-1`. Это значение снимает ограничения на количество подключений. Общее количество подключений устанавливают в файле php.ini через директиву pgsql.max_links.

Функция pg_close() не закрывает соединения, которые открыли функцией pg_pconnect().

### Список параметров

`connection_string`

  Параметр `connection_string` принимает пустую строку или настройки параметров через пробел. При передаче пустой строки функция открывает постоянное соединение с параметрами по умолчанию. Каждую настройку параметра передают в форме `keyword = value`. Пробелы вокруг знака равенства необязательны. Пустые значения или значения с пробелами записывают в одинарных кавычках: `keyword = 'a value'`. Одинарные кавычки и обратные слеши внутри значения экранируют обратным слешем: `\'` и `\\`.

  Функция распознаёт следующие параметры: `host`, `hostaddr`, `port`, `dbname`, `user`, `password`, `connect_timeout`, `options`, `tty` (игнорируется), `sslmode`, `requiressl` (устарел в пользу `sslmode`) и `service`. Поддержка параметров зависит от версии СУБД PostgreSQL.

`flags`

  При передаче флага `PGSQL_CONNECT_FORCE_NEW` функция создаёт новое соединение, даже если строка подключения `connection_string` идентична строке подключения, которое уже установили.

### Возвращаемые значения

Функция возвращает экземпляр класса PgSql\Connection, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция теперь возвращает экземпляр класса PgSql\Connection; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример установки постоянного соединения функцией pg_pconnect()

    <?php

    // Подключение к базе данных "mary"
    $dbconn = pg_pconnect("dbname=mary");

    // Подключение к БД "mary" на хосте "localhost" и порте "5432"
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");

    // Подключение к базе данных "mary" на хосте "sheep" с именем пользователя и паролем
    $dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // Подключение к БД "test" на хосте "sheep" с именем пользователя и паролем
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_pconnect($conn_string);

    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL
- Постоянные соединения с базой данных

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Проверка соединения с базой данных

### Описание

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() проверяет соединение с базой данных и переподключается, если оно нарушено.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_ping()

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("Соединение нарушено\n");
    ?>

### Смотрите также

- pg_connection_status() - Определяет состояние подключения
- pg_connection_reset() - Сброс подключения (переподключение)

# pg_port

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

pg_port — Возвращает номер порта, соответствующий заданному соединению

### Описание

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() возвращает номер порта, соответствующего заданному соединению PostgreSQL `connection`.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Строка (string), соответствующая номеру порта, либо пустая строка в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_port()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Успешно соединено с портом : " . pg_port($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Отправляет на сервер запрос на подготовку SQL-запроса с параметрами-заполнителями и ждёт, пока завершится подготовка запроса

### Описание

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

Функция pg_prepare() подготавливает SQL-запрос, который затем запустит функция pg_execute() или pg_send_execute(). Функция помогает разбирать и планировать команды только один раз, а не каждый раз при выполнении, а потом многократно выполнять такие команды. Функция pg_prepare() поддерживает соединения только с БД PostgreSQL 7.4 или новее; функция не будет работать c серверами предыдущих версий.

Функция создает подготовленный запрос с названием `statement_name` из строки `query`, которая содержит одну команду. Значение параметра `statement_name` указывают как пустую строку `""`, чтобы создать безымянный запрос, который автоматически заменяет предыдущий безымянный запрос; в остальных случаях попытка назвать запрос именем, которое уже определили в текущей сессии, вызовет ошибку. Параметры, которые передали при выполнении запроса, указывают на обозначения `$1`, `$2` и т. д. в запросе `query`.

Подготовленные для функции pg_prepare() запросы создают также SQL-командой `PREPARE`, но функция pg_prepare() гибче, поскольку не заставляет указывать типы параметров. Хотя в PHP нет функции для удаления подготовленного запроса, это сделает SQL-команда `DEALLOCATE`.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`statement_name`

  Уникальное в пределах сессии имя, которым функция назовёт подготовленный запрос. Функция создаст безымянный запрос, который перезапишет предыдущий безымянный запрос текущей сессии, если задали пустую строку `""`.

`query`

  Один параметризованный SQL-запрос; несколько запросов через точку с запятой не поддерживаются. Параметры, которые передали, относятся к обозначениям запроса `$1`, `$2` и т. д.

### Возвращаемые значения

Функция возвращает экземпляр PgSql\Result в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример подготовки запроса функцией pg_prepare()

    <?php

    // Подключение к базе данных "mary"
    $dbconn = pg_connect("dbname=mary");

    // Подготовка запроса
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Запуск запроса на выполнение. Обратите внимание: спецсимволы в строке "Joe's Widgets"
    // не заэкранированы
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Запуск на выполнение того же запроса, но с другим параметром
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Смотрите также

- pg_execute() - Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
- pg_send_execute() - Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Отправляет данные на сервер при выполнении операции COPY

### Описание

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

Функция отправляет данные на сервер при выполнении операции `COPY FROM STDIN`. Функция отправит данные, только если перед вызовом на сервер предварительно отправили команду `COPY` функцией pg_query().

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`cmd`
  Данные для отправки на сервер. При пропуске завершающий символ перевода строки добавляется автоматически. Для правильной обработки данных строку приводят в соответствие с форматом команды `COPY`.

### Возвращаемые значения

Функция возвращает `1`, если выполнилась успешно, `0`, если данные невозможно поставить в очередь — только в неблокирующем режиме, или `-1`, если возникла ошибка.

### Смотрите также

- pg_put_copy_end() - Сообщает серверу о завершении операции COPY
- pg_query() - Выполняет запрос

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Сообщает серверу о завершении операции COPY

### Описание

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

Функция отправляет на сервер признак конца данных при выполнении операции `COPY FROM STDIN`.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`error`
  Сообщение об ошибке, с которым операция `COPY` принудительно завершается ошибкой, если значение аргумента не равно `null`.

### Возвращаемые значения

Функция возвращает `1`, если выполнилась успешно, `0`, если данные невозможно поставить в очередь — только в неблокирующем режиме, или `-1`, если возникла ошибка.

### Смотрите также

- pg_put_copy_data() - Отправляет данные на сервер при выполнении операции COPY
- pg_query() - Выполняет запрос

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — Передаёт на PostgreSQL сервер строку с завершающим нулём

### Описание

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() передаёт на PostgreSQL сервер строку с завершающим нулём. Завершение строки значением NULL необходимо при её объединении с командой PostgreSQL `COPY FROM`.

`COPY` является высокоскоростным интерфейсом передачи данных, поддерживаемым PostgreSQL. Данные передаются одной транзакцией и не разбираются парсером.

В качестве альтернативы можно использовать функцию pg_copy_from(). Она значительно проще в использовании.

> Замечание:

> Перед запуском функции pg_end_copy() приложение должно сообщить о серверу о завершении передачи данных, добавив в конец последней строки символы "\.".

Внимание

Использование pg_put_line() может привести к отказу операций с большими объектами, включающих функции pg_lo_read() и pg_lo_tell(). Для этих целей используйте функции pg_copy_from() и pg_copy_to().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`query`

  Текстовая строка для прямой пересылки на сервер. Завершающий `NULL` добавляется автоматически.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_put_line()

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Смотрите также

- pg_end_copy() - Синхронизирует с бэкендом PostgreSQL

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — Выполняет запрос

### Описание

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() выполняет `query` к указанной в `connection` базе данных. pg_query_params() должна быть предпочтительнее в большинстве случаев.

В случае возникновения ошибки функция возвращает `false`, детали ошибки можно получить с помощью функции pg_last_error(), если соединение с БД не нарушено.

> Замечание: Несмотря на то, что параметр `connection` может быть опущен, делать так не рекомендуется, так как это может привести к трудно находимым ошибкам в скриптах.

> Замечание:

> Ранее данная функция называлась pg_exec(). pg_exec() всё ещё доступна в целях обеспечения совместимости, но лучше использовать новое имя.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`query`

  Выражение или выражения SQL для выполнения. Если передано несколько выражений они автоматически выполняются, как одна транзакция если явно не указаны команды BEGIN/COMMIT внутри выражения. Тем не менее, использовать несколько транзакций в одном вызове функции не рекомендуется.

  Внимание

  Строковое представление пользовательских данных очень опасно и часто приводит к возможности SQL инъекции. В большинстве случаев лучше передавать пользовательские данные параметром в pg_query_params(), а не подставлять их в строку запроса.

  Любые данные передаваемые от пользователя непосредственно в строку запроса должны быть хорошо экранированы.

### Возвращаемые значения

Экземпляр PgSql\Result в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Автор: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

Пример #2 Использование нескольких выражений в pg_query()

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // эти выражения будут исполнены в одной транзакции

    $query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
    $query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
    $query .= "UPDATE authors SET author=NULL WHERE id=3;";

    pg_query($conn, $query);

    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL
- pg_pconnect() - Открывает постоянное соединение с сервером PostgreSQL
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_num_rows() - Возвращает количество строк в выборке
- pg_affected_rows() - Возвращает количество затронутых запросом записей (кортежей)

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса

### Описание

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

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

pg_query_params() подобна функции pg_query(), но предоставляет дополнительный функционал: параметры запроса можно передавать отдельно от строки запроса.

Если используются параметры `params`, они заменяют псевдопеременные $1, $2 и т.д. в строке запроса `query`. Один и тот же параметр может быть указан больше одного раза в `query`; в этом случае будут использованы одинаковые значения. `params` определяют текущие значения параметров. Значение `null` в массиве параметров будет означать SQL `NULL` в запросе.

Главное преимущество pg_query_params() перед pg_query() заключается в том, что значения параметров могут передаваться отдельно от строки запроса `query`. Это даёт возможность избежать утомительную и подверженную ошибкам процедуру экранирования спецсимволов и заключения значений в кавычки. Однако, в отличие от pg_query(), эта функция поддерживает только один SQL запрос в передаваемой строке. (Он может содержать точку с запятой, но не более одной непустой SQL-команды.)

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`query`

  Параметризованный SQL запрос. Должен содержать только одно выражение (несколько выражений разделённых точкой с запятой не поддерживаются). Если в запрос будут передаваться параметры, то они заменят псевдопеременные $1, $2 и т.д.

  Пользовательские данные всегда должны передаваться как параметры, и не передаваться в строку запроса напрямую, где они могут привести к возможным атакам через SQL-инъекции и приводит к ошибкам, если данные содержат кавычки. Если по каким-то причинам вы не можете использовать параметр, убедитесь, что пользовательские данные правильно экранированы.

`params`

  Массив значений параметров запроса для замены псевдопеременных $1, $2 и т.д. в исходной строке запроса. Количество элементов массива должно точно совпадать с количеством псевдопеременных.

  Значения предназначенные для `bytea` полей нельзя передавать в параметрах. Используйте функцию pg_escape_bytea() или функции для больших объектов.

### Возвращаемые значения

Экземпляр PgSql\Result в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция возвращает экземпляр класса PgSql\Result; раньше функция возвращала ресурс (resource).
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_query_params()

    <?php
    // Подключение к базе данных "mary"
    $dbconn = pg_connect("dbname=mary");

    // Найдём все магазины с названием "Joe's Widgets". Стоит отметить, что нет необходимости экранировать
    // спецсимволы в строке "Joe's Widgets"
    $result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

    // Для сравнения то же самое, используя функцию pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

    ?>

### Смотрите также

- pg_query() - Выполняет запрос

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — Возвращает сообщение об ошибке, связанное с запросом результата

### Описание

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() возвращает сообщение о любой ошибке, связанное с экземпляром `result`. Таким образом, возможно получить более верное сообщение об ошибке, чем при использовании pg_last_error().

Функция pg_result_error_field() может дать гораздо более подробную информацию об ошибке, чем pg_result_error().

Так как pg_query() возвращает `false` в случае возникновения ошибки запроса, необходимо использовать pg_send_query() и pg_get_result() для получения дескриптора результата.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Возвращает строку (string). Возвращает пустую строку, если нет ошибки. Если же есть ошибка, не связанная с параметром `result`, то возвращается `false`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_result_error()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Смотрите также

- pg_result_error_field() - Возвращает конкретное поле из отчёта об ошибках
- pg_query() - Выполняет запрос
- pg_send_query() - Отправляет асинхронный запрос
- pg_get_result() - Получает результат асинхронного запроса
- pg_last_error() - Получает сообщение о последней произошедшей ошибке на соединении с базой данных
- pg_last_notice() - Возвращает последнее уведомление от сервера PostgreSQL

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Возвращает конкретное поле из отчёта об ошибках

### Описание

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() возвращает одно из полей отчёта об ошибках, связанного с экземпляром `result`. Нужное поле задаётся аргументом `field_code`.

Функции pg_query() и pg_query_params() в случае ошибок возвращают `false` вместо ресурса. Чтобы иметь возможность обрабатывать ошибки, пользуйтесь функциями pg_send_query() и pg_get_result().

Для получения дополнительной информации о ходе выполнения отказавшей функции pg_query() используйте функции pg_set_error_verbosity() и pg_last_error() и обрабатывайте результат их выполнения.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`field_code`

  Возможные значения аргумента `field_code`: `PGSQL_DIAG_SEVERITY`, `PGSQL_DIAG_SQLSTATE`, `PGSQL_DIAG_MESSAGE_PRIMARY`, `PGSQL_DIAG_MESSAGE_DETAIL`, `PGSQL_DIAG_MESSAGE_HINT`, `PGSQL_DIAG_STATEMENT_POSITION`, `PGSQL_DIAG_INTERNAL_POSITION`, `PGSQL_DIAG_INTERNAL_QUERY`, `PGSQL_DIAG_CONTEXT`, `PGSQL_DIAG_SOURCE_FILE`, `PGSQL_DIAG_SOURCE_LINE`, `PGSQL_DIAG_SOURCE_FUNCTION`.

### Возвращаемые значения

Сообщение об ошибке из заданного поля в виде строки (string); `null`, если заданное поле не существует; `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_result_error_field()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
    ?>

### Смотрите также

- pg_result_error() - Возвращает сообщение об ошибке, связанное с запросом результата

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Возвращает объём памяти, выделенный для результата запроса

### Описание

function pg_result_memory_size(PgSql\Result `$result`): int

Функция возвращает объём памяти в байтах, выделенный экземпляру результата запроса PgSql\Result. Значение равно объему, который освободила бы функция pg_free_result().

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).

### Возвращаемые значения

Функция возвращает объём памяти в байтах.

### Примеры

Пример #1 Пример получения функцией pg_result_memory_size() объёма памяти, выделенного для результата запроса

    <?php

    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);

    ?>

Вывод приведённого примера будет похож на:

    int(3288)

### Смотрите также

- pg_free_result() - Очищает результат запроса и освобождает память

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

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

### Описание

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() устанавливает смещение внутреннего указателя в экземпляре `result`.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`row`

  Количество строк, на которое требуется сместить внутренний указатель ресурса PgSql\Result. Строки нумеруются с нуля.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_result_seek()

    <?php

    // Подключение к базе данных
    $conn = pg_pconnect("dbname=publisher");

    // Выполнение запроса
    $result = pg_query($conn, "SELECT author, email FROM authors");

    // Перемещаемся сразу на третью строку
    // (допускаем, что в результате есть хотя бы три строки)
    pg_result_seek($result, 2);

    // Выбираем третью строку из результата
    $row = pg_fetch_row($result);

    ?>

### Смотрите также

- pg_fetch_row() - Выбирает строку результата запроса и помещает данные в массив
- pg_fetch_assoc() - Выбирает строку результата запроса и помещает данные в ассоциативный массив
- pg_fetch_array() - Возвращает строку результата в виде массива
- pg_fetch_object() - Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result() - Возвращает запись из результата запроса

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — Возвращает статус результата запроса

### Описание

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

Функция pg_result_status() возвращает текущий статус экземпляра PgSql\Result или тег завершения PostgreSQL-команды, который связан с результатом.

### Список параметров

`result`
  Экземпляр класса PgSql\Result, который возвращают функции pg_query(), pg_query_params() или pg_execute() (среди прочего).
`mode`

  Параметр принимает значение `PGSQL_STATUS_LONG` для возврата числового статуса, который содержится в объекте с результатами запроса и который передали в аргументе `result`, или значение `PGSQL_STATUS_STRING` для возврата тега команды из того же объекта с результатами запроса — `result`. Значение по умолчанию равно `PGSQL_STATUS_LONG`.

### Возвращаемые значения

При передаче в аргументе константы `PGSQL_STATUS_LONG` функция возвращает константу из следующего списка: `PGSQL_EMPTY_QUERY`, `PGSQL_COMMAND_OK`, `PGSQL_TUPLES_OK`, `PGSQL_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR`, `PGSQL_FATAL_ERROR`. В остальных случаях функция вернёт строковое представление состояния результата запроса.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `result` теперь принимает объект PgSql\Result; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример возврата статуса результата запроса функцией pg_result_status()

    <?php

    // Подключаемся к базе данных
    $conn = pg_pconnect("dbname=publisher");

    // Выполняем команду COPY
    $result = pg_query($conn, "COPY authors FROM STDIN;");

    // Получаем состояние результата запроса
    $status = pg_result_status($result);

    // Разбираем полученные данные
    if ($status == PGSQL_COPY_IN) {
       echo "Copy began.";
    } else {
       echo "Copy failed.";
    }

    ?>

Результат выполнения приведённого примера:

    Copy began.

### Смотрите также

- pg_connection_status() - Определяет состояние подключения

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — Выбирает записи из базы данных

### Описание

function pg_select(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions` = [],
int `$flags` = `PGSQL_DML_EXEC`,
int `$mode` = `PGSQL_ASSOC`
): array|string|false

Функция pg_select() выбирает из базы данных записи, которые удовлетворяют условиям `field=>value` в массиве `conditions`. Функция вернёт массив записей, поля которых удовлетворяют условиям `conditions`.

При установке параметра `flags` функция применит к каждому условию в массиве `conditions` функцию pg_convert() с этими флагами.

При установке для параметра `mode` режима `PGSQL_NUM` функция вернёт значение в форме индексного массива, в режиме по умолчанию `PGSQL_ASSOC` возвращается ассоциативный массив, а в режиме `PGSQL_BOTH` функция возвращает значения полей и с целочисленными, и со строковыми ключами.

По умолчанию функция pg_select() передаёт необработанные значения. Значения потребуется заэкранировать или указать опцию PGSQL_DML_ESCAPE. Опция PGSQL_DML_ESCAPE берёт в кавычки и экранирует параметры и идентификаторы. Поэтому названия таблиц и столбцов становятся чувствительными к регистру.

Обратите внимание, что ни экранирование, ни подготовленный запрос не защитят запрос LIKE, JSON, массив, регулярные выражения и т. д. Эти параметры потребуется обработать в соответствии с их контекстом — заэкранировать или проверить значения.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Название таблицы, из которой требуется выбрать данные.

`conditions`

  Массив (array), ключи которого соответствуют названиям полей таблицы `table_name`, а значения — условиям извлечения строк. Начиная с PHP 8.4.0 при передаче пустого массива функция не применяет условия. Раньше при передаче пустого массива `conditions` функция завершалась ошибкой.

`flags`

  Параметр принимает произвольное сочетание следующих констант: `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC`, `PGSQL_DML_STRING`. Функция вернёт строку запроса, если в списке флагов `flags` содержится флаг `PGSQL_DML_STRING`. При установке флага `PGSQL_DML_NO_CONV` или `PGSQL_DML_ESCAPE` функция pg_convert() внутренне не вызывается.

`mode`

  Константа `PGSQL_ASSOC`, `PGSQL_NUM` или `PGSQL_BOTH`. В режиме `PGSQL_ASSOC` функция возвращает ассоциативный массив, в режиме `PGSQL_NUM` возвращается индексный массив, а в режиме `PGSQL_BOTH` функция вернёт значения и с ассоциативным, и с числовым ключом.

### Возвращаемые значения

Функция возвращает значение с типом string, если аргумент `flags` содержит флаг `PGSQL_DML_STRING`, в остальных случаях функция возвращает значение с типом array, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `conditions` стал необязательным.
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
7.1.0 | Добавили параметр `mode`.

### Примеры

Пример #1 Пример выборки записей функцией pg_select()

    <?php

    $db = pg_connect('dbname=foo');

    // Отчасти это безопасно, поскольку значения экранируются.
    // Однако СУБД PostgreSQL поддерживает типы JSON и массив. Для таких значений это небезопасно
    // ни с экранированием, ни в подготовленном запросе
    $rec = pg_select($db, 'post_log', $_POST);

    if ($rec) {
        echo "Функция выбрала следующие записи\n";
        var_dump($rec);
    } else {
        echo "Пользователь, должно быть, отправил неверные данные\n";
    }

    ?>

### Смотрите также

- pg_convert() - Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата

### Описание

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата.

Работает аналогично функции pg_send_query_params(), только вместо строки с запросом принимает имя предварительно подготовленного SQL-запроса. Аргументы функции обрабатываются так же, как и в функции pg_execute(). Как и pg_execute() эта функция не будет работать на соединениях с серверами PostgreSQL версий ниже 7.4.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`statement_name`

  Имя подготовленного к исполнению запроса. Если передана пустая строка "", будет выполнен безымянный запрос. Имя и содержимое запроса должны быть подготовлены функцией pg_prepare(), pg_send_prepare() либо с помощью SQL-команды `PREPARE`.

`params`

  Массив значений параметров запроса для замены псевдопеременных $1, $2 и т.д. в исходной строке запроса. Количество элементов массива должно точно совпадать с количеством псевдопеременных.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения, `false` или `0` в случае возникновения ошибки. Для получения результата запроса используйте функцию pg_get_result().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_send_execute()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      // Подготовка запроса
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Запуск запроса на выполнение. Стоит отметить, что нет необходимости экранировать
      // спецсимволы в строке "Joe's Widgets"
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Запуск на выполнение того же запроса, но с другим параметром
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Смотрите также

- pg_prepare() - Отправляет на сервер запрос на подготовку SQL-запроса с параметрами-заполнителями и ждёт, пока завершится подготовка запроса
- pg_send_prepare() - Посылает запрос на создание параметризованного SQL-выражения, не дожидаясь его завершения
- pg_execute() - Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Посылает запрос на создание параметризованного SQL-выражения, не дожидаясь его завершения

### Описание

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Посылает запрос на создание параметризованного SQL выражения и не ждёт его завершения.

Это асинхронный вариант функции pg_prepare(): она возвращает `true`, если удалось отправить запрос, иначе `false`. После успешной отправки, воспользуйтесь функцией pg_get_result(), чтобы узнать, создалось ли требуемое SQL выражение. Аргументы функции обрабатываются так же, как в pg_prepare(). Функция не будет работать с серверами PostgreSQL версий ниже 7.4.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`statement_name`

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

`query`

  Параметризованный SQL запрос. Должен содержать только одно выражение (несколько выражений разделённых точкой с запятой не поддерживаются). Если в запрос будут передаваться параметры, то они заменят псевдопеременные $1, $2 и т. д.

### Возвращаемые значения

Функция возвращает `true` в случае успешного выполнения, `false` или `0`, если возникла ошибка. Результат запроса получают функцией pg_get_result().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования функции pg_send_prepare()

    <?php

    $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

    // Подготовка запроса
    if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
    }

    // Запуск запроса на выполнение. Стоит отметить, что нет необходимости экранировать
    // спецсимволы в строке "Joe's Widgets"
    if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
    }

    // Запуск на выполнение того же запроса, но с другим параметром
    if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
    }

    ?>

### Смотрите также

- pg_connect() - Открывает соединение с базой данных PostgreSQL
- pg_pconnect() - Открывает постоянное соединение с сервером PostgreSQL
- pg_execute() - Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
- pg_send_execute() - Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата
- pg_send_query_params() - Посылает параметризованный запрос на сервер, не ожидает возвращаемого результата

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — Отправляет асинхронный запрос

### Описание

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() отправляет на выполнение асинхронный запрос. В отличие от pg_query() запрос может содержать несколько SQL-выражений, разделённых точкой с запятой. Для получения результата запроса используйте функцию pg_get_result().

Выполнение запроса не прерывает работу скрипта. Для определения занятости соединения (когда запрос ещё выполняется) используйте функцию pg_connection_busy(). Выполнение запроса можно прервать функцией pg_cancel_query().

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

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`query`

  Одно или несколько SQL-выражений, разделённых точкой с запятой.

  Спецсимволы в строке запроса должны быть экранированы.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения, `false` или `0` в случае возникновения ошибки. Для получения результата запроса используйте функцию pg_get_result().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_send_query()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось подключиться");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Первый вызов pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 содержит $rows1 записей\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Второй вызов pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 содержит $rows2 записей\n";
    ?>

Результат выполнения приведённого примера:

    Первый вызов pg_get_result(): Resource id #3
    Resource id #3 содержит 3 записей

    Второй вызов pg_get_result(): Resource id #4
    Resource id #4 содержит 1 записей

### Смотрите также

- pg_query() - Выполняет запрос
- pg_cancel_query() - Остановка асинхронного запроса.
- pg_get_result() - Получает результат асинхронного запроса
- pg_connection_busy() - Проверяет, занято ли соединение в данный момент.

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Посылает параметризованный запрос на сервер, не ожидает возвращаемого результата

### Описание

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

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

Функция является аналогом pg_send_query() за одним исключением: параметры запроса можно передавать отдельно от строки запроса. Аргументы функции обрабатываются так же, как и в pg_query_params(). pg_send_query() поддерживается на соединениях с серверами PostgreSQL версий 7.4 и выше. Функция не будет работать с серверами ранних версий. Также она поддерживает только одну SQL-команду в выражении.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`query`

  Параметризованный SQL запрос. Должен содержать только одно выражение (несколько выражений разделённых точкой с запятой не поддерживаются). Если в запрос будут передаваться параметры, то они заменят псевдопеременные $1, $2 и т.д.

`params`

  Массив значений параметров запроса для замены псевдопеременных $1, $2 и т.д. в исходной строке запроса. Количество элементов массива должно точно совпадать с количеством псевдопеременных.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения, `false` или `0` в случае возникновения ошибки. Для получения результата запроса используйте функцию pg_get_result().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_send_query_params()

    <?php

    $dbconn = pg_connect("dbname=publisher") or die("Не удалось подключиться");

    // Передача параметров. Заметьте, что
    // брать в кавычки и экранировать параметр не обязательно.
    pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));

    // В сравнении с pg_send_query
    $str = pg_escape_string('Perth');
    pg_send_query($dbconn, "select count(*) from authors where city = '{$str}'");

    ?>

### Смотрите также

- pg_send_query() - Отправляет асинхронный запрос

# pg_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — Устанавливает для подключения режим, в котором результаты запроса извлекаются частями

### Описание

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

Функция устанавливает для подключения режим извлечения результатов по частям. Результаты запроса, которые возвращаются функцией получения данных, разделяются на части, каждая из которых содержит количество строк, которое указали в аргументе `size`. Функцию вызывают перед получением результатов функцией pg_get_result(). Функция доступна только с библиотекой libpq версии 17 или выше.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`size`
  Количество строк, которое требуется извлечь в каждой части.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция выбросит ошибку ValueError, если значение аргумента `size` меньше, чем `1`.

### Примеры

Пример #1 Пример установки режима частичного извлечения результатов функцией pg_result_memory_size()

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
        pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    // Ни на что не влияет после получения результата
    var_dump(pg_set_chunked_rows_size($conn, 10));

    ?>

Результат выполнения приведённого примера:

    int(1)
    bool(false)

### Смотрите также

- pg_get_result() - Получает результат асинхронного запроса
- pg_result_status() - Возвращает статус результата запроса

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — Устанавливает клиентскую кодировку

### Описание

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() устанавливает клиентскую кодировку и возвращает 0 в случае успешного выполнения, -1 в случае возникновения ошибки.

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

> Замечание:

> Прежнее название функции: pg_setclientencoding().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`encoding`

  Требуемая клиентская кодировка. Список возможных значений: `SQL_ASCII`, `EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`, `UNICODE`, `MULE_INTERNAL`, `LATINX` (X=1...9), `KOI8`, `WIN`, `ALT`, `SJIS`, `BIG5` or `WIN1250`.

  Список доступных кодировок зависит от версии PostgreSQL. Смотрите документацию к вашей версии сервера.

### Возвращаемые значения

Возвращает `0` в случае успешного выполнения, либо `-1` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_set_client_encoding()

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Произошла ошибка.\n";
      exit;
    }

    // Установка кодировки в UNICODE. Данные будут автоматически
    // преобразованы из кодировки в базе данных к клиентской.
    pg_set_client_encoding($conn, "UNICODE");

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Произошла ошибка.\n";
      exit;
    }

    // Выводим UTF-8 данные
    while ($row = pg_fetch_row($result)) {
      echo "Author: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Смотрите также

- pg_client_encoding() - Получение кодировки клиента.

# pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — Определяет видимость сообщений об ошибках контекста, возвращаемых функциями pg_last_error() и pg_result_error()

### Описание

function pg_set_error_context_visibility(PgSql\Connection `$connection`, int `$visibility`): int

Определяет видимость сообщений об ошибках контекста, возвращаемых функциями pg_last_error() и pg_result_error().

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`visibility`

  Требуемая видимость: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` или `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Возвращаемые значения

Функция возвращает предыдущий уровень видимости: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` или `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Примеры

Пример #1 Пример использования функции pg_set_error_context_visibility()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Не удалось установить соединение");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Смотрите также

- pg_last_error() - Получает сообщение о последней произошедшей ошибке на соединении с базой данных
- pg_result_error() - Возвращает сообщение об ошибке, связанное с запросом результата

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Определяет объем текста сообщений, возвращаемых функциями pg_last_error() и pg_result_error()

### Описание

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Определяет объем текста сообщений, возвращаемых функциями pg_last_error() и pg_result_error().

pg_set_error_verbosity() устанавливает режим, отвечающий за полноту сообщений об ошибках. В режиме `PGSQL_ERRORS_TERSE` сообщения будут содержать только важность ошибки, основной текст и место возникновения; эта информация обычно умещается в одну строку. В режиме по умолчанию `PGSQL_ERRORS_DEFAULT` в сообщения будут добавлены детали ошибки, подсказка или поля контекста (это может занять несколько строк). В режиме `PGSQL_ERRORS_VERBOSE` сообщения будут содержать все возможные поля. Изменение режима не затронет сообщения уже существующих ресурсов. Новый режим будет применяться только к вновь создаваемым.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если параметр `connection` не указали. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`verbosity`

  Требуемый режим: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` или `PGSQL_ERRORS_VERBOSE`.

### Возвращаемые значения

Предыдущий режим действовавший до запуска функции: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` или `PGSQL_ERRORS_VERBOSE`, или `false` в случае ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_set_error_verbosity()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Смотрите также

- pg_last_error() - Получает сообщение о последней произошедшей ошибке на соединении с базой данных
- pg_result_error() - Возвращает сообщение об ошибке, связанное с запросом результата

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — Получить дескриптор только для чтения на сокет, лежащего в основе соединения PostgreSQL

### Описание

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() возвращает ресурс (resource) только для чтения, соответствующий сокету, лежащему в основе данного соединения PostgreSQL.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Ресурс сокета в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Проверяет, готов ли сокет PostgreSQL-соединения к чтению или записи

### Описание

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

Функция проверяет, готов ли сокет PostgreSQL-соединения к чтению или записи. Сокет получают путём вызова функции pg_socket(). Функция помогает выстраивать неблокирующую асинхронную обработку запросов.

### Список параметров

`socket`
  Ресурс сокета, который вернула функции pg_socket().
`read`
  Параметр определяет, требуется ли проверять готовность сокета к чтению: `1` — проверять, `0` — пропустить.
`write`
  Параметр определяет, требуется ли проверять готовность сокета к записи: `1` — проверять, `0` — пропустить.
`timeout`
  Предельное время ожидания готовности сокета в миллисекундах: `-1` — ждать бесконечно, `0` — не ждать.

### Возвращаемые значения

Функция возвращает положительное значение, если сокет готов, `0`, если время ожидания истекло, или `-1`, если возникла ошибка.

### Смотрите также

- pg_socket() - Получить дескриптор только для чтения на сокет, лежащего в основе соединения PostgreSQL
- pg_consume_input() - Читает вводные данные на соединении
- pg_send_query() - Отправляет асинхронный запрос

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — Включает трассировку подключения PostgreSQL

### Описание

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() включает трассировку соединения с PostgreSQL сервером во внешний файл. Чтобы понимать содержимое таких файлов, необходимо хорошо разбираться во внутреннем устройстве клиент-серверного взаимодействия.

Для тех, кто не обладает подобными навыками, трассировка всё же может оказаться полезной для поиска ошибок при отправке запросов на сервер. Например, можно выполнить команду grep '^To backend' trace.log и посмотреть, какие запросы реально отправлены на сервер. Дополнительную информацию можно почерпнуть из » документации PostgreSQL.

### Список параметров

`filename`

  Полный путь и имя файла для записи журнала трассировки. Аналогично fopen().

`mode`

  Необязательный аргумент. Режим доступа к файлу. Аналогично fopen().

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

`trace_mode`

  Необязательный режим трассировки со следующими константами: `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` и `PGSQL_TRACE_REGRESS_MODE`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Добавлен параметр `trace_mode`.
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_trace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Теперь /tmp/trace.log будет хранить информацию о взаимодействии с сервером
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Смотрите также

- fopen() - Открывает файл или URL-адрес
- pg_untrace() - Отключает трассировку соединения с PostgreSQL

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Возвращает текущее состояние транзакции на сервере

### Описание

function pg_transaction_status(PgSql\Connection `$connection`): int

Возвращает текущее состояние транзакции на сервере.

Предостережение

pg_transaction_status() выдаёт некорректный результат при работе с сервером PostgreSQL 7.3, на котором выключена опция `autocommit`. Автоматическое завершение транзакций на стороне сервера устарело и не используется в более поздних версиях.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.

### Возвращаемые значения

Список возможных состояний: `PGSQL_TRANSACTION_IDLE` (сервер бездействует), `PGSQL_TRANSACTION_ACTIVE` (выполняется запрос), `PGSQL_TRANSACTION_INTRANS` (сервер бездействует, работа в режиме транзакции), или `PGSQL_TRANSACTION_INERROR` (сервер бездействует, транзакция потерпела неудачу). `PGSQL_TRANSACTION_UNKNOWN` - ошибка подключения. `PGSQL_TRANSACTION_ACTIVE` возвращается только когда запрос уже отправлен на сервер, но ещё не обработан.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_transaction_status()

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Подключиться не удалось");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'Соединение не удалось';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'Соединение свободно и простаивает';
      } else {
          echo 'Соединение в режиме транзакции';
      }
    ?>

# pg_tty

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

pg_tty — Возвращает имя терминала TTY, связанное с соединением

### Описание

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() возвращает имя терминала, связанного с экземпляром `connection`, на который выводится отладочная информация.

> Замечание:

> pg_tty() устарела, но оставлена для обратной совместимости.

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Имя TTY для подключения `connection` в виде строки (string).

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_tty()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "TTY отладки сервера: " . pg_tty($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — Убирает экранирование двоичных данных типа bytea

### Описание

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() убирает экранирование спецсимволов в значениях типа PostgreSQL bytea. Возвращает неэкранированную строку, содержащую двоичные данные.

> Замечание:

> При выборке SQL функцией `SELECT` данных типа bytea PostgreSQL возвращает значения в восьмеричной системе счисления с префиксом '\' (такие как \032). Пользователю необходимо вручную преобразовывать их в двоичный формат.

### Список параметров

`string`

  Строка (string), содержащая данные типа PostgreSQL bytea и подлежащая преобразованию в двоичную строку PHP.

### Возвращаемые значения

Строка (string) с неэкранированными спецсимволами.

### Примеры

Пример #1 Пример использования pg_unescape_bytea()

    <?php
      // Подключение к базе данных
      $dbconn = pg_connect('dbname=foo');

      // Получение bytea данных
      $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
      $raw = pg_fetch_result($res, 'data');

      // Преобразование в двоичный формат и отправка в броузер
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### Смотрите также

- pg_escape_bytea() - Экранирует спецсимволы в строке для вставки в поле типа bytea
- pg_escape_string() - Экранирование спецсимволов в строке запроса

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — Отключает трассировку соединения с PostgreSQL

### Описание

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

Останавливает трассировку, запущенную функцией pg_trace().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_untrace()

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Теперь трассировка взаимодействия с сервером отключена
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Смотрите также

- pg_trace() - Включает трассировку подключения PostgreSQL

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — Обновление данных в таблице

### Описание

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() заменяет записи в таблице, удовлетворяющие условиям `conditions` данными `values`.

Если `flags` указан, pg_convert() применяется к `values` с указанными флагами.

По умолчанию pg_update() передаёт необработанные значения. Значения должны быть экранированы или опция `PGSQL_DML_ESCAPE` должна быть указана. `PGSQL_DML_ESCAPE` заключает в кавычки и экранирует параметры/идентификаторы. Поэтому имена таблиц/столбцов становятся чувствительными к регистру.

Обратите внимание, что ни экранирование, ни подготовленный запрос не защитят запрос LIKE, JSON, массив, регулярные выражения и т.д.. Эти параметры должны обрабатываться в соответствии с их контекстами, т.е. следует экранировать/проверять значения.

### Список параметров

`connection`
  Экземпляр класса PgSql\Connection.
`table_name`

  Имя таблицы, в которой обновляются записи.

`values`

  Массив (array), ключи которого соответствуют именам колонок таблицы `table_name`, а значения заменят данные в этих колонках.

`conditions`

  Массив (array), ключи которого соответствуют именам колонок таблицы `table_name`. Будут обновлены только те строки, значения полей которых совпадут со значениями массива.

`flags`

  Одна из констант `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` или `PGSQL_DML_STRING`, либо их комбинация. Если `flags` содержит `PGSQL_DML_STRING`, функция вернёт строку. Если установлены `PGSQL_DML_NO_CONV` или `PGSQL_DML_ESCAPE`, то функция pg_convert() внутренне не вызывается.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Функция вернёт строку (string), если константа `PGSQL_DML_STRING` содержится в `flags`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.

### Примеры

Пример #1 Пример использования pg_update()

    <?php
      $db = pg_connect('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');

      // Это безопасно в некоторой степени, поскольку все значения экранируются.
      // Однако PostgreSQL поддерживает JSON/массив. Для этих значений это не безопасно
      // ни с через экранирование, ни с помощью подготовленного запроса.
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Данные обновлены: $res\n";
      } else {
          echo "Должно быть переданы неверные данные\n";
      }
    ?>

### Смотрите также

- pg_convert() - Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Возвращает массив, содержащий версии клиента, протокола клиент-серверного взаимодействия и сервера (если доступно)

### Описание

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() возвращает массив, содержащий версии клиента, протокола клиент-серверного взаимодействия и сервера.

Для получения детальной информации о сервере используйте функцию pg_parameter_status().

### Список параметров

`connection`

  Экземпляр класса PgSql\Connection. Функция выберет соединение по умолчанию, если для параметра `connection` указали значение `null`. Соединение по умолчанию — последнее соединение, которое установила функция pg_connect() или pg_pconnect().

  Внимание

  Начиная с PHP 8.1.0 выбор функцией соединения по умолчанию устарел.

### Возвращаемые значения

Возвращает массив с ключами `client`, `protocol` и `server` и соответствующими значениями версий.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `connection` теперь принимает объект PgSql\Connection; раньше параметр принимал тип resource.
8.0.0 | `connection` теперь допускает значение null.

### Примеры

Пример #1 Пример использования pg_version()

    <?php
      $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
         or die("Could not connect");

      $v = pg_version($dbconn);

      echo $v['client'];
    ?>

Результат выполнения приведённого примера:

    7.4

### Смотрите также

- pg_parameter_status() - Просмотр текущих значений параметров сервера

## Содержание

- pg_affected_rows — Возвращает количество затронутых запросом записей (кортежей)
- pg_cancel_query — Остановка асинхронного запроса.
- pg_change_password — Изменяет пароль пользователя PostgreSQL
- pg_client_encoding — Получение кодировки клиента.
- pg_close — Закрывает соединение с базой данных PostgreSQL
- pg_connect — Открывает соединение с базой данных PostgreSQL
- pg_connect_poll — Опросить статус попытки асинхронного соединения PostgreSQL.
- pg_connection_busy — Проверяет, занято ли соединение в данный момент.
- pg_connection_reset — Сброс подключения (переподключение)
- pg_connection_status — Определяет состояние подключения
- pg_consume_input — Читает вводные данные на соединении
- pg_convert — Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам
- pg_copy_from — Вставляет записи из массива в таблицу
- pg_copy_to — Копирует данные из таблицы в массив
- pg_dbname — Определяет имя базы данных
- pg_delete — Удаляет записи
- pg_end_copy — Синхронизирует с бэкендом PostgreSQL
- pg_escape_bytea — Экранирует спецсимволы в строке для вставки в поле типа bytea
- pg_escape_identifier — Экранирует идентификатор перед вставкой в текст SQL-инструкции
- pg_escape_literal — Экранировать литерал при вставке в текстовое поле
- pg_escape_string — Экранирование спецсимволов в строке запроса
- pg_execute — Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
- pg_fetch_all — Выбирает все данные из результата запроса и помещает их в массив
- pg_fetch_all_columns — Выбирает все записи из одной колонки результата запроса и помещает их в массив
- pg_fetch_array — Возвращает строку результата в виде массива
- pg_fetch_assoc — Выбирает строку результата запроса и помещает данные в ассоциативный массив
- pg_fetch_object — Выбирает строку результата запроса и возвращает данные в виде объекта
- pg_fetch_result — Возвращает запись из результата запроса
- pg_fetch_row — Выбирает строку результата запроса и помещает данные в массив
- pg_field_is_null — Проверяет поля на значение SQL NULL
- pg_field_name — Возвращает наименование поля
- pg_field_num — Возвращает порядковый номер именованного поля
- pg_field_prtlen — Возвращает количество печатаемых символов
- pg_field_size — Возвращает размер поля
- pg_field_table — Возвращает наименование или идентификатор таблицы, содержащей заданное поле
- pg_field_type — Возвращает имя типа заданного поля
- pg_field_type_oid — Возвращает идентификатор типа заданного поля
- pg_flush — Сбросить данные исходящего запроса на соединении
- pg_free_result — Очищает результат запроса и освобождает память
- pg_get_notify — Получение SQL NOTIFY сообщения
- pg_get_pid — Получает ID процесса сервера БД
- pg_get_result — Получает результат асинхронного запроса
- pg_host — Возвращает имя хоста, соответствующего подключению
- pg_insert — Заносит данные массива в таблицу базы данных
- pg_jit — Возвращает информацию о JIT сервера
- pg_last_error — Получает сообщение о последней произошедшей ошибке на соединении с базой данных
- pg_last_notice — Возвращает последнее уведомление от сервера PostgreSQL
- pg_last_oid — Возвращает OID последней добавленной в базу строки
- pg_lo_close — Закрывает большой объект
- pg_lo_create — Создаёт большой объект
- pg_lo_export — Вывод большого объекта в файл
- pg_lo_import — Импортирует большой объект из файла
- pg_lo_open — Открывает большой объект базы данных
- pg_lo_read — Читает данные большого объекта
- pg_lo_read_all — Читает содержимое большого объекта и посылает напрямую в браузер
- pg_lo_seek — Перемещает внутренний указатель большого объекта
- pg_lo_tell — Возвращает текущее положение внутреннего указателя большого объекта
- pg_lo_truncate — Обрезает большой объект
- pg_lo_unlink — Удаление большого объекта
- pg_lo_write — Записывает данные в большой объект
- pg_meta_data — Получение метаданных таблицы
- pg_num_fields — Возвращает количество полей в выборке
- pg_num_rows — Возвращает количество строк в выборке
- pg_options — Получение параметров соединения с сервером баз данных
- pg_parameter_status — Просмотр текущих значений параметров сервера
- pg_pconnect — Открывает постоянное соединение с сервером PostgreSQL
- pg_ping — Проверка соединения с базой данных
- pg_port — Возвращает номер порта, соответствующий заданному соединению
- pg_prepare — Отправляет на сервер запрос на подготовку SQL-запроса с параметрами-заполнителями и ждёт, пока завершится подготовка запроса
- pg_put_copy_data — Отправляет данные на сервер при выполнении операции COPY
- pg_put_copy_end — Сообщает серверу о завершении операции COPY
- pg_put_line — Передаёт на PostgreSQL сервер строку с завершающим нулём
- pg_query — Выполняет запрос
- pg_query_params — Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса
- pg_result_error — Возвращает сообщение об ошибке, связанное с запросом результата
- pg_result_error_field — Возвращает конкретное поле из отчёта об ошибках
- pg_result_memory_size — Возвращает объём памяти, выделенный для результата запроса
- pg_result_seek — Смещает указатель на строку выборки в экземпляре результата запроса
- pg_result_status — Возвращает статус результата запроса
- pg_select — Выбирает записи из базы данных
- pg_send_execute — Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата
- pg_send_prepare — Посылает запрос на создание параметризованного SQL-выражения, не дожидаясь его завершения
- pg_send_query — Отправляет асинхронный запрос
- pg_send_query_params — Посылает параметризованный запрос на сервер, не ожидает возвращаемого результата
- pg_set_chunked_rows_size — Устанавливает для подключения режим, в котором результаты запроса извлекаются частями
- pg_set_client_encoding — Устанавливает клиентскую кодировку
- pg_set_error_context_visibility — Определяет видимость сообщений об ошибках контекста, возвращаемых функциями pg_last_error и pg_result_error
- pg_set_error_verbosity — Определяет объем текста сообщений, возвращаемых функциями pg_last_error и pg_result_error
- pg_socket — Получить дескриптор только для чтения на сокет, лежащего в основе соединения PostgreSQL
- pg_socket_poll — Проверяет, готов ли сокет PostgreSQL-соединения к чтению или записи
- pg_trace — Включает трассировку подключения PostgreSQL
- pg_transaction_status — Возвращает текущее состояние транзакции на сервере
- pg_tty — Возвращает имя терминала TTY, связанное с соединением
- pg_unescape_bytea — Убирает экранирование двоичных данных типа bytea
- pg_untrace — Отключает трассировку соединения с PostgreSQL
- pg_update — Обновление данных в таблице
- pg_version — Возвращает массив, содержащий версии клиента, протокола клиент-серверного взаимодействия и сервера (если доступно)

# Класс PgSql\Connection

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `pgsql link` в PHP 8.1.0.

## Обзор класса

namespace PgSql;
final class Connection {
}

# Класс PgSql\Result

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `pgsql result` в PHP 8.1.0.

## Обзор класса

namespace PgSql;
final class Result {
}

# Класс PgSql\Lob

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `pgsql large object` в PHP 8.1.0.

## Обзор класса

namespace PgSql;
final class Lob {
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Примеры
  - Основы взаимодействия с БД PostgreSQL
  - Пользовательские функции взаимодействия с БД PostgreSQL
- Функции PostgreSQL
  - pg_affected_rows — Возвращает количество затронутых запросом записей (кортежей)
  - pg_cancel_query — Остановка асинхронного запроса.
  - pg_change_password — Изменяет пароль пользователя PostgreSQL
  - pg_client_encoding — Получение кодировки клиента.
  - pg_close — Закрывает соединение с базой данных PostgreSQL
  - pg_connect — Открывает соединение с базой данных PostgreSQL
  - pg_connect_poll — Опросить статус попытки асинхронного соединения PostgreSQL.
  - pg_connection_busy — Проверяет, занято ли соединение в данный момент.
  - pg_connection_reset — Сброс подключения (переподключение)
  - pg_connection_status — Определяет состояние подключения
  - pg_consume_input — Читает вводные данные на соединении
  - pg_convert — Преобразовывает значения ассоциативного массива в вид, который соответствует SQL-запросам
  - pg_copy_from — Вставляет записи из массива в таблицу
  - pg_copy_to — Копирует данные из таблицы в массив
  - pg_dbname — Определяет имя базы данных
  - pg_delete — Удаляет записи
  - pg_end_copy — Синхронизирует с бэкендом PostgreSQL
  - pg_escape_bytea — Экранирует спецсимволы в строке для вставки в поле типа bytea
  - pg_escape_identifier — Экранирует идентификатор перед вставкой в текст SQL-инструкции
  - pg_escape_literal — Экранировать литерал при вставке в текстовое поле
  - pg_escape_string — Экранирование спецсимволов в строке запроса
  - pg_execute — Запускает выполнение ранее подготовленного параметризованного запроса и ждёт результат
  - pg_fetch_all — Выбирает все данные из результата запроса и помещает их в массив
  - pg_fetch_all_columns — Выбирает все записи из одной колонки результата запроса и помещает их в массив
  - pg_fetch_array — Возвращает строку результата в виде массива
  - pg_fetch_assoc — Выбирает строку результата запроса и помещает данные в ассоциативный массив
  - pg_fetch_object — Выбирает строку результата запроса и возвращает данные в виде объекта
  - pg_fetch_result — Возвращает запись из результата запроса
  - pg_fetch_row — Выбирает строку результата запроса и помещает данные в массив
  - pg_field_is_null — Проверяет поля на значение SQL NULL
  - pg_field_name — Возвращает наименование поля
  - pg_field_num — Возвращает порядковый номер именованного поля
  - pg_field_prtlen — Возвращает количество печатаемых символов
  - pg_field_size — Возвращает размер поля
  - pg_field_table — Возвращает наименование или идентификатор таблицы, содержащей заданное поле
  - pg_field_type — Возвращает имя типа заданного поля
  - pg_field_type_oid — Возвращает идентификатор типа заданного поля
  - pg_flush — Сбросить данные исходящего запроса на соединении
  - pg_free_result — Очищает результат запроса и освобождает память
  - pg_get_notify — Получение SQL NOTIFY сообщения
  - pg_get_pid — Получает ID процесса сервера БД
  - pg_get_result — Получает результат асинхронного запроса
  - pg_host — Возвращает имя хоста, соответствующего подключению
  - pg_insert — Заносит данные массива в таблицу базы данных
  - pg_jit — Возвращает информацию о JIT сервера
  - pg_last_error — Получает сообщение о последней произошедшей ошибке на соединении с базой данных
  - pg_last_notice — Возвращает последнее уведомление от сервера PostgreSQL
  - pg_last_oid — Возвращает OID последней добавленной в базу строки
  - pg_lo_close — Закрывает большой объект
  - pg_lo_create — Создаёт большой объект
  - pg_lo_export — Вывод большого объекта в файл
  - pg_lo_import — Импортирует большой объект из файла
  - pg_lo_open — Открывает большой объект базы данных
  - pg_lo_read — Читает данные большого объекта
  - pg_lo_read_all — Читает содержимое большого объекта и посылает напрямую в браузер
  - pg_lo_seek — Перемещает внутренний указатель большого объекта
  - pg_lo_tell — Возвращает текущее положение внутреннего указателя большого объекта
  - pg_lo_truncate — Обрезает большой объект
  - pg_lo_unlink — Удаление большого объекта
  - pg_lo_write — Записывает данные в большой объект
  - pg_meta_data — Получение метаданных таблицы
  - pg_num_fields — Возвращает количество полей в выборке
  - pg_num_rows — Возвращает количество строк в выборке
  - pg_options — Получение параметров соединения с сервером баз данных
  - pg_parameter_status — Просмотр текущих значений параметров сервера
  - pg_pconnect — Открывает постоянное соединение с сервером PostgreSQL
  - pg_ping — Проверка соединения с базой данных
  - pg_port — Возвращает номер порта, соответствующий заданному соединению
  - pg_prepare — Отправляет на сервер запрос на подготовку SQL-запроса с параметрами-заполнителями и ждёт, пока завершится подготовка запроса
  - pg_put_copy_data — Отправляет данные на сервер при выполнении операции COPY
  - pg_put_copy_end — Сообщает серверу о завершении операции COPY
  - pg_put_line — Передаёт на PostgreSQL сервер строку с завершающим нулём
  - pg_query — Выполняет запрос
  - pg_query_params — Посылает параметризованный запрос на сервер, параметры передаются отдельно от текста SQL запроса
  - pg_result_error — Возвращает сообщение об ошибке, связанное с запросом результата
  - pg_result_error_field — Возвращает конкретное поле из отчёта об ошибках
  - pg_result_memory_size — Возвращает объём памяти, выделенный для результата запроса
  - pg_result_seek — Смещает указатель на строку выборки в экземпляре результата запроса
  - pg_result_status — Возвращает статус результата запроса
  - pg_select — Выбирает записи из базы данных
  - pg_send_execute — Запускает предварительно подготовленный SQL-запрос и передаёт ему параметры; не ожидает возвращаемого результата
  - pg_send_prepare — Посылает запрос на создание параметризованного SQL-выражения, не дожидаясь его завершения
  - pg_send_query — Отправляет асинхронный запрос
  - pg_send_query_params — Посылает параметризованный запрос на сервер, не ожидает возвращаемого результата
  - pg_set_chunked_rows_size — Устанавливает для подключения режим, в котором результаты запроса извлекаются частями
  - pg_set_client_encoding — Устанавливает клиентскую кодировку
  - pg_set_error_context_visibility — Определяет видимость сообщений об ошибках контекста, возвращаемых функциями pg_last_error и pg_result_error
  - pg_set_error_verbosity — Определяет объем текста сообщений, возвращаемых функциями pg_last_error и pg_result_error
  - pg_socket — Получить дескриптор только для чтения на сокет, лежащего в основе соединения PostgreSQL
  - pg_socket_poll — Проверяет, готов ли сокет PostgreSQL-соединения к чтению или записи
  - pg_trace — Включает трассировку подключения PostgreSQL
  - pg_transaction_status — Возвращает текущее состояние транзакции на сервере
  - pg_tty — Возвращает имя терминала TTY, связанное с соединением
  - pg_unescape_bytea — Убирает экранирование двоичных данных типа bytea
  - pg_untrace — Отключает трассировку соединения с PostgreSQL
  - pg_update — Обновление данных в таблице
  - pg_version — Возвращает массив, содержащий версии клиента, протокола клиент-серверного взаимодействия и сервера (если доступно)
- PgSql\Connection — Класс PgSql\Connection
- PgSql\Result — Класс PgSql\Result
- PgSql\Lob — Класс PgSql\Lob

# SQLite3

# Введение

Обеспечение поддержки баз данных SQLite версии 3.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Начиная с PHP 7.4.0 требуется библиотека » libsqlite версии 3.7.4 или новее. Ранее встроенный из коробки libsqlite мог использовался вместо этого.

## Установка

Модуль SQLite3 доступен по умолчанию. Модуль можно отключить помощью `--without-sqlite3` во время компиляции.

Пользователи Windows должны включить поддержку php_sqlite3.dll для того, чтобы использовать модуль. Этот DLL входит в состав Windows-дистрибутивов PHP начиная с версии PHP 5.3.0.

> Замечание: Дополнительная настройка на Windows с PHP 7.4.0

> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libsqlite3.dll.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки SQLite3
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | Доступно, начиная с PHP 7.2.17 и 7.3.4 для libsqlite ≥ 3.26.0. До PHP 8.2.0 этот параметр можно было изменить только как `INI_SYSTEM`.

Краткое разъяснение конфигурационных директив.

`sqlite3.extension_dir` string

  Путь к каталогу, в котором находятся файлы модуля SQLite.

`sqlite3.defensive` bool

  Если установлен флаг defensive, языковые конструкции, которые позволяют обычному SQL-запросу преднамеренно повреждать файл базы данных, отключены. Запрещается запись непосредственно в схему, в теневые таблицы (т.е. таблицы данных FTS) или виртуальную таблицу sqlite_dbpage. Эта настройка php.ini работает только с libsqlite ≥ 3.26.0.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`SQLITE3_ASSOC` (int)
  Указывает на то, что Sqlite3Result::fetchArray() метод должен вернуть массив, индексированный по имени столбца в соответствующий набор результатов.
`SQLITE3_NUM` (int)
  Указывает на то, что Sqlite3Result::fetchArray() метод должен вернуть массив, индексированный по номеру столбца в соответствующий набор результатов, начиная со столбца 0.
`SQLITE3_BOTH` (int)
  Указывает на то, что Sqlite3Result::fetchArray() метод должен вернуть массив, индексированный по имени столбца и его номеру в соответствующий набор результатов, начиная со столбца 0.
`SQLITE3_INTEGER` (int)
  Представляет класс хранения типа SQLite3 INTEGER.
`SQLITE3_FLOAT` (int)
  Представляет класс хранения типа SQLite3 REAL (FLOAT).
`SQLITE3_TEXT` (int)
  Представляет класс хранения типа SQLite3 TEXT.
`SQLITE3_BLOB` (int)
  Представляет класс хранения типа SQLite3 BLOB.
`SQLITE3_NULL` (int)
  Представляет класс хранения типа SQLite3 NULL.
`SQLITE3_OPEN_READONLY` (int)
  Указывает на то, что база данных SQLite3 доступна только для чтения.
`SQLITE3_OPEN_READWRITE` (int)
  Указывает на то, что база данных SQLite3 доступна как для чтения, так и для записи.
`SQLITE3_OPEN_CREATE` (int)
  Указывает на то, что файл базы данных SQLite3 будет создан в том случае, если он ещё не существует.
`SQLITE3_DETERMINISTIC` (int)
  Указывает, что функция созданная SQLite3::sqliteCreateFunction() детерминирована. Т.е. она всегда возвращает одинаковый результат для для одинаковых входных данных в одном выражении SQL. (Доступно с PHP 7.1.4.)

# Класс SQLite3

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Класс взаимодействует с базами данных SQLite 3.

## Обзор класса

class SQLite3 {
/* Константы */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* Методы */
public function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function version(): array
}

## Предопределённые константы

`SQLite3::OK`

`SQLite3::DENY`

`SQLite3::IGNORE`

`SQLite3::CREATE_INDEX`

`SQLite3::CREATE_TABLE`

`SQLite3::CREATE_TEMP_INDEX`

`SQLite3::CREATE_TEMP_TABLE`

`SQLite3::CREATE_TEMP_TRIGGER`

`SQLite3::CREATE_TEMP_VIEW`

`SQLite3::CREATE_TRIGGER`

`SQLite3::CREATE_VIEW`

`SQLite3::DELETE`

`SQLite3::DROP_INDEX`

`SQLite3::DROP_TABLE`

`SQLite3::DROP_TEMP_INDEX`

`SQLite3::DROP_TEMP_TABLE`

`SQLite3::DROP_TEMP_TRIGGER`

`SQLite3::DROP_TEMP_VIEW`

`SQLite3::DROP_TRIGGER`

`SQLite3::DROP_VIEW`

`SQLite3::INSERT`

`SQLite3::PRAGMA`

`SQLite3::READ`

`SQLite3::SELECT`

`SQLite3::TRANSACTION`

`SQLite3::UPDATE`

`SQLite3::ATTACH`

`SQLite3::DETACH`

`SQLite3::ALTER_TABLE`

`SQLite3::REINDEX`

`SQLite3::ANALYZE`

`SQLite3::CREATE_VTABLE`

`SQLite3::DROP_VTABLE`

`SQLite3::FUNCTION`

`SQLite3::SAVEPOINT`

`SQLite3::COPY`

`SQLite3::RECURSIVE`

# SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — Резервное копирование одной базы данных в другую

### Описание

public function SQLite3::backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool

SQLite3::backup() копирует содержимое одной базы в другую, перезаписывая содержимое целевой базы. Это полезно как для создания резервных копий, так и для копирования in-memory баз в файл или из файла.

Подсказка

Начиная с SQLite 3.27.0 (07.02.2019), также можно использовать конструкцию `VACUUM INTO 'file.db';` для резервного копирования базы данных в новый файл.

### Список параметров

`destination`

  Соединение с базой, открытое с помощью SQLite3::open().

`sourceDatabase`

  Имя базы данных. Для главной базы `"main"`, для временной `"temp"`, или имя, заданное после ключевого слова `AS` в выражении `ATTACH` для присоединённых баз.

`destinationDatabase`

  Аналогично `sourceDatabase` но для `destinationDatabase`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Создание резервной копии существующей базы

    <?php
    // $conn is a connection to an already opened sqlite3 database

    $backup = new SQLite3('backup.sqlite');
    $conn->backup($backup);
    ?>

# SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — Установить обработчик "занято" на соединение

### Описание

public function SQLite3::busyTimeout(int `$milliseconds`): bool

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

### Список параметров

`milliseconds`

  Миллисекунды. Установка равным 0 или отрицательному значению приведёт к отключению уже установленного обработчика.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Получить количество строк, которые были изменены/удалены/вставлены последним запросом

### Описание

public function SQLite3::changes(): int

Возвращает количество строк, которые были изменены/удалены/вставлены последним SQL-запросом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество строк (int), которые были изменены/удалены/вставлены последним SQL-запросом.

### Примеры

Пример #1 Пример использования SQLite3::changes()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Количество изменённых строк: ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Закрыть соединение с базой данных

### Описание

public function SQLite3::close(): bool

Закрывает соединение с БД.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования SQLite3::close()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — Создаёт экземпляр объекта SQLite3 и открывает соединение с базой

### Описание

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

Создаёт экземпляр объекта SQLite3 и открывает соединение с базой. Если включили шифрование, то появляется возможность использовать ключ.

### Список параметров

`filename`

  Путь к SQLite базе или `:memory:`, для использования базы в оперативной памяти. Если `filename` задать как пустую строку, то будет создана приватная, временная база данных на диске. Эта база данных будет удалена сразу после закрытия соединения с ней.

`flags`

  Необязательные флаги, для определения типа открытия базы данных. По умолчанию, используется `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY`: Открыть только для чтения.

  - `SQLITE3_OPEN_READWRITE`: Открыть для чтения и записи.

  - `SQLITE3_OPEN_CREATE`: Создать новый файл базы данных, если он отсутствует

`encryptionKey`

  Необязательный ключ для шифрования/расшифровки базы данных. Если модуль шифрования не установлен, то данный параметр будет проигнорирован.

### Ошибки

Метод выбрасывает исключение Exception, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.0.10 | Параметр `filename` разрешается задавать пустой строкой, чтобы создать на диске приватную временную базу данных.

### Примеры

Пример #1 Пример использования метода SQLite3::__construct()

    <?php

    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());

    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — Зарегистрировать функцию PHP в качестве агрегирующей функции SQL

### Описание

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Регистрирует функцию PHP или пользовательскую функцию в качестве агрегирующей функции SQL для использования в запросах.

### Список параметров

`name`

  Имя агрегирующей функции SQL, которая должна быть создана или переопределена.

`stepCallback`

  Функция обратного вызова, которая будет вызвана для каждой строки результирующего набора. Ваша PHP-функция должна аккумулировать результат и хранить его в контексте агрегации.

  Эта функция должна быть определена следующим образом:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

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

  `rownumber`

    Номер текущей строки.

  `value`

    Первый аргумент переданный агрегатору.

  `values`

    Последующие аргументы.

  Возвращаемое значение функции будет использовано как параметр `context` при следующем запуске функции, либо как значение передаваемое финализирующей функции.
`finalCallback`

  Функция обратного вызова для вычисление итогового агрегированного значения. Она будет вызвана как только все строки результирующего набора будут обработаны, ей будет передан агрегирующий контекст и она вернёт финальное значение. Данная функция должна вернуть значение типа понятного SQLite (т.е. скалярный тип).

  Эта функция должна быть определена следующим образом:

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Содержит результат самого последнего вызова агрегирующей функции.

  `rownumber`

    Всегда `0`.

  Возвращаемое значение этой функции будет использовано как возвращаемое значение всего агрегатора.
`argCount`

  Количество аргументов, которое принимает функция агрегирования SQL. Если значение отрицательное, то функция может использовать любое количество аргументов.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример агрегирующей функции max_length

    <?php
    $data = array(
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
       );
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->bindValue(1, $str);
        $insert->execute();
    }
    $insert = null;

    function max_len_step($context, $rownumber, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $rownumber)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->querySingle('SELECT max_len(a) from strings'));
    ?>

Результат выполнения приведённого примера:

    int(5)

В этом примере мы написали агрегирующую функцию, которая вычисляет самой длинной строки в одной колонке таблицы. Для каждой строки вызывается функция `max_len_step` и ей передаётся параметр `$context`. Этот параметр ничем не отличается от обычной переменной PHP и спокойно может содержать массив или объект. В этом примере мы используем её для хранения максимальной найденной длины строки. Если `$string` будет иметь длину больше, чем текущая сохранённая, то значение контекста будет обновлено.

После того, как все строки обработаны, SQLite вызовет функцию `max_len_finalize`, для окончательной подготовки результата. Тут мы можем произвести необходимые расчёты на основе данных из `$context`. В нашем простом примере никакая постобработке не нужна и мы просто возвращаем полученное значение.

Подсказка

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

Подсказка

Для переопределения встроенных в SQLite агрегирующих функций вы можете использовать SQLite3::createAggregate().

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Регистрирует функцию PHP для использования в качестве функции сортировки SQL

### Описание

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

Регистрирует функцию PHP или пользовательскую функцию для использования в качестве функции сортировки в SQL-запросах.

### Список параметров

`name`

  Имя создаваемой или переопределяемой функции сортировки SQL

`callback`

  Имя PHP-функции или определяемой пользователем функции для применения в качестве callback, определяющей поведение параметров сортировки. Она должна принимать два значения и возвращаемый результат должен быть такой же, как у strcmp(), т.е. он должен возвращать -1, 1 или 0, если первая строка сортируется до, после или равной второй.

  Функция должна быть определена как:

  function collation(mixed `$value1`, mixed `$value2`): int

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования SQLite3::createCollation()

Регистрирует PHP-функцию strnatcmp() как последовательность сортировки в базе данных SQLite3.

    <?php

    $db = new SQLite3(":memory:");
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->createCollation('NATURAL_CMP', 'strnatcmp');

    $defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
    $naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

    echo "сортировка по умолчанию:\n";
    while ($row = $defaultSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    echo "\nсортировка natural order:\n";
    while ($row = $naturalSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    $db->close();

    ?>

Результат выполнения приведённого примера:

    default:
    a1
    a10
    a2

    natural:
    a1
    a2
    a10

### Смотрите также

- Документация по сопоставлению SQLite: » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Регистрирует функцию PHP для использования в качестве скалярной функции SQL

### Описание

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Регистрирует функцию PHP или пользовательскую функцию для использования в качестве скалярной функции SQL для использования в SQL-выражениях.

### Список параметров

`name`

  Имя создаваемой или переопределяемой функции SQL.

`callback`

  Имя функции PHP или пользовательской функции, применяемой в качестве callback, определяющей поведение функции SQL.

  Функция должна быть определена как:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Первый аргумент, передаваемый функции SQL.

  `values`

    Дополнительные аргументы, передаваемые функции SQL.

`argCount`

  Число аргументов, принимаемых функцией SQL. Если этот параметр равен `-1`, то функция SQL может принимать любое количество аргументов.

`flags`

  Побитовое объединение флагов. В настоящее время поддерживается только `SQLITE3_DETERMINISTIC`, который указывает, что функция всегда возвращает один и тот же результат, учитывая одни и те же входные данные внутри одного SQL-выражения.

### Возвращаемые значения

Возвращает `true` в случае успешного создания функции или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
7.1.4 | Добавлен параметр `flags`.

### Примеры

Пример #1 Пример использования SQLite3::createFunction()

    <?php

    function my_udf_md5($string)
    {
        return hash('md5', $string);
    }

    $db = new SQLite3('mysqlitedb.db');
    $db->createFunction('my_udf_md5', 'my_udf_md5');

    var_dump($db->querySingle('SELECT my_udf_md5("test")'));

    ?>

Вывод приведённого примера будет похож на:

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Включает генерацию исключений

### Описание

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Метод определяет, будет ли экземпляр SQLite3 выбрасывать исключения или предупреждения об ошибке.

### Список параметров

`enable`

  Когда передано значение `true`, экземпляр SQLite3 и экземпляры SQLite3Stmt и SQLite3Result, производные от него, будут выбрасывать исключения в случае возникновения ошибки.

  Когда передано значение `false`, экземпляр SQLite3 и экземпляры SQLite3Stmt и SQLite3Result, производные от него, будут генерировать предупреждения в случае возникновения ошибки.

  В любом случае, код ошибки и сообщение, если есть, будут доступны через методы SQLite3::lastErrorCode() и SQLite3::lastErrorMsg() соответственно.

### Возвращаемые значения

Метод возвращает старое значение; `true`, если исключения включены, иначе `false`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Метод SQLite3::enableExceptions() выдаст предупреждение уровня `E_DEPRECATED`, если при вызове метода значение параметра `enable` равно `false`.

### Примеры

Пример #1 Пример использования метода SQLite3::enableExceptions()

    <?php

    $sqlite = new SQLite3(':memory:');
    try {
        $sqlite->exec('create table foo');
        $sqlite->enableExceptions(true);
        $sqlite->exec('create table bar');
    } catch (Exception $e) {
        echo 'Поймано исключение: ' . $e->getMessage();
    }

    ?>

Вывод приведённого примера будет похож на:

    Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
    Поймано исключение: near "bar": syntax error

# SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — Возвращает правильно экранированную строку

### Описание

public static function SQLite3::escapeString(string `$string`): string

Возвращает правильно экранированную сроку для безопасного включения в SQL-инструкцию.

Внимание

Функция пока небезопасна для обработки данных в двоичной форме!

Для обработки полей типа BLOB, которые могут содержать символ NUL, вместо этой функции используйте SQLite3Stmt::bindParam().

### Список параметров

`string`

  Строка для обработки

### Возвращаемые значения

Возвращает правильно экранированную сроку, которая может быть безопасно использована в SQL-инструкции.

### Примечания

Внимание

addslashes() НЕ должен использоваться для экранирования ваших строк в запросах SQLite; это будет приводить к неожиданным результатам при извлечении ваших данных.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Выполняет запрос без результата к текущей базе данных

### Описание

public function SQLite3::exec(string `$query`): bool

Выполняет запрос без результата к текущей базе данных.

> Замечание: SQLite3, возможно, потребуется создать » временные файлы во время выполнения запросов, так что соответствующие директории должны быть доступны для записи.

### Список параметров

`query`

  Выполняемый запрос SQL (обычно запрос INSERT, UPDATE или DELETE).

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения запроса или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования SQLite3::exec()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE bar (bar TEXT)');
    ?>

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — Возвращает числовой код результата последнего неудачного запроса SQLite

### Описание

public function SQLite3::lastErrorCode(): int

Возвращает числовой код результата последнего неудачного запроса SQLite.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целочисленное значение, представляющее числовой код результата последнего неудачного запроса SQLite.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Возвращает текст на английском, описывающий последний неудачный запрос SQLite

### Описание

public function SQLite3::lastErrorMsg(): string

Возвращает текст на английском, описывающий последний неудачный запрос SQLite.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку на английском, описывающую самый последний неудачный запрос SQLite.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Возвращает идентификатор строки последней вставки (INSERT) в базу данных

### Описание

public function SQLite3::lastInsertRowID(): int

Возвращает идентификатор строки последней вставки (INSERT) в базу данных.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает идентификатор строки последней вставки (INSERT) в базу данных. Если при этом соединении с базой данных никогда не происходило успешных операций INSERT в таблицы rowid, то SQLite3::lastInsertRowID() возвращает `0`.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Попытаться загрузить библиотеку модуля SQLite

### Описание

public function SQLite3::loadExtension(string `$name`): bool

Попытаться загрузить библиотеку модуля SQLite.

### Список параметров

`name`

  Имя загружаемой библиотеки. Библиотека должна находиться в каталоге, указанном в конфигурационной опции sqlite3.extension_dir.

### Возвращаемые значения

Возвращает `true` в случае, если модуль успешно загружен или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования SQLite3::loadExtension()

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Открывает базу данных SQLite

### Описание

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Открывает базу данных SQLite 3. Если сборка включает шифрование, то она будет пробовать использовать ключ.

### Список параметров

`filename`

  Путь к БД SQLite или `:memory:` для использования БД в памяти.

`flags`

  Опциональные флаги используемые для определения, как открывать БД. По умолчанию `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE`.

  - `SQLITE3_OPEN_READONLY`: Открыть БД только для чтения.

  - `SQLITE3_OPEN_READWRITE`: Открыть БД для чтения и записи.

  - `SQLITE3_OPEN_CREATE`: Создать БД, если базы данных нет.

`encryptionKey`

  Опциональный ключ, для использования шифрования при работе с БД. Если модуль шифрования не установлен, то данная опция не будет использована.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования метода SQLite3::open()

    <?php

    /**
     * Простой пример расширения класса SQLite3 и изменения параметров конструктора.
     * После чего использование метода open для инициализации БД.
     */
    class MyDB extends SQLite3
    {
        function __construct()
        {
            $this->open('mysqlitedb.db');
        }
    }

    $db = new MyDB();

    $db->exec('CREATE TABLE foo (bar STRING)');
    $db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());

    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — Открывает ресурс потока для чтения BLOB

### Описание

public function SQLite3::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false

Открывает ресурс потока для чтения или записи BLOB, который будет выбран:

SELECT `column` FROM `database`.`table` WHERE rowid = `rowid`

> Замечание: Невозможно изменить размер BLOB путём записи в поток. Вместо этого необходимо выполнить запрос UPDATE, возможно, используя SQLite-функцию zeroblob(), чтобы задать желаемый размер BLOB.

### Список параметров

`table`

  Название таблицы.

`column`

  Название столбца.

`rowid`

  Идентификатор строки.

`database`

  Символическое название базы данных

`flags`

  Либо `SQLITE3_OPEN_READONLY`, либо `SQLITE3_OPEN_READWRITE`, чтобы открыть поток только для чтения или для чтения и записи, соответственно.

### Возвращаемые значения

Возвращает ресурс потока или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Добавлен параметр `flags`, позволяющий записать BLOB; ранее поддерживалось только чтение.

### Примеры

Пример #1 Пример использования SQLite3::openBlob()

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
    $stream = $conn->openBlob('test', 'text', 1);
    echo stream_get_contents($stream);
    fclose($stream); // обязательно, иначе на следующей строке произойдёт ошибка
    $conn->close();
    ?>

Результат выполнения приведённого примера:

    Lorem ipsum

Пример #2 Пошаговая запись BLOB

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES (zeroblob(36))");
    $stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
    for ($i = 0; $i < 3; $i++) {
        fwrite($stream,  "Lorem ipsum\n");
    }
    fclose($stream);
    echo $conn->querySingle("SELECT text FROM test");
    $conn->close();
    ?>

Результат выполнения приведённого примера:

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Подготавливает SQL-запрос для выполнения

### Описание

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Подготавливает SQL-запрос для выполнения и возвращает объект SQLite3Stmt.

### Список параметров

`query`

  SQL-запрос на подготовку.

### Возвращаемые значения

Возвращает объект SQLite3Stmt в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования SQLite3::prepare()

    <?php
    unlink('mysqlitedb.db');
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'Тестовое значение')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray());
    ?>

### Смотрите также

- SQLite3Stmt::paramCount() - Возвращает количество параметров в подготовленном запросе
- SQLite3Stmt::bindValue() - Связывает значение параметра с переменной подготовленного запроса
- SQLite3Stmt::bindParam() - Связывает параметр с переменной подготовленного запроса

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — Выполняет SQL-запрос

### Описание

public function SQLite3::query(string `$query`): SQLite3Result|false

Выполняет SQL-запрос и возвращает объект SQLite3Result. Если запрос не возвращает результат (например, запрос типа DLM), то возвращённый объект SQLite3Result бесполезен. Для подобных запросов используйте метод SQLite3::exec().

### Список параметров

`query`

  SQL-запрос для выполнения.

### Возвращаемые значения

Возвращает объект SQLite3Result или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования SQLite3::query()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $results = $db->query('SELECT bar FROM foo');
    while ($row = $results->fetchArray()) {
        var_dump($row);
    }
    ?>

# SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — Выполняет запрос и возвращает одиночный результат

### Описание

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Выполняет запрос и возвращает одиночный результат.

### Список параметров

`query`

  SQL запрос для выполнения.

`entireRow`

  По умолчанию, функция querySingle() возвращает значение первого столбца, возвращаемого запросом. Если параметр `entireRow` является `true`, то запрос возвращает массив всего первого ряда.

### Возвращаемые значения

Возвращает значение первого столбца результатов или массив всей первой строки (если параметр `entireRow` является `true`).

Если запрос корректный, но результат пуст, то вернётся `null`, если параметр `entireRow` является `false`, в противном случае возвращается пустой массив.

Неверный или отсутствующий запрос возвращает `false`.

### Примеры

Пример #1 Пример использования SQLite3::querySingle()

    <?php
    $db = new SQLite3('mysqlitedb.db');

    var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
    print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
    ?>

Вывод приведённого примера будет похож на:

    string(5) "Scott"
    Array
    (
        [username] => Scott
        [email] => scott@example.com
    )

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — Устанавливает callback-функцию, которая будет использоваться в качестве авторизатора для ограничения действий выражения

### Описание

public function SQLite3::setAuthorizer(?callable `$callback`): bool

Устанавливает callback-функцию, которая будет вызываться SQLite каждый раз при выполнении действия (чтение, удаление, модификация и т.д.). Это используется при подготовке SQL-выражения из ненадёжного источника, чтобы гарантировать, что SQL-выражения не будут пытаться получить доступ к данным, которые им не разрешено видеть, или чтобы они не пытались выполнить вредоносные выражения, которые повреждают базу данных. Например, приложение может позволить пользователю вводить произвольные SQL-запросы для выполнения в базе данных. Но приложение не хочет, чтобы пользователь мог вносить произвольные изменения в базу данных. Тогда можно установить авторизатор, который запрещает использование любых выражений, кроме SELECT, пока готовится введённый пользователем SQL-запрос.

Callback-авторизатор может бывать вызван несколько раз для каждого выражения, подготовленного SQLite. Запросы `SELECT` или `UPDATE` будут вызывать авторизатор для каждой считываемой или модифицируемой колонки.

При вызове авторизатора может использоваться до пяти параметров. Первый параметр передаётся всегда, его тип - целое число (int) (код действия), совпадающий с константой `SQLite3`. Другие параметры передаются только для некоторых действий. Данная таблица описывает второй и третий параметры в соответствии с действием:

Список кодов действия и параметров
Действие | Второй параметр | Третий параметр
--- | --- | ---
`SQLite3::CREATE_INDEX` | Имя индекса | Имя таблицы
`SQLite3::CREATE_TABLE` | Имя таблицы | `null`
`SQLite3::CREATE_TEMP_INDEX` | Имя индекса | Имя таблицы
`SQLite3::CREATE_TEMP_TABLE` | Имя таблицы | `null`
`SQLite3::CREATE_TEMP_TRIGGER` | Имя триггера | Имя таблицы
`SQLite3::CREATE_TEMP_VIEW` | Имя представления | `null`
`SQLite3::CREATE_TRIGGER` | Имя триггера | Имя таблицы
`SQLite3::CREATE_VIEW` | Имя представления | `null`
`SQLite3::DELETE` | Имя таблицы | `null`
`SQLite3::DROP_INDEX` | Имя индекса | Имя таблицы
`SQLite3::DROP_TABLE` | Имя таблицы | `null`
`SQLite3::DROP_TEMP_INDEX` | Имя индекса | Имя таблицы
`SQLite3::DROP_TEMP_TABLE` | Имя таблицы | `null`
`SQLite3::DROP_TEMP_TRIGGER` | Имя триггера | Имя таблицы
`SQLite3::DROP_TEMP_VIEW` | Имя представления | `null`
`SQLite3::DROP_TRIGGER` | Имя триггера | Имя таблицы
`SQLite3::DROP_VIEW` | Имя представления | `null`
`SQLite3::INSERT` | Имя таблицы | `null`
`SQLite3::PRAGMA` | Имя pragma | Первый аргумент, переданный pragma, или `null`
`SQLite3::READ` | Имя таблицы | Имя колонки
`SQLite3::SELECT` | `null` | `null`
`SQLite3::TRANSACTION` | Операция | `null`
`SQLite3::UPDATE` | Имя таблицы | Имя колонки
`SQLite3::ATTACH` | Имя файла | `null`
`SQLite3::DETACH` | Имя базы данных | `null`
`SQLite3::ALTER_TABLE` | Имя базы данных | Имя таблицы
`SQLite3::REINDEX` | Имя индекса | `null`
`SQLite3::ANALYZE` | Имя таблицы | `null`
`SQLite3::CREATE_VTABLE` | Имя таблицы | Имя модуля
`SQLite3::DROP_VTABLE` | Имя таблицы | Имя модуля
`SQLite3::FUNCTION` | `null` | Имя функции
`SQLite3::SAVEPOINT` | Операция | Имя точки сохранения
`SQLite3::RECURSIVE` | `null` | `null`

Четвёртым параметром будет имя базы данных (`"main"`, `"temp"` и т.д.), если необходимо.

Пятый параметр callback-авторизатора - имя самого внутреннего триггера или представления, ответственного за попытку получения доступа, или `null`, если эта попытка получения доступа произведена напрямую из кода SQL верхнего уровня.

Когда callback-функция возвращает `SQLite3::OK`, это значит, что запрошенная операция принята. Когда callback-функция возвращает `SQLite3::DENY`, вызов, запустивший авторизатор, потерпит неудачу с сообщением об ошибке, объясняющим, что доступ запрещён.

Если код действия - `SQLite3::READ`, и callback-функция возвращает `SQLite3::IGNORE`, то подготовленное выражение составляется для замены на `null` значения колонки таблицы, которое бы считывалось, если бы вернулся код `SQLite3::OK`. Возврат `SQLite3::IGNORE` может использоваться, чтобы запретить недоверенному пользователю доступ к отдельным колонкам таблицы.

Когда на таблицу ссылаются через `SELECT`, но из неё не извлекается ни одного значения колонок, (например, в запросе `"SELECT count(*) FROM table"`), то callback-авторизатор `SQLite3::READ` вызывается один раз для этой таблицы с именем колонки, которое равно пустой строке.

Если код действия - `SQLite3::DELETE`, и callback-функция возвращает `SQLite3::IGNORE`, тогда операция DELETE продолжает свою работу, но с выключенной оптимизацией удаления, и все строки удаляются по отдельности.

В соединении с базой данных одновременно может использоваться только один авторизатор. Каждый вызов SQLite3::setAuthorizer() перезаписывает предыдущий. Отключить авторизатор можно, передав `null` вместо callback-функции. По умолчанию авторизатор выключен.

Callback-авторизатор не должен делать ничего, что изменяет подключение к базе данных, которое вызвало callback-авторизатор.

Заметьте, что авторизатор вызывается только тогда, когда выражение подготавливается, а не тогда, когда оно исполняется.

Более подробную информацию можно найти в » Документации SQLite3.

### Список параметров

`callback`

  Функция callable для вызова.

  Если передан `null`, то текущий callback-авторизатор будет отключён.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Этот метод не вызывает никаких ошибок, но если авторизатор включён и возвращает некорректное значение, то при подготовке выражения будет вызвана ошибка (или выброшено исключение, в зависимости от использования метода SQLite3::enableExceptions()).

### Примеры

Пример #1 Пример использования SQLite3::setAuthorizer()

В данном примере разрешён доступ только для чтения, и только некоторые из колонок таблицы `users` будут возвращены. Остальные колонки будут заменены на `null`.

    <?php
    $db = new SQLite3('data.sqlite');
    $db->exec('CREATE TABLE users (id, name, password);');
    $db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

    $allowed_columns = ['id', 'name'];

    $db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
        if ($action === SQLite3::READ) {
            list($table, $column) = $args;

            if ($table === 'users' && in_array($column, $allowed_columns)) {
                return SQLite3::OK;
            }

            return SQLite3::IGNORE;
        }

        return SQLite3::DENY;
    });

    print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

Результат выполнения приведённого примера:

    Array
    (
        [id] => 1
        [name] => Pauline
        [password] =>
    )

# SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — Возвращает версию библиотеки SQLite3, содержит как строковую константу, так и числовую

### Описание

public static function SQLite3::version(): array

Возвращает версию библиотеки SQLite3, содержит как строковую константу, так и числовую.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив с ключами "versionString" и "versionNumber".

### Примеры

Пример #1 Пример использования SQLite3::version()

    <?php
    print_r(SQLite3::version());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## Содержание

- SQLite3::backup — Резервное копирование одной базы данных в другую
- SQLite3::busyTimeout — Установить обработчик "занято" на соединение
- SQLite3::changes — Получить количество строк, которые были изменены/удалены/вставлены последним запросом
- SQLite3::close — Закрыть соединение с базой данных
- SQLite3::__construct — Создаёт экземпляр объекта SQLite3 и открывает соединение с базой
- SQLite3::createAggregate — Зарегистрировать функцию PHP в качестве агрегирующей функции SQL
- SQLite3::createCollation — Регистрирует функцию PHP для использования в качестве функции сортировки SQL
- SQLite3::createFunction — Регистрирует функцию PHP для использования в качестве скалярной функции SQL
- SQLite3::enableExceptions — Включает генерацию исключений
- SQLite3::escapeString — Возвращает правильно экранированную строку
- SQLite3::exec — Выполняет запрос без результата к текущей базе данных
- SQLite3::lastErrorCode — Возвращает числовой код результата последнего неудачного запроса SQLite
- SQLite3::lastErrorMsg — Возвращает текст на английском, описывающий последний неудачный запрос SQLite
- SQLite3::lastInsertRowID — Возвращает идентификатор строки последней вставки (INSERT) в базу данных
- SQLite3::loadExtension — Попытаться загрузить библиотеку модуля SQLite
- SQLite3::open — Открывает базу данных SQLite
- SQLite3::openBlob — Открывает ресурс потока для чтения BLOB
- SQLite3::prepare — Подготавливает SQL-запрос для выполнения
- SQLite3::query — Выполняет SQL-запрос
- SQLite3::querySingle — Выполняет запрос и возвращает одиночный результат
- SQLite3::setAuthorizer — Устанавливает callback-функцию, которая будет использоваться в качестве авторизатора для ограничения действий выражения
- SQLite3::version — Возвращает версию библиотеки SQLite3, содержит как строковую константу, так и числовую

# Класс SQLite3Exception

(PHP 8 >= 8.3.0)

## Введение

Представляет собой исключение, специфичное для SQLite3.

## Обзор класса

class SQLite3Exception extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс SQLite3Stmt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Класс, предоставляющий доступ к подготовленным запросам в модуле SQLite 3.

## Обзор класса

class SQLite3Stmt {
/* Методы */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — Связывает параметр с переменной подготовленного запроса

### Описание

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Связывает параметр с переменной подготовленного запроса.

Предостережение

До PHP 7.2.14 и 7.3.0, SQLite3Stmt::reset() должен вызываться до первого вызова SQLite3Stmt::execute(), если надо, чтобы связанное значение корректно обновлялось при последующих вызовах SQLite3Stmt::execute(). Если метод SQLite3Stmt::reset() не вызывался, то связанное значение не будет изменяться, даже если значение, присвоенное переменной, переданной SQLite3Stmt::bindParam(), изменилось или снова был вызван метод SQLite3Stmt::bindParam().

### Список параметров

`param`
  Либо строка (string) (для именованных параметров), либо целое число (int) (для положительных параметров), идентифицирующая переменную подготовленного запроса, к которому должно быть привязано значение. Если именованный параметр не начинается с двоеточия ((`:`)) или знака `@`, автоматически добавляется двоеточие (`:`). Положительные параметры начинаются с 1.
`var`

  Параметр для привязки к переменной подготовленного запроса.

`type`

  Тип данных параметра для привязки.

  - `SQLITE3_INTEGER`: Значение является целым числом со знаком, которое хранится в 1, 2, 3, 4, 6 или 8 байт в зависимости от величины значения.

  - `SQLITE3_FLOAT`: Значение является числом с плавающей точкой, которое хранится в виде 8-байтного числа IEEE с плавающей точкой.

  - `SQLITE3_TEXT`: Значение является текстовой строкой, которое хранится в кодировке базы данных (UTF-8, UTF-16BE или UTF-16-LE).

  - `SQLITE3_BLOB`: Значение является большим двоичным объектом (blob) данных, который хранится точно так же, как и входные данные.

  - `SQLITE3_NULL`: Значение является NULL-значением.

  В PHP 7.0.7, если `type` опущен, то он автоматически определяется из типа `var`: bool и int рассматриваются как `SQLITE3_INTEGER`, float как `SQLITE3_FLOAT`, null как `SQLITE3_NULL` и все остальные как `SQLITE3_TEXT`. Раньше, если тип опущен, то по умолчанию использовался `SQLITE3_TEXT`.

  > Замечание:

  > Если `var` равен `null`, он всегда обрабатывается как `SQLITE3_NULL`, независимо от заданного `type`.

### Возвращаемые значения

Возвращает `true`, если параметр привязан к переменной подготовленного запроса, `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Параметр `param` теперь поддерживает нотацию `@param`.

### Примеры

Пример #1 Пример использования SQLite3Stmt::bindParam()

В примере показано, как один подготовленный запрос с привязкой одного параметра может использоваться для вставки нескольких строк с различными значениями.

    <?php
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE foo (bar TEXT)");

    $stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
    $stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

    $bar = 'baz';
    $stmt->execute();

    $bar = 42;
    $stmt->execute();

    $res = $db->query("SELECT * FROM foo");
    while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
        var_dump($row);
    }
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### Смотрите также

- SQLite3Stmt::bindValue() - Связывает значение параметра с переменной подготовленного запроса
- SQLite3::prepare() - Подготавливает SQL-запрос для выполнения

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Связывает значение параметра с переменной подготовленного запроса

### Описание

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Связывает значение параметра с переменной подготовленного запроса.

Предостережение

До PHP 7.2.14 и 7.3.0, если выполнен запрос, необходимо вызвать метод SQLite3Stmt::reset() для того, чтобы можно было поменять значения связанных параметров.

### Список параметров

`param`
  Либо строка (string) (для именованных параметров), либо целое число (int) (для положительных параметров), идентифицирующая переменную подготовленного запроса, к которому должно быть привязано значение. Если именованный параметр не начинается с двоеточия ((`:`)) или знака `@`, автоматически добавляется двоеточие (`:`). Положительные параметры начинаются с 1.
`value`

  Значение для привязки к переменной подготовленного запроса.

`type`

  Тип данных значения для привязки.

  - `SQLITE3_INTEGER`: Значение является целым числом со знаком, которое хранится в 1, 2, 3, 4, 6 или 8 байт в зависимости от величины значения.

  - `SQLITE3_FLOAT`: Значение является числом с плавающей точкой, которое хранится в виде 8-байтного числа IEEE с плавающей точкой.

  - `SQLITE3_TEXT`: Значение является текстовой строкой, которое хранится в кодировке базы данных (UTF-8, UTF-16BE или UTF-16-LE).

  - `SQLITE3_BLOB`: Значение является большим двоичным объектом (blob) данных, который хранится точно так же, как и входные данные.

  - `SQLITE3_NULL`: Значение является NULL-значением.

  В PHP 7.0.7, если `type` опущен, то он автоматически определяется из типа `param`: bool и int рассматриваются как `SQLITE3_INTEGER`, float как `SQLITE3_FLOAT`, null как `SQLITE3_NULL` и всех остальных как `SQLITE3_TEXT`. Раньше, если тип опущен, он по умолчанию использовался `SQLITE3_TEXT`.

  > Замечание:

  > Если `param` равен `null`, он всегда обрабатывается как `SQLITE3_NULL`, независимо от заданного `type`.

### Возвращаемые значения

Возвращает `true`, если параметр привязан к переменной подготовленного запроса или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | Параметр `param` теперь поддерживает нотацию `@param`.

### Примеры

Пример #1 Пример использования SQLite3Stmt::bindValue()

    <?php
    $db = new SQLite3(':memory:');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray(SQLITE3_ASSOC));
    ?>

Результат выполнения приведённого примера:

    array(1) {
      ["bar"]=>
      string(14) "This is a test"
    }

### Смотрите также

- SQLite3Stmt::bindParam() - Связывает параметр с переменной подготовленного запроса
- SQLite3::prepare() - Подготавливает SQL-запрос для выполнения

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Удаляет все текущие привязанные параметры

### Описание

public function SQLite3Stmt::clear(): bool

Удаляет все текущие привязанные параметры (устанавливает их на значение `null`).

Предостережение

Метод необходимо использовать с SQLite3Stmt::reset(). Если используется один, любой вызов SQLite3Stmt::bindValue() или SQLite3Stmt::bindParam() не будет иметь никакого эффекта, и все привязанные параметры будут иметь значение `null`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` в случае успешной очистки привязанных параметров и `false` в случае возникновения ошибки.

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — Закрывает подготовленный запрос

### Описание

public function SQLite3Stmt::close(): true

Закрывает подготовленный запрос.

> Замечание: Обратите внимание, что все объекты SQLite3Result, полученные при выполнении этого подготовленного запроса будут признаны недействительными при закрытии этого запроса.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает ошибку Error, если вызывается на неинициализированном объекте.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Метод теперь выбрасывает ошибку Error, если объект неправильно инициализирован; ранее возвращалось значение `false`.

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — Конструктор класса SQLite3Stmt

### Описание

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

Экземпляры SQLite3Stmt создаются с помощью SQLite3::prepare().

### Список параметров

`sqlite3`

`query`

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — Выполняет подготовленный запрос и возвращает объект с результирующим набором

### Описание

public function SQLite3Stmt::execute(): SQLite3Result|false

Выполняет подготовленный запрос и возвращает объект с результирующим набором.

Предостережение

Объекты результирующего набора, полученные при вызове этого метода для одного и того же объекта подготовленного запроса, не являются независимыми, а используют одну и ту же базовую структуру. Поэтому рекомендуется вызвать SQLite3Result::finalize(), прежде чем вызывать SQLite3Stmt::execute() на том же объекте подготовленного запроса снова.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект SQLite3Result в случае успешного выполнения подготовленного запроса и `false` в случае возникновения ошибки.

### Смотрите также

- SQLite3::prepare() - Подготавливает SQL-запрос для выполнения
- SQLite3Stmt::bindValue() - Связывает значение параметра с переменной подготовленного запроса
- SQLite3Stmt::bindParam() - Связывает параметр с переменной подготовленного запроса

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — Получить SQL-запрос в виде строки из запроса

### Описание

public function SQLite3Stmt::getSQL(bool `$expand` = `false`): string|false

Возвращает строковое представление SQL-запроса для подготовленного запроса. Если параметр `expand` задан как `false`, будет возвращён не модифицированный SQL. Если же `expand` задан как `true`, все подставляемые параметры запроса будут заменены на конкретные значения, либо на `NULL`, если значения ещё не были привязаны.

### Список параметров

`expand`

  Заменять ли в возвращаемом SQL-запросе параметры на конкретные значения. `true` поддерживается только с libsqlite 3.14.

### Возвращаемые значения

Возвращает SQL-запрос из подготовленного запроса или `false`, если возникла ошибка.

### Ошибки

Если `expand` задан как `true`, но версия libsqlite ниже 3.14, будет вызвана ошибка уровня `E_WARNING` либо выброшено исключение Exception, в зависимости от настроек SQLite3::enableExceptions().

### Примеры

Пример #1 Получение расширенного SQL-запроса

    <?php
    $db = new SQLite3(':memory:');
    $stmt = $db->prepare("SELECT :a, ?, :c");
    $stmt->bindValue(':a', 'foo');
    $answer = 42;
    $stmt->bindParam(2, $answer);
    var_dump($stmt->getSQL(true));
    ?>

Вывод приведённого примера будет похож на:

    string(24) "SELECT 'foo', '42', NULL"

# SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — Возвращает количество параметров в подготовленном запросе

### Описание

public function SQLite3Stmt::paramCount(): int

Возвращает количество параметров в подготовленном запросе.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество параметров в подготовленном запросе.

### Смотрите также

- SQLite3::prepare() - Подготавливает SQL-запрос для выполнения

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Проверяет, является ли подготовленный запрос только для чтения

### Описание

public function SQLite3Stmt::readOnly(): bool

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если запрос только для чтения, `false` в противном случае.

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — Сбрасывает подготовленный запрос

### Описание

public function SQLite3Stmt::reset(): bool

Сбрасывает подготовленный запрос в состояние до его выполнения. После сброса все привязки остаются неизменными.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` в случае, если подготовленный запрос был успешно сброшен или `false`, если возникла ошибка.

## Содержание

- SQLite3Stmt::bindParam — Связывает параметр с переменной подготовленного запроса
- SQLite3Stmt::bindValue — Связывает значение параметра с переменной подготовленного запроса
- SQLite3Stmt::clear — Удаляет все текущие привязанные параметры
- SQLite3Stmt::close — Закрывает подготовленный запрос
- SQLite3Stmt::__construct — Конструктор класса SQLite3Stmt
- SQLite3Stmt::execute — Выполняет подготовленный запрос и возвращает объект с результирующим набором
- SQLite3Stmt::getSQL — Получить SQL-запрос в виде строки из запроса
- SQLite3Stmt::paramCount — Возвращает количество параметров в подготовленном запросе
- SQLite3Stmt::readOnly — Проверяет, является ли подготовленный запрос только для чтения
- SQLite3Stmt::reset — Сбрасывает подготовленный запрос

# Класс SQLite3Result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Класс, предоставляющий доступ к результирующему набору модуля SQLite 3.

## Обзор класса

class SQLite3Result {
/* Методы */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — >Возвращает имя n-ого столбца

### Описание

public function SQLite3Result::columnName(int `$column`): string|false

Возвращает имя столбца, указанного в `column_number`. Обратите внимание, что имя столбца результата — это значение предложения `AS` для этого столбца, если есть предложение `AS`. Если предложение `AS` отсутствует, тогда имя столбца не указано и может измениться с одного выпуска libsqlite3 на другой.

### Список параметров

`column`

  Номер столбца, начиная с нуля.

### Возвращаемые значения

Возвращает имя (string) столбца, указанного в `column`.

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — Возвращает тип n-ного столбца

### Описание

public function SQLite3Result::columnType(int `$column`): int|false

Возвращает тип столбца, указанного в `column`.

### Список параметров

`column`

  Номер столбца, начиная с нуля.

### Возвращаемые значения

Возвращает тип столбца, указанного в `column`. Возвращает значение `SQLITE3_INTEGER`, `SQLITE3_FLOAT`, `SQLITE3_TEXT`, `SQLITE3_BLOB`, `SQLITE3_NULL`) или `false`, если столбец не существует.

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — Конструктор класса SQLite3Result

### Описание

private function SQLite3Result::__construct()

Экземпляры SQLite3Result создаются с помощью SQLite3::query() и SQLite3Stmt::execute().

### Список параметров

Сигнатура функции не содержит параметров.

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — Выбирает одну строку из результирующего набора и помещает её в ассоциативный или нумерованный массив, или в оба сразу

### Описание

public function SQLite3Result::fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false

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

### Список параметров

`mode`

  Этот необязательный параметр принимает значение константы, которая указывает на тип массива, в который требуется поместить данные. Возможные значения параметра: `SQLITE3_ASSOC`, `SQLITE3_NUM` или `SQLITE3_BOTH`.

  - `SQLITE3_ASSOC`: возвращает ассоциативный массив, в котором индекс соответствует имени столбца в результирующем наборе.

  - `SQLITE3_NUM`: возвращает индексированный массив, в котором индекс соответствует номеру столбца в результирующем наборе, начиная с 0.

  - `SQLITE3_BOTH`: возвращает индексированный массив, в котором индекс соответствует имени и номеру столбца в результирующем наборе, начиная с 0.

### Возвращаемые значения

Метод возвращает строку из результирующего набора в виде ассоциированного или нумерованного массива, или обоих. Если строк больше нет, метод возвращает `false`.

Типы значений возвращаемого массива преобразовываются из типов SQLite3 по следующим правилам: целые числа преобразовываются в int если помещаются в диапазон `PHP_INT_MIN`..`PHP_INT_MAX`, иначе в строки. Рациональные числа преобразовываются в числа с плавающей точкой (float), значения `NULL` в null, а строки и BLOB — в строки.

# SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — Закрывает результирующий набор

### Описание

public function SQLite3Result::finalize(): true

Закрывает результирующий набор.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает ошибку Error, если вызывается на неинициализированном объекте.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Метод теперь выбрасывает ошибку Error, если объект неправильно инициализирован; ранее возвращалось значение `false`.

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — Возвращает количество столбцов в результирующем наборе

### Описание

public function SQLite3Result::numColumns(): int

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

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

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — Сбрасывает указатель результирующего набора на первую строку

### Описание

public function SQLite3Result::reset(): bool

Метод сбрасывает указатель результирующего набора на первую строку.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает `true`, если результирующий набор успешно сброшен на первую строку, или `false`, если возникла ошибка.

## Содержание

- SQLite3Result::columnName — >Возвращает имя n-ого столбца
- SQLite3Result::columnType — Возвращает тип n-ного столбца
- SQLite3Result::__construct — Конструктор класса SQLite3Result
- SQLite3Result::fetchArray — Выбирает одну строку из результирующего набора и помещает её в ассоциативный или нумерованный массив, или в оба сразу
- SQLite3Result::finalize — Закрывает результирующий набор
- SQLite3Result::numColumns — Возвращает количество столбцов в результирующем наборе
- SQLite3Result::reset — Сбрасывает указатель результирующего набора на первую строку

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- SQLite3 — Класс SQLite3
  - SQLite3::backup — Резервное копирование одной базы данных в другую
  - SQLite3::busyTimeout — Установить обработчик "занято" на соединение
  - SQLite3::changes — Получить количество строк, которые были изменены/удалены/вставлены последним запросом
  - SQLite3::close — Закрыть соединение с базой данных
  - SQLite3::__construct — Создаёт экземпляр объекта SQLite3 и открывает соединение с базой
  - SQLite3::createAggregate — Зарегистрировать функцию PHP в качестве агрегирующей функции SQL
  - SQLite3::createCollation — Регистрирует функцию PHP для использования в качестве функции сортировки SQL
  - SQLite3::createFunction — Регистрирует функцию PHP для использования в качестве скалярной функции SQL
  - SQLite3::enableExceptions — Включает генерацию исключений
  - SQLite3::escapeString — Возвращает правильно экранированную строку
  - SQLite3::exec — Выполняет запрос без результата к текущей базе данных
  - SQLite3::lastErrorCode — Возвращает числовой код результата последнего неудачного запроса SQLite
  - SQLite3::lastErrorMsg — Возвращает текст на английском, описывающий последний неудачный запрос SQLite
  - SQLite3::lastInsertRowID — Возвращает идентификатор строки последней вставки (INSERT) в базу данных
  - SQLite3::loadExtension — Попытаться загрузить библиотеку модуля SQLite
  - SQLite3::open — Открывает базу данных SQLite
  - SQLite3::openBlob — Открывает ресурс потока для чтения BLOB
  - SQLite3::prepare — Подготавливает SQL-запрос для выполнения
  - SQLite3::query — Выполняет SQL-запрос
  - SQLite3::querySingle — Выполняет запрос и возвращает одиночный результат
  - SQLite3::setAuthorizer — Устанавливает callback-функцию, которая будет использоваться в качестве авторизатора для ограничения действий выражения
  - SQLite3::version — Возвращает версию библиотеки SQLite3, содержит как строковую константу, так и числовую
- SQLite3Exception — Класс SQLite3Exception
- SQLite3Stmt — Класс SQLite3Stmt
  - SQLite3Stmt::bindParam — Связывает параметр с переменной подготовленного запроса
  - SQLite3Stmt::bindValue — Связывает значение параметра с переменной подготовленного запроса
  - SQLite3Stmt::clear — Удаляет все текущие привязанные параметры
  - SQLite3Stmt::close — Закрывает подготовленный запрос
  - SQLite3Stmt::__construct — Конструктор класса SQLite3Stmt
  - SQLite3Stmt::execute — Выполняет подготовленный запрос и возвращает объект с результирующим набором
  - SQLite3Stmt::getSQL — Получить SQL-запрос в виде строки из запроса
  - SQLite3Stmt::paramCount — Возвращает количество параметров в подготовленном запросе
  - SQLite3Stmt::readOnly — Проверяет, является ли подготовленный запрос только для чтения
  - SQLite3Stmt::reset — Сбрасывает подготовленный запрос
- SQLite3Result — Класс SQLite3Result
  - SQLite3Result::columnName — >Возвращает имя n-ого столбца
  - SQLite3Result::columnType — Возвращает тип n-ного столбца
  - SQLite3Result::__construct — Конструктор класса SQLite3Result
  - SQLite3Result::fetchArray — Выбирает одну строку из результирующего набора и помещает её в ассоциативный или нумерованный массив, или в оба сразу
  - SQLite3Result::finalize — Закрывает результирующий набор
  - SQLite3Result::numColumns — Возвращает количество столбцов в результирующем наборе
  - SQLite3Result::reset — Сбрасывает указатель результирующего набора на первую строку

# Драйвер СУБД Microsoft SQL Server для PHP

# Введение

Модуль SQLSRV позволяет подключиться к базам данных Microsoft SQL Server или SQL Azure. Релиз драйвера версии 3.0 поддерживает SQL Server начиная с версии SQL Server 2005, включая Server 2012 и SQL Server 2012 LocalDB. Подробное описание LocalDB можно прочитать по тут: » Драйвер PHP Driver для SQL Server, поддержка LocalDB и » SQL Server 2012 Express LocalDB.

Модуль SQLSRV поддерживается компанией Microsoft и доступен по ссылке - » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx. SQL Server 2012 LocalDB можно загрузить отсюда - » http://go.microsoft.com/fwlink/?LinkID=237665.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Модуль SQLSRV может использоваться в следующих операционных системах:

- Windows Vista Service Pack 2 или позже
- Windows Server 2008 Service Pack 2 или позже
- Windows Server 2008 R2
- Windows 7

Модуль SQLSRV требует, чтобы на компьютере, на котором установлен PHP, была установлена библиотека Microsoft SQL Server 2008 R2 Native Client. Если Microsoft SQL Server 2008 R2 ещё не установлен, вы можете скачать требуемый дистрибутив по ссылкам ниже:

- » Скачать версию x86
- » Скачать версию x64

Загружаемая копия модуля PDO_SQLSRV включает в себя восемь файлов драйверов, четыре из них для поддержки PDO.

Наиболее часто используемая версия драйвера доступна здесь: » Загрузка SQLSRV.

За подробностями о системных требованиях обратитесь к разделу » Системные требования SQLSRV.

## Установка

Модуль SQLSRV включается добавлением соответствующего файла DLL в директорию модулей вашей установленной копии PHP и соответствующей записи в файл php.ini. Загружаемая копия модуля PDO_SQLSRV включает в себя восемь файлов драйверов, четыре из них для поддержки PDO.

Наиболее часто используемая версия драйвера доступны здесь: » Загрузка SQLSRV.

За подробностями о системных требованиях обратитесь к разделу » Системные требования SQLSRV.

Начиная с версии 4.0, модуль SQLSRV работает только с PHP 7.0 под Linux и Windows.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

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

SQLSRV Опции настройки
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
sqlsrv.WarningsReturnAsErrors | 1 (`true`) | `INI_ALL` | Доступно с версии SQLSRV 1.0
sqlsrv.LogSubsystems | 0 | `INI_ALL` | Доступно с версии SQLSRV 1.0
sqlsrv.LogSeverity | 1 | `INI_ALL` | Доступно с версии SQLSRV 1.0

## Типы ресурсов

## Дескриптор соединения

Дескриптор соединения возвращается функцией sqlsrv_connect().

## Дескриптор выражения

Дескриптор выражения (statement resource) возвращается функциями sqlsrv_query() или sqlsrv_prepare().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`SQLSRV_FETCH_ASSOC` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_fetch_array() возвращать ассоциативный массив.
`SQLSRV_FETCH_NUMERIC` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_fetch_array() возвращать массив с числовыми ключами.
`SQLSRV_FETCH_BOTH` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_fetch_array() возвращать массив с ключами и числовыми и ассоциативными (поведение по умолчанию).
`SQLSRV_ERR_ALL` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_errors() возвращать и ошибки и предупреждения (поведение по умолчанию).
`SQLSRV_ERR_ERRORS` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_errors() возвращать только ошибки (без предупреждений).
`SQLSRV_ERR_WARNINGS` (int)
  Переданный в качестве параметра, заставляет функцию sqlsrv_errors() возвращать только предупреждения (без ошибок).
`SQLSRV_LOG_SYSTEM_ALL` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), включает журналирование всех подсистем.
`SQLSRV_LOG_SYSTEM_CONN` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), включает журналирование активности соединения.
`SQLSRV_LOG_SYSTEM_INIT` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), включает журналирование активности инициализации.
`SQLSRV_LOG_SYSTEM_OFF` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), отключает журналирование всех подсистем.
`SQLSRV_LOG_SYSTEM_STMT` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), включает журналирование активности выполнения выражений (statement activity).
`SQLSRV_LOG_SYSTEM_UTIL` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), включает журналирование активности функций ошибок.
`SQLSRV_LOG_SEVERITY_ALL` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), определяет, что ошибки, предупреждения и замечания будут журналироваться.
`SQLSRV_LOG_SEVERITY_ERROR` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), определяет, что ошибки будут журналироваться.
`SQLSRV_LOG_SEVERITY_NOTICE` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), определяет, что замечания будут журналироваться.
`SQLSRV_LOG_SEVERITY_WARNING` (int)
  Переданный в качестве параметра функции sqlsrv_configure(), определяет, что предупреждения будут журналироваться.
`SQLSRV_NULLABLE_YES` (int)
  Показывает, что значение столбца может быть NULL.
`SQLSRV_NULLABLE_NO` (int)
  Показывает, что значение столбца не может быть NULL.
`SQLSRV_NULLABLE_UNKNOWN` (int)
  Показывает, что неизвестно, может ли значение столбца быть NULL.
`SQLSRV_PARAM_IN` (int)
  При передаче в качестве параметра в функции sqlsrv_query() или sqlsrv_prepare() показывает, что параметр является входным.
`SQLSRV_PARAM_INOUT` (int)
  При передаче в качестве параметра в функции sqlsrv_query() или sqlsrv_prepare() показывает, что параметр является и входным и выходным.
`SQLSRV_PARAM_OUT` (int)
  При передаче в качестве параметра в функции sqlsrv_query() или sqlsrv_prepare() показывает, что параметр является выходным.
`SQLSRV_PHPTYPE_INT` (int)
  Определяет целочисленный тип данных PHP (integer). За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_PHPTYPE_DATETIME` (int)
  Определяет временной тип данных PHP (datetime). За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_PHPTYPE_FLOAT` (int)
  Определяет тип данных PHP с плавающей точкой (float). За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_PHPTYPE_STREAM` (int)
  Определяет поток данных PHP (stream). Данная константа работает как функция и принимает константы кодировок. Смотрите константы вида SQLSRV_ENC_*. За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_PHPTYPE_STRING` (int)
  Определяет строковый тип данных PHP (string). Данная константа работает как функция и принимает константы кодировок. Смотрите константы вида SQLSRV_ENC_*. За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_ENC_BINARY` (int)
  Определяет, что данные от сервера возвращаются в виде потока байтов без выполнения кодирования или преобразования. За информацией об использовании обратитесь к разделу » Определение типов PHP.
`SQLSRV_ENC_CHAR` (int)
  Данные возвращаются в формате восьмибитных символов как определено кодовой странице локали Windows, установленной в системе. Любые мультибайтовые символы или символы, не преобразуемые в данную кодовую страницу, заменяются однобайтовым символом вопроса (?). Данная кодировка является кодировкой по умолчанию. За информацией об использовании обратитесь к разделу документации » Определение типов PHP.
`SQLSRV_SQLTYPE_BIGINT` (int)
  Описывает SQL-тип BIGINT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_BINARY` (int)
  Описывает SQL-тип BINARY. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_BIT` (int)
  Описывает SQL-тип BIT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_CHAR` (int)
  Описывает SQL-тип CHAR. Эта константа работает как функция и принимает один параметр, задающий количество символов. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_DATE` (int)
  Описывает SQL-тип DATE. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_DATETIME` (int)
  Описывает SQL-тип DATETIME. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_DATETIME2` (int)
  Описывает SQL-тип DATETIME2. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_DATETIMEOFFSET` (int)
  Описывает SQL-тип DATETIMEOFFSET. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_DECIMAL` (int)
  Описывает SQL-тип DECIMAL. Эта константа работает как функция и принимает два параметра, задающий точность и разрядность. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_FLOAT` (int)
  Описывает SQL-тип FLOAT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_IMAGE` (int)
  Описывает SQL-тип IMAGE. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_INT` (int)
  Описывает SQL-тип INT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_MONEY` (int)
  Описывает SQL-тип MONEY. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_NCHAR` (int)
  Описывает SQL-тип NCHAR. Эта константа работает как функция и принимает один параметр, задающий количество символов. За информацией об использовании обратитесь к разделу документации » Определение типов SQL.
`SQLSRV_SQLTYPE_NUMERIC` (int)
  Описывает SQL-тип NUMERIC. Эта константа работает как функция и принимает два параметра, задающий точность и разрядность. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_NVARCHAR` (int)
  Описывает SQL-тип NVARCHAR. Эта константа работает как функция и принимает один параметр, задающий количество символов. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_NVARCHAR('max')` (int)
  Описывает SQL-тип NVARCHAR(MAX). За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_NTEXT` (int)
  Описывает SQL-тип NTEXT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_REAL` (int)
  Описывает SQL-тип REAL. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_SMALLDATETIME` (int)
  Описывает SQL-тип SMALLDATETIME. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_SMALLINT` (int)
  Описывает SQL-тип SMALLINT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_SMALLMONEY` (int)
  Описывает SQL-тип SMALLMONEY. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_TEXT` (int)
  Описывает SQL-тип TEXT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_TIME` (int)
  Описывает SQL-тип TIME. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_TIMESTAMP` (int)
  Описывает SQL-тип TIMESTAMP. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_TINYINT` (int)
  Описывает SQL-тип TINYINT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_UNIQUEIDENTIFIER` (int)
  Описывает SQL-тип UNIQUEIDENTIFIER. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_UDT` (int)
  Описывает SQL-тип UDT. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_VARBINARY` (int)
  Описывает SQL-тип VARBINARY. Эта константа работает как функция и принимает один параметр, задающий количество байт. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_VARBINARY('max')` (int)
  Описывает SQL-тип VARBINARY(MAX). За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_VARCHAR` (int)
  Описывает SQL-тип VARCHAR. Эта константа работает как функция и принимает один параметр, задающий количество символов. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_VARCHAR('max')` (int)
  Описывает SQL-тип VARCHAR(MAX). За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_SQLTYPE_XML` (int)
  Описывает SQL-тип XML. За информацией об использовании обратитесь к разделу » Определение типов SQL.
`SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Задаёт уровень изоляции транзакции равным READ UNCOMMITTED. Это значение используется для установки уровня TransactionIsolation в массиве $connectionOptions, переданном аргументом в функцию sqlsrv_connect().
`SQLSRV_TXN_READ_COMMITTED` (int)
  Задаёт уровень изоляции транзакции равным READ COMMITTED. Это значение используется для установки уровня TransactionIsolation в массиве $connectionOptions, переданном аргументом в функцию sqlsrv_connect().
`SQLSRV_TXN_REPEATABLE_READ` (int)
  Задаёт уровень изоляции транзакции равным REPEATABLE READ. Это значение используется для установки уровня TransactionIsolation в массиве $connectionOptions, переданном аргументом в функцию sqlsrv_connect().
`SQLSRV_TXN_SNAPSHOT` (int)
  Задаёт уровень изоляции транзакции равным SNAPSHOT. Это значение используется для установки уровня TransactionIsolation в массиве $connectionOptions, переданном аргументом в функцию sqlsrv_connect().
`SQLSRV_TXN_READ_SERIALIZABLE` (int)
  Задаёт уровень изоляции транзакции равным SERIALIZABLE. Это значение используется для установки уровня TransactionIsolation в массиве $connectionOptions, переданном аргументом в функцию sqlsrv_connect().
`SQLSRV_CURSOR_FORWARD` (int)
  Задаёт тип курсора как forward-only. За информацией об использовании обратитесь к разделу » Определение типов курсоров.
`SQLSRV_CURSOR_STATIC` (int)
  Задаёт тип курсора как static. За информацией об использовании обратитесь к разделу » Определение типов курсоров.
`SQLSRV_DYNAMIC` (int)
  Задаёт тип курсора как dynamic. За информацией об использовании обратитесь к разделу » Определение типов курсоров.
`SQLSRV_CURSOR_KEYSET` (int)
  Задаёт тип курсора как keyset. За информацией об использовании обратитесь к разделу » Определение типов курсоров.
`SQLSRV_CURSOR_BUFFERED` (int)
  Создаёт запрос с курсором на стороне клиента. Позволяет получать строки в любом порядке. За информацией об использовании обратитесь к разделу » Определение типов курсоров.
`SQLSRV_SCROLL_NEXT` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.
`SQLSRV_SCROLL_PRIOR` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.
`SQLSRV_SCROLL_FIRST` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.
`SQLSRV_SCROLL_LAST` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.
`SQLSRV_SCROLL_ABSOLUTE` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.
`SQLSRV_SCROLL_RELATIVE` (int)
  Указывает, какую строку выбрать из результирующего набора. За информацией об использовании обратитесь к разделу » Определение типов курсоров и выборка строк.

# Функции SQLSRV

# sqlsrv_begin_transaction

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Начинает транзакцию базы данных

### Описание

function sqlsrv_begin_transaction(resource `$conn`): bool

Транзакция, начатая с помощью sqlsrv_begin_transaction(), включает все операторы, которые были выполнены после вызова sqlsrv_begin_transaction() и до вызовов sqlsrv_rollback() или sqlsrv_commit(). Явные транзакции должны запускаться и фиксироваться или откатываться с использованием этих функций вместо выполнения операторов SQL, которые запускают и фиксируют/откатывают транзакции. Для получения дополнительной информации смотрите » Транзакции SQLSRV.

### Список параметров

`conn`
  Ресурс подключения, возвращаемый вызовом sqlsrv_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_begin_transaction()

В следующем примере показано, как использоватьsqlsrv_begin_transaction() вместе с sqlsrv_commit() и sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Начало транзакции. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Инициализация значений параметров. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Настройка и выполнение первого запроса. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
              VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Настройка и выполнение второго запроса. */
    $sql2 = "UPDATE InventoryTable
              SET Quantity = (Quantity - ?)
              WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Если оба запроса были успешными, зафиксируйте транзакцию. */
    /* В противном случае откатите транзакцию. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Транзакция зафиксирована.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Транзация откачена.<br />";
    }
    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- sqlsrv_commit() - Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction
- sqlsrv_rollback() - Откатывает транзакцию, начатую sqlsrv_begin_transaction

# sqlsrv_cancel

(No version information available, might only be in Git)

sqlsrv_cancel — Отменяет оператор

### Описание

function sqlsrv_cancel(resource `$stmt`): bool

Отменяет оператор. Все неиспользованные результаты, связанные с оператором, удаляются. После вызова sqlsrv_cancel() указанный оператор может быть выполнен повторно, если он был создан с помощью sqlsrv_prepare(). Вызов sqlsrv_cancel() не требуется, если все результаты, связанные с оператором, были использованы.

### Список параметров

`stmt`
  Ресурс оператора, который нужно отменить.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_cancel()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Sales FROM Table_1";

    $stmt = sqlsrv_prepare( $conn, $sql);

    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    if( sqlsrv_execute( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    $salesTotal = 0;
    $count = 0;

    while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
    {
         $qty = $row[0];
         $price = $row[1];
         $salesTotal += ( $price * $qty);
         $count++;
    }

    echo "$count продаж составили первый $$salesTotal выручки.<br />";

    // Отменить ожидающие результаты. Оператор можно использовать повторно.
    sqlsrv_cancel( $stmt);
    ?>

### Примечания

Основное различие между sqlsrv_free_stmt() и sqlsrv_cancel() заключается в том, что ресурс оператора, отменённый с помощью sqlsrv_cancel(), может быть повторно выполнен, если он был создан с помощью sqlsrv_prepare(). Ресурс оператора, отменённый с помощью sqlsrv_free_statement(), не может быть повторно выполнен.

### Смотрите также

- sqlsrv_free_stmt() - Освобождает все ресурсы для указанного оператора
- sqlsrv_prepare() - Подготавливает запрос к исполнению

# sqlsrv_client_info

(No version information available, might only be in Git)

sqlsrv_client_info — Возвращает информацию о клиенте и указанном подключении

### Описание

function sqlsrv_client_info(resource `$conn`): array

Возвращает информацию о клиенте и указанном подключении.

### Список параметров

`conn`
  Соединение, о котором возвращается информация.

### Возвращаемые значения

Возвращает ассоциативный массив с ключами, описанными в таблице ниже. В противном случае возвращает `false`.

Массив, возвращаемый sqlsrv_client_info
Ключ | Описание
--- | ---
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | Версия ODBC (xx.yy)
DriverVer | Версия SQL Server Native Client DLL (10.5.xxx)
ExtensionVer | Версия php_sqlsrv.dll (2.0.xxx.x)

### Примеры

Пример #1 Пример использования sqlsrv_client_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connOptions );

    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    if( $client_info = sqlsrv_client_info( $conn)) {
        foreach( $client_info as $key => $value) {
            echo $key.": ".$value."<br />";
        }
    } else {
        echo "Ошибка при получении информации о клиенте.<br />";
    }
    ?>

### Смотрите также

- sqlsrv_server_info() - Возвращает информацию о сервере

# sqlsrv_close

(No version information available, might only be in Git)

sqlsrv_close — Закрывает открытое соединение и освобождает ресурсы, связанные с этим соединением

### Описание

function sqlsrv_close(resource `$conn`): bool

Закрывает открытое соединение и освобождает ресурсы, связанные с этим соединением.

### Список параметров

`conn`
  Соединение, которое необходимо закрыть.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_close()

    <?php
    $serverName = "serverName\sqlexpres";
    $connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
    $conn = sqlsrv_connect( $serverName, $connOptions );
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    //-------------------------------------
    // Выполнение операций с базой данных.
    //-------------------------------------

    // Закрытие соединения.
    sqlsrv_close( $conn );
    ?>

### Смотрите также

- sqlsrv_connect() - Открывает соединение с базой данных Microsoft SQL Server

# sqlsrv_commit

(No version information available, might only be in Git)

sqlsrv_commit — Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction()

### Описание

function sqlsrv_commit(resource `$conn`): bool

Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction(). Соединение возвращается в режим автоматической фиксации после вызова sqlsrv_commit(). Подтверждённая транзакция включает все операторы, которые были выполнены после вызова sqlsrv_begin_transaction(). Явные транзакции должны запускаться и фиксироваться или откатываться с использованием этих функций вместо выполнения SQL-операторов, которые запускают и фиксируют/откатывают транзакции. Для получения дополнительной информации смотрите » Транзакции SQLSRV.

### Список параметров

`conn`
  Соединение, на котором должна быть совершена транзакция.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_commit()

В следующем примере показано, как использовать sqlsrv_commit() вместе с sqlsrv_begin_transaction() и sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Начало транзакции. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Инициализация значения параметров. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Настройка и выполнение первого запроса. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Настройка и выполнение второго запроса. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Если оба запроса были успешными, зафиксируйте транзакцию. */
    /* В противном случае откатите транзакцию */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Транзакция зафиксирована.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Транзакция откачена.<br />";
    }
    ?>

### Смотрите также

- sqlsrv_begin_transaction() - Начинает транзакцию базы данных
- sqlsrv_rollback() - Откатывает транзакцию, начатую sqlsrv_begin_transaction

# sqlsrv_configure

(No version information available, might only be in Git)

sqlsrv_configure — Изменяет конфигурацию обработки ошибок драйвера и ведения журнала

### Описание

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Изменяет конфигурацию обработки ошибок драйвера и ведения журнала.

### Список параметров

`setting`
  Имя настройки. Возможные значения: "WarningsReturnAsErrors", "LogSubsystems" и "LogSeverity".
`value`

  Значение указанного параметра. В следующей таблице показаны возможные значения:

  Параметры настройки ошибок и ведения журнала
  Настройка | Опции
  --- | ---
  WarningsReturnAsErrors | 1 (`true`) или 0 (`false`)
  LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
  LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- » Обработка ошибок SQLSRV.
- » Ведение журнала активности SQLSRV.

# sqlsrv_connect

(No version information available, might only be in Git)

sqlsrv_connect — Открывает соединение с базой данных Microsoft SQL Server

### Описание

function sqlsrv_connect(string `$serverName`, array `$connectionInfo` = ?): resource

Открывает соединение с базой данных Microsoft SQL Server. По умолчанию попытка подключения выполняется с использованием проверки подлинности Windows. Чтобы подключиться с использованием проверки подлинности SQL Server, включите "UID" и "PWD" в массив параметров подключения.

### Список параметров

`serverName`
  Имя сервера, к которому устанавливается соединение. Чтобы подключиться к определённому экземпляру, после имени сервера укажите обратную косую черту и имя экземпляра (например, serverName\sqlexpress).
`connectionInfo`
  Ассоциативный массив, определяющий параметры подключения к серверу. Если значения для ключей UID и PWD не указаны, будет предпринята попытка подключения с использованием проверки подлинности Windows. Полный список поддерживаемых ключей смотрите в разделе » Параметры подключения SQLSRV.

### Возвращаемые значения

Ресурс подключения. Если соединение не может быть открыто, возвращается `false`.

### Примеры

Пример #1 Подключение с использованием проверки подлинности Windows.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName

    // Поскольку UID и PWD не указаны в массиве $connectionInfo,
    // будет предпринята попытка подключения с использованием проверки подлинности Windows.
    $connectionInfo = array( "Database"=>"dbName");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Соединение установлено.<br />";
    }else{
         echo "Соединение не установлено.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Пример #2 Подключение с использованием имени пользователя и пароля.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Соединение установлено.<br />";
    }else{
         echo "Соединение не установлено.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Пример #3 Подключение с использованием порта.

    <?php
    $serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (по умолчанию 1433)
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Соединение установлено.<br />";
    }else{
         echo "Соединение не установлено.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Примечания

По умолчанию sqlsrv_connect() использует пул соединений для повышения производительности соединения. Чтобы отключить пул соединений (т.е. принудительно устанавливать новое соединение при каждом вызове), установите для параметра "ConnectionPooling" в массиве $connectionOptions значение 0 (или `false`). Для получения дополнительной информации смотрите раздел » Пул соединений SQLSRV.

У модуля SQLSRV нет специальной функции для изменения базы данных после подключения. Целевая база данных указывается в массиве $connectionOptions, который передаётся в sqlsrv_connect. Чтобы изменить базу данных при открытом соединении, выполните следующий запрос "USE dbName" (например, sqlsrv_query($conn, "USE dbName")).

### Смотрите также

- sqlsrv_close() - Закрывает открытое соединение и освобождает ресурсы, связанные с этим соединением
- sqlsrv_errors() - Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV
- sqlsrv_query() - Подготавливает и выполняет запрос

# sqlsrv_errors

(No version information available, might only be in Git)

sqlsrv_errors — Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV

### Описание

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV.

### Список параметров

`errorsOrWarnings`
  Определяет, возвращаются ли сведения об ошибках, предупреждения или и то и другое. Если параметр не указан, возвращаются как информация об ошибке, так и информация о предупреждениях. Поддерживаются следующие значения параметра: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

### Возвращаемые значения

Если при последней операции sqlsrv возникли ошибки и/или предупреждения, возвращается массив массивов, содержащих информацию об ошибках. Если при последней операции sqlsrv не было ошибок и/или предупреждений, возвращается `null`. В следующей таблице описана структура возвращаемых массивов:

Массив, возвращаемый sqlsrv_errors
Ключ | Описание
--- | ---
SQLSTATE | Для ошибок, которые возникают из-за драйвера ODBC, возвращается SQLSTATE, возвращаемый ODBC. Для ошибок, которые возникают из-за драйверов Microsoft для PHP для SQL Server, возвращается SQLSTATE IMSSP. Для предупреждений, которые возникают из-за драйверов Microsoft для PHP для SQL Server, SQLSTATE возвращает значение 01SSP.
code | Для ошибок, которые возникают из-за SQL Server, возвращает собственный код ошибки SQL Server. Для ошибок, возникающих из-за драйвера ODBC, возвращается код ошибки, возвращаемый ODBC. Для ошибок, которые возникают из-за драйверов Microsoft для PHP для SQL Server, возвращается код ошибки Microsoft Drivers для PHP для SQL Server.
message | Описание ошибки.

### Примеры

Пример #1 Пример использования functionname()

    <?php
    $serverName = "serverName/sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /* Настройка запроса для выборки недопустимого имени столбца. */
    $sql = "SELECT BadColumnName FROM Table_1";

    /* Выполнение запроса завершится ошибкой из-за неправильного имени столбца. */
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false ) {
        if( ($errors = sqlsrv_errors() ) != null) {
            foreach( $errors as $error ) {
                echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
                echo "Код: ".$error[ 'code']."<br />";
                echo "Сообщение: ".$error[ 'message']."<br />";
            }
        }
    }
    ?>

### Примечания

По умолчанию предупреждения, генерируемые при вызове любой функции SQLSRV, обрабатываются как ошибки. Это означает, что если при вызове функции SQLSRV возникает предупреждение, функция возвращает `false`. Однако предупреждения, соответствующие значениям SQLSTATE 01000, 01001, 01003 и 01S02, никогда не рассматриваются как ошибки. Для получения информации об изменении этого поведения смотрите описание функции sqlsrv_configure() и параметр WarningsReturnAsErrors.

### Смотрите также

- sqlsrv_configure() - Изменяет конфигурацию обработки ошибок драйвера и ведения журнала

# sqlsrv_execute

(No version information available, might only be in Git)

sqlsrv_execute — Выполняет запрос, подготовленный с помощью sqlsrv_prepare()

### Описание

function sqlsrv_execute(resource `$stmt`): bool

Выполняет запрос, подготовленный с помощью sqlsrv_prepare(). Функция идеально подходит для многократного выполнения подготовленного запроса с разными значениями параметров.

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_prepare().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_execute()

В этом примере показано, как подготовить оператор с помощью sqlsrv_prepare() и повторно выполнить его несколько раз (с разными значениями параметров) с помощью sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Инициализация параметров и подготовка запроса.
    // Переменные $qty и $id связаны с оператором $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Настройка информации SalesOrderDetailID и OrderQty.
    // Этот массив сопоставляет идентификатор заказа с количеством заказа в парах ключ => значение.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Выполнение запроса для каждого заказа.
    foreach( $orders as $id => $qty) {
        // Поскольку $id и $qty привязаны к $stmt1,
        // их обновлённые значения используются при каждом выполнении запроса.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Примечания

Когда вы подготавливаете запрос, который использует переменные в качестве параметров, переменные привязываются к оператору. Это означает, что если вы обновите значения переменных, в следующий раз, когда вы выполните запрос, он будет работать с обновлёнными значениями параметров. Для операторов, которые вы планируете выполнить только один раз, используйте sqlsrv_query().

### Смотрите также

- sqlsrv_prepare() - Подготавливает запрос к исполнению
- sqlsrv_query() - Подготавливает и выполняет запрос

# sqlsrv_fetch

(No version information available, might only be in Git)

sqlsrv_fetch — Делает следующую строку в наборе результатов доступной для чтения

### Описание

function sqlsrv_fetch(resource `$stmt`, int `$row` = ?, int `$offset` = ?): mixed

Делает следующую строку в наборе результатов доступной для чтения. Используйте sqlsrv_get_field() для чтения полей строки.

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_query() или sqlsrv_execute().
`row`

  Строка, к которой нужно получить доступ. Параметр можно использовать только в том случае, если указанный оператор был подготовлен с помощью курсора с возможностью прокрутки. В этом случае параметр может принимать одно из следующих значений:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Указывает строку, к которой будет осуществляться доступ, если для параметра строки установлено значение `SQLSRV_SCROLL_ABSOLUTE` или `SQLSRV_SCROLL_RELATIVE`. Обратите внимание, что первая строка в наборе результатов имеет индекс 0.

### Возвращаемые значения

Возвращает `true`, если следующая строка набора результатов была успешно получена, `false` в случае возникновения ошибки и `null`, если в наборе результатов больше нет строк.

### Примеры

Пример #1 Пример использования sqlsrv_fetch()

В следующем примере показано, как получить строку с помощью sqlsrv_fetch() и получить поля строки с помощью sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Сделайте первую (и в данном случае единственную) строку набора результатов доступной для чтения.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Получите поля строки. Индексы полей начинаются с 0 и должны извлекаться по порядку.
    // Получение полей строки по имени не поддерживается sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Смотрите также

- sqlsrv_get_field() - Получает данные поля из текущей выбранной строки
- sqlsrv_fetch_array() - Возвращает строку как массив
- sqlsrv_fetch_object() - Получает следующую строку данных в наборе результатов как объект

# sqlsrv_fetch_array

(No version information available, might only be in Git)

sqlsrv_fetch_array — Возвращает строку как массив

### Описание

function sqlsrv_fetch_array(
resource `$stmt`,
int `$fetchType` = ?,
int `$row` = ?,
int `$offset` = ?
): array

Возвращает следующую доступную строку данных в виде ассоциативного массива, числового массива или и того и другого (по умолчанию).

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_query или sqlsrv_prepare.
`fetchType`
  Предопределённая константа, указывающая тип возвращаемого массива. Возможные значения: `SQLSRV_FETCH_ASSOC`, `SQLSRV_FETCH_NUMERIC` или `SQLSRV_FETCH_BOTH` (по умолчанию). Тип выборки SQLSRV_FETCH_ASSOC не следует использовать при использовании набора результатов с несколькими столбцами с одинаковым именем.
`row`
  Задаёт строку для доступа в результирующем наборе, в котором используется прокручиваемый курсор. Возможные значения: `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE` и `SQLSRV_SCROLL_RELATIVE` (по умолчанию). Если этот параметр указан, `fetchType` должен быть явно определён.
`offset`
  Указывает строку, к которой будет осуществляться доступ, если для параметра строки установлено значение `SQLSRV_SCROLL_ABSOLUTE` или `SQLSRV_SCROLL_RELATIVE`. Обратите внимание, что первая строка в наборе результатов имеет индекс 0.

### Возвращаемые значения

В случае успешного выполнения возвращает массив, `null`, если в наборе результатов больше нет строк и `false` в случае возникновения ошибки.

### Примеры

Пример #1 Получение ассоциативного массива.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
          echo $row['LastName'].", ".$row['FirstName']."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

Пример #2 Получение числового массива.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
          echo $row[0].", ".$row[1]."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

### Примечания

Не указанный `fetchType` или явное использование константы `SQLSRV_FETCH_TYPE` в приведённых выше примерах вернёт массив, у которого ключи будут как ассоциативные, так и числовые.

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

Если возвращается столбец без имени, ассоциативный ключ для элемента массива будет пустой строкой ("").

### Смотрите также

- sqlsrv_connect() - Открывает соединение с базой данных Microsoft SQL Server
- sqlsrv_query() - Подготавливает и выполняет запрос
- sqlsrv_errors() - Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV
- sqlsrv_fetch() - Делает следующую строку в наборе результатов доступной для чтения

# sqlsrv_fetch_object

(No version information available, might only be in Git)

sqlsrv_fetch_object — Получает следующую строку данных в наборе результатов как объект

### Описание

function sqlsrv_fetch_object(
resource `$stmt`,
string `$className` = ?,
array `$ctorParams` = ?,
int `$row` = ?,
int `$offset` = ?
): mixed

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

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_query() или sqlsrv_execute().
`className`
  Имя класса для создания экземпляра. Если имя класса не указано, создаётся экземпляр stdClass.
`ctorParams`
  Значения передаваемые конструктору указанного класса. Если конструктор указанного класса принимает параметры, необходимо предоставить массив ctorParams.
`row`

  Строка, к которой нужно получить доступ. Параметр можно использовать только в том случае, если указанный оператор был подготовлен с помощью курсора с возможностью прокрутки. В этом случае этот параметр может принимать одно из следующих значений:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Указывает строку, к которой будет осуществляться доступ, если для параметра строки установлено значение `SQLSRV_SCROLL_ABSOLUTE` или `SQLSRV_SCROLL_RELATIVE`. Обратите внимание, что первая строка в наборе результатов имеет индекс 0.

### Возвращаемые значения

В случае успешного выполнения возвращает объект, `null`, если в наборе результатов больше нет строк и `false` в случае возникновения ошибки или если указанный класс не существует.

### Примеры

Пример #1 Пример использования sqlsrv_fetch_object()

В следующем примере показано, как получить строку как объект stdClass.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT fName, lName FROM Table_1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Получение каждой строки как объект.
    // Поскольку класс не указан, каждая строка будет получена как объект stdClass.
    // Имена свойств соответствуют именам полей.
    while( $obj = sqlsrv_fetch_object( $stmt)) {
          echo $obj->fName.", ".$obj->lName."<br />";
    }
    ?>

### Примечания

Если имя класса указано с необязательным параметром $className и у класса есть свойства, имена которых совпадают с именами полей набора результатов, к свойствам применяются соответствующие значения набора результатов. Если имя поля набора результатов не соответствует свойству класса, свойство с именем поля набора результатов добавляется к объекту, а значение набора результатов применяется к свойству. При использовании параметра $className применяются следующие правила:

- При сопоставлении имён свойств поля учитывается регистр.
- Сопоставление свойств поля происходит независимо от модификаторов доступа.
- Типы данных свойств класса игнорируются при применении значения поля к свойству.
- Если класс не существует, функция возвращает `false` и добавляет ошибку в коллекцию ошибок.

Независимо от того, указан ли параметр $className, если возвращается поле без имени, значение поля будет проигнорировано, а в коллекцию ошибок будет добавлено предупреждение.

При использовании набора результатов, содержащего несколько столбцов с одинаковым именем, может быть лучше использовать sqlsrv_fetch_array() или комбинацию sqlsrv_fetch() и sqlsrv_get_field().

### Смотрите также

- sqlsrv_fetch() - Делает следующую строку в наборе результатов доступной для чтения
- sqlsrv_fetch_array() - Возвращает строку как массив

# sqlsrv_field_metadata

(No version information available, might only be in Git)

sqlsrv_field_metadata — Получает метаданные для полей оператора, подготовленного с помощью sqlsrv_prepare() или sqlsrv_query()

### Описание

function sqlsrv_field_metadata(resource `$stmt`): mixed

Получает метаданные для полей оператора, подготовленного с помощью sqlsrv_prepare() или sqlsrv_query(). sqlsrv_field_metadata() может вызываться для оператора до или после выполнения оператора.

### Список параметров

`stmt`
  Ресурс оператора, для которого возвращаются метаданные.

### Возвращаемые значения

В случае успешного выполнения возвращает массив массивов. В противном случае возвращает `false`. Каждый возвращаемый массив описывается следующей таблицей:

Массив, возвращаемый sqlsrv_field_metadata
Ключ | Описание
--- | ---
Name | Имя поля.
Type | Числовое значение для типа SQL.
Size | Количество символов для полей символьного типа, количество байтов для полей двоичного типа или `null` для других типов.
Precision | Точность для типов переменной точности, `null` для других типов.
Scale | Масштаб для типов масштабируемых типов данных, `null` для других типов.
Nullable | Перечисление, указывающее, допускает ли столбец значение NULL, недопустимое значение NULL или неизвестно.

Для получения дополнительной информации смотрите » sqlsrv_field_metadata в документации Microsoft SQLSRV.

### Примеры

Пример #1 Пример использования sqlsrv_field_metadata()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_prepare( $conn, $sql );

    foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
        foreach( $fieldMetadata as $name => $value) {
           echo "$name: $value<br />";
        }
          echo "<br />";
    }
    ?>

### Смотрите также

- sqlsrv_client_info() - Возвращает информацию о клиенте и указанном подключении

# sqlsrv_free_stmt

(No version information available, might only be in Git)

sqlsrv_free_stmt — Освобождает все ресурсы для указанного оператора

### Описание

function sqlsrv_free_stmt(resource `$stmt`): bool

Освобождает все ресурсы для указанного оператора. Оператор нельзя использовать после того, как для него была вызвана функция sqlsrv_free_stmt(). Если sqlsrv_free_stmt() вызывается в выполняющемся операторе, который изменяет состояние сервера, выполнение оператора прекращается и оператор откатывается.

### Список параметров

`stmt`
  Оператор, ресурсы которого необходимо освободить. Обратите внимание, что `null` - допустимое значение параметра. Это позволяет вызывать функцию в скрипте несколько раз.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_free_stmt()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /*-------------------------------
         Здесь можно обработать результаты запроса.
    -------------------------------*/

    /* Освободите ресурсы для оператора */
    sqlsrv_free_stmt( $stmt);

    ?>

### Примечания

Основное различие между sqlsrv_free_stmt() и sqlsrv_cancel() заключается в том, что ресурс оператора, отменённый с помощью sqlsrv_cancel(), может быть повторно выполнен, если он был создан с помощью sqlsrv_prepare(). Ресурс оператора, отменённый с помощью sqlsrv_free_statement(), не может быть повторно выполнен.

### Смотрите также

- sqlsrv_cancel() - Отменяет оператор

# sqlsrv_get_config

(No version information available, might only be in Git)

sqlsrv_get_config — Возвращает значение указанного параметра конфигурации

### Описание

function sqlsrv_get_config(string `$setting`): mixed

Возвращает значение указанного параметра конфигурации.

### Список параметров

`setting`
  Имя параметра, для которого возвращается значение. Список настраиваемых параметров смотрите в разделе sqlsrv_configure().

### Возвращаемые значения

Возвращает значение указанного параметра. Если указан неверный параметр, возвращается `false`.

### Смотрите также

- sqlsrv_configure() - Изменяет конфигурацию обработки ошибок драйвера и ведения журнала

# sqlsrv_get_field

(No version information available, might only be in Git)

sqlsrv_get_field — Получает данные поля из текущей выбранной строки

### Описание

function sqlsrv_get_field(resource `$stmt`, int `$fieldIndex`, int `$getAsType` = ?): mixed

Получает данные поля из текущей выбранной строки. Доступ к полям должен осуществляться по порядку. Индексы полей начинаются с 0.

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_query() или sqlsrv_execute().
`fieldIndex`
  Индекс поля, которое нужно получить. Индексы полей начинаются с 0. К полям нужно обращаться по порядку. т.е. если вы обращаетесь к полю с индексом 1, то индекс поля 0 будет недоступен.
`getAsType`
  Тип данных PHP для возвращаемых данных поля. Если этот параметр не установлен, данные поля будут возвращены как тип данных PHP по умолчанию. Для получения информации о типах данных PHP по умолчанию смотрите » Типы данных PHP по умолчанию в документации Microsoft SQLSRV.

### Возвращаемые значения

В случае успешного выполнения возвращает данные из указанного поля. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования sqlsrv_get_field()

В следующем примере показано, как получить строку с помощью sqlsrv_fetch() и получить поля строки с помощью sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Сделайте первую (и в данном случае единственную) строку набора результатов доступной для чтения.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Получите поля строки. Индексы полей начинаются с 0 и должны извлекаться по порядку.
    // Получение полей строки по имени не поддерживается sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Смотрите также

- sqlsrv_fetch() - Делает следующую строку в наборе результатов доступной для чтения
- sqlsrv_fetch_array() - Возвращает строку как массив
- sqlsrv_fetch_object() - Получает следующую строку данных в наборе результатов как объект

# sqlsrv_has_rows

(No version information available, might only be in Git)

sqlsrv_has_rows — Указывает, есть ли у указанного оператора строки

### Описание

function sqlsrv_has_rows(resource `$stmt`): bool

Указывает, есть ли у указанного оператора строки.

### Список параметров

`stmt`
  Ресурс оператора, возвращаемый sqlsrv_query() или sqlsrv_execute().

### Возвращаемые значения

Возвращает `true`, если в указанном операторе есть строки и `false`, если в операторе нет строк или произошла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_has_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

    if ($stmt) {
       $rows = sqlsrv_has_rows( $stmt );
       if ($rows === true)
          echo "Есть строки. <br />";
       else
          echo "Нет строк. <br />";
    }
    ?>

### Смотрите также

- sqlsrv_num_rows() - Получает количество строк в наборе результатов
- sqlsrv_query() - Подготавливает и выполняет запрос

# sqlsrv_next_result

(No version information available, might only be in Git)

sqlsrv_next_result — Делает активным следующий результат указанного оператора

### Описание

function sqlsrv_next_result(resource `$stmt`): mixed

Делает активным следующий результат указанного оператора. Результаты включают наборы результатов, количество строк и выходные параметры.

### Список параметров

`stmt`
  Оператор, по которому вызывается следующий результат.

### Возвращаемые значения

Возвращает `true`, если следующий результат был успешно получен, `false`, если произошла ошибка и `null`, если результатов для получения больше нет.

### Примеры

Пример #1 Пример использования sqlsrv_next_result()

В следующем примере выполняется пакетный запрос, который добавляет записи в таблицу, а затем выбирает данные из таблицы. Это даёт два результата оператора: один для строк, на которые влияет INSERT, и один для строк, возвращаемых SELECT. Чтобы перейти к строкам, возвращаемым SELECT, необходимо вызвать sqlsrv_next_result(), чтобы пройти мимо первого результата.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    $query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
    $params = array(1, "some data");
    $stmt = sqlsrv_query($conn, $query, $params);

    // Использовать первый результат (строки, затронутые INSERT) без вызова sqlsrv_next_result.
    echo "Затронуто строк: ".sqlsrv_rows_affected($stmt)."<br />";

    // Переход к следующему результату и отображение результатов.
    $next_result = sqlsrv_next_result($stmt);
    if( $next_result ) {
       while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
          echo $row['id'].": ".$row['data']."<br />";
       }
    } elseif( is_null($next_result)) {
         echo "Больше строк нет.<br />";
    } else {
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Смотрите также

- sqlsrv_query() - Подготавливает и выполняет запрос
- sqlsrv_fetch_array() - Возвращает строку как массив
- sqlsrv_rows_affected() - Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE

# sqlsrv_num_fields

(No version information available, might only be in Git)

sqlsrv_num_fields — Извлекает количество полей (столбцов) оператора

### Описание

function sqlsrv_num_fields(resource `$stmt`): mixed

Извлекает количество полей (столбцов) оператора.

### Список параметров

`stmt`
  Оператор, для которого возвращается количество полей. sqlsrv_num_fields() может вызываться для оператора до или после выполнения оператора.

### Возвращаемые значения

В случае успешного выполнения возвращает количество полей. В противном случае возвращает `false`.

### Примеры

Пример #1 Пример использования sqlsrv_num_fields()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_query($conn, $sql);
    if( $stmt === false) {
       die( print_r( sqlsrv_errors(), true));
    }

    $numFields = sqlsrv_num_fields( $stmt );

    while( sqlsrv_fetch( $stmt )) {
       // Пройдитесь по полям каждой строки.
       for($i = 0; $i < $numFields; $i++) {
          echo sqlsrv_get_field($stmt, $i)." ";
       }
       echo "<br />";
    }
    ?>

### Смотрите также

- sqlsrv_field_metadata() - Получает метаданные для полей оператора, подготовленного с помощью sqlsrv_prepare или sqlsrv_query
- sqlsrv_fetch() - Делает следующую строку в наборе результатов доступной для чтения
- sqlsrv_get_field() - Получает данные поля из текущей выбранной строки

# sqlsrv_num_rows

(No version information available, might only be in Git)

sqlsrv_num_rows — Получает количество строк в наборе результатов

### Описание

function sqlsrv_num_rows(resource `$stmt`): mixed

Извлекает количество строк в наборе результатов. Функция требует, чтобы ресурс оператора был создан с помощью статического курсора или курсора набора ключей. Для получения дополнительной информации смотрите описание функций sqlsrv_query(), sqlsrv_prepare() или » Указание типа курсора и выбор строк в документации Microsoft SQLSRV.

### Список параметров

`stmt`
  Оператор, для которого возвращается количество строк. Ресурс оператора должен быть создан с помощью статического курсора или курсора набора ключей. Для получения дополнительной информации смотрите описание функций sqlsrv_query(), sqlsrv_prepare() или » Указание типа курсора и выбор строк в документации Microsoft SQLSRV.

### Возвращаемые значения

Возвращает количество строк, полученных в случае успешного выполнения или `false` в случае возникновения ошибки. Если используется прямой курсор (по умолчанию) или динамический курсор, возвращается `false`.

### Примеры

Пример #1 Пример использования sqlsrv_num_rows()

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $sql = "SELECT * FROM Table_1";
    $params = array();
    $options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
    $stmt = sqlsrv_query( $conn, $sql , $params, $options );

    $row_count = sqlsrv_num_rows( $stmt );

    if ($row_count === false)
       echo "Ошибка при получении количества строк.";
    else
       echo $row_count;
    ?>

### Смотрите также

- sqlsrv_has_rows() - Указывает, есть ли у указанного оператора строки
- sqlsrv_rows_affected() - Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE

# sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_prepare — Подготавливает запрос к исполнению

### Описание

function sqlsrv_prepare(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Подготавливает запрос к исполнению. Функция идеально подходит для подготовки запроса, который будет выполняться несколько раз с разными значениями параметров.

### Список параметров

`conn`
  Ресурс подключения, возвращаемый sqlsrv_connect().
`sql`
  Строка, определяющая запрос, который нужно подготовить и выполнить.
`params`

  Массив, определяющий информацию о параметрах при выполнении запроса. Элементы массива могут быть любыми из следующих:

  - Строковое значение
  - Переменная PHP
  - Массив с такой структурой: array($value [, $direction [, $phpType [, $sqlType]]])
  В следующей таблице описаны элементы в структуре массива выше:

  Структура массива
  Элемент | Описание
  --- | ---
  $value | Строковое значение, переменная PHP или переменная PHP, переданная по ссылке.
  $direction (необязательный) | Одна из следующих констант SQLSRV, используемых для указания направления параметра: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. Значение по умолчанию - SQLSRV_PARAM_IN.
  $phpType (необязательный) | Константа SQLSRV_PHPTYPE_*, указывающая тип данных PHP возвращаемого значения.
  $sqlType (необязательный) | Константа SQLSRV_SQLTYPE_*, указывающая тип данных SQL Server входного значения.

`options`
  Массив, определяющий параметры свойств запроса. Поддерживаемые ключи описаны в следующей таблице:

  Опции запроса
  Ключ | Значения | Описание
  --- | --- | ---
  QueryTimeout | Положительное целочисленное значение. | Устанавливает время ожидания запроса в секундах. По умолчанию драйвер будет ожидать результатов бесконечно.
  SendStreamParamsAtExec | `true` или `false` (по умолчанию `true`) | Настраивает драйвер для отправки всех данных потока при выполнении (`true`) или для отправки данных потока частями (`false`). По умолчанию установлено значение `true`. Для получения дополнительной информации смотрите sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, или SQLSRV_CURSOR_KEYSET | Смотрите » Указание типа курсора и выбор строк в документации Microsoft SQLSRV.

### Возвращаемые значения

Возвращает ресурс оператора в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования sqlsrv_prepare()

В этом примере показано, как подготовить оператор с помощью sqlsrv_prepare() и повторно выполнить его несколько раз (с разными значениями параметров) с помощью sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Инициализация параметров и подготовка запроса.
    // Переменные $qty и $id связаны с оператором $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Настройка информации SalesOrderDetailID и OrderQty.
    // Этот массив сопоставляет идентификатор заказа с количеством заказа в парах ключ => значение.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Выполнение запроса для каждого заказа.
    foreach( $orders as $id => $qty) {
        // Поскольку $id и $qty привязаны к $stmt1,
        // их обновлённые значения используются при каждом выполнении запроса.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Примечания

Когда вы подготавливаете запрос, который использует переменные в качестве параметров, переменные привязываются к оператору. Это означает, что если вы обновите значения переменных, в следующий раз, когда вы выполните запрос, он будет работать с обновлёнными значениями параметров. Для операторов, которые вы планируете выполнить только один раз, используйте sqlsrv_query().

### Смотрите также

- sqlsrv_execute() - Выполняет запрос, подготовленный с помощью sqlsrv_prepare
- sqlsrv_query() - Подготавливает и выполняет запрос

# sqlsrv_query

(No version information available, might only be in Git)

sqlsrv_query — Подготавливает и выполняет запрос

### Описание

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Подготавливает и выполняет запрос.

### Список параметров

`conn`
  Ресурс подключения, возвращаемый sqlsrv_connect().
`sql`
  Строка, определяющая запрос, который нужно подготовить и выполнить.
`params`

  Массив, определяющий информацию о параметрах при выполнении параметризованного запроса. Элементы массива могут быть любыми из следующих:

  - Строкового значения
  - Переменной PHP
  - Массива со следующей структурой: array($value [, $direction [, $phpType [, $sqlType]]])
  В следующей таблице описаны элементы в структуре массива выше:

  Структура массива
  Элемент | Описание
  --- | ---
  $value | Строковое значение, переменная PHP или переменная PHP, переданная по ссылке.
  $direction (optional) | Одна из следующих констант SQLSRV, используемых для указания направления параметра: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. Значение по умолчанию - SQLSRV_PARAM_IN.
  $phpType (optional) | Константа SQLSRV_PHPTYPE_*, указывающая тип данных PHP возвращаемого значения.
  $sqlType (optional) | Константа SQLSRV_SQLTYPE_*, указывающая тип данных SQL Server входного значения.

`options`
  Массив, определяющий параметры свойств запроса. Поддерживаемые ключи описаны в следующей таблице:

  Свойства запроса
  Ключ | Значения | Описание
  --- | --- | ---
  QueryTimeout | Положительное целочисленное значение. | Устанавливает время ожидания запроса в секундах. По умолчанию драйвер будет ждать результатов бесконечно.
  SendStreamParamsAtExec | `true` или `false` (по умолчанию `true`) | Настраивает драйвер для отправки всех данных потока при выполнении (`true`) или для отправки данных потока частями (`false`). По умолчанию установлено значение `true`. Для получения дополнительной информации смотрите sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, или SQLSRV_CURSOR_KEYSET | Смотрите » Указание типа курсора и выбор строк в документации Microsoft SQLSRV.

### Возвращаемые значения

Возвращает ресурс выражения в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования sqlsrv_query()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
    $params = array(1, "some data");

    $stmt = sqlsrv_query( $conn, $sql, $params);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Примечания

Для операторов, которые вы планируете выполнить только один раз, используйте sqlsrv_query(). Если вы намереваетесь повторно выполнить выражение с другими значениями параметров, используйте комбинацию sqlsrv_prepare() и sqlsrv_execute().

### Смотрите также

- sqlsrv_prepare() - Подготавливает запрос к исполнению
- sqlsrv_execute() - Выполняет запрос, подготовленный с помощью sqlsrv_prepare

# sqlsrv_rollback

(No version information available, might only be in Git)

sqlsrv_rollback — Откатывает транзакцию, начатую sqlsrv_begin_transaction()

### Описание

function sqlsrv_rollback(resource `$conn`): bool

Откатывает транзакцию, начатую sqlsrv_begin_transaction() и возвращает соединение с режимом автоматической фиксации.

### Список параметров

`conn`
  Ресурс подключения, возвращаемый вызовом sqlsrv_connect().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования sqlsrv_rollback()

В следующем примере показано, как использовать sqlsrv_begin_transaction() вместе с sqlsrv_commit() или sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Начало транзакции. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Инициализация значений параметров. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Настройка и выполнение первого запроса */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Настройка и выполнение второго запроса */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* Если оба запроса выполнены успешно, зафиксируйте транзакцию. */
    /* В противном случае, откатите транзакцию. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Транзакция зафиксирована.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Транзакция откачена.<br />";
    }
    ?>

### Смотрите также

- sqlsrv_begin_transaction() - Начинает транзакцию базы данных
- sqlsrv_commit() - Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction

# sqlsrv_rows_affected

(No version information available, might only be in Git)

sqlsrv_rows_affected — Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE

### Описание

function sqlsrv_rows_affected(resource `$stmt`): int|false

Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE. Для получения информации о количестве строк, возвращаемых запросом SELECT, смотрите sqlsrv_num_rows().

### Список параметров

`stmt`
  Ресурс выполненного выражения, для которого возвращается количество затронутых строк.

### Возвращаемые значения

Возвращает количество строк, затронутых последним запросом INSERT, UPDATE или DELETE. Если никакие строки не были затронуты, возвращается 0. Если количество затронутых строк не может быть определено, возвращается -1. В случае возникновения ошибки возвращается `false`.

### Примеры

Пример #1 Пример использования sqlsrv_rows_affected()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

    $params = array("updated data", 1);

    $stmt = sqlsrv_query( $conn, $sql, $params);

    $rows_affected = sqlsrv_rows_affected( $stmt);
    if( $rows_affected === false) {
         die( print_r( sqlsrv_errors(), true));
    } elseif( $rows_affected == -1) {
          echo "Нет доступной информации.<br />";
    } else {
          echo $rows_affected." строк было обновлено.<br />";
    }
    ?>

### Смотрите также

- sqlsrv_num_rows() - Получает количество строк в наборе результатов

# sqlsrv_send_stream_data

(No version information available, might only be in Git)

sqlsrv_send_stream_data — Отправляет данные из потоков параметров на сервер

### Описание

function sqlsrv_send_stream_data(resource `$stmt`): bool

Отправлять данные из потоков параметров на сервер. При каждом вызове отправляется до 8 КБ данных.

### Список параметров

`stmt`
  Ресурс выражения, возвращаемый sqlsrv_query() или sqlsrv_execute().

### Возвращаемые значения

Возвращает `true`, если есть ещё данные для отправки и `false`, если нет.

### Примеры

Пример #1 Пример использования sqlsrv_send_stream_data()

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

    // Откройте данные параметров как поток и поместите их в массив $params.
    $data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
    $params = array( &$data);

    // Подготовьте выражение. Используйте массив $options, чтобы
    // отключить поведение по умолчанию, которое заключается в отправке всех данных
    // потока во время выполнения запроса.
    $options = array("SendStreamParamsAtExec"=>0);
    $stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

    sqlsrv_execute( $stmt);

    // Отправляйте до 8 КБ данных параметров на сервер
    // при каждом вызове sqlsrv_send_stream_data.
    $i = 1;
    while( sqlsrv_send_stream_data( $stmt)) {
          $i++;
    }
    echo "$i вызовов было сделано.";
    ?>

### Смотрите также

- sqlsrv_prepare() - Подготавливает запрос к исполнению
- sqlsrv_query() - Подготавливает и выполняет запрос

# sqlsrv_server_info

(No version information available, might only be in Git)

sqlsrv_server_info — Возвращает информацию о сервере

### Описание

function sqlsrv_server_info(resource `$conn`): array

Возвращает информацию о сервере.

### Список параметров

`conn`
  Ресурс подключения, который соединяет клиент и сервер.

### Возвращаемые значения

Возвращает массив, описанный в таблице:

Возвращаемый массив
CurrentDatabase | Подключённая база данных.
--- | ---
SQLServerVersion | Версия SQL Server.
SQLServerName | Имя сервера.

### Примеры

Пример #1 Пример использования sqlsrv_server_info()

    <?php
    $serverName = "serverName\sqlexpress";
    $conn = sqlsrv_connect( $serverName);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $server_info = sqlsrv_server_info( $conn);
    if( $server_info )
    {
        foreach( $server_info as $key => $value) {
           echo $key.": ".$value."<br />";
        }
    } else {
          die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Смотрите также

- sqlsrv_client_info() - Возвращает информацию о клиенте и указанном подключении

## Содержание

- sqlsrv_begin_transaction — Начинает транзакцию базы данных
- sqlsrv_cancel — Отменяет оператор
- sqlsrv_client_info — Возвращает информацию о клиенте и указанном подключении
- sqlsrv_close — Закрывает открытое соединение и освобождает ресурсы, связанные с этим соединением
- sqlsrv_commit — Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction
- sqlsrv_configure — Изменяет конфигурацию обработки ошибок драйвера и ведения журнала
- sqlsrv_connect — Открывает соединение с базой данных Microsoft SQL Server
- sqlsrv_errors — Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV
- sqlsrv_execute — Выполняет запрос, подготовленный с помощью sqlsrv_prepare
- sqlsrv_fetch — Делает следующую строку в наборе результатов доступной для чтения
- sqlsrv_fetch_array — Возвращает строку как массив
- sqlsrv_fetch_object — Получает следующую строку данных в наборе результатов как объект
- sqlsrv_field_metadata — Получает метаданные для полей оператора, подготовленного с помощью sqlsrv_prepare или sqlsrv_query
- sqlsrv_free_stmt — Освобождает все ресурсы для указанного оператора
- sqlsrv_get_config — Возвращает значение указанного параметра конфигурации
- sqlsrv_get_field — Получает данные поля из текущей выбранной строки
- sqlsrv_has_rows — Указывает, есть ли у указанного оператора строки
- sqlsrv_next_result — Делает активным следующий результат указанного оператора
- sqlsrv_num_fields — Извлекает количество полей (столбцов) оператора
- sqlsrv_num_rows — Получает количество строк в наборе результатов
- sqlsrv_prepare — Подготавливает запрос к исполнению
- sqlsrv_query — Подготавливает и выполняет запрос
- sqlsrv_rollback — Откатывает транзакцию, начатую sqlsrv_begin_transaction
- sqlsrv_rows_affected — Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE
- sqlsrv_send_stream_data — Отправляет данные из потоков параметров на сервер
- sqlsrv_server_info — Возвращает информацию о сервере

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Функции SQLSRV
  - sqlsrv_begin_transaction — Начинает транзакцию базы данных
  - sqlsrv_cancel — Отменяет оператор
  - sqlsrv_client_info — Возвращает информацию о клиенте и указанном подключении
  - sqlsrv_close — Закрывает открытое соединение и освобождает ресурсы, связанные с этим соединением
  - sqlsrv_commit — Фиксирует транзакцию, начатую с помощью sqlsrv_begin_transaction
  - sqlsrv_configure — Изменяет конфигурацию обработки ошибок драйвера и ведения журнала
  - sqlsrv_connect — Открывает соединение с базой данных Microsoft SQL Server
  - sqlsrv_errors — Возвращает информацию об ошибке и предупреждении последней выполненной операции SQLSRV
  - sqlsrv_execute — Выполняет запрос, подготовленный с помощью sqlsrv_prepare
  - sqlsrv_fetch — Делает следующую строку в наборе результатов доступной для чтения
  - sqlsrv_fetch_array — Возвращает строку как массив
  - sqlsrv_fetch_object — Получает следующую строку данных в наборе результатов как объект
  - sqlsrv_field_metadata — Получает метаданные для полей оператора, подготовленного с помощью sqlsrv_prepare или sqlsrv_query
  - sqlsrv_free_stmt — Освобождает все ресурсы для указанного оператора
  - sqlsrv_get_config — Возвращает значение указанного параметра конфигурации
  - sqlsrv_get_field — Получает данные поля из текущей выбранной строки
  - sqlsrv_has_rows — Указывает, есть ли у указанного оператора строки
  - sqlsrv_next_result — Делает активным следующий результат указанного оператора
  - sqlsrv_num_fields — Извлекает количество полей (столбцов) оператора
  - sqlsrv_num_rows — Получает количество строк в наборе результатов
  - sqlsrv_prepare — Подготавливает запрос к исполнению
  - sqlsrv_query — Подготавливает и выполняет запрос
  - sqlsrv_rollback — Откатывает транзакцию, начатую sqlsrv_begin_transaction
  - sqlsrv_rows_affected — Возвращает количество строк, изменённых последним выполненным запросом INSERT, UPDATE или DELETE
  - sqlsrv_send_stream_data — Отправляет данные из потоков параметров на сервер
  - sqlsrv_server_info — Возвращает информацию о сервере

- CUBRID
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции CUBRID
  - Функции совместимости CUBRID MySQL
  - Устаревшие псевдонимы и функции CUBRID
- dBase
  - Установка и настройка
  - Предопределённые константы
  - dBase
- Firebird/InterBase
  - Установка и настройка
  - Предопределённые константы
  - Функции Firebird/InterBase
- IBM DB2 — IBM DB2, Cloudscape и Apache Derby
  - Установка и настройка
  - Предопределённые константы
  - Функции IBM DB2
- MongoDB — Модуль MongoDB
  - Установка и настройка
  - Предопределённые константы
  - Обучающие материалы
  - Архитектура и внутреннее устройство драйвера — Обзор архитектуры драйвера и её особенностей
  - Безопасность
  - MongoDB\Driver — Классы модуля MongoDB
  - MongoDB\BSON — Классы и функции модуля MongoDB для работы с форматом BSON
  - MongoDB\Driver\Monitoring — Классы мониторинга и функции подписчика
  - MongoDB\Driver\Exception — Классы исключений
- MySQL — Драйверы и плагины MySQL
  - Обзор PHP-драйверов MySQL
  - MySQLi — Улучшенный модуль MySQL (MySQL Improved)
  - Mysql_xdevapi
  - Оригинальный MySQL — Оригинальный API-интерфейс доступа к MySQL-серверам
  - Mysqlnd — Встроенный драйвер MySQL
- OCI8 — Oracle OCI8
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Работа с соединениями OCI8 и Connection Pooling
  - Поддержка OCI8 Fast Application Notification (FAN)
  - Поддержка прозрачного для приложений восстановления после отказа (Transparent Application Failover или TAF) для OCI8
  - OCI8 и динамическая трассировка DTrace
  - Поддерживаемые типы данных
  - OCI8 Функции
  - OCICollection — Класс OCICollection
  - OCILob — Класс OCILob
  - Устаревшие наименования и функции OCI8
- PostgreSQL
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции PostgreSQL
  - PgSql\Connection — Класс PgSql\Connection
  - PgSql\Result — Класс PgSql\Result
  - PgSql\Lob — Класс PgSql\Lob
- SQLite3
  - Установка и настройка
  - Предопределённые константы
  - SQLite3 — Класс SQLite3
  - SQLite3Exception — Класс SQLite3Exception
  - SQLite3Stmt — Класс SQLite3Stmt
  - SQLite3Result — Класс SQLite3Result
- SQLSRV — Драйвер СУБД Microsoft SQL Server для PHP
  - Установка и настройка
  - Предопределённые константы
  - Функции SQLSRV

- Уровни абстракции
  - DBA — Database (dbm-style) Abstraction Layer
  - ODBC — Модуль Unified ODBC
  - PDO — Модуль доступа к базам данных PHP Data Objects
- Модули для работы с базами данных отдельных производителей
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — IBM DB2, Cloudscape и Apache Derby
  - MongoDB — Модуль MongoDB
  - MySQL — Драйверы и плагины MySQL
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Драйвер СУБД Microsoft SQL Server для PHP

# Модули для работы с датой и временем

# Календарь

# Введение

Модуль календарь предоставляет ряд функций для упрощения перевода дат из одного формата в другой. Промежуточной датой или стандартом является исчисление с Юлианского дня. Исчисление с Юлианского дня - это исчисление, начинающееся с 1 января 4713г. до н.э. Для конвертации между календарными форматами сначала нужно перевести дату в Юлианское исчисление, а затем в любой другой календарный формат на ваш выбор. Юлианское исчисление сильно отличается от Юлианского календаря! Для более подробной информации посетите страницу » http://www.hermetic.ch/cal_stud/jdn.htm. Подробная информации по календарным форматам: » http://www.fourmilab.ch/documents/calendar/. Выдержки из этой страницы включены в инструкцию и заключены в кавычки.

# Установка и настройка

## Содержание

- Установка

## Установка

Для работы с данными функциями нужно скомпилировать PHP c --enable-calendar.

В версию PHP для Windows встроили поддержку модуля PCRE. Доступ к функциям модуля открыт без загрузки дополнительных модулей.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`CAL_EASTER_DEFAULT` (int)
  Для easter_days(): вычислять Пасху для лет до 1753 года по юлианскому календарю, а в последующие годы по григорианскому календарю.
`CAL_EASTER_ROMAN` (int)
  Для easter_days(): вычислять Пасху для лет до 1583 года по юлианскому календарю, а в последующие годы по григорианскому календарю.
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  Для easter_days(): вычислять Пасху в соответствии с пролептическим григорианским календарём.
`CAL_EASTER_ALWAYS_JULIAN` (int)
  Для easter_days(): вычислять Пасху в соответствии с юлианским календарём.
`CAL_GREGORIAN` (int)
  Для cal_days_in_month(), cal_from_jd(), cal_info() и cal_to_jd(): использовать пролептический григорианский календарь.
`CAL_JULIAN` (int)
  Для cal_days_in_month(), cal_from_jd(), cal_info() и cal_to_jd(): использовать юлианский календарь.
`CAL_JEWISH` (int)
  Для cal_days_in_month(), cal_from_jd(), cal_info() и cal_to_jd(): использовать еврейский календарь.
`CAL_FRENCH` (int)
  Для cal_days_in_month(), cal_from_jd(), cal_info() и cal_to_jd(): использовать французский республиканский календарь.
`CAL_NUM_CALS` (int)
  Количество доступных календарей.
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  Для jdtojewish(): добавляет знак гореш (geresh), напоминающий одинарную кавычку в качестве разделителя тысяч для количества лет.
`CAL_JEWISH_ADD_ALAFIM` (int)
  Для jdtojewish(): добавляет слово alafim в качестве разделителя тысяч для количества лет.
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  For jdtojewish(): добавить символ гершаим (gershayim), напоминающий двойную кавычку перед последней буквой дня и числом лет
`CAL_DOW_DAYNO` (int)
  Для jddayofweek(): день недели в виде целого числа (int), где `0` означает воскресенье, а `6` означает субботу.
`CAL_DOW_SHORT` (int)
  Для jddayofweek(): сокращённое английское название дня недели.
`CAL_DOW_LONG` (int)
  Для jddayofweek(): английское название дня недели.
`CAL_MONTH_GREGORIAN_SHORT` (int)
  Для jdmonthname(): сокращённое григорианское название месяца.
`CAL_MONTH_GREGORIAN_LONG` (int)
  Для jdmonthname(): григорианское название месяца.
`CAL_MONTH_JULIAN_SHORT` (int)
  Для jdmonthname(): сокращённое юлианское название месяца.
`CAL_MONTH_JULIAN_LONG` (int)
  Для jdmonthname(): юлианское название месяца.
`CAL_MONTH_JEWISH` (int)
  Для jdmonthname(): еврейское название месяца.
`CAL_MONTH_FRENCH` (int)
  Для jdmonthname(): французское республиканское название месяца.

# Календарь

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — Возвращает количество дней в месяце для заданного года и календаря

### Описание

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

Эта функция возвращает количество дней в месяце `month` года `year` для заданного календаря `calendar`.

### Список параметров

`calendar`

  Календарь, используемый для вычисления

`month`

  Месяц в выбранном календаре

`year`

  Год в выбранном календаре

### Возвращаемые значения

Количество дней в конкретном месяце выбранного календаря

### Примеры

Пример #1 Пример использования cal_days_in_month()

    <?php
    $number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "Всего {$number} дней в Августе 2003 года";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря

### Описание

function cal_from_jd(int `$julian_day`, int `$calendar`): array

Функция cal_from_jd() преобразовывает дату юлианского календаря, заданную в параметре `julian_day`, в дату указанного в параметре `calendar` календаря. Поддерживаемые параметром `calendar` значения: `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` и `CAL_FRENCH`.

### Список параметров

`julian_day`

  День юлианского календаря как целое число.

`calendar`

  Календарь, в который нужно преобразовать дату.

### Возвращаемые значения

Возвращает массив, содержащий информацию о дате, такую как месяц, день, год, день недели (`dow`), сокращённое и полное название дня недели, месяца и дату в форме "месяц/день/год". День недели варьируется от `0` (воскресенье) to `6` (суббота).

### Примеры

Пример #1 Пример использования cal_from_jd()

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [date] => 8/16/2003
        [month] => 8
        [day] => 16
        [year] => 2003
        [dow] => 6
        [abbrevdayname] => Sat
        [dayname] => Saturday
        [abbrevmonth] => Aug
        [monthname] => August
    )

### Смотрите также

- cal_to_jd() - Преобразовывает заданную дату в юлианскую
- jdtofrench() - Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю
- jdtogregorian() - Переводит число дней в юлианском летоисчислении в дату по Григорианскому календарю
- jdtojewish() - Переводит количество дней из юлианского календаря в дату по еврейскому календарю
- jdtojulian() - Переводит число дней в юлианском летоисчислении в дату по юлианскому календарю
- jdtounix() - Переводит число дней в юлианском летоисчислении в метку времени Unix

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — Возвращает информацию о заданном календаре

### Описание

function cal_info(int `$calendar` = -1): array

cal_info() возвращает информацию о заданном календаре `calendar`.

Информация о календаре возвращается в виде массива с элементами `calname`, `calsymbol`, `month`, `abbrevmonth` и `maxdaysinmonth` В качестве `calendar` могут быть использованы следующие названия календарей:

- 0 or `CAL_GREGORIAN` - Григорианский календарь
- 1 or `CAL_JULIAN` - Юлианский календарь
- 2 or `CAL_JEWISH` - Еврейский календарь
- 3 or `CAL_FRENCH` - Календарь со дня Французской революции

Если параметр `calendar` не задан, возвращается информация о всех поддерживаемых календарях в виде массива.

### Список параметров

`calendar`

  Календарь, о котором будет возвращена информация. Если параметр не задан, возвращается информация обо всех календарях.

### Возвращаемые значения

### Примеры

Пример #1 Пример cal_info()

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [months] => Array
            (
                [1] => January
                [2] => February
                [3] => March
                [4] => April
                [5] => May
                [6] => June
                [7] => July
                [8] => August
                [9] => September
                [10] => October
                [11] => November
                [12] => December
            )

        [abbrevmonths] => Array
            (
                [1] => Jan
                [2] => Feb
                [3] => Mar
                [4] => Apr
                [5] => May
                [6] => Jun
                [7] => Jul
                [8] => Aug
                [9] => Sep
                [10] => Oct
                [11] => Nov
                [12] => Dec
            )

        [maxdaysinmonth] => 31
        [calname] => Gregorian
        [calsymbol] => CAL_GREGORIAN
    )

# cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — Преобразовывает заданную дату в юлианскую

### Описание

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

Функция cal_to_jd() рассчитывает количество дней в юлианском календаре для даты в указанном календаре `calendar`. Список поддерживаемых календарей `calendar`: `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` и `CAL_FRENCH`.

### Список параметров

`calendar`

  Календарь, из которого будет произведена конвертация, одна из констант: `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` или `CAL_FRENCH`.

`month`

  Месяц в виде числа, разрешённый диапазон зависит от календаря `calendar`.

`day`

  День в виде числа, разрешённый диапазон зависит от календаря `calendar`.

`year`

  Год в виде числа, разрешённый диапазон зависит от календаря `calendar`.

### Возвращаемые значения

Возвращает количество дней в юлианском календаре.

### Смотрите также

- cal_from_jd() - Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря
- frenchtojd() - Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении
- gregoriantojd() - Преобразовывает дату по григорианскому календарю в количество дней в юлианском летоисчислении
- jewishtojd() - Переводит дату по еврейскому календарю в число дней в юлианском летоисчислении
- juliantojd() - Переводит дату по юлианскому календарю в число дней в юлианском летоисчислении
- unixtojd() - Переводит метку времени Unix в юлианский день

# easter_date

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

easter_date — Получает метку времени Unix, которая соответствует местной полночи на Пасху в заданном году

### Описание

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Функция возвращает метку времени Unix, которая соответствует местной полночи на Пасху в заданном году.

Дату Пасхи установили на Первом Никейском соборе в 325 году до н. э. в честь воскресенья, которое следовало за полнолунием, которое наступило в день или после весеннего равноденствия. Древние считали, что День весеннего равноденствия всегда наступает 21 марта, поэтому расчёт дня Пасхи сводился к определению даты полнолуния и следующего за ней воскресенья. Алгоритм, которым пользуется функция, ввёл Дионисий Малой около 532 года. В юлианском летоисчислении (до 1753 года) для отслеживания фаз луны брали простой 19-летний цикл. В григорианском календаре (годы после 1753 — разработал Христофор Клавиус и Алоизий Лилиус, а ввёл Папа Григорий XIII в октябре 1582, а в Великобритании и её колониях в сентябре 1752 г.) добавили 2 поправочных коэффициента, которые увеличили точность расчёта дат.

### Список параметров

`year`

  Год указывается как число от 1970 до 2037 для 32-битных или 2 000 000 000 для 64-битных систем. Функция возьмёт текущий год по местному времени, если год не указали или значение параметра равно `null`.

`mode`

  Разрешает рассчитывать даты Пасхи на основе Юлианского календаря, если установили значение `CAL_EASTER_ALWAYS_JULIAN`. Смотрите также константы календаря.

### Возвращаемые значения

Функция возвращает дату Пасхи в виде метки времени Unix.

### Ошибки

Функция выбросит ошибку ValueError, если значение года окажется меньше 1970 или больше 2037 для 32-битных или 2 000 000 000 для 64-битных систем.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | На 64-битных системах параметр `year` теперь принимает значения в диапазоне от 1970 до 2 000 000 000.
8.0.0 | Параметр `year` теперь принимает значение `null`.
8.0.0 | Функция выбрасывает ошибку ValueError, если значение параметра `year` выходит за пределы допустимого диапазона. Раньше вызывалась ошибка уровня `E_WARNING` и функция возвращала `false`.

### Примеры

Пример #1 Пример получения метки времени Unix функцией easter_date()

    <?php

    echo date("M-d-Y", easter_date(1999)); // Apr-04-1999
    echo date("M-d-Y", easter_date(2000)); // Apr-23-2000
    echo date("M-d-Y", easter_date(2001)); // Apr-15-2001

    ?>

Пример #2 Пример получения метки времени Unix функцией easter_date() с объектом класса DateTime

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### Примечания

> Замечание:

> Функция easter_date() полагается не на внутренние PHP-функции, которые работают с датой и временем, а на системные функции библиотеки языка Си. Поэтому для определения часового пояса, в котором она должна работать, функция easter_date() использует переменную окружения `TZ`, а не часовой пояс по умолчанию, который установили в PHP, что иногда приводит к неожиданному поведению в сочетании с другими функциями PHP для работы с датами.

> Как обходным путём для расчёта начала Пасхи в текущем часовом поясе PHP пользуются функцией easter_days() с объектами классов DateTime и DateInterval:

>     <?php

>     function get_easter_datetime($year)
>     {
>         $base = new DateTime("$year-03-21");
>         $days = easter_days($year);

>         return $base->add(new DateInterval("P{$days}D"));
>     }

>     foreach (range(2012, 2015) as $year) {
>         printf(
>             "Пасха в %d году приходится на %s\n",
>             $year,
>             get_easter_datetime($year)->format('F j')
>         );
>     }

>     ?>

> Результат выполнения приведённого примера:

>     Пасха в 2012 году приходится на April 8
>     Пасха в 2013 году приходится на March 31
>     Пасха в 2014 году приходится на April 20
>     Пасха в 2015 году приходится на April 5

### Смотрите также

- easter_days() - Получает количество дней между 21 марта и Пасхой в заданном году для расчёта дня Пасхи до 1970 или после 2037 года

# easter_days

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

easter_days — Получает количество дней между 21 марта и Пасхой в заданном году

### Описание

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

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

Эту функцию можно использовать вместо easter_date() для расчёта даты Пасхи для дат, выходящих за рамки диапазона временных меток Unix (с 1970 по 2037 годы).

Дата Пасхального дня была введена Консулом Никеи в 325 году до н.э. Это первое воскресенье, следующее за первым полнолунием после весеннего равноденствия. Днём весеннего равноденствия принято считать 21 марта, так что расчёт дня Пасхи сводится к определению даты полнолуния и следующего за ней воскресенья. Используемый здесь алгоритм введён Дионисием Малым в 532 году. В юлианском летоисчислении (до 1753 года) для отслеживания фаз луны использовался простой 19-летний цикл. В григорианском календаре (годы после 1753 - разработан Христофором Клавиусом и Алоизием Лилиусом и введён Папой Григорием XIII в октябре 1582г., а в Великобритании и её колониях в сентябре 1752г.) было добавлено 2 поправочных коэффициента увеличивающих точность расчёта дат.

### Список параметров

`year`

  Год, положительное число. Если не задан или `null`, используется текущий год в соответствии с локальным временем сервера.

`mode`

  Позволяет рассчитать Пасхальные даты, основываясь на григорианском календаре для 1582 - 1752 годов, если установить `CAL_EASTER_ROMAN`. Смотрите список констант календаря, чтобы узнать о всех допустимых константах.

### Возвращаемые значения

Количество дней между 21 марта и Пасхальным воскресеньем в заданном году `year`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `year` теперь допускает значение null.

### Примеры

Пример #1 Пример использования easter_days()

    <?php

    echo easter_days(1999);        // 14, т.e. April 4
    echo easter_days(1492);        // 32, т.e. April 22
    echo easter_days(1913);        //  2, т.e. March 23

    ?>

### Смотрите также

- easter_date() - Получает метку времени Unix, которая соответствует местной полночи на Пасху в заданном году

# frenchtojd

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

frenchtojd — Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении

### Описание

function frenchtojd(int `$month`, int `$day`, int `$year`): int

Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении.

Функция преобразовывает даты только с 1 по 14 годов (григорианские даты с 22 сентября 1792 г. по 22 сентября 1806 г.) Это более чем охватывает период, когда этот календарь использовался.

### Список параметров

`month`

  Месяц в виде числа от 1 (для месяца Vendémiaire) до 13 (для периода 5-6 дней в конце каждого года)

`day`

  День в виде числа от 1 до 30

`year`

  Год в виде числа между 1 и 14

### Возвращаемые значения

Возвращает количество дней в юлианском летоисчислении для заданной даты по французскому республиканскому календарю.

### Смотрите также

- jdtofrench() - Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю
- cal_to_jd() - Преобразовывает заданную дату в юлианскую

# gregoriantojd

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

gregoriantojd — Преобразовывает дату по григорианскому календарю в количество дней в юлианском летоисчислении

### Описание

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

Разрешённый диапазон дат для григорианского календаря с 25 ноября 4714 года до н. э. по 31 декабря 9999 год н. э.

Несмотря на возможность обработки дат вплоть до 4714 года до н. э., такое использование имеет мало смысла. Григорианский календарь не существовал до 15 октября 1582 года (или 5 октября 1582 в юлианском календаре). Некоторые страны не переходили на этот календарь очень долгое время. Например, Великобритания совершила переход в 1752 году, СССР в 1918 г., Греция в 1923 г. Большинство стран Европы предпочитали юлианский календарь григорианскому.

### Список параметров

`month`

  Месяц в виде числа от 1 (январь) до 12 (декабрь)

`day`

  День в виде числа от 1 до 31. Если в месяце меньше дней, чем передано, то произойдёт переполнение; смотрите пример ниже.

`year`

  Года в виде числа от -4714 до 9999. Отрицательные числа означают года до н. э., положительные - н. э. Обратите внимание, что не существует года `0`; 31 декабря 1 года до н. э. следует сразу после 1 января 1 года н. э.

### Возвращаемые значения

Возвращает количество дней в юлианском летоисчислении для даты по григорианскому календарю. Даты за пределами допустимого диапазона вернут `0`.

### Примеры

Пример #1 Календарные функции

    <?php
    $jd = gregoriantojd(10, 11, 1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

Результат выполнения приведённого примера:

    2440871
    10/11/1970

Пример #2 Поведение при переполнении

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    2458181
    2458181

### Смотрите также

- jdtogregorian() - Переводит число дней в юлианском летоисчислении в дату по Григорианскому календарю
- cal_to_jd() - Преобразовывает заданную дату в юлианскую

# jddayofweek

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

jddayofweek — Возвращает день недели

### Описание

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

Возвращает день недели. Может возвращать строку или число в зависимости от режима работы.

### Список параметров

`julian_day`

  День в виде числа в юлианском летоисчислении

`mode`

  Режимы отображения дней недели
  Режим | Значение
  --- | ---
  0 (По умолчанию) | День недели возвращается в виде числа (0=Воскресенье, 1=Понедельник и т.д.)
  1 | Возвращается строка, содержащая день недели (Английский-Григорианский)
  2 | Возвращается строка, содержащая аббревиатуру дня недели (Английскую-Григорианскую)

### Возвращаемые значения

День недели по григорианскому календарю в виде строки или числа.

# jdmonthname

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

jdmonthname — Возвращает название месяца

### Описание

function jdmonthname(int `$julian_day`, int `$mode`): string

Возвращает строку, содержащую название месяца. `mode` задаёт режим работы функции преобразования из числа дней в юлианском летоисчислении, а также определяет тип возвращаемого значения названия месяца.

Режимы работы
Режим | Название месяца | Значения
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | Григорианское - сокращённое | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | Григорианское | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | Юлианское - сокращённое | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | Юлианское | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | Еврейское | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | Французское республиканское | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### Список параметров

`julian_day`

  Число дней в юлианском летоисчислении, которое требуется преобразовать

`mode`

  Режим календаря (смотрите таблицу выше)

### Возвращаемые значения

Название месяца для заданного Юлианского Дня, соответствующее календарю `mode`.

# jdtofrench

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

jdtofrench — Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю

### Описание

function jdtofrench(int `$julian_day`): string

Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю

### Список параметров

`julian_day`

  Номер дня в юлианском летоисчислении

### Возвращаемые значения

Дата со дня французской революции в виде строки формата "месяц/день/год"

### Смотрите также

- frenchtojd() - Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении
- cal_from_jd() - Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря

# jdtogregorian

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

jdtogregorian — Переводит число дней в юлианском летоисчислении в дату по Григорианскому календарю

### Описание

function jdtogregorian(int `$julian_day`): string

Переводит число дней в юлианском летоисчислении в строку, содержащую григорианскую дату в формате "месяц/день/год".

### Список параметров

`julian_day`

  Номер дня в юлианском летоисчислении в виде целого числа

### Возвращаемые значения

Дата по григорианскому календарю в виде строки формата "месяц/день/год"

### Смотрите также

- gregoriantojd() - Преобразовывает дату по григорианскому календарю в количество дней в юлианском летоисчислении
- cal_from_jd() - Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря

# jdtojewish

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

jdtojewish — Переводит количество дней из юлианского календаря в дату по еврейскому календарю

### Описание

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

Переводит количество дней из юлианского календаря в дату по еврейскому календарю.

### Список параметров

`julian_day`

  Номер дня в юлианском летоисчислении в виде целого числа

`hebrew`

  Если аргумент `hebrew` установлен в `true`, дата будет возвращена в виде закодированной строки ISO-8859-8 в еврейском формате, заданном аргументом `flags`.

`flags`

  Битовая маска может состоять из: `CAL_JEWISH_ADD_ALAFIM_GERESH`, `CAL_JEWISH_ADD_ALAFIM` и `CAL_JEWISH_ADD_GERESHAYIM`.

### Возвращаемые значения

Еврейская дата в виде строки формата "месяц/день/год" или закодированная строка ISO-8859-8 даты на иврите в соответствии с параметром `hebrew`.

### Примеры

Пример #1 Пример использования jdtojewish()

    <?php
    $jd = gregoriantojd(10, 8, 2002);
    echo jdtojewish($jd, true), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
         jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### Смотрите также

- jewishtojd() - Переводит дату по еврейскому календарю в число дней в юлианском летоисчислении
- cal_from_jd() - Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря

# jdtojulian

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

jdtojulian — Переводит число дней в юлианском летоисчислении в дату по юлианскому календарю

### Описание

function jdtojulian(int `$julian_day`): string

Переводит число дней в юлианском летоисчислении в строку, содержащую дату по юлианскому календарю в формате "месяц/день/год".

### Список параметров

`julian_day`

  Номер дня в юлианском летоисчислении

### Возвращаемые значения

Дата по юлианскому календарю в виде строки формата "месяц/день/год"

### Смотрите также

- juliantojd() - Переводит дату по юлианскому календарю в число дней в юлианском летоисчислении
- cal_from_jd() - Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря

# jdtounix

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

jdtounix — Переводит число дней в юлианском летоисчислении в метку времени Unix

### Описание

function jdtounix(int `$julian_day`): int

Эта функция вернёт метку времени Unix, соответствующую номеру дня в юлианском летоисчислении, заданному в `julian_day`. Будет возвращено UTC.

### Список параметров

`julian_day`

  Номер дня в юлианском летоисчислении между `2440588` и `106751993607888` в 64-битных системах или между `2440588` и `2465443` в 32-битных системах.

### Возвращаемые значения

Метка времени Unix на момент начала (полночь) юлианского дня.

### Ошибки

Если `julian_day` находится за пределами допустимого диапазона, выбрасывается ValueError.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция больше не возвращает `false` в случае возникновения ошибки, вместо этого выбрасывает ValueError.
7.3.24, 7.4.12 | Увеличен верхний предел `julian_day`. Раньше он был `2465342` независимо от архитектуры.

### Смотрите также

- unixtojd() - Переводит метку времени Unix в юлианский день

# jewishtojd

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

jewishtojd — Переводит дату по еврейскому календарю в число дней в юлианском летоисчислении

### Описание

function jewishtojd(int `$month`, int `$day`, int `$year`): int

Несмотря на то, что функция может обрабатывать даты вплоть до 1-го года (3761 до н.э.), практически преобразование для таких ранних дат не имеет смысла. Еврейский календарь использовался несколько тысяч лет, но давние времена не было формулы для расчёта начала месяца. Новый месяц начинался с того момента как впервые можно было наблюдать новую луну.

### Список параметров

`month`

  Номер месяца в виде числа от 1 до 13, где `1` означает `Тишрей`, `13` означает `Элул`, и `6` и `7` означает `Адар` в обычном году, но `Адар I` и `Адар II`, соответственно, в високосном.

`day`

  Номер дня в виде числа от 1 до 30. Если в месяце всего 29 дней, то будет подразумеваться первый день следующего месяца.

`year`

  Год в виде числа от 1 до 9999

### Возвращаемые значения

Номер дня в юлианском летоисчислении в виде числа для заданной еврейской даты.

### Смотрите также

- jdtojewish() - Переводит количество дней из юлианского календаря в дату по еврейскому календарю
- cal_to_jd() - Преобразовывает заданную дату в юлианскую

# juliantojd

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

juliantojd — Переводит дату по юлианскому календарю в число дней в юлианском летоисчислении

### Описание

function juliantojd(int `$month`, int `$day`, int `$year`): int

Диапазон возможных дат для юлианского календаря: с 4713 года до н.э. по 9999 год н.э.

Несмотря на то, что функция может обрабатывать даты вплоть до 4713 года до н.э., практически преобразование для таких ранних дат не имеет смысла. Календарь был создан в 46 году до н.э., но некоторые детали ещё дорабатывались по крайней мере до 8 года н.э., а по некоторым данным до 4 века. Также, начало года различалось от одной культуры к другой - не везде Январь был первым месяцем года.

Предостережение

Помните, что на данный момент общепринятым в мире считается григорианский календарь. Функция gregoriantojd() может преобразовывать даты по этому календарю в число дней в юлианском летоисчислении.

### Список параметров

`month`

  Месяц в виде числа от 1 (январь) до 12 (декабрь)

`day`

  День в виде числа от 1 до 31

`year`

  Год в виде числа между -4713 и 9999

### Возвращаемые значения

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

### Смотрите также

- jdtojulian() - Переводит число дней в юлианском летоисчислении в дату по юлианскому календарю
- cal_to_jd() - Преобразовывает заданную дату в юлианскую

# unixtojd

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

unixtojd — Переводит метку времени Unix в юлианский день

### Описание

function unixtojd(?int `$timestamp` = `null`): int|false

Возвращает юлианский день для заданной метки времени Unix `timestamp` (количество секунд с 1.1.1970) либо для текущего времени, если аргумент `timestamp` не задан. В любом случае, время рассматривается как местное время (не UTC).

### Список параметров

`timestamp`

  Метка времени Unix для преобразования.

### Возвращаемые значения

Число дней в юлианском летоисчислении или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `timestamp` теперь допускает значение null.

### Смотрите также

- jdtounix() - Переводит число дней в юлианском летоисчислении в метку времени Unix

## Содержание

- cal_days_in_month — Возвращает количество дней в месяце для заданного года и календаря
- cal_from_jd — Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря
- cal_info — Возвращает информацию о заданном календаре
- cal_to_jd — Преобразовывает заданную дату в юлианскую
- easter_date — Получает метку времени Unix, которая соответствует местной полночи на Пасху в заданном году
- easter_days — Получает количество дней между 21 марта и Пасхой в заданном году
- frenchtojd — Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении
- gregoriantojd — Преобразовывает дату по григорианскому календарю в количество дней в юлианском летоисчислении
- jddayofweek — Возвращает день недели
- jdmonthname — Возвращает название месяца
- jdtofrench — Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю
- jdtogregorian — Переводит число дней в юлианском летоисчислении в дату по Григорианскому календарю
- jdtojewish — Переводит количество дней из юлианского календаря в дату по еврейскому календарю
- jdtojulian — Переводит число дней в юлианском летоисчислении в дату по юлианскому календарю
- jdtounix — Переводит число дней в юлианском летоисчислении в метку времени Unix
- jewishtojd — Переводит дату по еврейскому календарю в число дней в юлианском летоисчислении
- juliantojd — Переводит дату по юлианскому календарю в число дней в юлианском летоисчислении
- unixtojd — Переводит метку времени Unix в юлианский день

- Установка и настройка
  - Установка
- Предопределённые константы
- Календарь
  - cal_days_in_month — Возвращает количество дней в месяце для заданного года и календаря
  - cal_from_jd — Преобразовывает дату, заданную в юлианском календаре, в дату указанного календаря
  - cal_info — Возвращает информацию о заданном календаре
  - cal_to_jd — Преобразовывает заданную дату в юлианскую
  - easter_date — Получает метку времени Unix, которая соответствует местной полночи на Пасху в заданном году
  - easter_days — Получает количество дней между 21 марта и Пасхой в заданном году
  - frenchtojd — Преобразовывает дату Французского республиканского календаря в количество дней в Юлианском летоисчислении
  - gregoriantojd — Преобразовывает дату по григорианскому календарю в количество дней в юлианском летоисчислении
  - jddayofweek — Возвращает день недели
  - jdmonthname — Возвращает название месяца
  - jdtofrench — Переводит число дней в юлианском летоисчислении в дату по французскому республиканскому календарю
  - jdtogregorian — Переводит число дней в юлианском летоисчислении в дату по Григорианскому календарю
  - jdtojewish — Переводит количество дней из юлианского календаря в дату по еврейскому календарю
  - jdtojulian — Переводит число дней в юлианском летоисчислении в дату по юлианскому календарю
  - jdtounix — Переводит число дней в юлианском летоисчислении в метку времени Unix
  - jewishtojd — Переводит дату по еврейскому календарю в число дней в юлианском летоисчислении
  - juliantojd — Переводит дату по юлианскому календарю в число дней в юлианском летоисчислении
  - unixtojd — Переводит метку времени Unix в юлианский день

# Модуль работы с датой и временем

# Введение

Класс DateTimeImmutable и классы, которые с ним связаны, представляют информацию о дате и времени. Объекты даты и времени создают путём передачи строкового представления информации о дате и времени или на основе текущего времени системы.

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

Функции даты и времени в PHP реализуют календарь по стандарту ISO 8601 — » пролептический григорианский календарь, который реализует текущие правила високосных дней, которые действовали до введения григорианского календаря, и включает год со значением `0` в качестве номера года между значениями `-1 до нашей эры` и `1 нашей эры`. Високосные секунды не поддерживаются.

Информация о дате и времени хранится в памяти в виде 64-разрядных чисел, поэтому поддерживается каждое пригодное представление даты, включая отрицательные годы. В диапазон дат входят значения от примерно 292 миллиардов лет в прошлом до такого же количества лет в будущем.

> Замечание: Часовые пояса, которые описывает раздел, приводит «Список поддерживаемых часовых поясов».

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

Функции работают без установки, поскольку составляют часть PHP-ядра.

> Замечание: Получение последней базы часовых поясов

> Последнюю версию часовых поясов можно установить с помощью PECL » timezonedb.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Настройки конфигурации даты/времени
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | До PHP 8.0.0 значение по умолчанию было "90.583333".
date.sunset_zenith | "90.833333" | `INI_ALL` | До PHP 8.0.0 значение по умолчанию было "90.583333".
date.timezone | "UTC" | `INI_ALL` | Начиная с PHP 8.2, при установке недопустимого значения или пустой строки выдаётся предупреждение.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`date.default_latitude` float

  Широта по умолчанию. в диапазоне от `0` на экваторе до `+90` к северу и `-90` к югу.

`date.default_longitude` float

  Долгота по умолчанию. в диапазоне от `0` на нулевом меридиане до `+180` на восток и `-180` на запад.

`date.sunrise_zenith` float

  Угол, под которым солнце светит во время восхода.

  Значение по умолчанию составляет 90°50'. Дополнительные 50' обусловлены двумя компонентами: радиусом Солнца, который составляет 16' и атмосферной рефракцией, которая составляет 34'.

`date.sunset_zenith` float

  Угол, под которым солнце светит во время заката.

`date.timezone` string

  Часовой пояс, используемый по умолчанию всеми функциями даты/времени. Порядок приоритета используемых часовых поясов описан на странице date_default_timezone_get(). Смотрите также Список поддерживаемых часовых поясов.

> Замечание: Первые четыре опции настройки в настоящее время используются только в функциях date_sunrise() и date_sunset().

# Предопределённые константы

PHP определяет семейство констант `DATE_*`, которые предлагают стандартные представления даты при работе с функциями форматирования даты наподобие функции date().

Форматы возврата, доступные для параметра `returnFormat` функций date_sunrise() и date_sunset()
Внимание

Эти константы устарели с PHP 8.4.0. Функции date_sunrise() и date_sunset() устарели с PHP 8.1.0.

`SUNFUNCS_RET_TIMESTAMP` (int)
  Время в секундах с начала эпохи Unix.
`SUNFUNCS_RET_STRING` (int)
  Часы:минуты, например: `08:02`.
`SUNFUNCS_RET_DOUBLE` (int)
  Часы как число с плавающей точкой: `8.75`.

`Константы семейства DATE_*`
`DATE_ATOM` (string)
  Дата и время в формате Atom: `2005-08-15T15:52:01+00:00`; формат совместим со стандартами ISO-8601, RFC 3339 и XML Schema.
`DATE_COOKIE` (string)
  Дата и время в формате блоков данных Cookies HTTP-протокола: `Monday, 15-Aug-2005 15:52:01 UTC`.
`DATE_ISO8601` (string)
  Дата и время в формате, подобном стандарту ISO-8601: `2005-08-15T15:52:01+0000`.

  > Замечание: Формат несовместим со стандартом ISO-8601, но сохранился по причинам обратной совместимости. Вместо этой константы указывают константы `DATE_ISO8601_EXPANDED` и `DATE_ATOM` для совместимости со стандартом ISO-8601 (см. пункт d раздела 4.3.3 стандарта ISO8601:2004).

`DATE_ISO8601_EXPANDED` (string)
  Дата и время в формате расширенного стандарта ISO-8601: `+10191-07-26T08:59:52+01:00`.

  > Замечание: Этот формат, в отличие от стандартного диапазона лет по стандарту ISO-8601 — `0000`-`9999`, допускает диапазоны лет, за счёт включения знакового символа. Это также гарантирует, что часть, в которой указывается часовой пояс, (`+01:00`) совместима со стандартом ISO-8601.

`DATE_RFC822` (string)
  Дата и время в формате стандарта RFC 822: `Mon, 15 Aug 05 15:52:01 +0000`.
`DATE_RFC850` (string)
  Дата и время в формате стандарта RFC 850: `Monday, 15-Aug-05 15:52:01 UTC`.
`DATE_RFC1036` (string)
  Дата и время в формате стандарта RFC 1036: `Mon, 15 Aug 05 15:52:01 +0000`.
`DATE_RFC1123` (string)
  Дата и время в формате стандарта RFC 1123: `Mon, 15 Aug 2005 15:52:01 +0000`.
`DATE_RFC7231` (string)
  Дата и время в формате стандарта RFC 7231 (начиная с PHP 7.0.19 и 7.1.5): `Sat, 30 Apr 2016 17:52:13 GMT`.
`DATE_RFC2822` (string)
  Дата и время в формате стандарта RFC 2822: `Mon, 15 Aug 2005 15:52:01 +0000`.
`DATE_RFC3339` (string)
  То же, что `DATE_ATOM`.
`DATE_RFC3339_EXTENDED` (string)
  Дата и время в формате расширенного стандарта RFC 3339: `2005-08-15T15:52:01.000+00:00`.
`DATE_RSS` (string)
  Дата и время в RSS-формате: `Mon, 15 Aug 2005 15:52:01 +0000`. Псевдоним константы `DATE_RFC1123`.
`DATE_W3C` (string)
  Дата и время в W3C-формате: `2005-08-15T15:52:01+00:00`. Псевдоним константы `DATE_RFC3339`.

# Примеры

## Содержание

- Арифметика даты/времени

## Арифметика даты/времени

В следующих примерах показываются некоторые подводные камни вычислений даты/времени, относительно переходов на летнее и зимнее время (DST), и месяцев, имеющих разное количество дней.

Пример #1 DateTimeImmutable::add/sub добавляет интервалы, охватывающие прошедшее время

Добавление PT24H через переход DST приведёт к добавлению 23/25 часов (для большинства часовых поясов).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Результат выполнения приведённого примера:

    Начало: 2015-11-01 00:00:00 -04:00
    Конец:  2015-11-01 02:00:00 -05:00

Пример #2 DateTimeImmutable::modify и strtotime увеличит или уменьшит значения индивидуальных компонентов

Добавление +24 часов через переход DST добавит точно 24 часов (вместо учёта перехода на зимнее или летнее время).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Результат выполнения приведённого примера:

    Начало:  2015-11-01 00:00:00 -04:00
    Конец:   2015-11-02 00:00:00 -05:00

Пример #3 Добавление или вычитание времени может уменьшить или увеличить дату

Например, 31 января + 1 месяц вернёт 2 марта (високосный год) или 3 марта (обычный год).

    <?php
    echo "Обычный год:\n"; // В феврале 28 дней
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Високосный год:\n"; // В феврале 29 дней
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Результат выполнения приведённого примера:

    Обычный год:
    Начало: 2015-01-31 00:00:00 -05:00
    Конец:  2015-03-03 00:00:00 -05:00
    Високосный год:
    Начало: 2016-01-31 00:00:00 -05:00
    Конец:  2016-03-02 00:00:00 -05:00

Для получения последнего дня следующего месяца (то есть чтобы предотвратить переполнение) существует директива `last day of`.

    <?php
    echo "Обычный год:\n"; // Февраль содержит 28 дней
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Високосный год:\n"; // Февраль содержит 29 дней
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Начало: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Конец:  ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Результат выполнения приведённого примера:

    Обычный год:
    Начало: 2015-01-31 00:00:00 -05:00
    Конец:  2015-02-28 00:00:00 -05:00
    Високосный год:
    Начало: 2016-01-31 00:00:00 -05:00
    Конец:  2016-02-29 00:00:00 -05:00

# Класс DateTime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Введение

Представление даты и времени.

Класс ведёт себя так же, как и DateTimeImmutable, за исключением того, что объекты модифицируются сами при вызове таких методов модификации, как DateTime::modify().

Внимание

Вызов методов для объектов класса DateTime изменит информацию, заключённую в этих объектах, если вы хотите предотвратить это, вам придётся использовать оператор `clone` для создания нового объекта. Используйте класс DateTimeImmutable вместо DateTime, чтобы получить рекомендуемое поведение по умолчанию.

## Обзор класса

class DateTime implements DateTimeInterface {
/* Наследуемые константы */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Методы */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса теперь типизированы.
7.2.0 | Константы класса теперь DateTime определены в DateTimeInterface.
7.1.0 | Конструктор класса DateTime теперь включает текущие микросекунды. До этого он всегда инициализировал микросекунды со значением `0`.

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд

### Описание

Объектно-ориентированный стиль

public function DateTime::add(DateInterval `$interval`): DateTime

Процедурный стиль

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

Прибавляет заданный объект DateInterval к объекту DateTime.

Подобен методу DateTimeImmutable::add(), за исключением работы с объектом DateTime.

Процедурная версия принимает в качестве первого аргумента объект DateTime.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`interval`

  Объект класса DateInterval.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Смотрите также

- DateTimeImmutable::add() - Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — Конструктор класса DateTime

### Описание

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Этот конструктор похож на конструктор DateTimeImmutable::__construct(), но работает с объектом DateTime. Учтите, что вместо этого класса лучше работать с классом DateTimeImmutable и его функциями.

Возвращает новый объект DateTime.

### Список параметров

`datetime`

  Строка даты и времени. Объяснение корректных форматов даёт раздел «Форматы даты и времени».

  Если используется аргумент `$timezone`, то для получения текущего времени в новом объекте достаточно передать `"now"` в качестве этого аргумента.

`timezone`

  Объект класса DateTimeZone, представляющий часовой пояс параметра `$datetime`.

  Если аргумент `$timezone` не задан или `null`, будет использован текущий часовой пояс.

  > Замечание:

  > Значение аргумента `$timezone`, равно как и текущий часовой пояс не будут учитываться, если в качестве аргумента `$datetime` передаётся метка времени UNIX (например, `@946684800`) или время, в котором часовой пояс уже содержится (например, `2010-01-28T15:00:00+02:00`).

### Возвращаемые значения

Возвращает созданный объект класса DateTime.

### Ошибки

Если будет передана недопустимая строка даты/времени, будет выброшено исключение DateMalformedStringException. До PHP 8.3 выбрасывалось исключение Exception.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь вместо исключения Exception выбрасывается исключение DateMalformedStringException, если передана недопустимая строка.

### Смотрите также

- DateTimeImmutable::__construct() - Возвращает новый объект DateTimeImmutable

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — Разбирает строку времени по заданному формату

### Описание

Объектно-ориентированный стиль

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Процедурный стиль

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Метод возвращает новый объект DateTime, который представляет строку даты и времени `datetime` в формате `format`.

Метод работает аналогично методу DateTimeImmutable::createFromFormat() и функции date_create_immutable_from_format(), но создаёт объект DateTime.

Этот метод, включая параметры, примеры и рекомендации, описывает страница метода DateTimeImmutable::createFromFormat.

### Список параметров

Смотрите параметры и их описание на странице метода DateTimeImmutable::createFromFormat.

### Возвращаемые значения

Метод возвращает новый экземпляр класса DateTime или `false`, если возникла ошибка.

### Ошибки

Метод выбрасывает исключение ValueError, если параметр `datetime` содержит NULL-байты.

### Список изменений

Версия | Описание
--- | ---
8.0.21, 8.1.8, 8.2.0 | Теперь метод выбрасывает исключение ValueError, если в параметр `datetime` передали NULL-байты, что раньше метод без предупреждения игнорировал.

### Примеры

Подробный набор примеров смотрите на странице метода DateTimeImmutable::createFromFormat.

### Смотрите также

- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Создаёт новый объект DateTime на основе объекта DateTimeImmutable

### Описание

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### Список параметров

`object`

  Неизменяемый объект DateTimeImmutable, который требуется преобразовать в изменяемый. Исходный объект не изменяется, а создаётся новый экземпляр класса DateTime с теми же датой, временем и часовым поясом.

### Возвращаемые значения

Метод возвращает новый объект DateTime.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Метод теперь возвращает экземпляр текущего класса — на котором вызвали метод; раньше метод создавал новый экземпляр класса DateTime.

### Примеры

Пример #1 Пример создания изменяемого объекта даты и времени

    <?php

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — Создаёт новый объект DateTime на основе объекта, совместимого с интерфейсом DateTimeInterface

### Описание

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### Список параметров

`object`

  Объект — подтип DateTimeInterface, который требуется преобразовать в изменяемую версию. Исходный объект не изменяется, а создаётся новый объект DateTime с той же информацией о дате, времени и часовом поясе.

### Возвращаемые значения

Метод возвращает новый объект DateTime.

### Примеры

Пример #1 Пример создания изменяемого объекта даты и времени

    <?php

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

    $mutable = DateTime::createFromInterface($date);

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $also_mutable = DateTime::createFromInterface($date);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Создаёт экземпляр из метки времени Unix

### Описание

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Создаёт экземпляр из метки времени Unix.

### Список параметров

`timestamp`
  Метка времени Unix, представляющая дату. Также принимается значение с плавающей точкой (float), что позволяет получить точность до микросекунд.

### Возвращаемые значения

Метод возвращает новый экземпляр класса DateTime.

### Ошибки

Если метка времени `timestamp` выходит за пределы диапазона [`PHP_INT_MIN`, `PHP_INT_MAX`], выбрасывается исключение DateRangeError.

### Примеры

Пример #1 Пример использования метода DateTime::createFromTimestamp()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

Результат выполнения приведённого примера:

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — Псевдоним DateTimeImmutable::getLastErrors()

### Описание

Псевдоним функции DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — Изменяет метку времени

### Описание

Объектно-ориентированный стиль

public function DateTime::modify(string `$modifier`): DateTime

Процедурный стиль

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

Метод изменяет метку времени объекта DateTime путём добавления или вычитания времени в формате, который принимает метод DateTimeImmutable::__construct().

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`modifier`

  Строка даты и времени. Объяснение корректных форматов даёт раздел «Форматы даты и времени».

### Возвращаемые значения

Метод возвращает новый экземпляр даты и времени DateTime, если выполнился успешно. Процедурный стиль возвращает `false`, если возникла ошибка.

### Ошибки

Только для объектно-ориентированного API-интерфейса: метод выбрасывает исключение DateMalformedStringException, если передали строку с недопустимой датой и временем.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь предварительный тип возвращаемого значения — DateTime; ранее был DateTime|false.
8.3.0 | Метод DateTime::modify() теперь выбрасывает исключение DateMalformedStringException, если передали строку в недопустимом формате. Раньше метод возвращал значение `false` и выдавал предупреждение. Функция date_modify() не изменилась.

### Примеры

Пример #1 Пример изменения метки времени методом DateTime::modify()

Объектно-ориентированный стиль

    <?php

    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

Результат выполнения приведённого примера:

    2006-12-13

Процедурный стиль

    <?php

    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

Результат выполнения приведённого примера:

    2006-12-13

Пример #2 При добавлении и вычитании месяцев соблюдают осторожность

    <?php

    $date = new DateTime('2000-12-31');

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2001-01-31
    2001-03-03

Пример #3 Метод поддерживает все форматы даты и времени

    <?php

    $date = new DateTime('2020-12-31');

    $date->modify('July 1st, 2023');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('Monday next week');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('17:30');
    echo $date->format('Y-m-d H:i') . "\n";

Результат выполнения приведённого примера:

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### Смотрите также

- strtotime() - Преобразовывает текстовое представление даты на английском языке в метку времени Unix
- DateTimeImmutable::modify() - Создаёт новый объект с изменённой временной меткой
- DateTime::add() - Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд
- DateTime::sub() - Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime
- DateTime::setDate() - Устанавливает дату
- DateTime::setISODate() - Устанавливает дату в формате ISO
- DateTime::setTime() - Устанавливает время
- DateTime::setTimestamp() - Устанавливает дату и время на основе метки времени Unix

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — Обработчик __set_state

### Описание

public static function DateTime::__set_state(array `$array`): DateTime

Обработчик __set_state().

Подобен методу DateTimeImmutable::__set_state(), за исключением работы с объектом DateTime.

### Список параметров

`array`

  Массив для инициализации.

### Возвращаемые значения

Возвращает новый экземпляр класса DateTime.

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — Устанавливает дату

### Описание

Объектно-ориентированный стиль

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

Процедурный стиль

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

Переустанавливает текущее значение даты объекта DateTime в новое значение.

Подобен методу DateTimeImmutable::setDate(), за исключением работы с объектом DateTime и изменением существующего объекта.

Процедурная версия принимает объект DateTime в качестве первого аргумента.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`year`

  Год новой даты.

`month`

  Месяц новой даты.

`day`

  День новой даты.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Смотрите также

- DateTimeImmutable::setDate() - Устанавливает дату

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — Устанавливает дату в формате ISO

### Описание

Объектно-ориентированный стиль

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

Процедурный стиль

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

Установка даты в соответствии со стандартом ISO 8601, в котором использование недель и смещения в днях предпочтительней указания даты.

Подобен методу DateTimeImmutable::setISODate(), за исключением работы с объектом DateTime.

Процедурная версия принимает объект DateTime в качестве первого аргумента.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`year`

  Год новой даты.

`week`

  Неделя новой даты.

`dayOfWeek`

  Смещение относительно начала недели.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Смотрите также

- DateTimeImmutable::setISODate() - Устанавливает дату в формате ISO

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Устанавливает микросекундную часть времени

### Описание

public function DateTime::setMicrosecond(int `$microsecond`): static

Устанавливает микросекундную часть времени.

Аналогичен методу DateTimeImmutable::setMicrosecond(), но работает с классом DateTime.

### Список параметров

`microsecond`
  Значение микросекунд для установки (от `0` до `999999`).

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Ошибки

Если значение микросекунд `microsecond` выходит за пределы диапазона [`0`, `999999`], выбрасывается исключение DateRangeError.

### Примеры

Пример #1 Пример использования метода DateTime::setMicrosecond()

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Смотрите также

- DateTimeInterface::getMicrosecond() - Получает микросекундную часть метки времени Unix

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — Устанавливает время

### Описание

Объектно-ориентированный стиль

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Процедурный стиль

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Переустанавливает текущее значение времени объекта DateTime в новое значение.

Подобен методу DateTimeImmutable::setTime(), за исключением работы с объектом DateTime.

Процедурная версия принимает объект DateTime в качестве первого аргумента.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`hour`

  Час нового времени.

`minute`

  Минуты нового времени.

`second`

  Секунды нового времени.

`microsecond`

  Микросекунды.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Поведение с двойными существующими часами (во время перехода на летнее время) изменилось. Ранее PHP выбирал второе вхождение (после перехода на летнее время), а не первое (до перехода на летнее время).
7.1.0 | Добавлен параметр `microsecond`.

### Смотрите также

- DateTimeImmutable::setTime() - Устанавливает время

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Устанавливает дату и время на основе метки времени Unix

### Описание

Объектно-ориентированный стиль

public function DateTime::setTimestamp(int `$timestamp`): DateTime

Процедурный стиль

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Метод устанавливает дату и время на основе на метки времени Unix.

Метод аналогичен методу DateTimeImmutable::setTimestamp(), но работает с объектом DateTime.

Процедурная версия в первом аргументе принимает объект DateTime.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`timestamp`

  Метка времени Unix, которая представляет дату. Установку меток времени за пределами диапазона значений int поддерживает метод DateTimeImmutable::modify() в формате с символом `@` в начале числовой строки с допустимой дробной частью до 6 знаков для микросекунд.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Смотрите также

- DateTimeImmutable::setTimestamp() - Устанавливает дату и время на основе метки времени Unix
- DateTime::setMicrosecond() - Устанавливает микросекундную часть времени

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — Устанавливает часовой пояс для объекта DateTime

### Описание

Объектно-ориентированный стиль

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

Процедурный стиль

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

Метод устанавливает новый часовой пояс для объекта (object) DateTime.

Метод аналогичен методу DateTimeImmutable::setTimezone(), но работает с объектом DateTime.

Процедурная версия в первом аргументе принимает объект DateTime.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`timezone`

  Объект DateTimeZone, который представляет часовой пояс.

### Возвращаемые значения

Метод возвращает объект DateTime, что помогает выстраивать цепочку вызовов. При вызове метода исходный момент времени не изменяется.

### Примеры

Пример #1 Пример установки часового пояса методом DateTime::setTimeZone()

Объектно-ориентированный стиль

    <?php

    $date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

Результат выполнения приведённого примера:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

Процедурный стиль

    <?php

    $date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

    date_timezone_set($date, timezone_open('Pacific/Chatham'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

Результат выполнения приведённого примера:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Смотрите также

- DateTimeImmutable::setTimezone() - Устанавливает часовой пояс
- DateTime::getTimezone() - Возвращает часовой пояс объекта даты и времени
- DateTimeZone::__construct() - Создаёт новый объект DateTimeZone

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime

### Описание

Объектно-ориентированный стиль

public function DateTime::sub(DateInterval `$interval`): DateTime

Процедурный стиль

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

Метод вычитает из времени объекта DateTime интервал DateInterval.

Метод работает аналогично методу DateTimeImmutable::sub(), за исключением работы с объектом DateTime.

Процедурная версия в первом аргументе принимает объект DateTime.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`interval`

  Объект класса DateInterval.

### Возвращаемые значения

Возвращает модифицированный объект DateTime для применения в цепи методов.

### Ошибки

Только объекто-ориентированный API-интерфейс: при попытке выполнить неподдерживаемую операцию, например, если в объекте DateInterval содержатся относительные характеристики времени наподобие `next weekday`, метод выбросит исключение DateInvalidOperationException.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | При попытке выполнить неподдерживаемую операцию метод DateTime::sub() теперь вместо предупреждения выбрасывает исключение DateInvalidOperationException. Функция date_sub() не изменилась.

### Смотрите также

- DateTimeImmutable::sub() - Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд

## Содержание

- DateTime::add — Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд
- DateTime::__construct — Конструктор класса DateTime
- DateTime::createFromFormat — Разбирает строку времени по заданному формату
- DateTime::createFromImmutable — Создаёт новый объект DateTime на основе объекта DateTimeImmutable
- DateTime::createFromInterface — Создаёт новый объект DateTime на основе объекта, совместимого с интерфейсом DateTimeInterface
- DateTime::createFromTimestamp — Создаёт экземпляр из метки времени Unix
- DateTime::getLastErrors — Псевдоним DateTimeImmutable::getLastErrors
- DateTime::modify — Изменяет метку времени
- DateTime::__set_state — Обработчик __set_state
- DateTime::setDate — Устанавливает дату
- DateTime::setISODate — Устанавливает дату в формате ISO
- DateTime::setMicrosecond — Устанавливает микросекундную часть времени
- DateTime::setTime — Устанавливает время
- DateTime::setTimestamp — Устанавливает дату и время на основе метки времени Unix
- DateTime::setTimezone — Устанавливает часовой пояс для объекта DateTime
- DateTime::sub — Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime

# Класс DateTimeImmutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Представление даты и времени.

Этот класс ведёт себя так же, как и класс DateTime, за исключением того, что при вызове методов изменения, таких как DateTime::modify(), возвращаются новые объекты.

## Обзор класса

class DateTimeImmutable implements DateTimeInterface {
/* Наследуемые константы */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Методы */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = null): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = false): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса теперь типизированы.
7.1.0 | Конструктор класса DateTimeImmutable теперь включает текущие микросекунды. До этого он всегда инициализировал микросекунды со значением `0`.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Метод клонирует текущий объект даты и времени, добавляет к копии временной интервал DateInterval и возвращает изменённую копию объекта DateTimeImmutable, которая представляет новое значение.

### Список параметров

`interval`

  Объект DateInterval.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Примеры

Пример #1 Пример добавления интервала времени методом DateTimeImmutable::add()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";

    ?>

Пример #2 Дополнительный пример добавления интервала времени методом DateTimeImmutable::add()

    <?php

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    ?>

Результат выполнения приведённого примера:

    2000-01-01 10:00:30
    2007-06-05 04:03:02

Пример #3 Пример поведения при добавлении месяцев

    <?php

    $date = new DateTimeImmutable('2000-12-31');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->add($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->add($interval);
    echo $newDate2->format('Y-m-d') . "\n";

    ?>

Результат выполнения приведённого примера:

    2001-01-31
    2001-03-03

### Смотрите также

- DateTimeImmutable::sub() - Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд
- DateTimeImmutable::diff() - Возвращает разницу между двумя объектами даты и времени
- DateTimeImmutable::modify() - Создаёт новый объект с изменённой временной меткой

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Возвращает новый объект DateTimeImmutable

### Описание

Объектно-ориентированный стиль

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Процедурный стиль

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Функция возвращает новый объект DateTimeImmutable.

### Список параметров

`datetime`

  Строка даты и времени. Объяснение корректных форматов даёт раздел «Форматы даты и времени».

  Для получения текущего времени в параметр `timezone` передают строку `"now"`.

`timezone`

  Объект DateTimeZone, которым представляется часовой пояс параметра `datetime`.

  Функция использует текущий часовой пояс, если параметр `timezone` опустили или значение аргумента равно значению `null`.

  > Замечание:

  > Функция проигнорирует значение аргумента `timezone` и текущий часовой пояс, если в аргументе `datetime` передали или метку времени эпохи Unix наподобие `@946684800`), или указали часовой пояс наподобие `2010-01-28T15:00:00+02:00` или `2010-07-05T06:00:00Z`.

### Возвращаемые значения

Функция возвращает новый экземпляр даты и времени DateTimeImmutable.

### Ошибки

При передаче строки с недопустимой датой и временем функция выбросит исключение DateMalformedStringException. До PHP 8.3 выбрасывалось исключение Exception.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | При передаче строки с недопустимой датой и временем функция теперь выбрасывает исключение DateMalformedStringException вместо исключения Exception.
7.1.0 | Микросекунды теперь заполняются фактическим значением, а не значением '00000'.

### Примеры

Пример #1 Пример создания объекта даты и времени методом DateTimeImmutable::__construct()

Объектно-ориентированный стиль

    <?php

    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();

        exit(1);
    }

    echo $date->format('Y-m-d');

Результат выполнения приведённого примера:

    2000-01-01

Процедурный стиль

    <?php

    $date = date_create('2000-01-01');

    if (!$date) {
        $e = date_get_last_errors();

        foreach ($e['errors'] as $error) {
            echo "$error\n";
        }

        exit(1);
    }

    echo date_format($date, 'Y-m-d');

Результат выполнения приведённого примера:

    2000-01-01

Пример #2 Тонкости работы метода DateTimeImmutable::__construct()

    <?php

    date_default_timezone_set('America/Jamaica');

    // Дата и время в часовом поясе текущей машины
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Дата и время в заданном часовом поясе
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Текущая дата и время в часовом поясе по умолчанию для PHP-скриптов
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Текущая дата и время в заданном часовом поясе
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Передача метки времени эпохи Unix. Обратите внимание, что результат будет в часовом поясе UTC
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Несуществующие значения перетекают
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";

Вывод приведённого примера будет похож на:

    2000-01-01 00:00:00-05:00
    2000-01-01 00:00:00+12:00
    2010-04-24 10:24:16-04:00
    2010-04-25 02:24:16+12:00
    2000-01-01 00:00:00+00:00
    2000-03-01 00:00:00-05:00

> Замечание:

> Переполнение дат обнаруживают путём проверки предупреждений методом DateTimeImmutable::getLastErrors().

Пример #3 Пример изменения начального часового пояса

    <?php

    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

Вывод приведённого примера будет похож на:

    2022/08/12 23:49:23 Asia/Tokyo

Пример #4 Пример с датой и временем в относительном формате

    <?php

    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

Вывод приведённого примера будет похож на:

    2021/08/12 15:43:51

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Разбирает строку времени по заданному формату

### Описание

Объектно-ориентированный стиль

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Процедурный стиль

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Метод возвращает новый объект DateTimeImmutable, который представляет строку даты и времени `datetime` в формате `format`.

### Список параметров

`format`

  Формат даты и времени в виде строки (string), которому соответствует значение второго аргумента функции. Список параметров форматирования приводят следующие параграфы. В большей части случаев работают те же символы, что и для функции date().

  Метод инициализирует каждое поле текущей датой и временем системы. Поля часто приходится «обнулять» до значений начала эпохи Unix — `1970-01-01 00:00:00 UTC`. Поля, которые не указали в строке формата `format`, сбрасывают до начальных значений Unix-эпохи путём включения в начало строки формата символа `!` или в конец строки формата символа `|`. Подробнее о работе символов рассказывает документация к каждому параметру в таблице ниже.

  Метод анализирует формат слева направо, поэтому в отдельных случаях порядок расположения символов формата влияет на результат. Методу вначале требуется проанализировать год, например, через символы `Y` или `y`, если строка формата содержит символ `z`, для которого метод ищет день года.

  Символы для разбора чисел допускают широкий диапазон значений, который выходит за пределы логического диапазона. Например, символ `d`, для которого метод ищет в строке разбора день месяца, принимает значения в диапазоне от `00` до `99`. Единственное ограничение — количество цифр. При установке значения за пределами диапазона срабатывает механизм переполнения анализатора даты и времени. Примеры показывают поведение при переполнении.

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

  Список символов, которые распознаёт строка формата `format`
  Символ в строке `format` | Описание | Пример доступных для разбора значений
  --- | --- | ---
  День | --- | ---
  `d` и `j` | День месяца, 2 цифры с ведущим нулём или без него | От `01` до `31` или от `1` до `31`. Параметр принимает двузначные числа, которые превышают количество дней в месяце, тогда месяц переполняется и разница переносится на следующий месяц. Например, число 33 с январём означает 2 февраля
  `D` и `l` | Текстовое представление дня недели | От `Mon` до `Sun` или от `Sunday` до `Saturday`. Дата переполняется до следующей даты с заданным названием дня недели, если заданное название дня недели отличается от названия дня, который принадлежит разобранной дате (или дате по умолчанию). Примеры ниже содержат объяснение
  `S` | Английское наращение — суффикс для порядкового числительного, которое означает день месяца, 2 буквы. Метод пропустит эти буквы при разборе строки | `st`, `nd`, `rd` или `th`
  `z` | День года начиная с 0; перед параметром требуется указать параметр `Y` или `y` | От `0` до `365`. Параметр принимает трёхзначные числа, которые превышают количество дней в году, тогда год переполняется и разница переносится на следующий год. Например, число 366 с 2022 годом означает 2 января 2023 года
  Месяц | --- | ---
  `F` и `M` | Текстовое представление названия месяца, например January или Sept | С `January` по `December` или с `Jan` по `Dec`
  `m` и `n` | Числовое представление номера месяца в году с ведущим нулём или без него | От `01` до `12` или от `1` до `12`. Параметр принимает двузначные числа больше 12, тогда год переполняется и разница переносится на следующий год. Например, число 13 означает январь следующего года
  Год | --- | ---
  `X` и `x` | Полное числовое представление года длиной до 19 цифр с необязательным префиксом `+` или `-` | Примеры: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Полное числовое представление года длиной до 4 цифр | Примеры: `25` (аналогично `0025`), `787`, `1999`, `2003`
  `y` | Двузначное представление года в диапазоне 1970-2069 включительно | Примеры: `99` или `03`, которые метод интерпретирует как `1999` и `2003`
  Время | --- | ---
  `a` и `A` | Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») | Регистронезависимые обозначения `am` или `pm`
  `g` и `h` | 12-часовой формат часа с ведущим нулём или без него | От `1` до `12` или от `01` до `12`. Параметр принимает двузначные числа больше 12, тогда день переполняется и разница переносится на следующий день. Например, число `14` означает `02` часа следующего AM- или PM-периода
  `G` и `H` | 24-часовой формат часа с ведущим нулём или без него | От `0` до `23` или от `00` до `23`. Параметр принимает двузначные числа больше 24, тогда день переполняется и разница переносится на следующий день. Например, число `26` означает `02:00` следующего дня
  `i` | Минуты с ведущим нулём | От `00` до `59`. Параметр принимает двузначные числа больше 59, тогда час переполняется и разница переносится на следующий час. Например, число `66` означает `:06` минут следующего часа
  `s` | Секунды с ведущим нулём | От `00` до `59`. Параметр принимает двузначные числа больше 59, тогда час переполняется и разница переносится на следующую минуту. Например, число `90` означает `:30` секунд следующей минуты
  `v` | Миллисекунды длиной до 3 цифр | Примеры: `12` (`0.12` секунды), `345` (`0.345` секунды)
  `u` | Микросекунды длиной до 6 цифр | Примеры: `45` (`0.45` секунды), `654321` (`0.654321` секунды)
  Часовой пояс | --- | ---
  `e`, `O`, `p`, `P` и `T` | Идентификатор часового пояса, разница в часах относительно UTC, разница относительно UTC с двоеточием между часами и минутами или аббревиатура часового пояса | Примеры: `UTC`; `GMT`; `Atlantic/Azores`, `+0200`, `+02:00` или `EST`; `MDT`
  Полные дата и время | --- | ---
  `U` | Количество секунд с начала эпохи Unix — January 1 1970 00:00:00 GMT | Пример: `1292177455`
  Пробел и разделители | --- | ---
  `` (пробел) | Ноль или более символов пробела, табуляции, неразрывного пробела NBSP (U+A0) или узкого неразрывного пробела NNBSP (U+202F) | Пример: `"\t"`, `" "`
  `#` | Один из следующих символов разделения: `;`, `:`, `/`, `.`, `,`, `-`, `(` или `)` | Пример: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` или `)` | Заданный символ | Пример: `-`
  `?` | Случайный байт | Пример: `^`. Предостережение: для символов в кодировке UTF-8 иногда требуется указать больше одного символа `?`, поскольку в Юникоде отдельные символы кодируются больше чем одним байтом. Разобрать многобайтовые символы помогает модификатор `*`
  `*` | Случайные байты до следующего разделителя или цифры | Пример: символ `*` в строке формата `Y-*-d` для строки разбора `2009-aWord-08` будет соответствовать части `aWord`
  `!` | Сбрасывает поля «год», «месяц», «день», «час», «минута», «секунда», «милли-» или «микросекунда» и «часовой пояс» до начальных значений Unix-эпохи: `0` для часа, минуты и секунды, `1` для месяца и дня, `1970` для года и часового пояса по умолчанию | Без символа `!` метод установит полям текущие дату и время системы
  `|` | Сбрасывает значения полей «год», «месяц», «день», «час», «минута», «секунда», «милли-» или «микросекунда» и «часовой пояс», которые метод ещё не разобрал, до начальных значений Unix-эпохи | Формат `Y-m-d|` установит год, месяц и день на основе информации, которую нашёл в строке для разбора, а для часа, минуты и секунды установит значение 0
  `+` | С этим спецификатором формата лишние данные в конце строки разбора, добавят в структуру, которую создаёт метод, не ошибку, а предупреждение | Содержала ли строка разбора в конце лишние данные, покажет метод DateTime::getLastErrors()

  Символы в строке формата, которые метод не распознал, вызовут сбой разбора, и метод добавит в структуру с предупреждениями и ошибками, которую он создаёт, сообщение об ошибке. Сообщения об ошибке запрашивают методом DateTime::getLastErrors().

  При включении в строку формата `format` буквальных символов, символы экранируют обратным слешем: `\`.

  Метод сгенерирует дату и время на основе информации в строке разбора, а частям даты и времени, которые не указали в строке формата `format`, установит текущее время системы, если строка формата `format` не содержит символ `!`.

  Метод сгенерирует дату и время на основе информации в строке разбора, а частям даты и времени, которые не указали в строке формата `format`, и значениям слева от символа `!` установит значения даты и времени начала Unix-эпохи, если строка формата `format` содержит символ `!`.

  Метод установит нулевые значения остальным полям времени, которые не указали в строке формата, если разобрал хотя бы один символ для поля времени.

  Начало эпохи Unix — 1970-01-01 00:00:00 UTC.

`datetime`

  Строка, которая представляет время.

`timezone`

  Объект класса DateTimeZone, который представляет часовой пояс.

  Метод установит текущий часовой пояс, если часовой пояс `timezone` опустили или установили для параметра значение `null`, а дата и время `datetime` не содержит часового пояса.

  > Замечание:

  > Метод проигнорирует параметр `timezone` и текущий часовой пояс, если параметр `datetime` либо содержит метку времени UNIX наподобие `946684800`, либо указывает часовой пояс наподобие `2010-01-28T15:00:00+02:00`.

### Возвращаемые значения

Метод возвращает новый экземпляр класса DateTimeImmutable или `false`, если возникла ошибка.

### Ошибки

Метод выбрасывает исключение ValueError, если параметр `datetime` содержит NUL-байты.

### Список изменений

Версия | Описание
--- | ---
8.2.9 | Спецификатор `` (пробел) теперь также поддерживает символы неразрывного пробела NBSP (U+A0) и узкого неразрывного пробела NNBSP (U+202F).
8.2.0 | Добавили спецификаторы `X` и `x` для параметра `format`.
8.0.21, 8.1.8, 8.2.0 | Теперь метод выбрасывает исключение ValueError, если в параметр `datetime` передали NULL-байты, что раньше метод без предупреждения игнорировал.
7.3.0 | Добавили спецификатор `v` для параметра `format`.

### Примеры

Пример #1 Пример использования метода DateTimeImmutable::createFromFormat()

Объектно-ориентированный стиль

    <?php

    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');

Пример #2 Пример передачи в метод DateTimeImmutable::createFromFormat() предопределённых констант формата

Объектно-ориентированный стиль

    <?php

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::ISO8601,
        '2004-02-12T15:19:21+00:00'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

Константы форматирования в этом примере состоят из строки символов для форматирования объекта DateTimeImmutable. В большей части случаев эти буквы совпадают с теми же элементами информации о дате и времени, которые определили в параметрах выше, но обычно они более мягкие.

Пример #3 Тонкости работы метода DateTimeImmutable::createFromFormat()

    <?php

    echo 'Текущее время: ' . date('Y-m-d H:i:s') . "\n";

    // Поля «год», «месяц» и «день» метод распознает в строке разбора,
    // а поля «час», «минута» и «секунда» заполнит значениями системного времени
    $format = 'Y-m-d';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
    echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    // Метод распознает каждое поле в строке разбора
    $format = 'Y-m-d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    /**
     * Метод распознает каждое поле в строке разбора,
     * а затем сбросит поля «год» и «месяц» на начальные значения даты и времени Unix-эпохи,
     * поскольку эти параметры оказались слева от символа «!» в строке формата,
     * а поля «день», «час», «минута» и «секунда» сохранят значения, которые получили из строки разбора,
     * поскольку эти параметры оказались справа от символа «!» и метод распознал для них значения;
     * дробная часть времени со значением долей секунды вернёт значение 000000, поскольку метод
     * не разобрал ни милли-, ни микросекунды, а другие поля времени при этом указали
     */
    $format = 'Y-m-!d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Формат: $format; " . $date->format('Y-m-d H:i:s.u') . "\n";

    /**
     * Метод заполнит поле «день» значением «15», поскольку в строке формата указали символ дня
     * и метод распознал в строке разбора значение для этого параметра,
     * а остальные поля даты и времени метод сбросит на начальные значения
     * даты и времени эпохи Unix, поскольку для этих полей не указали
     * параметры и значения в строках формата и разбора
     */
    $format = '!d';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    /**
     * Метод заполнит поле «минуты» значением 15,
     * поскольку распознал в строке разбора значение для символа минут i.
     * Поля «год», «месяц» и «день» получат значения системной даты,
     * поскольку метод не разобрал эти поля в строках формата и разбора, а в строке формата
     * не было символов «!» или «|», при которых год, месяц и день получили бы значения начала Unix-эпохи.
     * А остальным полям времени метод установит нулевые значения,
     * поскольку метод не нашёл эти параметры и значения для них в строках формата и разбора,
     * но методу удалось разобрать хотя бы одно временно́е поле
     */
    $format = 'i';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Формат: $format; " . $date->format('Y-m-d H:i:s') . "\n";

Вывод приведённого примера будет похож на:

    Текущее время: 2022-06-02 15:50:46
    Формат: Y-m-d; 2009-02-15 15:50:46
    Формат: Y-m-d H:i:s; 2009-02-15 15:16:17
    Формат: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Формат: !d; 1970-01-15 00:00:00
    Формат: i; 2022-06-02 00:15:00

Пример #4 Пример строки формата с литеральными символами

    <?php

    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

Вывод приведённого примера будет похож на:

    23:15:03

Пример #5 Пример поведения при переполнении

    <?php

    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

Вывод приведённого примера будет похож на:

    Sat, 04 Jun 2022 17:01:37 +0000

Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:

1. `97` секунд переполняют `1` минуту и оставляют `37` секунд.
2. `61` минута переполняет `1` час и оставляет `1` минуту.
3. `35` дней переполняют `1` месяц и оставляют `4` дня. Количество дней, которое останется, зависит от месяца, поскольку не в каждом месяце одинаковое количество дней.
4. `18` месяцев переполняют `1` год и оставляют `6` месяцев.

Пример #6 Пример поведения при переполнении названия дня недели

    <?php

    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";

Вывод приведённого примера будет похож на:

    Mon, 10 Aug 2020 01:00:00 +0000

Результат правильный, хотя и кажется странным, причина состоит в следующих переполнениях:

1. Из-за переполнения дня количеством часов дата `3 Aug 2020 25:00:00`, понедельник, перетекает на `(Tue) 4 Aug 2020 01:00`, вторник.
2. Метод применяет понедельник — `Mon`, что переносит дату на следующий период с аналогичным названием дня недели — `Mon, 10 Aug 2020 01:00:00`. Объяснение относительных ключевых слов наподобие `Mon` описывает раздел об относительных форматах.

Метод DateTimeImmutable::getLastErrors() помогает обнаружить переполнение дат и включает предупреждение, если возникло переполнение.

Пример #7 Пример обнаружения переполнения дат

    <?php

    $d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
    echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

    var_dump(DateTimeImmutable::getLastErrors());

Вывод приведённого примера будет похож на:

    Sat, 04 Jun 2022 17:01:37 +0000

    array(4) {
      'warning_count' =>
      int(2)
      'warnings' =>
      array(1) {
        [19] =>
        string(27) "The parsed date was invalid"
      }
      'error_count' =>
      int(0)
      'errors' =>
      array(0) {
      }
    }

Пример #8 Пример жадного поведения при разборе

    <?php

    print_r(date_parse_from_format('Gis', '60101'));

Вывод приведённого примера будет похож на:

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] => 60
        [minute] => 10
        [second] => 0
        [fraction] => 0
        [warning_count] => 1
        [warnings] => Array
            (
                [5] => The parsed time was invalid
            )

        [error_count] => 1
        [errors] => Array
            (
                [4] => A two digit second could not be found
            )

        [is_localtime] =>
    )

Символ формата `G` разбирает поле «час» в 24-часовом формате с ведущим нулём или без него. Для разбора поля «час» методу требуется разобрать 1 или 2 цифры. Поскольку строка формата первым содержит параметр G, и строка разбора в начале содержит две цифры, которые идут одна за другой, метод жадно считывает значение часа как `60`.

Каждому из следующих символов формата `i` и `s` требуется две цифры. Поэтому число `10` передаётся как значение параметра `i`, который ищет в строке разбора двузначное число для установки значения полю «минута», а для разбора параметра `s`, который также ищет двузначное число для установки значения полю «секунда», не остаётся цифр.

На эту проблему в структуре, которую создаёт метод, указывает массив `errors`.

Кроме того, значение `60` для поля «час» лежит за пределами диапазона `0`-`24`, что добавляет в массив `warnings` предупреждение о недействительности времени.

### Смотрите также

- DateTimeImmutable::__construct() - Возвращает новый объект DateTimeImmutable
- DateTimeImmutable::getLastErrors() - Возвращает предупреждения и ошибки
- checkdate() - Проверяет корректность даты по григорианскому календарю
- strptime() - Разбирает строку даты и времени, которую сгенерировала функция strftime

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Создаёт новый объект DateTimeImmutable на основе объекта, совместимого с интерфейсом DateTimeInterface

### Описание

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### Список параметров

`object`

  Объект — подтип DateTimeInterface, который требуется преобразовать в неизменяемую версию. Исходный объект не изменяется, а создаётся новый объект DateTimeImmutable с той же информацией о дате, времени и часовом поясе.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable.

### Примеры

Пример #1 Пример создания неизменяемого объекта даты и времени

    <?php

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromInterface($date);

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $also_immutable = DateTimeImmutable::createFromInterface($date);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — Создаёт новый объект DateTimeImmutable на основе объекта DateTime

### Описание

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### Список параметров

`object`

  Изменяемый объект DateTime, который требуется преобразовать в неизменяемую версию. Исходный объект не изменяется, а создаётся новый объект DateTimeImmutable с той же информацией о дате, времени и часовом поясе.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Метод теперь возвращает экземпляр текущего класса — на котором вызвали метод; раньше метод создавал новый экземпляр класса DateTimeImmutable.

### Примеры

Пример #1 Пример создания неизменяемого объекта даты и времени

    <?php

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromMutable( $date );

# DateTimeImmutable::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Создаёт экземпляр из метки времени Unix

### Описание

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Создаёт экземпляр из метки времени Unix.

### Список параметров

`timestamp`
  Метка времени Unix, представляющая дату. Также принимается значение с плавающей точкой (float), что позволяет получить точность до микросекунд.

### Возвращаемые значения

Метод возвращает новый экземпляр класса DateTimeImmutable.

### Ошибки

Если метка времени `timestamp` выходит за пределы диапазона [`PHP_INT_MIN`, `PHP_INT_MAX`], выбрасывается исключение DateRangeError.

### Примеры

Пример #1 Пример использования метода DateTimeImmutable::createFromTimestamp()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

Результат выполнения приведённого примера:

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Возвращает предупреждения и ошибки

### Описание

public static function DateTimeImmutable::getLastErrors(): array|false

Метод возвращает массив предупреждений и ошибок, которые обнаружил при разборе строки с датой и временем.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив, который содержит информацию о предупреждениях и ошибках, или `false`, если нет ни предупреждений, ни ошибок.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | До версии PHP 8.2.0 метод не возвращал `false`, когда не было предупреждений или ошибок. Вместо этого метод каждый раз возвращал задокументированную структуру массива.

### Примеры

Пример #1 Пример получения ошибки разбора строки с датой и временем методом DateTimeImmutable::getLastErrors()

    <?php

    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // Обработка исключения таким способом приводится только в демонстрационных целях…
        print_r(DateTimeImmutable::getLastErrors());

        // …в объектно-ориентированном стиле лучше выводить сообщение вот так:
        echo $e->getMessage();
    }

Результат выполнения приведённого примера:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [6] => Double timezone specification
            )

        [error_count] => 1
        [errors] => Array
            (
                [0] => The timezone could not be found in the database
            )

    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

Индексы 6 и 0 в выводе примера относятся к индексу символа в строке разбора, на котором возникла ошибка.

Пример #2 Пример обнаружения переполнения дат

    <?php

    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

Результат выполнения приведённого примера:

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Создаёт новый объект с изменённой временной меткой

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Метод клонирует исходный объект даты и времени, модифицирует в копии метку времени и возвращает изменённую копию объекта DateTimeImmutable. Исходный объект не изменяется.

### Список параметров

`modifier`

  Строка даты и времени. Объяснение корректных форматов даёт раздел «Форматы даты и времени».

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable, если выполнился успешно, или `false`, если возникла ошибка. Процедурный стиль возвращает `false`, если возникла ошибка.

### Ошибки

Метод DateTimeImmutable::modify() теперь выбрасывает исключение DateMalformedStringException, если передали строку с недопустимой датой и временем. Раньше метод возвращал значение `false` и выдавал предупреждение.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь предварительный тип возвращаемого значения — DateTimeImmutable; ранее был DateTimeImmutable|false.
8.3.0 | При передаче строки в недопустимом формате вместо предупреждения метод теперь выбрасывает исключение DateMalformedStringException.

### Примеры

Пример #1 Пример изменения метки времени методом DateTimeImmutable::modify()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

Результат выполнения приведённого примера:

    2006-12-13

Пример #2 Пример поведения при добавлении или вычитании месяцев

    <?php

    $date = new DateTimeImmutable('2000-12-31');

    $newDate1 = $date->modify('+1 month');
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->modify('+1 month');
    echo $newDate2->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2001-01-31
    2001-03-03

### Смотрите также

- DateTimeImmutable::add() - Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд
- DateTimeImmutable::sub() - Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд
- DateTimeImmutable::setDate() - Устанавливает дату
- DateTimeImmutable::setISODate() - Устанавливает дату в формате ISO
- DateTimeImmutable::setTime() - Устанавливает время
- DateTimeImmutable::setTimestamp() - Устанавливает дату и время на основе метки времени Unix

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — Обработчик метода __set_state

### Описание

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

Метод играет роль обработчика метода __set_state().

### Список параметров

`array`

  Инициализирующий массив.

### Возвращаемые значения

Метод возвращает новый экземпляр класса DateTimeImmutable.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Устанавливает дату

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Метод клонирует текущий объект даты и времени DateTimeImmutable, устанавливает в копии новую дату и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`year`

  Год.

`month`

  Номер месяца в году.

`day`

  Номер дня в месяце.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Примеры

Пример #1 Пример установки даты методом DateTimeImmutable::setDate()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

Результат выполнения приведённого примера:

    2001-02-03

Пример #2 Значения, которые выходят за пределы диапазона, добавляются к своим родительским значениям

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setDate(2001, 2, 28);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 2, 29);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 14, 3);
    echo $newDate->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2001-02-28
    2001-03-01
    2002-02-03

### Смотрите также

- DateTimeImmutable::setISODate() - Устанавливает дату в формате ISO
- DateTimeImmutable::setTime() - Устанавливает время

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Устанавливает дату в формате ISO

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Метод клонирует текущий объект даты и времени, устанавливает в копии дату по стандарту ISO 8601 — на основе смещения номера недели относительно года и смещения дня относительно недели, а не конкретных дат, — и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`year`

  Год.

`week`

  Неделя.

`dayOfWeek`

  Смещение относительно первого дня недели.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Примеры

Пример #1 Пример установки даты методом DateTimeImmutable::setISODate()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2008-01-07
    2008-01-13

Процедурный стиль

    <?php

    $date = date_create();

    date_isodate_set($date, 2008, 2);
    echo date_format($date, 'Y-m-d') . "\n";

    date_isodate_set($date, 2008, 2, 7);
    echo date_format($date, 'Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2008-01-07
    2008-01-13

Пример #2 Значения, которые выходят за пределы диапазона, добавляются к своим родительским значениям

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 8);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 53, 7);
    echo $newDate->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2008-01-13
    2008-01-14
    2009-01-04

Пример #3 Поиск номера месяца, в который входит неделя

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

Результат выполнения приведённого примера:

    3

### Смотрите также

- DateTimeImmutable::setDate() - Устанавливает дату
- DateTimeImmutable::setTime() - Устанавливает время

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Устанавливает микросекундную часть времени

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

Возвращает новый объект DateTimeImmutable, построенный на основе старого, с изменённой микросекундной частью.

### Список параметров

`microsecond`
  Значение микросекунд для установки (от `0` до `999999`).

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Ошибки

Если значение микросекунд `microsecond` выходит за пределы диапазона [`0`, `999999`], выбрасывается исключение DateRangeError.

### Примеры

Пример #1 Пример использования метода DateTimeImmutable::setMicrosecond()

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Смотрите также

- DateTimeInterface::getMicrosecond() - Получает микросекундную часть метки времени Unix

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Устанавливает время

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Метод клонирует исходный объект даты и времени, устанавливает в копии новое время и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`hour`

  Час.

`minute`

  Минута.

`second`

  Секунда.

`microsecond`

  Микросекунда.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Изменилось поведение с повторным появлением одного и того же часа при переходе с летнего времени на зимнее, когда стрелки часов переводят на один час назад. Раньше PHP выбирал второе вхождение — момент после перехода на зимнее время, а теперь выбирает первое — до перехода.
7.1.0 | Добавили параметр `microsecond`.

### Примеры

Пример #1 Пример установки времени методом DateTimeImmutable::setTime()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

Вывод приведённого примера будет похож на:

    2001-01-01 14:55:00
    2001-01-01 14:55:24

Пример #2 Значения, которые выходят за пределы диапазона, добавляются к своим родительским значениям

    <?php

    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 65);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 65, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(25, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

Результат выполнения приведённого примера:

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### Смотрите также

- DateTimeImmutable::setDate() - Устанавливает дату
- DateTimeImmutable::setISODate() - Устанавливает дату в формате ISO

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Устанавливает дату и время на основе метки времени Unix

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Метод клонирует текущий объект даты и времени, устанавливает в копии новые дату и время на основе метки времени Unix и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`timestamp`

  Метка времени Unix, которая представляет дату и время. Установка меток времени за пределами диапазона значений для типа данных int возможна через метод DateTimeImmutable::modify() в формате с символом `@` в начале числовой строки с допустимой дробной частью до 6 знаков для микросекунд.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Примеры

Пример #1 Пример установки даты и времени методом DateTimeImmutable::setTimestamp()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable();
    echo $date->format('U = Y-m-d H:i:s') . "\n";

    $newDate = $date->setTimestamp(1171502725);
    echo $newDate->format('U = Y-m-d H:i:s') . "\n";

Вывод приведённого примера будет похож на:

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### Смотрите также

- DateTimeImmutable::getTimestamp() - Возвращает метку времени с начала эпохи Unix
- DateTimeImmutable::setMicrosecond() - Устанавливает микросекундную часть времени

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Устанавливает часовой пояс

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Метод клонирует текущий объект даты и времени DateTimeImmutable, устанавливает в копии часовой пояс и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`timezone`

  Объект DateTimeZone, который представляет часовой пояс.

### Возвращаемые значения

Метод возвращает новый модифицированный объект DateTimeImmutable для цепочки методов. При вызове метода исходный объект, который представляет момент времени, не изменяется.

### Примеры

Пример #1 Пример установки часового пояса методом DateTimeImmutable::setTimeZone()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $newDate->format('Y-m-d H:i:sP') . "\n";

Результат выполнения приведённого примера:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Смотрите также

- DateTimeImmutable::getTimezone() - Возвращает часовой пояс объекта даты и времени
- DateTimeZone::__construct() - Создаёт новый объект DateTimeZone

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд

### Описание

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Метод клонирует текущий объект даты и времени, вычитает из копии временной интервал DateInterval и возвращает изменённую копию объекта DateTimeImmutable.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create(). Функция изменяет этот объект.
`interval`

  Объект DateInterval.

### Возвращаемые значения

Метод возвращает новый объект DateTimeImmutable с модифицированными данными.

### Ошибки

При попытке выполнить неподдерживаемую операцию наподобие вычитания интервала DateInterval, который представляет относительный спецификатор времени `next weekday` или аналогичный, метод выбрасывает исключение DateInvalidOperationException.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | При попытке выполнить неподдерживаемую операцию вместо предупреждения метод теперь выбрасывает исключение DateInvalidOperationException.

### Примеры

Пример #1 Пример вычитания интервала времени методом DateTimeImmutable::sub()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";

Результат выполнения приведённого примера:

    2000-01-10

Пример #2 Дополнительный пример вычитания интервала времени методом DateTimeImmutable::sub()

    <?php

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

Результат выполнения приведённого примера:

    2000-01-19 13:59:30
    1992-08-15 19:56:58

Пример #3 Пример поведения при вычитании месяцев

    <?php

    $date = new DateTimeImmutable('2001-04-30');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->sub($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->sub($interval);
    echo $newDate2->format('Y-m-d') . "\n";

    ?>

Результат выполнения приведённого примера:

    2001-03-30
    2001-03-02

### Смотрите также

- DateTimeImmutable::add() - Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд
- DateTimeImmutable::diff() - Возвращает разницу между двумя объектами даты и времени
- DateTimeImmutable::modify() - Создаёт новый объект с изменённой временной меткой

## Содержание

- DateTimeImmutable::add — Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд
- DateTimeImmutable::__construct — Возвращает новый объект DateTimeImmutable
- DateTimeImmutable::createFromFormat — Разбирает строку времени по заданному формату
- DateTimeImmutable::createFromInterface — Создаёт новый объект DateTimeImmutable на основе объекта, совместимого с интерфейсом DateTimeInterface
- DateTimeImmutable::createFromMutable — Создаёт новый объект DateTimeImmutable на основе объекта DateTime
- DateTimeImmutable::createFromTimestamp — Создаёт экземпляр из метки времени Unix
- DateTimeImmutable::getLastErrors — Возвращает предупреждения и ошибки
- DateTimeImmutable::modify — Создаёт новый объект с изменённой временной меткой
- DateTimeImmutable::__set_state — Обработчик метода __set_state
- DateTimeImmutable::setDate — Устанавливает дату
- DateTimeImmutable::setISODate — Устанавливает дату в формате ISO
- DateTimeImmutable::setMicrosecond — Устанавливает микросекундную часть времени
- DateTimeImmutable::setTime — Устанавливает время
- DateTimeImmutable::setTimestamp — Устанавливает дату и время на основе метки времени Unix
- DateTimeImmutable::setTimezone — Устанавливает часовой пояс
- DateTimeImmutable::sub — Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд

# Интерфейс DateTimeInterface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Интерфейс DateTimeInterface разработали, чтобы объявления типов параметров, значений возврата или свойств принимали как значение объекты классов DateTimeImmutable и DateTime. Реализовать интерфейс в пользовательских классах невозможно.

В интерфейсе также определили общие константы для форматирования объектов DateTimeImmutable и DateTime методами DateTimeImmutable::format() и DateTime::format().

## Обзор интерфейса

interface DateTimeInterface {
/* Константы */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* Методы */
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Предопределённые константы

DateTimeInterface::ATOM string
DATE_ATOM
  Дата и время в формате стандарта Atom: 2005-08-15T15:52:01+00:00; формат совместим со стандартами ISO-8601, RFC 3339 и XML Schema.
DateTimeInterface::COOKIE string
DATE_COOKIE
  Дата и время для установки с блоках данных cookies HTTP-протокола: Monday, 15-Aug-05 15:52:01 UTC
DateTimeInterface::ISO8601 string
DATE_ISO8601
  Дата и время в формате, аналогичном стандарту ISO-8601: 2005-08-15T15:52:01+0000.

  > Замечание: Формат несовместим со стандартом ISO-8601, но остаётся по соображениям обратной совместимости. Для совместимости со стандартом ISO-8601 указывают константу DateTimeInterface::ISO8601_EXPANDED или DateTimeInterface::ATOM. См. пункт d раздела 4.3.3 стандарта ISO8601:2004.

DateTimeInterface::ISO8601_EXPANDED string
DATE_ISO8601_EXPANDED
  Дата и время по стандарту ISO-8601 Expanded: +10191-07-26T08:59:52+01:00

  > Замечание: За счёт включения знакового символа формат принимает диапазоны лет за пределами нормального диапазона стандарта ISO-8601 — `0000`-`9999`. Формат гарантирует, что часть `+01:00` с обозначением часового пояса совместима со стандартом ISO-8601.

DateTimeInterface::RFC822 string
DATE_RFC822
  Дата и время по стандарту RFC 822: Mon, 15 Aug 05 15:52:01 +0000
DateTimeInterface::RFC850 string
DATE_RFC850
  Дата и время по стандарту RFC 850: Monday, 15-Aug-05 15:52:01 UTC
DateTimeInterface::RFC1036 string
DATE_RFC1036
  Дата и время по стандарту RFC 1036: Mon, 15 Aug 05 15:52:01 +0000
DateTimeInterface::RFC1123 string
DATE_RFC1123
  Дата и время по стандарту RFC 1123: Mon, 15 Aug 2005 15:52:01 +0000
DateTimeInterface::RFC7231 string
DATE_RFC7231
  Дата и время по стандарту RFC 7231: Sat, 30 Apr 2016 17:52:13 GMT. Константа доступна с PHP 7.0.19 и 7.1.5
DateTimeInterface::RFC2822 string
DATE_RFC2822
  Дата и время по стандарту RFC 2822: Mon, 15 Aug 2005 15:52:01 +0000
DateTimeInterface::RFC3339 string
DATE_RFC3339
  То же, что и DATE_ATOM
DateTimeInterface::RFC3339_EXTENDED string
DATE_RFC3339_EXTENDED
  Дата и время по стандарту RFC 3339 EXTENDED: 2005-08-15T15:52:01.000+00:00
DateTimeInterface::RSS string
DATE_RSS
  Дата и время в RSS-формате: Mon, 15 Aug 2005 15:52:01 +0000
DateTimeInterface::W3C string
DATE_W3C
  Дата и время в формате W3C (англ. World Wide Web Consortium): 2005-08-15T15:52:01+00:00

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Константы `DATE_RFC7231` и `DateTimeInterface::RFC7231` устарели.
8.4.0 | Константы класса стали типизированными.
8.2.0 | Добавили константу `DateTimeInterface::ISO8601_EXPANDED`.
7.2.0 | Константы класса DateTime теперь определяются в интерфейсе DateTimeInterface.

# DateTimeInterface::diff

# DateTimeImmutable::diff

# DateTime::diff

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Возвращает разницу между двумя объектами даты и времени

### Описание

Объектно-ориентированный стиль

public function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Процедурный стиль

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Метод возвращает разницу между двумя объектами, совместимыми с интерфейсом DateTimeInterface.

### Список параметров

`datetime`

  Дата, с которой требуется сравнить исходную.

`absolute`

  Параметр определяет, переводить ли интервал в абсолютную величину.

### Возвращаемые значения

Метод возвращает объект DateInterval, который представляет разницу между двумя датами.

Параметр `absolute` влияет только на свойство `invert` объекта DateInterval.

Конкретнее: метод возвращает значение — представление интервала времени, который потребуется применить к исходному объекту `$this` или `$originObject`, чтобы получить целевой объект `$targetObject`. Восстановление исходной даты из целевой и интервала иногда невозможно.

Метод учитывает переходы на летнее время и поэтому иногда возвращает интервал `24 hours and 30 minutes`, как во втором примере. Для расчёта абсолютного времени объекты `$this` или `$baseObject` и `$targetObject` сначала преобразовывают ко времени по стандарту UTC.

### Примеры

Пример #1 Пример вычисления разницы между датами методом DateTimeImmutable::diff()

Объектно-ориентированный стиль

    <?php

    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a days');

Результат выполнения приведённого примера:

    +2 days

Процедурный стиль

    <?php

    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a days');

Результат выполнения приведённого примера:

    +2 days

Пример #2 Пример вычисления разницы между датами методом DateTimeInterface::diff() при переходе на летнее время

    <?php

    $originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    echo $interval->format("%H:%I:%S (Полных дней: %a)"), "\n";

Результат выполнения приведённого примера:

    24:30:00 (Полных дней: 0)

Пример #3 Пример вычисления разницы для диапазона дат методом DateTimeInterface::diff()

Значение, которое возвращает метод, — точное количество времени, которое требуется для перехода от времени объекта `$this` ко времени объекта `$targetObject`. Поэтому сравнение 1 января с 31 декабря для невисокосных годов возвращает 364 дня, а не 365.

    <?php

    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Полных дней: ", $interval->format("%a"), "\n";

Результат выполнения приведённого примера:

    Полных дней: 364

Пример #4 Сравнение объектов DateTime

> Замечание:

> Объекты DateTimeImmutable и DateTime возможно сравнивать операторами сравнения.

    <?php

    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- DateInterval::format() - Форматирует интервал
- DateTime::add() - Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд
- DateTime::sub() - Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime

# DateTimeInterface::format

# DateTimeImmutable::format

# DateTime::format

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — Форматирует дату в заданном формате

### Описание

Объектно-ориентированный стиль

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

Процедурный стиль

function date_format(DateTimeInterface `$object`, string `$format`): string

Метод возвращает строку с датой в формате, который указали при вызове метода.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create().
`format`

  Шаблон результирующей строки (string) с датой. Смотрите параметры форматирования ниже. Вместо шаблона также указывают предопределённые константы даты и времени, например, константа `DATE_RSS` содержит строку формата `'D, d M Y H:i:s'`.

  Символы, которые метод распознаёт в строке параметра `format`
  Символ в строке `format` | Описание | Пример возвращаемого значения
  --- | --- | ---
  День | --- | ---
  `d` | День месяца, 2 цифры с ведущим нулём | От `01` до `31`
  `D` | Текстовое представление дня недели, 3 символа | От `Mon` до `Sun`
  `j` | День месяца без ведущего нуля | От `1` до `31`
  `l` (строчная 'L') | Полное наименование дня недели | От `Sunday` до `Saturday`
  `N` | Числовое представление дня недели по стандарту ISO 8601 | От `1` для понедельника до `7` для воскресенья
  `S` | Английское наращение — суффикс для порядкового числительного, которое означает день месяца, 2 буквы | Значения `st`, `nd`, `rd` или `th`. Опция хорошо работает с параметром формата `j`
  `w` | Порядковый номер дня недели | От `0` для воскресенья до `6` для субботы
  `z` | Порядковый номер дня в году начиная с 0 | От `0` до `365`
  Неделя | --- | ---
  `W` | Порядковый номер недели года по стандарту ISO 8601; недели начинаются с понедельника | Например: `42` — 42-я неделя года
  Месяц | --- | ---
  `F` | Полное название месяца, например January или March | От `January` до `December`
  `m` | Порядковый номер месяца с ведущим нулём | От `01` до `12`
  `M` | Сокращённое название месяца, 3 символа | От `Jan` до `Dec`
  `n` | Порядковый номер месяца без ведущего нуля | От `1` до `12`
  `t` | Количество дней в заданном месяце | От `28` до `31`
  Год | --- | ---
  `L` | Признак високосного года | `1`, если год високосный, иначе `0`
  `o` | Номер года с учётом нумерации недель стандартом ISO 8601. Параметр возвращает то же значение, что и параметр `Y`, за исключением случаев, когда номер недели по стандарту ISO, как возвращает параметр `W`, принадлежит предыдущему или следующему году, тогда возвращается год, которому принадлежит такая неделя | Примеры: `1999` или `2003`
  `X` | Расширенное полное числовое представление года, не меньше 4 цифр, со знаком `-` перед значением года, если год относится к периоду до нашей эры, и знаком `+` перед значением года нашей эры | Примеры: `-0055`, `+0787`, `+1999`, `+10191`
  `x` | Расширенное полное числовое представление, если требуется, или стандартное полное числовое представление по аналогии с параметром `Y`, если возможно. Не меньше четырёх цифр. Параметр добавит знак `-` перед значением года, если год относится к периоду до нашей эры. Перед значениями года после (и включая) `10000` параметр добавит знак `+` | Примеры: `-0055`, `0787`, `1999`, `+10191`
  `Y` | Полное числовое представление года, не меньше 4 цифр, со знаком `-` перед значениями лет до нашей эры | Примеры: `-0055`, `0787`, `1999`, `2003`, `10191`
  `y` | Номер года, 2 цифры | Примеры: `99`, `03`
  Время | --- | ---
  `a` | Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в нижнем регистре | `am` или `pm`
  `A` | Ante meridiem (лат. «до полудня») или Post meridiem (лат. «после полудня») в верхнем регистре | `AM` или `PM`
  `B` | Время в формате интернет-времени — альтернативной системы отсчета времени суток, которую предложила швейцарская компания — производитель часов Swatch | От `000` до `999`
  `g` | Часы в 12-часовом формате без ведущего нуля | От `1` до `12`
  `G` | Часы в 24-часовом формате без ведущего нуля | От `0` до `23`
  `h` | Часы в 12-часовом формате с ведущим нулём | От `01` до `12`
  `H` | Часы в 24-часовом формате с ведущим нулём | От `00` до `23`
  `i` | Минуты с ведущим нулём | От `00` до `59`
  `s` | Секунды с ведущим нулём | От `00` до `59`
  `u` | Микросекунды. Обратите внимание, что функция date() генерирует для поля микросекунд значение `000000`, поскольку принимает метку времени как целочисленное (int) значение в секундах, тогда как метод DateTimeInterface::format() поддерживает микросекунды, если объект DateTimeInterface создали с микросекундами | Например: `654321`
  `v` | Миллисекунды. Примечание к параметру `u` касается и этого параметра | Пример: `654`
  Часовой пояс | --- | ---
  `e` | Идентификатор часового пояса | Примеры: `UTC`, `GMT`, `Atlantic/Azores`
  `I` (заглавная i) | Признак летнего времени | `1`, если дата соответствует летнему времени, иначе `0`
  `O` | Разница со временем по Гринвичу без двоеточия между часами и минутами | Например: `+0200`
  `P` | Разница со временем по Гринвичу с двоеточием между часами и минутами | Например: `+02:00`
  `p` | То же, что и параметр `P`, но вместо `+00:00` возвращает `Z`. Параметр доступен с PHP 8.0.0 | Например: `Z` или `+02:00`
  `T` | Аббревиатура часового пояса, если известна; иначе смещение по Гринвичу | Примеры: `EST`, `MDT`, `+05`
  `Z` | Смещение часового пояса в секундах. Смещение для часовых поясов к западу от времени UTC — отрицательное, а для часовых поясов к востоку от времени UTC — положительное | От `-43200` до `50400`
  Полная дата/время | --- | ---
  `c` | Дата в формате стандарта ISO 8601. Спецификатор несовместим с расширенным форматом дат после 9999 года. Строковое представление дат позднее 9999 в расширенном формате получают через спецификатор `x` или `X`, поскольку для таких дат метод вернёт недопустимую строку. | 2004-02-12T15:19:21+00:00
  `r` | Дата в формате стандартов » RFC 222 и » RFC 5322 | Например: `Thu, 21 Dec 2000 16:01:07 +0200`
  `U` | Количество секунд, которое прошло с начала Unix-эпохи — с 1 января 1970 00:00:00 GMT | Смотрите также time()

  Метод выводит нераспознанные в строке формата символы без изменений. Параметр `Z` возвращает `0` при каждом вызове функции gmdate().

  > Замечание:

  > Форматирующий символ `u` полезен только при работе с функцией date_format() и пользовательскими метками времени, которые создали функцией date_create(), поскольку функция принимает только целочисленные (int) метки времени.

### Возвращаемые значения

Метод возвращает строку с отформатированной датой, если выполнился успешно.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Добавили символы форматирования `X` и `x`.
8.0.0 | Добавили символ форматирования `p`.

### Примеры

Пример #1 Пример форматирования даты методом DateTimeInterface::format()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');

Результат выполнения приведённого примера:

    2000-01-01 00:00:00

Процедурный стиль

    <?php

    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');

Результат выполнения приведённого примера:

    2000-01-01 00:00:00

Пример #2 Больше примеров

    <?php

    // Установка часового пояса по умолчанию
    date_default_timezone_set('UTC');

    // Время «сейчас»
    $date = new DateTimeImmutable();

    // Выведет что-то наподобие: Wednesday
    echo $date->format('l'), "\n";

    // Выведет что-то наподобие: Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* Передача констант в параметр format */
    // Выведет что-то наподобие: Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";

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

Пример #3 Пример экранирования символов при форматировании

    <?php

    $date = new DateTimeImmutable();

    // Выведет что-то наподобие: Wednesday the 19th
    echo $date->format('l \t\h\e jS');

Даты на других языках вместо метода DateTimeInterface::format() форматируют методом IntlDateFormatter::format().

### Примечания

Метод не учитывает настройки локали и выводит данные на английском языке.

### Смотрите также

- date() - Форматирует метку времени эпохи Unix

# DateTimeInterface::getMicrosecond

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Получает микросекундную часть метки времени Unix

### Описание

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Получает микросекундную часть метки времени Unix.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает микросекундную часть метки времени Unix, представляющей дату.

### Примеры

Пример #1 Пример использования метода DateTimeInterface::getMicrosecond()

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

Результат выполнения приведённого примера:

    string(6) "789123"
    int(789123)

### Смотрите также

- DateTimeInterface::getTimestamp() - Возвращает метку времени с начала эпохи Unix
- DateTimeInterface::format() - Форматирует дату в заданном формате

# DateTimeInterface::getOffset

# DateTimeImmutable::getOffset

# DateTime::getOffset

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — Возвращает смещение часового пояса

### Описание

Объектно-ориентированный стиль

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

Процедурный стиль

function date_offset_get(DateTimeInterface `$object`): int

Метод возвращает смещение часового пояса.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create().

### Возвращаемые значения

Метод возвращает смещение времени заданного часового пояса относительно времени по стандарту UTC в секундах, если выполнился успешно.

### Примеры

Пример #1 Пример получения смещения часового пояса методом DateTime::getOffset()

Объектно-ориентированный стиль

    <?php

    $winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
    $summer = new DateTimeImmutable('2008-06-21', new DateTimeZone('America/New_York'));

    echo $winter->getOffset() . "\n";
    echo $summer->getOffset() . "\n";

Результат выполнения приведённого примера:

    -18000
    -14400

Процедурный стиль

    <?php

    $winter = date_create('2010-12-21', timezone_open('America/New_York'));
    $summer = date_create('2008-06-21', timezone_open('America/New_York'));

    echo date_offset_get($winter) . "\n";
    echo date_offset_get($summer) . "\n";

Результат выполнения приведённого примера:

    -18000
    -14400

Замечание: значение -18000 равно смещению в -5 часов, а значение -14400 — в -4 часа.

# DateTimeInterface::getTimestamp

# DateTimeImmutable::getTimestamp

# DateTime::getTimestamp

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Возвращает метку времени с начала эпохи Unix

### Описание

Объектно-ориентированный стиль

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

Процедурный стиль

function date_timestamp_get(DateTimeInterface `$object`): int

Метод возвращает метку времени с начала Unix-эпохи.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает Unix-метку, которая представляет момент времени.

### Ошибки

Метод выбросит ошибку DateRangeError, если не получится представить метку времени значением int. До PHP 8.3.0 выбрасывалась ошибка ValueError. А до PHP 8.0.0 возвращалось логическое значение `false`. При этом метку времени в виде значения string получают вызовом метода DateTimeInterface::format() с параметром форматирования `U`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | При выходе за пределы диапазона метод теперь выбрасывает ошибку DateRangeError.
8.0.0 | Функции больше не возвращают значение `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения метки времени методом DateTime::getTimestamp()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

Вывод приведённого примера будет похож на:

    1272509157

Процедурный стиль

    <?php

    $date = date_create();
    echo date_timestamp_get($date);

Вывод приведённого примера будет похож на:

    1272509157

Метку времени с миллисекундами или микросекундами помогает получить метод DateTimeInterface::format().

Пример #2 Пример получения метки времени с милли- и микросекундами

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable();
    $milli = (int) $date->format('Uv'); // Метка времени с миллисекундами
    $micro = (int) $date->format('Uu'); // Метка времени с микросекундами

    echo $milli, "\n", $micro, "\n";

Вывод приведённого примера будет похож на:

    1674057635586
    1674057635586918

### Смотрите также

- DateTime::setTimestamp() - Устанавливает дату и время на основе метки времени Unix
- DateTimeImmutable::setTimestamp() - Устанавливает дату и время на основе метки времени Unix
- DateTimeInterface::format() - Форматирует дату в заданном формате
- DateTimeInterface::getMicrosecond() - Получает микросекундную часть метки времени Unix

# DateTimeInterface::getTimezone

# DateTimeImmutable::getTimezone

# DateTime::getTimezone

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — Возвращает часовой пояс объекта даты и времени

### Описание

Объектно-ориентированный стиль

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

Процедурный стиль

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

Метод возвращает часовой пояс, который содержится в объекте даты и времени.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTime, который возвращает функция date_create().

### Возвращаемые значения

Метод возвращает объект DateTimeZone, если выполнился успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения часового пояса методом DateTime::getTimezone()

Объектно-ориентированный стиль

    <?php

    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

Результат выполнения приведённого примера:

    Europe/London

Процедурный стиль

    <?php

    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

Результат выполнения приведённого примера:

    Europe/London

### Смотрите также

- DateTime::setTimezone() - Устанавливает часовой пояс для объекта DateTime

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Подготавливает данные объекта даты и времени для сериализации

### Описание

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

Метод __serialize() обрабатывает данные объекта даты и времени при вызове функции сериализации.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив данных для представления объекта DateTime или других совместимых с интерфейсом объектов при сериализации.

### Примеры

Пример #1 Пример обработки объекта методом DateTime::__serialize() для подготовки данных к сериализации

    <?php

    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

Результат выполнения приведённого примера:

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### Смотрите также

- DateTime::__unserialize() - Подготавливает данные для восстановления объекта даты и времени при десериализации

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Подготавливает данные для восстановления объекта даты и времени при десериализации

### Описание

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

Метод __unserialize() обрабатывает данные промежуточного представления объекта даты и времени, аналогичные подготовленным методом DateTimeInterface::__serialize, для восстановления исходного объекта даты и времени при десериализации.

### Список параметров

`data`

  Параметр получает массив с данными представления объекта DateTime или другого объекта, совместимого с интерфейсом.

### Возвращаемые значения

Метод не возвращает значений, а только обрабатывает промежуточное представление объекта DateTime или другого объекта даты и времени, совместимого с интерфейсом.

### Примеры

Пример #1 Пример обработки промежуточного представления объекта даты и времени методом DateTime::__unserialize()

    <?php

    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

Результат выполнения приведённого примера:

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### Смотрите также

- DateTime::__serialize() - Подготавливает данные объекта даты и времени для сериализации

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — Обрабатывает событие __wakeup

Внимание

Начиная с PHP 8.5.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

Метод играет роль обработчика десериализации объекта аналогично методу __wakeup().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод не возвращает значение, только инициализирует объект DateTime.

## Содержание

- DateTimeInterface::diff — Возвращает разницу между двумя объектами даты и времени
- DateTimeInterface::format — Форматирует дату в заданном формате
- DateTimeInterface::getMicrosecond — Получает микросекундную часть метки времени Unix
- DateTimeInterface::getOffset — Возвращает смещение часового пояса
- DateTimeInterface::getTimestamp — Возвращает метку времени с начала эпохи Unix
- DateTimeInterface::getTimezone — Возвращает часовой пояс объекта даты и времени
- DateTime::__serialize — Подготавливает данные объекта даты и времени для сериализации
- DateTime::__unserialize — Подготавливает данные для восстановления объекта даты и времени при десериализации
- DateTime::__wakeup — Обрабатывает событие __wakeup

# Класс DateTimeZone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Введение

Представление часового пояса.

## Обзор класса

class DateTimeZone {
/* Константы */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* Методы */
public function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## Предопределённые константы

`DateTimeZone::AFRICA` int

  Часовые пояса Африки.

`DateTimeZone::AMERICA` int

  Часовые пояса Америки.

`DateTimeZone::ANTARCTICA` int

  Часовые пояса Антарктики.

`DateTimeZone::ARCTIC` int

  Часовые пояса Арктики.

`DateTimeZone::ASIA` int

  Часовые пояса Азии.

`DateTimeZone::ATLANTIC` int

  Часовые пояса Атлантики.

`DateTimeZone::AUSTRALIA` int

  Часовые пояса Австралии.

`DateTimeZone::EUROPE` int

  Часовые пояса Европы.

`DateTimeZone::INDIAN` int

  Часовые пояса Индии.

`DateTimeZone::PACIFIC` int

  Часовые пояса Тихого океана.

`DateTimeZone::UTC` int

  Часовой пояс UTC.

`DateTimeZone::ALL` int

  Все часовые пояса.

`DateTimeZone::ALL_WITH_BC` int

  Все часовые пояса, включая обратно совместимые.

`DateTimeZone::PER_COUNTRY` int

  Число часовых поясов на страну.

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — Создаёт новый объект DateTimeZone

### Описание

Объектно-ориентированный стиль

public function DateTimeZone::__construct(string `$timezone`)

Процедурный стиль

function timezone_open(string `$timezone`): DateTimeZone|false

Метод создаёт новый объект DateTimeZone.

Объект DateTimeZone поддерживает три типа представления часового пояса: тип `1` — смещение относительно времени UTC, тип `2` — аббревиатура часового пояса и тип `3` — идентификатор часового пояса, которые публикуются в базе данных часовых поясов организации IANA.

Объект DateTimeZone прикрепляют к объектам DateTime и DateTimeImmutable для форматирования времени в заданном часовом поясе.

### Список параметров

`timezone`

  Поддерживаемое название часового пояса, значение смещения в формате +0200 или аббревиатура часового пояса наподобие BST.

### Возвращаемые значения

Метод возвращает объект DateTimeZone, если выполнился успешно. Процедурный стиль возвращает `false`, если возникла ошибка.

### Ошибки

При передаче недопустимого часового пояса метод выбрасывает исключение DateInvalidTimeZoneException. До PHP 8.3 вместо этого выбрасывалось исключение Exception.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | При передаче недопустимых значений часового пояса вместо общего исключения Exception метод теперь выбрасывает исключение DateInvalidTimeZoneException.

### Примеры

Пример #1 Пример создания и прикрепления часового пояса DateTimeZone к объекту даты и времени DateTimeImmutable

    <?php

    $d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

    $timezones = ['Europe/London', 'GMT+04:45', '-06:00', 'CEST'];

    foreach ($timezones as $tz) {
        $tzo = new DateTimeZone($tz);

        $local = $d->setTimezone($tzo);
        echo $local->format(DateTimeInterface::RFC2822 . ' — e') . "\n";
    }

Результат выполнения приведённого примера:

    Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
    Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
    Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
    Thu, 02 Jun 2022 17:44:48 +0200 — CEST

Пример #2 Пример перехвата ошибок при создании объекта DateTimeZone

    <?php

    // Обработка ошибок путём перехвата исключений
    $timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

    foreach ($timezones as $tz) {
        try {
            $mars = new DateTimeZone($tz);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

Результат выполнения приведённого примера:

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]:  Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — Возвращает информацию о местоположении для часового пояса

### Описание

Объектно-ориентированный стиль

public function DateTimeZone::getLocation(): array|false

Процедурный стиль

function timezone_location_get(DateTimeZone `$object`): array|false

Функция возвращает информацию о местоположении часового пояса, включая код страны, широту, долготу и комментарии.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTimeZone, который возвращает функция timezone_open().

### Возвращаемые значения

Функция возвращает массив с информацией о местоположении часового пояса или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения информации о местоположении для часового пояса методом DateTimeZone::getLocation()

    <?php

    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

Результат выполнения приведённого примера:

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

Элемент `country_code` содержит двубуквенный код страны по стандарту ISO 3166-1. Элементы `latitude` и `longitude` — координаты города из идентификатора часового пояса, а элемент `comments`, если не равен значению `false`, — содержит подсказку о территории страны, на которой действует часовой пояс. Эта информация выводится в удобном для чтения пользователями виде.

### Смотрите также

- Метод DateTimeZone::listIdentifiers() - Возвращает индексный массив идентификаторов часовых поясов для получения полного или частичного списка всех поддерживаемых идентификаторов часовых поясов.

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — Возвращает имя часового пояса

### Описание

Объектно-ориентированный стиль

public function DateTimeZone::getName(): string

Процедурный стиль

function timezone_name_get(DateTimeZone `$object`): string

Возвращает имя часового пояса.

### Список параметров

`object`

  Объект класса DateTimeZone, для которого нужно получить имя.

### Возвращаемые значения

В зависимости от типа зоны, смещения UTC (тип 1), аббревиатуры часового пояса (тип 2) и идентификаторов часовых поясов, опубликованных в базе данных часовых поясов IANA (тип 3), строка дескриптора для создания нового объекта DateTimeZone с тем же смещением и/или правилами. Например, `02:00`, `CEST` или одно из имён часовых поясов в списке часовых поясов.

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — Возвращает смещение времени часового пояса относительно времени UTC

### Описание

Объектно-ориентированный стиль

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

Процедурный стиль

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

Функция возвращает смещение времени заданного часового пояса относительно времени по стандарту UTC на конкретный момент времени, который содержится в объекте даты и времени аргумента `datetime`. Смещение вычисляется для часового пояса в объекте DateTimeZone относительно времени UTC.

### Список параметров

`object`
  Только для процедурного стиля: объект DateTimeZone, который возвращает функция timezone_open().
`datetime`

  Объект DateTime или другой совместимый с интерфейсом объект с датой и временем, относительно которого вычисляется смещение.

### Возвращаемые значения

Функция возвращает смещение времени часового пояса в секундах.

### Примеры

Пример #1 Пример получения смещения времени часового пояса относительно UTC-времени методом DateTimeZone::getOffset()

    <?php

    // Создаём два объекта часового пояса: один для города Тайбэй — столицы Тайваня,
    // и другой для города Токио — столицы Японии
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan  = new DateTimeZone("Asia/Tokyo");

    // Создаём два объекта DateTime, оба содержат идентичные метки Unix-времени,
    // но разные часовые пояса
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan  = new DateTime("now", $dateTimeZoneJapan);

    // Вычисляем смещение времени часового пояса Токио в объекте $dateTimeZoneJapan
    // относительно времени UTC на момент времени в объекте $dateTimeTaipei
    // с учётом переходов на летнее или зимнее время и исторических изменений наподобие календарных реформ
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // Выведет значение int(32400) для дат после 01:00:00 субботы 8 сентября 1951 года
    // по стандартному японскому времени в часовом поясе JST, Sat Sep 8 01:00:00 1951 JST
    var_dump($timeOffset);

Результат выполнения приведённого примера:

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Возвращает информацию о переходах времени для часового пояса

### Описание

Объектно-ориентированный стиль

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

Процедурный стиль

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

### Список параметров

`object`
  Только для процедурного стиля: объект DateTimeZone, который возвращает функция timezone_open().
`timestampBegin`

  Начальная метка времени.

`timestampEnd`

  Конечная метка времени.

### Возвращаемые значения

Функция возвращает индексный массив массивов с информацией об исторических, сезоннных и политико-административных переходах времени в хронологическом порядке, если выполнилась успешно, или `false`, если возникла ошибка. Объекты DateTimeZone, которые оборачивают смещения 1-го типа со смещением относительно времени UTC и 2-го типа с аббревиатурой названия часового пояса, не содержат переходов и вызов метода на таких объектах вернёт значение `false`.

При передаче аргумента `timestampBegin` первым элементом массива с результатами становится массив с информацией о последнем на момент `timestampBegin` переходе.

Структура переходов массива
Ключ | Тип | Описание
--- | --- | ---
`ts` | int | Метка времени Unix
`time` | string | Строка времени в формате `DateTimeInterface::ISO8601_EXPANDED` для PHP 8.2 и более поздних выпусков или в формате `DateTimeInterface::ISO8601` для PHP 8.1 и предыдущих выпусков
`offset` | int | Смещение относительно времени UTC в секундах
`isdst` | bool | Активно ли летнее время
`abbr` | string | Аббревиатура часового пояса

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Значение параметра `timestampEnd` по умолчанию изменено на 2147483647. Ранее оно было `PHP_INT_MAX`.

### Примеры

Пример #1 Пример получения хронологии переходов времени функцией timezone_transitions_get()

    <?php

    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

Пример #2 Пример работы функции timezone_transitions_get() с аргументом `timestampBegin`

    <?php

    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [ts] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Возвращает ассоциативный массив с флагами перехода на летнее время, смещениями и названиями часовых поясов

### Описание

Объектно-ориентированный стиль

public static function DateTimeZone::listAbbreviations(): array

Процедурный стиль

function timezone_abbreviations_list(): array

Функция возвращает список абрревиатур, который включает исторические сокращения названий часовых поясов. Список содержит формально корректные, но неоднозначные записи, и конфликты сокращений наподобие `PST`, которое обозначает как часовой пояс в США, так и на Филиппинах.

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

> Замечание:

> Данные для функции компилируются предварительно по соображениям производительности и не обновляются при установке более новой версии базы данных » timezonedb.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив сокращённых названий часовых поясов.

### Примеры

Пример #1 Пример получения списка сокращённых названий часовых поясов функцией timezone_abbreviations_list()

    <?php

    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### Смотрите также

- timezone_identifiers_list() - Псевдоним DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — Возвращает индексный массив идентификаторов часовых поясов

### Описание

Объектно-ориентированный стиль

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Процедурный стиль

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

Метод возвращает список » идентификаторов часовых поясов, которые определила администрация IANA.

> Замечание: Для определения часового пояса клиента, например браузера, в JavaScript обращаются к объекту » Intl.DateTimeFormat или » Temporal.ZonedDateTime.

### Список параметров

`timezoneGroup`

  Константа или комбинация констант класса DateTimeZone.

`countryCode`

  Двухбуквенный код страны в верхнем регистре, совместимый со стандартом ISO 3166-1.

  > Замечание: Параметр требуется и влияет на результат только при установке для параметра `timezoneGroup` флага `DateTimeZone::PER_COUNTRY`.

### Возвращаемые значения

Метод возвращает массив идентификаторов часовых поясов. Возвращаются только неустаревшие элементы. При передаче в параметр `timezoneGroup` флага `DateTimeZone::ALL_WITH_BC` метод возвращает все идентификаторы часовых поясов, включая устаревшие.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | До этой версии при ошибке возвращалось значение `false`.
7.1.0 | Параметр `countryCode` теперь принимает значение `null`.

### Примеры

Пример #1 Пример получения списка идентификаторов часовых поясов с комментарием о расположении

    <?php

    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
        $tz = new DateTimeZone($tzid);
        $comments = $tz->getLocation()['comments'];
        echo $tzid . " (" . ($comments ?: 'Whole region') . ")\n";
    }

Вывод приведённого примера будет похож на:

    America/Antigua (Whole region)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
    // (Только фрагмент вывода, из-за длины)

Пример #2 Пример получения списка идентификаторов конкретного региона

    <?php

    $timezone_identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ASIA);
    for ($i = 0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }

Вывод приведённого примера будет похож на:

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

Пример #3 Пример получения списка идентификаторов двух регионов

    <?php

    $timezone_identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ASIA | DateTimeZone::PACIFIC);
    echo join(', ', $timezone_identifiers);

Вывод приведённого примера будет похож на:

    Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
    Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
    Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
    Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
    Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
    Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
    Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
    Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
    Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
    Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
    Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
    Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
    Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
    Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
    Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
    Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
    Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
    Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
    Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
    Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
    Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
    Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
    Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
    Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
    Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
    Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

Пример #4 Пример получения списка идентификаторов одной страны

    <?php

    $timezone_identifiers = DateTimeZone::listIdentifiers(DateTimeZone::PER_COUNTRY, "UA");
    foreach ($timezone_identifiers as $identifier) {
        echo "$identifier\n";
    }

Вывод приведённого примера будет похож на:

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### Смотрите также

- timezone_abbreviations_list() - Псевдоним DateTimeZone::listAbbreviations

## Содержание

- DateTimeZone::__construct — Создаёт новый объект DateTimeZone
- DateTimeZone::getLocation — Возвращает информацию о местоположении для часового пояса
- DateTimeZone::getName — Возвращает имя часового пояса
- DateTimeZone::getOffset — Возвращает смещение времени часового пояса относительно времени UTC
- DateTimeZone::getTransitions — Возвращает информацию о переходах времени для часового пояса
- DateTimeZone::listAbbreviations — Возвращает ассоциативный массив с флагами перехода на летнее время, смещениями и названиями часовых поясов
- DateTimeZone::listIdentifiers — Возвращает индексный массив идентификаторов часовых поясов

# Класс DateInterval

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Представляет интервалы дат.

Интервал дат хранит либо определённое фиксированное время (в годах, месяцах, днях, часах и т.д.) или относительную строку времени в формате, поддерживаемом конструктором DateTimeImmutable и DateTime.

Более конкретно, информация в объекте класса DateInterval является инструкцией для перехода от одной даты/времени к другой дате/времени. Этот процесс не всегда обратим.

Распространённым способом создания объекта DateInterval является вычисление разницы между двумя объектами даты/времени с помощью DateTimeInterface::diff().

Поскольку не существует чётко определённого способа сравнения интервалов дат, экземпляры DateInterval являются несравнимыми.

## Обзор класса

class DateInterval {
/* Свойства */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* Методы */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## Свойства

Внимание

Доступные свойства, перечисленные ниже, зависят от версии PHP и должны рассматриваться как доступные только для чтения.

y

  Количество лет.

m

  Количество месяцев.

d

  Количество дней.

h

  Количество часов.

i

  Количество минут.

s

  Количество секунд.

f

  Количество микросекунд в виде долей секунды.

invert

  Принимает `1`, если интервал представляет отрицательный период времени и `0` в противном случае. Смотрите DateInterval::format().

days

  Если объект DateInterval создан методом DateTimeImmutable::diff() или DateTime::diff(), то это общее количество полных дней между начальной и конечной датами В противном случае days примет значение `false`.

from_string

  Если объект DateInterval был создан методом DateInterval::createFromDateString(), то значение свойства будет `true` и свойство date_string будет заполнено. В противном случае значение свойства будет `false` и свойства от y до f, invert и days будут заполнены.

date_string

  Строка, используемая в качестве аргумента метода DateInterval::createFromDateString().

## Список изменений

Версия | Описание
--- | ---
8.2.0 | Добавлены свойства from_string и date_string для экземпляров DateInterval, которые были созданы с помощью метода DateInterval::createFromDateString().
8.2.0 | Будут видны только значения от `y` до `f`, `invert` и `days`.
7.4.0 | Экземпляры DateInterval теперь несравнимы; ранее все экземпляры DateInterval считались равными.
7.1.0 | Добавлено свойство f.

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Создаёт новый объект DateInterval

### Описание

public function DateInterval::__construct(string `$duration`)

Создаёт новый объект DateInterval.

### Список параметров

`duration`

  Описание интервала.

  Формат описания интервала начинается с буквы `P` (от англ. period). Длительность периодов представляют целочисленным значением, за которым идёт обозначение периода. Перед частью описания с элементами времени указывают букву `T`.

  Обозначения периодов `duration`
  Обозначение периода | Описание
  --- | ---
  `Y` | Годы
  `M` | Месяцы
  `D` | Дни
  `W` | Недели. Преобразовываются в дни. До PHP 8.0.0 нельзя было объединять с обозначением дней `D`.
  `H` | Часы
  `M` | Минуты
  `S` | Секунды

  Вот несколько простых примеров. Два дня — `P2D`. Две секунды — `PT2S`. Шесть лет и пять минут — `P6YT5M`.

  > Замечание:

  > Единицы измерения записывают от наибольшей величины слева к наименьшей величине справа. То есть годы идут перед месяцами, месяцы перед днями, дни перед минутами и т. д. Поэтому один год и четыре дня представляют как `P1Y4D`, но не `P4D1Y`.

  Описание можно записать и в виде даты и времени. Пример одного года и четырёх дней можно описать как `P0001-00-04T00:00:00`. Но значения в этом формате не должны выходить за рамки допустимых значений даты и времени (например, `25` часов недопустимо).

  Эти форматы основаны на » стандарте ISO 8601.

### Ошибки

Метод выбросит исключение DateMalformedIntervalStringException, если не разберёт значение параметра `duration` как интервал. До PHP 8.3 метод выбрасывал исключение Exception.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь вместо исключения Exception выбрасывается исключение DateMalformedIntervalStringException.
8.2.0 | Из свойств объекта интервала будут видны только `y` в `f`, `invert` и `days`, включая новое логическое свойство `from_string`.
8.0.0 | Обозначение недель `W` теперь разрешено комбинировать с обозначением дней `D`.

### Примеры

Пример #1 Пример создания и использования объектов DateInterval

    <?php

    // Создаём конкретную дату
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Создаём интервал
    $interval = new \DateInterval("P7D");

    // Добавляем интервал
    $someDate->add($interval);

    // Преобразовываем интервал в строку
    echo $interval->format("%d");

Результат выполнения приведённого примера:

    7

Пример #2 Пример использования объекта DateInterval

    <?php

    $interval = new DateInterval('P1W2D');
    var_dump($interval);

Результат выполнения приведённого примера в PHP 8.2:

    object(DateInterval)#1 (10) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["from_string"]=>
      bool(false)
    }

Результат выполнения приведённого примера в PHP 8:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

Результат выполнения приведённого примера в PHP 7:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(2)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

### Смотрите также

- DateInterval::format() - Форматирует интервал
- DateTime::add() - Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд
- DateTime::sub() - Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime
- DateTime::diff() - Возвращает разницу между двумя объектами даты и времени

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Создаёт объект DateInterval из строки с обозначениями времени в относительном формате

### Описание

Объектно-ориентированный стиль

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

Процедурный стиль

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Метод создаёт объект DateInterval из строки, которая содержит обозначения времени в относительном формате. Метод разбирает строку с датой и временем аналогично конструктору класса DateTimeImmutable.

### Список параметров

`datetime`

  Строка с обозначениями даты и времени в относительном формате, который поддерживается методами классов DateTimeImmutable, DateTime и функцией strtotime().

  Интервалы на основе строки в формате стандарта ISO-8601 — наподобие `P7D` — создают методом DateInterval::__construct().

### Возвращаемые значения

Метод возвращает новый объект DateInterval, если выполнился успешно. Процедурный стиль возвращает `false`, если возникла ошибка.

### Ошибки

Только для объектно-ориентированного API: при передаче недопустимой строки с датой и временем метод выбрасывает исключение DateMalformedIntervalStringException.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вместо объединения типов DateInterval|false метод теперь возвращает тип DateInterval.
8.3.0 | Метод DateInterval::createFromDateString() теперь выбрасывает исключение DateMalformedIntervalStringException, если передали строку в недопустимом формате. Раньше метод возвращал значение `false` и выдавал предупреждение. Функция date_interval_create_from_date_string() не изменилась.
8.2.0 | Метод создаёт объект DateInterval, в котором останутся видимыми только свойства `from_string` и `date_string`.

### Примеры

Пример #1 Пример разбора допустимых интервалов времени

    <?php

    // Интервалы в каждом примере эквивалентны
    $i = new DateInterval('P1D');
    $i = DateInterval::createFromDateString('1 day');

    $i = new DateInterval('P2W');
    $i = DateInterval::createFromDateString('2 weeks');

    $i = new DateInterval('P3M');
    $i = DateInterval::createFromDateString('3 months');

    $i = new DateInterval('P4Y');
    $i = DateInterval::createFromDateString('4 years');

    $i = new DateInterval('P1Y1D');
    $i = DateInterval::createFromDateString('1 year + 1 day');

    $i = new DateInterval('P1DT12H');
    $i = DateInterval::createFromDateString('1 day + 12 hours');

    $i = new DateInterval('PT3600S');
    $i = DateInterval::createFromDateString('3600 seconds');

Пример #2 Пример разбора комбинации обозначений и отрицательных интервалов

    <?php

    $i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
    echo $i->format('%d %h %i'), "\n";

    $i = DateInterval::createFromDateString('1 year - 10 days');
    echo $i->format('%y %d'), "\n";

Результат выполнения приведённого примера:

    449 2 70
    1 -10

Пример #3 Пример разбора относительных интервалов времени

    <?php

    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

Результат выполнения приведённого примера в PHP 8.2:

    object(DateInterval)#1 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(22) "last day of next month"
    }
    object(DateInterval)#2 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(12) "last weekday"
    }

Результат выполнения приведённого примера в PHP 8 аналогичен:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(1)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(2)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }
    object(DateInterval)#2 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(1)
      ["special_amount"]=>
      int(-1)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(1)
    }

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — Форматирует интервал

### Описание

public function DateInterval::format(string `$format`): string

Метод форматирует интервал.

### Список параметров

`format`

  В строке `format` распознаются следующие символы. Каждому такому символу должен предшествовать знак процента (`%`).
  Символ в строке`format` | Описание | Пример значения
  --- | --- | ---
  `%` | Символ `%` | `%`
  `Y` | Годы, число, минимум две цифры с ведущими нулями | `01`, `03`
  `y` | Годы, число | `1`, `3`
  `M` | Месяцы, число, минимум две цифры с ведущими нулями | `01`, `03`, `12`
  `m` | Месяцы, число | `1`, `3`, `12`
  `D` | Дни, число, минимум две цифры с ведущими нулями | `01`, `03`, `31`
  `d` | Дни, число | `1`, `3`, `31`
  `a` | Общее количество дней в качестве результата выполнения DateTime::diff(), либо `unknown` | `4`, `18`, `8123`
  `H` | Часы, число, минимум две цифры с ведущими нулями | `01`, `03`, `23`
  `h` | Часы, число | `1`, `3`, `23`
  `I` | Минуты, число, минимум две цифры с ведущими нулями | `01`, `03`, `59`
  `i` | Минуты, число | `1`, `3`, `59`
  `S` | Секунды, число, минимум две цифры с ведущими нулями | `01`, `03`, `57`
  `s` | Секунды, число | `1`, `3`, `57`
  `F` | Микросекунды, число, как минимум 6 цифр с ведущим 0 | `007701`, `052738`, `428291`
  `f` | Микросекунды, число | `7701`, `52738`, `428291`
  `R` | Знак "`-`" при отрицательном числе, "`+`" при положительном | `-`, `+`
  `r` | Знак "`-`" при отрицательном числе, пусто при положительном | `-`, ``

### Возвращаемые значения

Возвращает отформатированный интервал.

### Список изменений

Версия | Описание
--- | ---
7.2.12 | Формат `F` и `f` теперь всегда будет положительным.
7.1.0 | Добавлены форматирующие символы `F` и `f`.

### Примеры

Пример #1 Пример использования DateInterval

    <?php

    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d days');

Результат выполнения приведённого примера:

    4 days

Пример #2 DateInterval и перенос единиц

    <?php

    $interval = new DateInterval('P32D');
    echo $interval->format('%d days');

Результат выполнения приведённого примера:

    32 days

Пример #3 DateInterval и DateTime::diff() с модификаторами %a и %d

    <?php

    $january = new DateTime('2010-01-01');
    $february = new DateTime('2010-02-01');
    $interval = $february->diff($january);

    // Модификатор %a выведет общее количество дней.
    echo $interval->format('%a total days')."\n";

    // В то время как модификатор %d выведет только количество дней, не покрытых месяцем
    echo $interval->format('%m month, %d days');

Результат выполнения приведённого примера:

    31 total days
    1 month, 0 days

### Примечания

> Замечание:

> Метод DateInterval::format() не делает пересчёта и переноса единиц времени при переполнении значений дат. Это ожидаемое поведение, поскольку невозможно реализовать перенос при значениях, например, `"32 дня"`, которые могут интерпретироваться по-разному, начиная `"1 месяц и 4 дня"` и заканчивая `"1 месяц и 1 день"`.

### Смотрите также

- DateTime::diff() - Возвращает разницу между двумя объектами даты и времени

## Содержание

- DateInterval::__construct — Создаёт новый объект DateInterval
- DateInterval::createFromDateString — Создаёт объект DateInterval из строки с обозначениями времени в относительном формате
- DateInterval::format — Форматирует интервал

# Класс DatePeriod

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Введение

Объекты класса представляют временной период.

На основе объектов класса перебирают набор дат и времени с повторением через равные временные интервалы заданное количество раз или до заданной конечной даты.

## Обзор класса

class DatePeriod implements IteratorAggregate {
/* Константы */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Свойства */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Методы */
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## Предопределённые константы

`DatePeriod::EXCLUDE_START_DATE` int

  Константа исключает начальную дату из набора дат и времени для перебора, передаётся в параметр опций метода DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Константа включает конечную дату в набор дат и времени для перебора, передаётся в параметр опций метода DatePeriod::__construct().

## Свойства

recurrences

  Минимальное количество экземпляров, которое верёт итератор.

  При передаче количества повторений через параметр recurrences в конструктор экземпляра DatePeriod свойство объекта содержит это значение, плюс один, если начальную дату не отключили константой `DatePeriod::EXCLUDE_START_DATE`, плюс один, если конечную дату исключили константой `DatePeriod::INCLUDE_END_DATE`.

  При пропуске количества повторений свойство объекта содержит минимальное количество возвращаемых экземпляров — `0`, плюс один, если начальную дату не включили константой `DatePeriod::EXCLUDE_START_DATE`, плюс один, если конечную дату исключили константой `DatePeriod::INCLUDE_END_DATE`.

      <?php

      $start = new DateTime('2018-12-31 00:00:00');
      $end   = new DateTime('2021-12-31 00:00:00');
      $interval = new DateInterval('P1M');
      $recurrences = 5;

      // Повторения устанавливаются через конструктор
      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
      echo $period->recurrences, "\n";

      // Повторения не задали в конструкторе
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  Результат выполнения приведённого примера:

      5
      6
      7
      1
      0

  Смотрите также описание метода DatePeriod::getRecurrences().

include_end_date

  Включать ли дату окончания в набор повторяющихся дат или нет.

include_start_date

  Включать ли начальную дату в набор дат или нет.

start

  Дата начала периода.

current

  В процессе итерации содержит текущую дату периода.

end

  Конечная дата периода.

interval

  Спецификация повторяющегося интервала согласно ISO 8601.

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Типизировали константы класса.
8.2.0 | Добавили константу `DatePeriod::INCLUDE_END_DATE` и свойство include_end_date.
8.0.0 | Класс DatePeriod теперь реализует интерфейс IteratorAggregate. Раньше вместо этого класс реализовывал интерфейс Traversable.

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Инициализирует новый экземпляр класса DatePeriod

### Описание

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
Внимание

Устаревший конструктор:

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

Начиная с PHP 8.4.0 вариант конструктора устарел; периоды на основе интервалов повторения в формате стандарта ISO 8601 создают методом DatePeriod::createFromISO8601String().

Метод инициализирует новый объект DatePeriod.

Объект DatePeriod работает как итератор для генерации серии объектов DateTimeImmutable или DateTime на основе трёх параметров: начальной даты `start`, интервала `interval` и дополнительно конечной даты `end` или количества повторений `recurrences`.

Объект периода генерирует объекты, класс которых эквивалентен классу объекта в параметре `start`: DateTimeImmutable или DateTime.

### Список параметров

`start`

  Начальная дата. По умолчанию включается в набор результатов.

`interval`

  Интервал.

`recurrences`

  Количество повторений: число больше `0`. Объект периода выдаст на одно повторение больше, поскольку начальная дата по умолчанию включается в набор результатов.

`end`

  Конечная дата. По умолчанию исключается из набора результатов.

`isostr`

  Строка с интервалом повторения, формат которого описывает спецификация стандарта » ISO 8601. PHP поддерживает только часть спецификаций.

  Пример отдельных спецификации интервалов по стандарту ISO 8601, которые PHP не поддерживает:

  1. нулевое количество повторений: `R0/`
  2. числовые обозначения смещения времени: `+02:00`; поддерживается только UTC-смещение `Z`
`options`

  Битовое поле для управления границами периода.

  `DatePeriod::EXCLUDE_START_DATE`: открывает границу слева и исключает начальную дату из набора повторений внутри периода.

  `DatePeriod::INCLUDE_END_DATE`: закрывает границу справа и включает конечную дату в набор повторений внутри периода.

### Ошибки

При передаче в параметр `isostr` интервала, формат которого не соответствует спецификациям стандарта ISO 8601, метод выбросит исключение DateMalformedPeriodStringException; до PHP 8.3 выбрасывалось исключение Exception.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Сигнатура с параметром `isostr` устарела; период на основе интервалов повторения в формате стандарта ISO 8601 создают методом DatePeriod::createFromISO8601String().
8.3.0 | Вместо исключения Exception теперь выбрасывается исключение DateMalformedPeriodStringException.
8.2.0 | Добавили константу `DatePeriod::INCLUDE_END_DATE`.
7.2.19, 7.3.6, 7.4.0 | Параметр `recurrences` теперь принимает только значения больше `0`.

### Примеры

Пример #1 Пример генерации последовательности дат через объект DatePeriod

    <?php

    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');
    $recurrences = 4;
    $iso = 'R4/2012-07-01T00:00:00Z/P7D';

    // Каждый следующий период создаст одинаковую последовательность дат
    $period = new DatePeriod($start, $interval, $recurrences);
    $period = new DatePeriod($start, $interval, $end);
    $period = new DatePeriod($iso);

    // При итерации по объекту DatePeriod повторяется генерация и вывод
    // каждой даты внутри периода.
    foreach ($period as $date) {
        echo $date->format('Y-m-d') . "\n";
    }

Результат выполнения приведённого примера:

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    2012-07-01
    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Пример #2 Пример исключения начальной даты из периода DatePeriod флагом `DatePeriod::EXCLUDE_START_DATE`

    <?php

    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');

    $period = new DatePeriod(
        $start,
        $interval,
        $end,
        DatePeriod::EXCLUDE_START_DATE
    );

    // При итерации по объекту DatePeriod повторяется генерация и вывод
    // каждой даты внутри периода,
    // кроме даты 2012-07-01.
    foreach ($period as $date) {
        echo $date->format('Y-m-d') . "\n";
    }

Результат выполнения приведённого примера:

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Пример #3 Пример вывода через объект DatePeriod даты последнего четверга для каждого месяца года

    <?php

    $begin = new DateTime('2021-12-31');
    $end = new DateTime('2022-12-31 23:59:59');

    $interval = DateInterval::createFromDateString('last thursday of next month');
    $period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

    foreach ($period as $dt) {
        echo $dt->format('l Y-m-d'), "\n";
    }

Результат выполнения приведённого примера:

    Thursday 2022-01-27
    Thursday 2022-02-24
    Thursday 2022-03-31
    Thursday 2022-04-28
    Thursday 2022-05-26
    Thursday 2022-06-30
    Thursday 2022-07-28
    Thursday 2022-08-25
    Thursday 2022-09-29
    Thursday 2022-10-27
    Thursday 2022-11-24
    Thursday 2022-12-29

### Примечания

Неограниченное количество повторений не поддерживается, поэтому ни передача спецификатора `"R/..."` в параметр `isostr`, ни передача `null` в параметр `end` — не сработает. Подробнее о повторных интервалах времени рассказывает раздел 4.5 "Recurring time interval" стандарта ISO 8601.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Создаёт новый объект DatePeriod из строки в формате стандарта ISO8601

### Описание

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Метод создаёт новый объект DatePeriod из строки в формате стандарта ISO8601, как указывает описание параметра `specification`.

### Список параметров

`specification`

  Подмножество » спецификации повторяющихся интервалов стандарта ISO 8601.

  Пример принимаемой спецификации интервала стандарта ISO 8601 — строка `R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M`, которая указывает:

  - 5 повторений (`R5/`)
  - Начинать с `2008-03-01T13:00:00Z`.
  - Каждое повторение равно интервалу в 1 год 2 месяца 10 дней 2 часа и 30 минут (`/P1Y2M10DT2H30M`).

  Примеры спецификации интервалов стандарта ISO 8601, которые PHP не поддерживает:

  1. ноль раз (`R0/`)
  2. смещения времени, отличные от UTC (`Z`), например, `+02:00`.
`options`

  Битовое поле, которое можно указывать для управления отдельным поведением с начальными и конечными датами.

  Константа `DatePeriod::EXCLUDE_START_DATE` исключает дату начала из набора повторяющихся дат в пределах периода.

  Константа `DatePeriod::INCLUDE_END_DATE` включает дату окончания в наборе повторяющихся дат в пределах периода.

### Возвращаемые значения

Метод возвращает созданный объект DatePeriod.

С объектом DatePeriod, который создаётся методом, работают как с итератором для генерации объектов DateTimeImmutable.

### Ошибки

Метод выбрасывает исключение DateMalformedPeriodStringException, если значение параметра `specification` невозможно разобрать как допустимое значение периода в формате стандарта ISO 8601.

### Примеры

Пример #1 Пример создания из строки в формате ISO8601 объекта периода времени методом DatePeriod::createFromISO8601String

    <?php

    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // При переборе объекта DatePeriod выведутся
    // повторяющиеся в пределах периода даты.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

Результат выполнения приведённого примера:

    2023-07-01
    2023-07-08
    2023-07-15
    2023-07-22
    2023-07-29

# DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — Возвращает временной интервал

### Описание

Объектно-ориентированный стиль

public function DatePeriod::getDateInterval(): DateInterval

Метод возвращает объект (object) DateInterval, который представляет временной интервал для периода времени.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект DateInterval

### Примеры

Пример #1 Пример получения интервала методом DatePeriod::getDateInterval()

    <?php

    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

Результат выполнения приведённого примера:

    1 day

### Смотрите также

- DatePeriod::getStartDate() - Возвращает начальную дату периода
- DatePeriod::getEndDate() - Возвращает конечную дату периода

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Возвращает конечную дату периода

### Описание

Объектно-ориентированный стиль

public function DatePeriod::getEndDate(): ?DateTimeInterface

Метод возвращает конечную дату периода времени.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает значение `null`, если объект DatePeriod не содержит конечной даты. Например, при инициализации с параметром `recurrences` или `isostr` без указания конечной даты.

Метод возвращает объект DateTimeImmutable, если объект DatePeriod инициализировали с объектом DateTimeImmutable в качестве параметра `end`.

В остальных случаях метод возвращает клонированный объект (object) DateTime, который представляет конечную дату.

### Примеры

Пример #1 Пример получения конечной даты методом DatePeriod::getEndDate()

    <?php

    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        new DateTime('2016-05-20T00:00:00Z')
    );

    $start = $period->getEndDate();
    echo $start->format(DateTime::ISO8601);

Результат выполнения приведённых примеров:

    2016-05-20T00:00:00+0000

Пример #2 Пример получения конечной даты методом DatePeriod::getEndDate() из объекта без конечной даты

    <?php

    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );

    var_dump($period->getEndDate());

Результат выполнения приведённого примера:

    NULL

### Смотрите также

- DatePeriod::getStartDate() - Возвращает начальную дату периода
- DatePeriod::getDateInterval() - Возвращает временной интервал

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Получает количество повторений

### Описание

Объектно-ориентированный стиль

public function DatePeriod::getRecurrences(): ?int

Метод получает количество повторений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество повторений, которое указали через параметр `$recurrences` конструктора класса DatePeriod, иначе значение `null`.

### Примеры

Пример #1 Пример значений в результатах метода DatePeriod::getRecurrences()

    <?php

    $start = new DateTime('2018-12-31 00:00:00');
    $end   = new DateTime('2021-12-31 00:00:00');
    $interval = new DateInterval('P1M');
    $recurrences = 5;

    // Повторения, которые установили в конструкторе
    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
    echo $period->getRecurrences(), "\n\n";

    // Повторения, не заданные в конструкторе
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

Результат выполнения приведённого примера:

    5
    5
    5

    NULL
    NULL

### Смотрите также

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Возвращает начальную дату периода

### Описание

Объектно-ориентированный стиль

public function DatePeriod::getStartDate(): DateTimeInterface

Метод возвращает начальную дату периода времени.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает объект DateTimeImmutable, если объект DatePeriod инициализировали объектом DateTimeImmutable в качестве параметра `start`.

В остальных случаях метод возвращает объект DateTime.

### Примеры

Пример #1 Пример получения начальной даты методом DatePeriod::getStartDate()

    <?php

    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

Результат выполнения приведённого примера:

    2016-05-16T00:00:00+0000

### Смотрите также

- DatePeriod::getEndDate() - Возвращает конечную дату периода
- DatePeriod::getDateInterval() - Возвращает временной интервал

## Содержание

- DatePeriod::__construct — Инициализирует новый экземпляр класса DatePeriod
- DatePeriod::createFromISO8601String — Создаёт новый объект DatePeriod из строки в формате стандарта ISO8601
- DatePeriod::getDateInterval — Возвращает временной интервал
- DatePeriod::getEndDate — Возвращает конечную дату периода
- DatePeriod::getRecurrences — Получает количество повторений
- DatePeriod::getStartDate — Возвращает начальную дату периода

# Функции даты и времени

# checkdate

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

checkdate — Проверяет корректность даты по григорианскому календарю

### Описание

function checkdate(int `$month`, int `$day`, int `$year`): bool

Функция проверяет корректность даты, которую формируют аргументы. Дата считается корректной, если каждый параметр принимает допустимые значения.

### Список параметров

`month`

  Месяц. Принимает значения от 1 до 12 включительно.

`day`

  День. Принимает значения, допустимые для месяца `month`. При этом учитывается, высокосный ли год `year`.

`year`

  Год. Принимает значения от 1 до 32767 включительно.

### Возвращаемые значения

Функция возвращает `true`, если проверяемая дата корректна, иначе `false`.

### Примеры

Пример #1 Пример проверки даты по григорианскому календарю функцией checkdate()

    <?php

    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

### Смотрите также

- mktime() - Получает метку Unix-времени для даты
- strtotime() - Преобразовывает текстовое представление даты на английском языке в метку времени Unix

# date

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

date — Форматирует метку времени эпохи Unix

### Описание

function date(string `$format`, ?int `$timestamp` = `null`): string

Функция возвращает отформатированную по заданной строке формата строку с датой и (или) временем, которую сгенерировала на основе параметра `timestamp` — целочисленной метки Unix-времени, которую передали в функцию или которую функция получила на основе текущего системного времени, если метку времени не передали. Поэтому параметр `timestamp` необязателен и по умолчанию равен значению, которое возвращает функция time().

Внимание

Метки времени Unix не обрабатывают часовые пояса. Информацию о дате и времени с прикреплённым часовым поясом форматируют методом DateTimeInterface::format() класса DateTimeImmutable.

### Список параметров

`format`

  Формат, который принимается методом DateTimeInterface::format().

  > Замечание: Функция date() генерирует для поля микросекунд значение `000000`, поскольку принимает метку времени как целочисленное (int) значение в секундах, тогда как метод DateTimeInterface::format() поддерживает микросекунды, если объект DateTimeInterface создали с микросекундами.

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает отформатированную строку с датой.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение null.

### Примеры

Пример #1 Примеры использования функции date()

    <?php

    // Установка часового пояса по умолчанию
    date_default_timezone_set('UTC');

    // Выведет что-то наподобие: Monday
    echo date("l") . "\n";

    // Выведет что-то наподобие: Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // Выведет: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* Пример константы в параметре format */
    // Выведет что-то наподобие: Mon, 15 Aug 2005 15:12:46 UTC
    echo date(DATE_RFC822) . "\n";

    // Выведет что-то наподобие: 2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

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

Пример #2 Экранирование символов в функции date()

    <?php

    // Выведет что-то наподобие: Wednesday the 15th
    echo date('l \t\h\e jS');

Приведём ещё ряд примеров форматирования даты функцией date(). Обратите внимание: каждый символ, которым не планировалось форматировать время, экранируется, поскольку символы со значением форматирования дадут нежелательный результат, если функция встретит такие символы там, где требовалось вывести сам символ, а другим символам могут назначить свойства форматирования в следующих версиях PHP. При экранировании указывают одинарные кавычки, чтобы символы наподобие \n не превращались в символы новой строки.

Пример #3 Пример форматирования даты функцией date()

    <?php

    // Предположим, что сегодня 10 марта 2001 и 5:16:18 вечера
    // в часовом поясе Mountain Standard Time (MST)
    date_default_timezone_set("America/Phoenix");

    echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    echo date("m.d.y") . "\n";                         // 03.10.01
    echo date("j, n, Y") . "\n";                       // 10, 3, 2001
    echo date("Ymd") . "\n";                           // 20010310
    echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
    echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
    echo date("H:i:s") . "\n";                         // 17:16:18
    echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (the MySQL DATETIME format)

Даты на других языках вместо функции date() форматируют методом IntlDateFormatter::format().

### Примечания

> Замечание:

> Метку времени из строкового представления даты генерируют функцией strtotime(). Кроме того, в отдельных базах данных есть функции для преобразования внутреннего представления даты в метки времени (например, функция » UNIX_TIMESTAMP БД MySQL).

Подсказка

Метка времени начала запроса доступна в переменной $_SERVER['REQUEST_TIME'].

### Смотрите также

- DateTimeImmutable::__construct() - Возвращает новый объект DateTimeImmutable
- DateTimeInterface::format() - Форматирует дату в заданном формате
- gmdate() - Форматирует дату и время как время UTC
- idate() - Форматирует компонент даты или времени местного часового пояса как целое число
- getdate() - Возвращает информацию о дате и времени
- getlastmod() - Получает время последней модификации страницы
- mktime() - Получает метку Unix-времени для даты
- IntlDateFormatter::format() - Форматирует значение даты и времени как строку
- time() - Возвращает метку времени Unix на основе текущего системного времени
- Предопределённые константы даты и времени

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — Псевдоним DateTime::add()

### Описание

Псевдоним функции DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — Создаёт новый объект DateTime

### Описание

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

Это процедурная версия метода DateTime::__construct().

В отличие от конструктора DateTime, функция возвращает `false` вместо исключения, если переданная в параметр `datetime` строка недопустима.

### Список параметров

Смотрите DateTimeImmutable::__construct.

### Возвращаемые значения

Возвращает новый экземпляр DateTime. или `false`, если возникла ошибка

### Смотрите также

- DateTimeImmutable::__construct() - Возвращает новый объект DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату
- DateTime::__construct() - Конструктор класса DateTime

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — Псевдоним DateTime::createFromFormat()

### Описание

Псевдоним функции DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — Создаёт новый объект DateTimeImmutable

### Описание

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Аналог метода DateTimeImmutable::__construct() в процедурном стиле.

В отличие от конструктора DateTimeImmutable, функция вернёт `false`, а не выбросит исключение, если переданная в конструктор строка `datetime` указана некорректно.

### Список параметров

Смотрите DateTimeImmutable::__construct.

### Возвращаемые значения

Возвращает новый экземпляр DateTimeImmutable. или `false`, если возникла ошибка

### Смотрите также

- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — Псевдоним DateTimeImmutable::createFromFormat()

### Описание

Псевдоним функции DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — Псевдоним DateTime::setDate()

### Описание

Псевдоним функции DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — Возвращает часовой пояс по умолчанию для функций работы с датой и временем в скрипте

### Описание

function date_default_timezone_get(): string

Функция пытается получить часовой пояс по умолчанию по порядку следующими способами:

- Считывает настройки часового пояса функцией date_default_timezone_set(), если применимо

- Считывает значения ini-настройки date.timezone, если установили

Функция date_default_timezone_get() вернёт часовой пояс `UTC`, если не получила часовой пояс другим способом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку (string).

### Примеры

Пример #1 Пример получения часового пояса по умолчанию

    <?php

    date_default_timezone_set('Europe/London');

    if (date_default_timezone_get()) {
        echo 'date_default_timezone_set: ' . date_default_timezone_get() . "\n";
    }

    if (ini_get('date.timezone')) {
        echo 'date.timezone: ' . ini_get('date.timezone');
    }

Вывод приведённого примера будет похож на:

    date_default_timezone_set: Europe/London
    date.timezone: Europe/London

Пример #2 Пример получения сокращённого названия часового пояса

    <?php

    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

Результат выполнения приведённого примера:

    America/Los_Angeles => America/Los_Angeles => PST

### Смотрите также

- date_default_timezone_set() - Устанавливает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
- Список поддерживаемых часовых поясов

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — Устанавливает часовой пояс по умолчанию для функций работы с датой и временем в скрипте

### Описание

function date_default_timezone_set(string `$timezoneId`): bool

Функция date_default_timezone_set() устанавливает часовой пояс по умолчанию для функций работы с датой и временем в PHP-скрипте.

Вместо этой функции часовой пояс указывают в INI-настройке date.timezone для установки часового пояса по умолчанию.

### Список параметров

`timezoneId`

  Идентификатор часового пояса, например, `UTC`, `Africa/Lagos`, `Asia/Hong_Kong` или `Europe/Lisbon`. Список допустимых идентификаторов часовых поясов можно найти в разделе Список поддерживаемых часовых поясов.

### Возвращаемые значения

Функция возвращает `false`, если `timezoneId` имеет неверное значение, в остальных случаях `true`.

### Примеры

Пример #1 Получение часового пояса по умолчанию

    <?php

    date_default_timezone_set('America/Los_Angeles');

    $script_tz = date_default_timezone_get();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)) {
        echo 'Часовой пояс скрипта отличается от заданного в INI-файле.';
    } else {
        echo 'Часовой пояс скрипта и настройки INI-файла совпадают.';
    }

### Смотрите также

- date_default_timezone_get() - Возвращает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
- Список поддерживаемых часовых поясов

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — Псевдоним DateTime::diff()

### Описание

Псевдоним функции DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — Псевдоним DateTime::format()

### Описание

Псевдоним функции DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — Псевдоним DateTimeImmutable::getLastErrors()

### Описание

Псевдоним функции DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — Псевдоним DateInterval::createFromDateString()

### Описание

Псевдоним функции DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — Псевдоним DateInterval::format()

### Описание

Псевдоним функции DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — Псевдоним DateTime::setISODate()

### Описание

Псевдоним функции DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — Псевдоним DateTime::modify()

### Описание

Псевдоним функции DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — Псевдоним DateTime::getOffset()

### Описание

Псевдоним функции DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Возвращает ассоциативный массив с подробной информацией о заданной дате/времени

### Описание

function date_parse(string `$datetime`): array

Функция date_parse() разбирает строку параметра `datetime` аналогично функции strtotime() или методу DateTimeImmutable::__construct(), но вместо возврата метки Unix-времени, как это делает функция strtotime(), или объекта DateTimeImmutable, который создаёт метод DateTimeImmutable::__construct()), функция возвращает ассоциативный массив с информацией, которую функция обнаружила в строке параметра `datetime`.

Функция установит элементам массива значение `false` или пропустит элемент, если не найдёт информацию о конкретных компонентах даты и времени. Поэтому в PHP предусмотрели другие функции для работы с датой и временем, которые при том же значении параметра `datetime` умеют создавать метку времени или объект DateTimeImmutable, в котором заполняют значения для большего количества компонентов времени, тогда как эта функция для аналогичных компонентов устанавливает значение `false`. Примеры на этой странице показывают обработку строк, из которых невозможно извлечь отдельные компоненты времени.

### Список параметров

`datetime`

  Строка с датой и временем в формате, который распознаёт метод DateTimeImmutable::__construct().

### Возвращаемые значения

Функция возвращает массив (array) с информацией о дате и времени.

Результирующий массив содержит следующие ключи: `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction` и `is_localtime`.

Элемент `zone_type` укажет тип часового пояса, если массив с результатами содержит элемент `is_localtime`. Для `1`-го типа представления часовых поясов — со смещением относительно UTC — добавляются поля `zone` и `is_dst`; для `2`-го типа представления — аббревиатура — добавляются поля `tz_abbr` и `is_dst`; для `3`-го тип — идентификатор часового пояса — добавляются поля `tz_abbr` и `tz_id`.

Функция включит в массив с результатами массив `relative`, если строка `datetime` содержит элементы относительного времени наподобие `+3 days`. Массив с результатами разбора элементов времени в относительном формате содержит следующие ключи: `year`, `month`, `day`, `hour`, `minute`, `second` и, если строка содержит названия дней недели или относительные количества рабочих дней, `weekday` и `weekdays`.

Массив включает поля `warning_count` и `warnings`. Первое указывает количество предупреждений. Ключи элементов массива `warnings` указывают позицию в аргументе `datetime`, на которой возникло предупреждение, а строковое значение содержит описание предупреждения.

Массив также содержит поля `error_count` и `errors`. Первое указывает количество ошибок. Ключи элементов массива `errors` указывают позицию в аргументе `datetime`, на которой возникла ошибка, а строковое значение содержит описание ошибки.

Внимание

Функция запишет в массивы `warnings` и `errors` меньшее количество элементов, чем указывают значения элементов `warning_count` и `error_count`, если предупреждения или ошибки возникнут на тех же позициях.

### Ошибки

При недопустимом формате даты и времени во входной строке функция заполнит массив 'errors' элементами с сообщениями об ошибках.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Элемент `zone` в массиве результатов теперь содержит секунды вместо минут, а знак инвертируется, например: значение `-120` теперь выводится как `7200`.

### Примеры

Пример #1 Пример разбора полной строки даты и времени `datetime`а функцией date_parse()

    <?php

    var_dump(date_parse("2006-12-12 10:00:00.5"));

Результат выполнения приведённого примера:

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Функция включает элементы часового пояса в результаты, только если строка параметра `datetime` содержит информацию о часовом поясе. Для часовых поясов функция включает элемент `zone_type` и ряд других элементов в зависимости от значения типа представления часового пояса.

Пример #2 Пример разбора строки с аббревиатурой часового пояса функцией date_parse()

    <?php

    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

Результат выполнения приведённого примера:

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Пример #3 Пример разбора строки с идентификатором часового пояса функцией date_parse()

    <?php

    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

Результат выполнения приведённого примера:

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

При разборе немногословной строки `datetime` функция возвращает меньше информации. В следующем примере функция возвращает массив, в котором все компоненты времени содержат значение `false`.

Пример #4 Пример разбора строки с минимумом информации о дате функцией date_parse()

    <?php

    var_dump(date_parse("June 2nd, 2022"));

Результат выполнения приведённого примера:

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Относительные форматы не влияют на значения, которые функция извлекла при разборе абсолютных форматов даты и времени, но результаты разбора относительных форматов включаются в элемент "relative".

Пример #5 Пример разбора строки с относительными форматами даты и времени функцией date_parse()

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

Результат выполнения приведённого примера:

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

При разборе названий дней недели наподобие `Thursday` функция установит для компонентов hour, minute, second и fraction значение `0`. При передаче значения `Thursday` в метод DateTimeImmutable::__construct() для каждого компонента времени также устанавливается значение `0`. В следующем примере для элемента year, однако, функция оставляет значение `false`.

Пример #6 Пример побочных эффектов в работе функции date_parse()

    <?php

    var_dump(date_parse("Thursday, June 2nd"));

Результат выполнения приведённого примера:

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Смотрите также

- date_parse_from_format() - Разбирает строку с датой по заданному формату для разбора параметра `datetime` с определённым заданным форматом
- checkdate() - Проверяет корректность даты по григорианскому календарю для проверки григорианской даты
- getdate() - Возвращает информацию о дате и времени

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Разбирает строку с датой по заданному формату

### Описание

function date_parse_from_format(string `$format`, string `$datetime`): array

Функция возвращает ассоциативный массив с подробной информацией о дате и времени.

### Список параметров

`format`

  Описание параметра `format` приводится в документации к методу DateTimeImmutable::createFromFormat(). Для параметра функции действуют аналогичные правила.

`datetime`

  Строковое представление даты и времени.

### Возвращаемые значения

Функция возвращает ассоциативный массив с подробной информацией о дате и времени.

Результирующий массив содержит следующие ключи: `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction` и `is_localtime`.

Элемент `zone_type` укажет тип часового пояса, если массив с результатами содержит элемент `is_localtime`. Для `1`-го типа представления часовых поясов — со смещением относительно времени UTC — добавляются поля `zone` и `is_dst`; для `2`-го типа представления — аббревиатура — добавляются поля `tz_abbr` и `is_dst`; для `3`-го тип — идентификатор часового пояса — добавляются поля `tz_abbr` и `tz_id`.

Массив включает поля `warning_count` и `warnings`. Первое указывает количество предупреждений. Ключи элементов массива `warnings` указывают позицию в аргументе `datetime`, на которой возникло предупреждение, а строковое значение содержит описание предупреждения.

Массив также содержит поля `error_count` и `errors`. Первое указывает количество ошибок. Ключи элементов массива `errors` указывают позицию в аргументе `datetime`, на которой возникла ошибка, а строковое значение содержит описание ошибки.

Внимание

Функция запишет в массивы `warnings` и `errors` меньшее количество элементов, чем указывают значения элементов `warning_count` и `error_count`, если предупреждения или ошибки возникнут на тех же позициях.

### Ошибки

Функция выбрасывает ошибку ValueError, если параметр `datetime` содержит нулевые байты.

### Список изменений

Версия | Описание
--- | ---
8.0.21, 8.1.8, 8.2.0 | При передаче нулевых байтов в параметр `datetime` функция теперь выбрасывает ошибку ValueError; раньше функция молча игнорировала нулевые байты.
7.2.0 | Элемент `zone` в массиве результатов теперь содержит секунды вместо минут, а знак инвертируется, например: значение `-120` теперь выводится как `7200`.

### Примеры

Пример #1 Пример разбора строки с датой и временем по заданному формату функцией date_parse_from_format()

    <?php

    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

Результат выполнения приведённого примера:

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => -60
        [is_dst] =>
    )

Пример #2 Пример предупреждения при разборе строки с датой функцией date_parse_from_format()

    <?php

    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Количество предупреждений: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tПозиция {$position}: {$message}\n";
    }

Результат выполнения приведённого примера:

    Количество предупреждений: 1
        Позиция 23: The parsed time was invalid

Пример #3 Пример ошибок при разборе строки с датой функцией date_parse_from_format()

    <?php

    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Количество ошибок: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tПозиция {$position}: {$message}\n";
    }

Результат выполнения приведённого примера:

    Количество ошибок: 3
        Позиция 15: A two digit hour could not be found
        Позиция 19: Not enough data available to satisfy format

### Смотрите также

- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату
- checkdate() - Проверяет корректность даты по григорианскому календарю

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — Псевдоним DateTime::sub()

### Описание

Псевдоним функции DateTime::sub()

### Смотрите также

- DateTimeImmutable::sub() - Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд
- DateTime::sub() - Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Возвращает массив с информацией о закате и восходе Солнца, и начале и окончании сумерек

### Описание

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### Список параметров

`timestamp`

  Метка Unix-времени.

`latitude`

  Широта в градусах.

`longitude`

  Долгота в градусах.

### Возвращаемые значения

Функция возвращает массив, подробную информацию о структуре которого содержит следующий список:

`sunrise`
  Метка времени восхода Солнца, когда угол зенита равен 90°35'.
`sunset`
  Метка времени заката Солнца, когда угол зенита равен 90°35'.
`transit`
  Метка времени кульминации Солнца — прохождения зенита, или наивысшей точки над горизонтом.
`civil_twilight_begin`
  Начало утренних гражданских сумерек, когда угол зенита равен 96°. Утренние гражданские сумерки заканчиваются в момент восхода Солнца — `sunrise`.
`civil_twilight_end`
  Конец вечерних гражданских сумерек, когда угол зенита равен 96°. Вечерние гражданские сумерки начинаются в момент заката Солнца — `sunset`.
`nautical_twilight_begin`
  Начало навигационного рассвета, когда угол зенита равен 102°. Навигационный рассвет заканчивается в момент начала гражданского рассвета — `civil_twilight_begin`.
`nautical_twilight_end`
  Конец навигационного заката, когда угол зенита равен 102°. Навигационный закат начинается в момент окончания вечерних гражданских сумерек — `civil_twilight_end`.
`astronomical_twilight_begin`
  Начало астрономического рассвета, когда угол зенита равен 108°. Астрономический рассвет заканчивается в момент начала навигационного рассвета — `nautical_twilight_begin`.
`astronomical_twilight_end`
  Конец астрономического заката, когда угол зенита равен 108°. Астрономический закат начинается в момент окончания навигационного заката — `nautical_twilight_end`.

Функция устанавливает для элементов массива следующие значения: а) метку Unix-времени, б) значение `false`, если Солнце в течение всего дня не достигает угла зенита для события, или в) значение `true`, если Солнце в течение всего дня остаётся выше угла зенита, который соответствует событию.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Функция теперь берёт за точку отсчёта местную полночь, а не местный полдень, что исправляет расчёты значений и повышает точность результатов.

### Примеры

Пример #1 Пример работы функции date_sun_info()

    <?php

    $sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);

    foreach ($sun_info as $key => $val) {
        echo "$key: " . date("H:i:s", $val) . "\n";
    }

Результат выполнения приведённого примера:

    sunrise: 05:52:11
    sunset: 15:41:21
    transit: 10:46:46
    civil_twilight_begin: 05:24:08
    civil_twilight_end: 16:09:24
    nautical_twilight_begin: 04:52:25
    nautical_twilight_end: 16:41:06
    astronomical_twilight_begin: 04:21:32
    astronomical_twilight_end: 17:12:00

Пример #2 Пример обработки результатов в дату внутри периода полярной ночи

    <?php

    $tz = new \DateTimeZone('America/Anchorage');
    $si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);

    foreach ($si as $key => $value) {
        echo
            match ($value) {
                true => 'always',
                false => 'never',
                default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
            },
            ": {$key}",
            "\n";
    }

Результат выполнения приведённого примера:

    never: sunrise
    never: sunset
    12:52:18 AKST: transit
    10:53:19 AKST: civil_twilight_begin
    14:51:17 AKST: civil_twilight_end
    09:01:47 AKST: nautical_twilight_begin
    16:42:48 AKST: nautical_twilight_end
    07:40:47 AKST: astronomical_twilight_begin
    18:03:49 AKST: astronomical_twilight_end

Пример #3 Пример результатов в дату внутри периода полярного дня в Тромсё, Норвегия

    <?php

    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

Результат выполнения приведённого примера:

    Array
    (
        [sunrise] => 1
        [sunset] => 1
        [transit] => 1656240426
        [civil_twilight_begin] => 1
        [civil_twilight_end] => 1
        [nautical_twilight_begin] => 1
        [nautical_twilight_end] => 1
        [astronomical_twilight_begin] => 1
        [astronomical_twilight_end] => 1
    )

Пример #4 Пример вычисления продолжительности дня в Киеве

    <?php

    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];

    echo "Продолжительность дня: ",
        floor($diff / 3600), " ч. ",
        floor(($diff % 3600) / 60), " сек.\n";

Результат выполнения приведённого примера:

    Продолжительность дня: 13 ч. 56 сек.

### Смотрите также

- date_sunrise() - Возвращает время рассвета для заданных дня и местоположения
- date_sunset() - Возвращает время захода солнца для заданных дня и расположения

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — Возвращает время рассвета для заданных дня и местоположения

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Разработчики языка настоятельно не рекомендуют полагаться на функцию. Вместо неё лучше пользоваться функцией date_sun_info().

### Описание

#[\Deprecated]
function date_sunrise(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

Функция date_sunrise() возвращает время рассвета для дня, который указали в аргументе `timestamp`, и расположения.

### Список параметров

`timestamp`

  Параметр `timestamp` принимает метку времени дня, для которого берётся время рассвета.

`returnFormat`

  Константы, которые принимает параметр `returnFormat`
  Константа | Описание | Пример
  --- | --- | ---
  SUNFUNCS_RET_STRING | Возвращает результат в виде значения с типом string | 16:46
  SUNFUNCS_RET_DOUBLE | Возвращает результат в виде значения с типом float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Возвращает метку времени в виде значения с типом int | 1095034606

`latitude`

  Значение по умолчанию — Северное полушарие, для Южного передаётся отрицательное значение. Смотрите также описание директивы date.default_latitude.

`longitude`

  Значение по умолчанию — восточная долгота, для западной передаётся отрицательное значение. Смотрите также описание директивы date.default_longitude.

`zenith`

  Параметр `zenith` устанавливает угол между центром Солнца и линией, перпендикулярной поверхности Земли. По умолчанию параметр берёт значение директивы date.sunrise_zenith.

  Распространённые углы зенита `zenith`
  Угол | Описание
  --- | ---
  90°50' | Восход солнца: точка, в которой солнце становится видимым.
  96° | Гражданские сумерки: традиционно обозначает начало рассвета.
  102° | Навигационные сумерки: точка, в которой горизонт становится видимым с моря.
  108° | Астрономические сумерки: момент, когда солнце становится источником освещения.

`utcOffset`

  Задаётся в часах. Функция игнорирует параметр `utcOffset`, если значение параметра `returnFormat` равно значению константы `SUNFUNCS_RET_TIMESTAMP`.

### Возвращаемые значения

Функция возвращает время восхода солнца в формате, который определили в параметре `returnFormat`, если завершилась успешно, или `false`, если возникла ошибка. Функция завершится неудачно, если солнце вообще не поднимается над горизонтом, что бывает внутри полярных кругов в течение части года.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела, пользуйтесь вместе неё функцию date_sun_info().
8.0.0 | Параметры `latitude`, `longitude`, `zenith` и `utcOffset` теперь принимают значение `null`.

### Примеры

Пример #1 Пример получения времени рассвета функцией date_sunrise()

    <?php

    /* Расчёт времени восхода солнца в Лиссабоне, Португалия
    Latitude: 38.4 North
    Longitude: 9 West
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', время восхода солнца : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Вывод приведённого примера будет похож на:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, время восхода солнца : 08:54

Пример #2 Пример работы функции для времени и расположения, при которых солнце не восходит

    <?php

    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

Результат выполнения приведённого примера:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Смотрите также

- date_sun_info() - Возвращает массив с информацией о закате и восходе Солнца, и начале и окончании сумерек

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — Возвращает время захода солнца для заданных дня и расположения

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Разработчики языка настоятельно не рекомендуют полагаться на функцию. Вместо неё лучше пользоваться функцией date_sun_info().

### Описание

#[\Deprecated]
function date_sunset(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

Функция date_sunset() возвращает время захода солнца для дня, который указали в аргументе `timestamp`, и расположения.

### Список параметров

`timestamp`

  Параметр `timestamp` принимает метку времени дня, для которого берётся время захода солнца.

`returnFormat`

  Константы, которые принимает параметр `returnFormat`
  Константа | Описание | Пример
  --- | --- | ---
  SUNFUNCS_RET_STRING | Возвращает результат в виде значения с типом string | 16:46
  SUNFUNCS_RET_DOUBLE | Возвращает результат в виде значения с типом float | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Возвращает метку времени в виде значения с типом int | 1095034606

`latitude`

  Значение по умолчанию — Северное полушарие, для Южного передаётся отрицательное значение. Смотрите также описание директивы date.default_latitude.

`longitude`

  Значение по умолчанию — восточная долгота, для западной передаётся отрицательное значение. Смотрите также описание директивы date.default_longitude.

`zenith`

  Параметр `zenith` устанавливает угол между центром Солнца и линией, перпендикулярной поверхности Земли. По умолчанию параметр берёт значение директивы date.sunrise_zenith.

  Распространённые углы зенита `zenith`
  Угол | Описание
  --- | ---
  90°50' | Восход солнца: точка, в которой солнце становится невидимым.
  96° | Гражданские сумерки: традиционно обозначает окончание заката.
  102° | Навигационные сумерки: точка, в которой горизонт становится невидимым с моря.
  108° | Астрономические сумерки: момент, в которой солнце перестаёт быть источником освещения.

`utcOffset`

  Задаётся в часах. Функция игнорирует параметр `utcOffset`, если значение параметра `returnFormat` равно значению константы `SUNFUNCS_RET_TIMESTAMP`.

### Возвращаемые значения

Функция возвращает время захода солнца в формате, который определили в параметре `returnFormat`, если завершилась успешно, или `false`, если возникла ошибка. Функция завершится неудачно, если солнце вообще не заходит, что бывает внутри полярных кругов в течение части года.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела, пользуйтесь вместе неё функцию date_sun_info().
8.0.0 | Параметры `latitude`, `longitude`, `zenith` и `utcOffset` теперь принимают значение `null`.

### Примеры

Пример #1 Пример получения времени заката функцией date_sunset()

    <?php

    /* Расчёт времени захода солнца в Лиссабоне, Португалия
    Latitude: 38.4 North
    Longitude: 9 West
    Zenith ~= 90
    offset: +1 GMT
    */

    echo date("D M d Y"). ', время захода солнца : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Вывод приведённого примера будет похож на:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, время захода солнца : 18:13

Пример #2 Пример работы функции для времени и расположения, при которых солнце не заходит

    <?php

    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

Результат выполнения приведённого примера:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Смотрите также

- date_sun_info() - Возвращает массив с информацией о закате и восходе Солнца, и начале и окончании сумерек

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — Псевдоним DateTime::setTime()

### Описание

Псевдоним функции DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — Псевдоним DateTime::getTimestamp()

### Описание

Псевдоним функции DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — Псевдоним DateTime::setTimestamp()

### Описание

Псевдоним функции DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — Псевдоним DateTime::getTimezone()

### Описание

Псевдоним функции DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — Псевдоним DateTime::setTimezone()

### Описание

Псевдоним функции DateTime::setTimezone()

# getdate

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

getdate — Возвращает информацию о дате и времени

### Описание

function getdate(?int `$timestamp` = `null`): array

Функция возвращает ассоциативный массив (array) с информацией о дате, которую представляет либо метка времени `timestamp`, либо текущее системное время, если аргумент `timestamp` опустили или передали значение `null`.

### Список параметров

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает ассоциативный массив (array) с информацией о моменте времени в параметре `timestamp`. Ассоциативный массив содержит следующие элементы:

Индексы возвращаемого ассоциативного массива
Индекс | Описание | Пример значения
--- | --- | ---
`"seconds"` | Числовое представление секунд | от `0` до `59`
`"minutes"` | Числовое представление минут | от `0` до `59`
`"hours"` | Числовое представление часов | от `0` до `23`
`"mday"` | Порядковый номер дня месяца | от `1` до `31`
`"wday"` | Порядковый номер дня недели | от `0` для воскресенья до `6` для субботы
`"mon"` | Порядковый номер месяца | от `1` до `12`
`"year"` | Номер года, 4 цифры | Примеры: `1999`, `2003`
`"yday"` | Порядковый номер дня в году | от `0` до `365`
`"weekday"` | Полное название дня недели | от `Sunday` до `Saturday`
`"month"` | Полное название месяца, например, January или March | от `January` до `December`
`0` | Количество секунд, которое прошло с начала эпохи Unix, аналогично значению, которое возвращает функция time(), и которое принимает функция date() | Значение в целочисленном диапазоне, доступном на платформе; на 32-битных системах значение от `-2147483648` до `2147483647`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример получения информации о дате и времени функцией getdate()

    <?php

    $today = getdate();
    print_r($today);

Вывод приведённого примера будет похож на:

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### Смотрите также

- date() - Форматирует метку времени эпохи Unix
- idate() - Форматирует компонент даты или времени местного часового пояса как целое число
- localtime() - Получает местное время
- time() - Возвращает метку времени Unix на основе текущего системного времени
- setlocale() - Устанавливает региональные настройки

# gettimeofday

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

gettimeofday — Возвращает текущее время

### Описание

function gettimeofday(bool `$as_float` = `false`): array|float

Функция — интерфейс к системному вызову функции gettimeofday(2). Функция возвращает ассоциативный массив с информацией, которую получила от системного вызова.

### Список параметров

`as_float`

  При передаче значения `true` вместо массива возвращается число с плавающей точкой.

### Возвращаемые значения

По умолчанию функция возвращает массив (array). При установке параметра `as_float` возвращается значение float.

Ключи массива:

- "sec" — количество секунд, которое прошло с начала эпохи Unix
- "usec" — микросекунды
- "minuteswest" — смещение к западу от Гринвича, в минутах
- "dsttime" — тип коррекции летнего времени

### Примеры

Пример #1 Пример получения информации о времени функцией gettimeofday()

    <?php

    print_r(gettimeofday());

    echo gettimeofday(true);

Вывод приведённого примера будет похож на:

    Array
    (
        [sec] => 1073504408
        [usec] => 238215
        [minuteswest] => 0
        [dsttime] => 1
    )
    1073504408.23910

# gmdate

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

gmdate — Форматирует дату и время как время UTC

### Описание

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

Функция работает аналогично функции date(), но игнорирует смещение времени в текущем часовом поясе и форматирует метку времени как UTC-время.

### Список параметров

`format`

  Формат даты. Функция вернёт значение string с датой в заданном формате. Параметры форматирования описывает страница функции date().

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает строку с отформатированной датой.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример форматирования даты и времени функцией gmdate()

    <?php

    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

Результат выполнения приведённого примера:

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### Смотрите также

- DateTimeImmutable::__construct() - Возвращает новый объект DateTimeImmutable
- DateTimeInterface::format() - Форматирует дату в заданном формате
- date() - Форматирует метку времени эпохи Unix
- mktime() - Получает метку Unix-времени для даты
- gmmktime() - Получает метку Unix-времени для времени UTC
- IntlDateFormatter::format() - Форматирует значение даты и времени как строку

# gmmktime

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

gmmktime — Получает метку Unix-времени для времени UTC

### Описание

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Функция работает аналогично функции mktime(), но игнорирует смещение времени в текущем часовом поясе и интерпретирует аргументы как UTC-время. Функция gmmktime() внутренне опирается на функцию mktime(), которая возвращает правильный результат только для допустимых для местного часового пояса моментов времени.

Аналогично функции mktime() необязательные аргументы опускают в порядке справа налево, при этом параметрам без аргументов функция установит значения, которые соответствуют компонентам текущего времени UTC.

Вызов функции gmmktime() без аргументов не поддерживается и выбросит ошибку ArgumentCountError. Метку времени без передачи аргументов получают функцией time().

### Список параметров

`hour`

  Номер часа с начала дня, который определили параметрами `month`, `day` и `year`. Отрицательные значения соответствуют часам предыдущих дней, а значения больше 23 — следующих.

`minute`

  Номер минуты с начала часа, который определили в параметре `hour`. Отрицательные значения соответствуют минутам предыдущих часов, а значения больше 59 — следующих.

`second`

  Номер секунды с начала минуты, которую определили в параметре `minute`. Отрицательные значения соответствуют секундам предыдущих минут, а значения больше 59 — следующих.

`month`

  Номер месяца в году. Значения от 1 до 12 соответствуют месяцам заданного года. Значения меньше 1, включая отрицательные, соответствуют месяцам предыдущих лет в обратном порядке, поэтому 0 станет декабрём, -1 — ноябрём и т. д. Значения больше 12 соответствуют месяцам следующих лет.

`day`

  Номер дня в месяце. Значения от 1 до 28, 29, 30 или 31 — в зависимости от месяца — соответствуют дням заданного месяца. Значения меньше 1, включая отрицательные, соответствуют дням предыдущих месяцев, поэтому 0 становится последним днём предыдущего месяца, -1 — предпоследним днём предыдущего месяца и т. д. Значения, которые превышают количество дней в заданном месяце, соответствуют дням следующих месяцев.

`year`

  Год.

### Возвращаемые значения

Функция возвращает значение int — метку времени Unix, если выполнилась успешно, значение `false`, если метка выходит за пределы целочисленного значения PHP.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `hour` стал обязательным. Метку времени Unix без передачи аргументов возвращает функция time().
8.0.0 | Параметры `minute`, `second`, `month`, `day` и `year` теперь принимают значение `null`.

### Примеры

Пример #1 Базовый пример получения метки UTC-времени функцией gmmktime()

    <?php

    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

Результат выполнения приведённого примера:

    July 1, 2000 is on a Saturday

### Смотрите также

- Класс DateTimeImmutable
- mktime() - Получает метку Unix-времени для даты
- date() - Форматирует метку времени эпохи Unix
- time() - Возвращает метку времени Unix на основе текущего системного времени

# gmstrftime

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

gmstrftime — Форматирует дату и время как время UTC с учётом региональных настроек

Внимание

Функция УСТАРЕЛА с PHP 8.1.0. Полагаться на функцию настоятельно не рекомендуют.

Разработчикам доступны следующие альтернативы:

- gmdate()
- IntlDateFormatter::format()

### Описание

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = null): string|false

Функция работает аналогично функции strftime(), но игнорирует смещение времени в текущем часовом поясе и форматирует метку времени как UTC-время с учётом региональных настроек. Например, при запуске в системе, в которой установили часовой пояс Eastern Standard Time со смещением GMT-0500, первая строка приведённого примера выведет "Dec 31 1998 20:00:00", а вторая — "Jan 01 1999 01:00:00".

Внимание

Функция зависит от региональных настроек операционной системы, которые не гарантируют совместимость или доступность региональных настроек в другой ОС. Для форматирования даты без влияния региональных настроек ОС вызывают метод IntlDateFormatter::format().

### Список параметров

`format`

  См. описание функции strftime().

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает строку в заданном формате. Функция форматирует дату и время на основе метки времени, которую передали в аргументе `timestamp`, или текущего локального времени, если метку времени не указали. Названия месяцев, дней недели и других языкозависимых строк учитывают настройки текущей локали, которую установили функцией setlocale(). Функция возвращает значение `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример форматирования даты и времени как UTC-времени с учетом текущей локали функцией gmstrftime()

    <?php

    setlocale(LC_TIME, 'es_ES.UTF-8');
    date_default_timezone_set('EST');

    echo strftime("%B %d %Y %H:%M:%S",   mktime(20, 0, 0, 12, 31, 98)) . "\n";
    echo gmstrftime("%B %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98));

Результат выполнения приведённого примера:

    Deprecated: Function strftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 6
    diciembre 31 1998 20:00:00

    Deprecated: Function gmstrftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 7
    enero 01 1999 01:00:00

### Смотрите также

- IntlDateFormatter::format() - Форматирует значение даты и времени как строку
- DateTimeInterface::format() - Форматирует дату в заданном формате
- strftime() - Форматирует местную дату и время с учётом региональных настроек

# idate

(PHP 5, PHP 7, PHP 8)

idate — Форматирует компонент даты или времени местного часового пояса как целое число

### Описание

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

Функция обрабатывает значение параметра `timestamp` или получает метку текущего системного времени, если параметр опустили, и возвращает целочисленное значение компонента даты или времени в заданном формате. Поэтому параметр `timestamp` необязателен и по умолчанию равен значению, которое возвращает функция time().

Функция idate(), в отличие от функции date(), принимает только один символ в аргументе `format`.

### Список параметров

`format`

  Допустимые символы в строке аргумента `format`
  Символ в аргументе `format` | Описание
  --- | ---
  `B` | «Бит» времени в системе Swatch, или интернет-время
  `d` | День месяца
  `h` | Час в 12-часовом формате
  `H` | Час в 24-часовом формате
  `i` | Минуты
  `I` (i в верхнем регистре) | Возвращает `1`, если действует летнее время, иначе `0`
  `L` (l в верхнем регистре) | Возвращает `1` для високосного года, иначе `0`
  `m` | Номер месяца
  `N` | День недели по стандарту ISO-8601, где `1` — понедельник, а `7` — воскресенье
  `o` | Год по стандарту ISO-8601 — 4 цифры
  `s` | Секунды
  `t` | Количество дней в текущем месяце
  `U` | Время в секундах с начала эпохи Unix — 00:00:00 1 января 1970 по времени UTC, аналогично значению, которое возвращает функция time()
  `w` | День недели, где `0` — воскресенье
  `W` | Номер недели года по стандарту ISO-8601, неделя начинается с понедельника
  `y` | Год в 1- или 2-значном формате, см. примечание в примере
  `Y` | Год в 4-значном формате
  `z` | День года
  `Z` | Смещение времени часового пояса в секундах

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает значение int, если выполнилась успешно, или `false`, если возникла ошибка.

Функция idate() иногда возвращает значение, разрядность которого меньшей ожидаемой, поскольку функция idate() возвращает только значения int, которым нельзя начинаться с нуля. См. пример.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Добавили символы форматирования: `N` — день недели по стандарту ISO-8601 и `o` — год по стандарту ISO-8601.
8.0.0 | Параметр `timestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример форматирования компонента даты или времени функцией idate()

    <?php

    $timestamp = strtotime('1st January 2004'); // 1072915200

    // Символ 'y' форматирует год в 2-значном формате,
    // но поскольку год выводился бы с символа 0,
    // код выведет только цифру 4
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

Результат выполнения приведённого примера:

    4
    24

### Смотрите также

- DateTimeInterface::format() - Форматирует дату в заданном формате
- date() - Форматирует метку времени эпохи Unix
- getdate() - Возвращает информацию о дате и времени
- time() - Возвращает метку времени Unix на основе текущего системного времени

# localtime

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

localtime — Получает местное время

### Описание

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

Функция localtime() возвращает массив, структура которого идентична структуре возврата C-функции localtime.

### Список параметров

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().
`associative`

  Параметр определяет, вернёт ли функция стандартный массив с числовыми индексами или ассоциативный.

### Возвращаемые значения

Функция возвращает стандартный массив с числовыми индексами, если значение аргумента `associative` равно `false` или аргумент не передали. Функция localtime() вернёт ассоциативный массив, который содержит элементы структуры возврата C-функции localtime, если значение аргумента `associative` равно `true`. Ассоциативный массив содержит следующие ключи:

- "tm_sec" — секунды, от `0` до `59`
- "tm_min" — минуты, от `0` до `59`
- "tm_hour" — часы, от `0` до `23`
- "tm_mday" — день месяца, от `1` до `31`
- "tm_mon" — месяц года, от `0` для января до `11` для декабря
- "tm_year" — количество лет, которое прошло с 1900 г.
- "tm_wday" — день недели, от `0` для воскресенья до `6` для субботы
- "tm_yday" — порядковый номер дня в году, от `0` до `365`
- "tm_isdst" — указывает, действует ли летнее время Элемент содержит положительное значение, если летнее время действует, `0`, если не действует, отрицательное, если неизвестно.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример получения местного времени функцией localtime()

    <?php

    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);

    print_r($localtime);
    print_r($localtime_assoc);

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 24
        [1] => 3
        [2] => 19
        [3] => 3
        [4] => 3
        [5] => 105
        [6] => 0
        [7] => 92
        [8] => 1
    )

    Array
    (
        [tm_sec] => 24
        [tm_min] => 3
        [tm_hour] => 19
        [tm_mday] => 3
        [tm_mon] => 3
        [tm_year] => 105
        [tm_wday] => 0
        [tm_yday] => 92
        [tm_isdst] => 1
    )

### Смотрите также

- getdate() - Возвращает информацию о дате и времени

# microtime

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

microtime — Возвращает текущую метку времени Unix с микросекундами

### Описание

function microtime(bool `$as_float` = `false`): string|float

Функция microtime() возвращает текущую метку времени Unix с микросекундами. Функция доступна только на операционных системах, в которых доступен системный вызов функции gettimeofday().

Для измерения производительности вызывают функцию hrtime().

### Список параметров

`as_float`

  При передаче значения `true` функция microtime() вернёт значение float вместо string, как описывает раздел значений возврата.

### Возвращаемые значения

По умолчанию функция microtime() возвращает строку (string) в формате "msec sec", где `sec` — количество секунд в виде десятичной дроби с начала эпохи Unix — 00:00:00 1 января 1970 по времени UTC, а `msec` — количество микросекунд, которое прошло после `sec`.

При передаче в параметр `as_float` значения `true` функция microtime() вернёт результат в вещественном виде (float) — текущее время в секундах, которое прошло с начала эпохи Unix с точностью до микросекунд.

### Примеры

Пример #1 Пример замера времени выполнения скрипта

    <?php

    $time_start = microtime(true);

    // Спим 1/100 секунды
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "Скрипт ничего не делал $time секунд\n";

Пример #2 Пример работы функции microtime() с флагом `REQUEST_TIME_FLOAT`

    <?php

    // Выбираем время сна случайным образом
    usleep(random_int(10_000, 1_000_000));

    // В суперглобальном массиве $_SERVER доступно значение REQUEST_TIME_FLOAT.
    // Переменная содержит метку времени начала запроса с точностью до микросекунд.
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Скрипт ничего не делал $time секунд\n";

### Смотрите также

- time() - Возвращает метку времени Unix на основе текущего системного времени
- hrtime() - Получить системное время высокого разрешения

# mktime

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

mktime — Получает метку Unix-времени для даты

### Описание

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Функция возвращает метку времени Unix, которая соответствует заданным аргументам. Метка времени — целое число, которое содержит количество секунд между началом эпохи Unix, которая началась 1 января 1970 00:00:00 GMT, и датой и временем.

Функция присвоит необязательным параметрам, которые не указали или присвоили значение `null`, текущие значения, которые соответствуют локальным дате и времени.

Внимание

Обратите внимание, что аргументы идут в странном порядке: `month`, `day`, `year`, а не в более рациональном порядке `year`, `month`, `day`.

Вызов функции mktime() без аргументов не поддерживается и вызовет исключение ArgumentCountError. Текущую метку времени возвращает функция time().

### Список параметров

`hour`

  Количество часов с начала дня, который определили параметрами `month`, `day` и `year`. Отрицательные значения относятся к часам до полуночи относительно заданного дня. Значения больше 23 определяют час, который соответствует следующему дню или дням.

`minute`

  Количество минут с начала часа, который установили параметром `hour`. Отрицательные значения относятся к минутам предыдущего часа. Значения больше 59 относятся к минутам, которые соответствуют следующему часу или часам.

`second`

  Количество секунд с начала минуты, которую установили параметром `minute`. Отрицательные значения относятся к секундам предыдущей минуты. Значения больше 59 относятся к секундам, которые соответствуют следующей минуте или минутам.

`month`

  Количество месяцев с начала текущего года. Значения от 1 до 12 относятся к обычным календарным месяцам заданного года Значения меньше 1 (включая отрицательные значения) относятся к месяцам предыдущего года в обратном порядке, то есть 0 — декабрь, -1 — ноябрь и т. д. Значения больше 12 относятся к месяцу следующего года или лет.

`day`

  Количество дней с начала текущего месяца. Значения от 1 до 28, 29, 30 или 31 (в зависимости от месяца) относятся к обычным дням месяца. Значения меньше 1 (включая отрицательные значения) относятся к дням предыдущего месяца, поэтому 0 — последний день предыдущего месяца, -1 — предпоследний день предыдущего месяца и т. д. Значения, которые превышают количество дней в месяце, относятся ко дню следующего месяца или месяцев.

`year`

  Номер года состоит из двух или четырёх цифр. Значения от 0 до 69 соответствуют 2000-2069 годам, а от 70 до 100 — 1970-2000 годам. В системах с арифметическим типом time_t в виде 32-разрядного целого числа со знаком, как самым распространённым способом представления времени, в допустимый диапазон параметра year входят значения примерно между 1901 и 2038 годами.

### Возвращаемые значения

Функция mktime() возвращает метку времени Unix по заданным аргументам или `false`, если метка времени выходит за пределы диапазона целых чисел PHP.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `hour` стал обязательным. Функция time() возвращает метку времени Unix без аргументов.
8.0.0 | Параметры `minute`, `second`, `month`, `day` и `year` теперь принимают значение `null`.

### Примеры

Пример #1 Пример базовой работы функции mktime()

    <?php

    // Устанавливаем часовой пояс по умолчанию
    date_default_timezone_set('UTC');

    // Выводит: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // Выводит что-то вроде: 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

Вывод приведённого примера будет похож на:

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

Пример #2 Пример получения метки времени функцией mktime()

Функция mktime() полезна для выполнения арифметических операций и проверки дат, поскольку функция автоматически вычисляет правильные значения для входных аргументов, которые выходят за пределы допустимого диапазона. В следующем примере каждая строка кода создаёт строку "Jan-01-1998".

    <?php

    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

Вывод приведённого примера будет похож на:

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

Пример #3 Пример получения метки времени для относительных дат функцией mktime

    <?php

    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m"), date("d") + 1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m") - 1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y") + 1) . "\n";
    print date('c', $nextyear) . "\n";

Вывод приведённого примера будет похож на:

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> Замечание:

> Добавление относительных интервалов времени часто надёжнее добавления или вычитания секунд в дне или месяце, поскольку учитывают переходы на летнее время.

Пример #4 Пример получения последнего дня месяца

Последний день любого месяца получится выразить «нулевым» днём следующего месяца, но не -1 днём. Оба следующих примера создадут строку "Последний день февраля 2000 г.: 29".

    <?php

    $lastday = mktime(0, 0, 0, 3, 0, 2000);
    echo 'Последний день февраля в 2000 году: ', date('d', $lastday) . "\n";

    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Последний день февраля в 2000 году: ', date('d', $lastday) . "\n";

Результат выполнения приведённого примера:

    Last day in Feb 2000 is: 29
    Last day in Feb 2000 is: 29

### Смотрите также

- Класс DateTimeImmutable
- checkdate() - Проверяет корректность даты по григорианскому календарю
- gmmktime() - Получает метку Unix-времени для времени UTC
- date() - Форматирует метку времени эпохи Unix
- time() - Возвращает метку времени Unix на основе текущего системного времени

# strftime

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

strftime — Форматирует местную дату и время с учётом региональных настроек

Внимание

Функция УСТАРЕЛА с PHP 8.1.0. Полагаться на функцию настоятельно не рекомендуют.

Разработчикам доступны следующие альтернативы:

- date()
- IntlDateFormatter::format()

### Описание

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = null): string|false

Функция форматирует дату и время с учётом локали. Названия месяцев, дней недели и других строк, которые зависят от языка, возвращаются с учётом текущих региональных настроек, которые установили функцией setlocale().

Внимание

Текущая библиотека языка C не всегда поддерживает каждый спецификатор преобразования, и тогда функция strftime() тоже не будет поддерживать каждый спецификатор. Кроме того, не каждая платформа поддерживает отрицательные метки времени, поэтому диапазон дат иногда ограничивается эпохой Unix. Это означает, что спецификаторы %e, %T, %R и %D (и, возможно, другие), как и даты до `1 января 1970`, не поддерживаются ОС Windows, отдельными версиями систем Linux и рядом других операционных системам. Список спецификаторов преобразования для Windows-систем даёт страница » на сайте MSDN. Вместо этой функции вызывают метод IntlDateFormatter::format().

### Список параметров

`format`

  В строке параметра `format` распознаются следующие символы
  Параметр `format` | Описание | Пример возвращаемых значений
  --- | --- | ---
  День | --- | ---
  `%a` | Сокращённое название дня недели | От `Sun` до `Sat`
  `%A` | Полное название дня недели | От `Sunday` до `Saturday`
  `%d` | Двузначный день месяца с ведущим нулём | От `01` до `31`
  `%e` | День месяца с пробелом перед одиночными цифрами. В ОС Windows обработку модификатора реализовали иначе, чем описывает руководство. Дополнительную информацию дают следующие параграфы. | От `1` до `31`
  `%j` | День года, 3 цифры с ведущими нулями | От `001` до `366`
  `%u` | Числовое представление дня недели по правилам стандарта ISO-8601 | От `1` (понедельник) до `7` (воскресенье)
  `%w` | Числовое представление дня недели | От `0` (воскресенье) до `6` (суббота)
  Неделя | --- | ---
  `%U` | Двузначный номер недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого воскресенья, которое играет роль первого дня недели | `13` (для 13-й полной недели года)
  `%V` | Номер недели года по правилам стандарта ISO-8601:1988, счёт начинается с недели, которая содержит не меньше 4 дней, неделя начинается с понедельника | От `01` до `53` (где 53 соответствует перекрывающейся неделе)
  `%W` | Двузначное числовое представление недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого понедельника года, который играет роль первого дня недели | `46` (для 46-й недели года, которая начинается с понедельника)
  Месяц | --- | ---
  `%b` | Сокращённое название месяца на основе локали | От `Jan` до `Dec`
  `%B` | Полное название месяца на основе локали | От `January` до `December`
  `%h` | Сокращённое название месяца на основе локали (псевдоним модификатора %b) | От `Jan` до `Dec`
  `%m` | Числовое представление месяца с ведущим нулём перед одиночными цифрами | От `01` для января до `12` для декабря
  Год | --- | ---
  `%C` | Двузначное представление столетия (год, разделённый на 100 и усечённый до целого числа) | `19` для 20-го века
  `%g` | Двузначное представление года по правилам стандарта ISO-8601:1988 (смотрите описание модификатора %V) | Пример: `09` для недели, в которую входит 6 января 2009
  `%G` | Полная 4-значная версия представления модификатора %g | Пример: `2009` для недели, в которую входит 3 января 2009
  `%y` | Двузначное представление года | Пример: `09` для 2009, `79` для 1979
  `%Y` | Четырёхзначное представление года | Пример: `2038`
  Время | --- | ---
  `%H` | Двузначное представление часа в 24-часовом формате | От `00` до `23`
  `%k` | Двузначное представление часа в 24-часовом формате с пробелом перед одиночной цифрой | От `0` до `23`
  `%I` | Двузначное представление часа в 12-часовом формате | От `01` до `12`
  `%l (строчная L)` | Час в 12-часовом формате с пробелом перед одиночной цифрой | От `1` до `12`
  `%M` | Двузначное представление минуты | От `00` до `59`
  `%p` | Обозначение первой или второй половины дня в верхнем регистре на основе времени, "AM" — до полудня или "PM" после полудня. | Пример: `AM` для 00:31, `PM` для 22:23. Точный результат зависит от операционной системы, которые иногда возвращают варианты в нижнем регистре или варианты с точками (например, `a.m.`)
  `%P` | Обозначение первой или второй половины дня в нижнем регистре на основе времени, "am" — до полудня или "pm" после полудня. | Пример: `am` для 00:31, `pm` для 22:23. Поддерживается не каждой операционной системой
  `%r` | То же, что и "%I:%M:%S %p" | Пример: `09:34:17 PM` для 21:34:17
  `%R` | То же, что и "%H:%M" | Пример: `00:35` для 12:35 AM, `16:44` для 4:44 PM
  `%S` | Двузначное представление секунды | От `00` до `59`
  `%T` | То же, что и "%H:%M:%S" | Пример: `21:34:17` для 09:34:17 PM
  `%X` | Предпочтительное представление времени на основе локали, без даты | Пример: `03:59:16` или `15:59:16`
  `%z` | Смещение часового пояса относительно стандарта UTC. В ОС Windows обработку модификатора реализовали иначе, чем описывает руководство. Дополнительную информацию дают следующие параграфы. | Пример: `-0500` для US Eastern Time
  `%Z` | Аббревиатура часового пояса. В ОС Windows обработку модификатора реализовали иначе, чем описывает руководство. Дополнительную информацию дают следующие параграфы. | Пример: `EST` для Eastern Time
  Метки даты и времени | --- | ---
  `%c` | Предпочтительная метка даты и времени на основе локали | Пример: `Tue Feb 5 00:45:10 2009` для 5 февраля 2009 00:45:10
  `%D` | То же, что и "%m/%d/%y" | Пример: `02/05/09` для 5 февраля 2009
  `%F` | То же, что и "%Y-%m-%d" (таким форматом часто пользуются в метках дат баз данных) | Пример: `2009-02-05` для 5 февраля 2009
  `%s` | Метка времени эпохи Unix (то же, что и функция time()) | Пример: `305815200` для 10 сентября 1979 08:40:00
  `%x` | Предпочтительное представление даты на основе локали, без времени | Пример: `02/05/09` для 5 февраля 2009
  Прочее | --- | ---
  `%n` | Символ перевода строки "\n" | ---
  `%t` | Символ табуляции "\t" | ---
  `%%` | Символ процента "%" | ---

  Внимание

  Вопреки стандарту ISO-9899:1999, в ОС Sun Solaris отсчёт числового представления дня недели начинается с воскресенья. Поэтому модификатор `%u` иногда работает не так, как описывает руководство.

  Внимание

  Только для Windows:

  Модификатор `%e` не поддерживается в Windows-реализации функции. Значение получают через модификатор `%#d`. Пример на этой странице показывает, как написать совместимую кросс-платформенную функцию.

  Модификаторы `%z` и `%Z` возвращают название часового пояса вместо смещения или аббревиатуры.

  Внимание

  Только для macOS и стандартной библиотеки musl языка C: модификатор `%P` не поддерживается в реализации этой функции в macOS.

`timestamp`
  Необязательный параметр `timestamp` — целочисленная (int) метка времени, которая по умолчанию равна текущему местному времени, если параметр `timestamp` не указали или равен `null`. Говоря по другому, значение по умолчанию равно результату функции time().

### Возвращаемые значения

Функция возвращает строковое представление метки времени `timestamp` или местного времени, если метку не указали, которые отформатировала по условиям параметра `format`. Названия месяцев и дней недели, а также другие строки, которые зависят от языка, будут соответствовать текущей локали, которую установили функцией setlocale(). Функция возвращает `false`, если параметр `format` пуст, содержит неподдерживаемые спецификаторы преобразования или если длина возвращаемой строки превысит значение `4095`.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

Поскольку вывод зависит от текущей библиотеки языка C, отдельные спецификаторы преобразования поддерживаются не всегда. В ОС Windows функция выдаст 5 сообщений об ошибках уровня `E_WARNING` и вернёт `false` при передаче неизвестных спецификаторов преобразования. В других операционных системах функция не всегда выдаёт сообщения об ошибках уровня `E_WARNING`, а вывод иногда содержит модификаторы без преобразования.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `timestamp` теперь принимает значение null.

### Примеры

Этот пример будет работать в системах с языковыми настройками, которые соответствуют модификаторам.

Пример #1 Пример форматирования даты функцией strftime() с разными языковыми настройками

    <?php

    setlocale(LC_TIME, "C");
    echo strftime("%A");

    setlocale(LC_TIME, "fi_FI");
    echo strftime(" по-фински — %A,");

    setlocale(LC_TIME, "fr_FR");
    echo strftime(" по-французски — %A и");

    setlocale(LC_TIME, "de_DE");
    echo strftime(" по-немецки — %A.\n");

Пример #2 Пример номеров недели по стандарту ISO 8601:1988

    <?php

    /*     Декабрь 2002 / Январь 2003
    ISOнед Пн  Вт  Ср  Чт  Пт  Сб  Вс
    ----- ----------------------------
    51     16  17  18  19  20  21  22
    52     23  24  25  26  27  28  29
    1      30  31   1   2   3   4   5
    2       6   7   8   9  10  11  12
    3      13  14  15  16  17  18  19   */

    // Вывод: Дата 12/28/2002 в формате %V, %G, %Y = 52,2002,2002
    echo "Дата 12/28/2002 в формате %V, %G, %Y = " . strftime("%V, %G, %Y", strtotime("12/28/2002")) . "\n";

    // Вывод: Дата 12/30/2002 в формате %V, %G, %Y = 1,2003,2002
    echo "Дата 12/30/2002 в формате %V, %G, %Y = " . strftime("%V, %G, %Y", strtotime("12/30/2002")) . "\n";

    // Вывод: Дата 1/3/2003 в формате %V, %G, %Y = 1,2003,2003
    echo "Дата1/3/2003 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("1/3/2003")) . "\n";

    // Вывод: Дата 1/10/2003 в формате %V, %G, %Y = 2,2003,2003
    echo "Дата1/10/2003 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("1/10/2003")) . "\n";

    /*     Декабрь 2004 / Январь 2005
    ISOнед Пн  Вт  Ср  Чт  Пт  Сб  Вс
    ----- ----------------------------
    51     13  14  15  16  17  18  19
    52     20  21  22  23  24  25  26
    53     27  28  29  30  31   1   2
    1       3   4   5   6   7   8   9
    2      10  11  12  13  14  15  16   */

    // Вывод: Дата 12/23/2004 в формате %V, %G, %Y = 52,2004,2004
    echo "Дата 12/23/2004 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("12/23/2004")) . "\n";

    // Вывод: Дата 12/31/2004 в формате %V,%G,%Y = 53,2004,2004
    echo "Дата 12/31/2004 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("12/31/2004")) . "\n";

    // Вывод: Дата 1/2/2005 в формате %V, %G, %Y = 53,2004,2005
    echo "Дата 1/2/2005 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("1/2/2005")) . "\n";

    // Вывод: Дата 1/3/2005 в формате %V, %G, %Y = 1,2005,2005
    echo "Дата 1/3/2005 в формате %V, %G, %Y = " . strftime("%V, %G, %Y",strtotime("1/3/2005")) . "\n";

Пример #3 Пример кросс-платформенной совместимости модификатора `%e`

    <?php

    // 1 января: выдаёт результат: '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Убедимся, что код выполняется в ОС Windows, и правильно заменим модификатор %e
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
    }

    echo strftime($format);

Пример #4 Отображение каждого известного и неизвестного формата

    <?php

    // Описание форматов
    $strftimeFormats = array(
        'A' => 'Полное название дня недели',
        'B' => 'Полное название месяца на основе локали',
        'C' => 'Двузначное представление столетия (год, разделённый на 100 и усечённый до целого числа)',
        'D' => 'То же, что и "%m/%d/%y"',
        'E' => '',
        'F' => 'То же, что и "%Y-%m-%d"',
        'G' => 'Полная 4-значная версия модификатора %g',
        'H' => 'Двузначное представление часа в 24-часовом формате',
        'I' => 'Двузначное представление часа в 12-часовом формате',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Двузначное представление минуты',
        'N' => '',
        'O' => '',
        'P' => 'Обозначение "am" или "pm" в нижнем регистре на основе времени',
        'Q' => '',
        'R' => 'То же, что и "%H:%M"',
        'S' => 'Двузначное представление секунды',
        'T' => 'То же, что и "%H:%M:%S"',
        'U' => 'Двузначный номер недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого воскресенья, которое играет роль первого дня недели',
        'V' => 'Номер недели года по правилам стандарта ISO-8601:1988, счёт начинается с недели, которая содержит не меньше 4 дней, неделя начинается с понедельника',
        'W' => 'Двузначное числовое представление недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого понедельника года, который играет роль первого дня недели',
        'X' => 'Предпочтительное представление времени на основе локали, без даты',
        'Y' => 'Четырёхзначное представление года',
        'Z' => 'Смещение или аббревиатура часового пояса, которые НЕ выдаёт модификатор %z (зависит от операционной системы)',
        'a' => 'Сокращённое название дня недели',
        'b' => 'Сокращённое название месяца на основе локали',
        'c' => 'Предпочтительная метка даты и времени на основе локали',
        'd' => 'Двузначный день месяца с ведущим нулём',
        'e' => 'День месяца с пробелом перед одиночными цифрами',
        'f' => '',
        'g' => 'Двузначное представление года по правилам стандарта ISO-8601:1988 (смотрите описание модификатора %V)',
        'h' => 'Сокращённое название месяца на основе локали (псевдоним модификатора %b)',
        'i' => '',
        'j' => 'День года, 3 цифры с ведущими нулями',
        'k' => 'Двузначное представление часа в 24-часовом формате с пробелом перед одиночной цифрой',
        'l' => 'Час в 12-часовом формате с пробелом перед одиночной цифрой',
        'm' => 'Числовое представление месяца с ведущим нулём перед одиночными цифрами',
        'n' => 'Символ новой строки "\n"',
        'o' => '',
        'p' => 'Обозначение "AM" или "PM" в верхнем регистре на основе времени',
        'q' => '',
        'r' => 'То же, что и "%I:%M:%S %p"',
        's' => 'Метка времени эпохи Unix',
        't' => 'Символ табуляции "\t"',
        'u' => 'Числовое представление дня недели по правилам стандарта ISO-8601',
        'v' => '',
        'w' => 'Числовое представление дня недели',
        'x' => 'Предпочтительное представление даты на основе локали, без времени',
        'y' => 'Двузначное представление года',
        'z' => 'Смещение или аббревиатура часового пояса относительно стандарта UTC (зависит от операционной системы)',
        '%' => 'Символ процента "%"',
    );

    // Результаты
    $strftimeValues = array();

    // Обрабатываем форматы и подавляем ошибки
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Находим самое длинное значение
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Отображаем известные форматы
    foreach ($strftimeValues as $format => $value) {
        echo "Известный формат   : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Отображаем неизвестные форматы
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Неизвестный формат : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

Вывод приведённого примера будет похож на:

    Известный формат   : 'A' = 'Friday'            ( Полное название дня недели )
    Известный формат   : 'B' = 'December'          ( Полное название месяца на основе локали )
    Известный формат   : 'H' = '11'                ( Двузначное представление часа в 24-часовом формате )
    Известный формат   : 'I' = '11'                ( Двузначное представление часа в 12-часовом формате )
    Известный формат   : 'M' = '24'                ( Двузначное представление минуты )
    Известный формат   : 'S' = '44'                ( Двузначное представление секунды )
    Известный формат   : 'U' = '48'                ( Двузначный номер недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого воскресенья, которое играет роль первого дня недели )
    Известный формат   : 'W' = '48'                ( Двузначное числовое представление недели года с ведущим нулём для одиночных чисел. Отсчёт недель начинается с первого понедельника года, который играет роль первого дня недели )
    Известный формат   : 'X' = '11:24:44'          ( Предпочтительное представление времени на основе локали, без даты )
    Известный формат   : 'Y' = '2010'              ( Четырёхзначное представление года )
    Известный формат   : 'Z' = 'GMT Standard Time' ( Смещение или аббревиатура часового пояса, которые НЕ выдаёт модификатор %z (зависит от операционной системы) )
    Известный формат   : 'a' = 'Fri'               ( Сокращённое название дня недели )
    Известный формат   : 'b' = 'Dec'               ( Сокращённое название месяца на основе локали )
    Известный формат   : 'c' = '12/03/10 11:24:44' ( Предпочтительная метка даты и времени на основе локали )
    Известный формат   : 'd' = '03'                ( Двузначный номер дня месяца (с ведущим нулём) )
    Известный формат   : 'j' = '337'               ( Номер дня в году, 3 цифры с ведущими нулями )
    Известный формат   : 'm' = '12'                ( Числовое представление месяца с ведущим нулём перед одиночными цифрами )
    Известный формат   : 'p' = 'AM'                ( Обозначение "AM" или "PM" в верхнем регистре на основе времени )
    Известный формат   : 'w' = '5'                 ( Числовое представление дня недели )
    Известный формат   : 'x' = '12/03/10'          ( Предпочтительное представление даты на основе локали, без времени )
    Известный формат   : 'y' = '10'                ( Двузначное представление года )
    Известный формат   : 'z' = 'GMT Standard Time' ( Смещение или аббревиатура часового пояса относительно стандарта UTC (зависит от операционной системы) )
    Известный формат   : '%' = '%'                 ( Символ процента ("%") )
    Неизвестный формат : 'C'                       ( Двузначное представление столетия (год, разделённый на 100 и усечённый до целого числа) )
    Неизвестный формат : 'D'                       ( То же, что и "%m/%d/%y" )
    Неизвестный формат : 'E'
    Неизвестный формат : 'F'                       ( То же, что и "%Y-%m-%d" )
    Неизвестный формат : 'G'                       ( Полная 4-значная версия модификатора %g )
    Неизвестный формат : 'J'
    Неизвестный формат : 'K'
    Неизвестный формат : 'L'
    Неизвестный формат : 'N'
    Неизвестный формат : 'O'
    Неизвестный формат : 'P'                       ( Обозначение "am" или "pm" в нижнем регистре на основе времени )
    Неизвестный формат : 'Q'
    Неизвестный формат : 'R'                       ( То же, что и "%H:%M" )
    Неизвестный формат : 'T'                       ( То же, что и "%H:%M:%S" )
    Неизвестный формат : 'V'                       ( Номер недели года по правилам стандарта ISO-8601:1988, счёт начинается с недели, которая содержит не меньше 4 дней, неделя начинается с понедельника )
    Неизвестный формат : 'e'                       ( День месяца с пробелом перед одиночными цифрами )
    Неизвестный формат : 'f'
    Неизвестный формат : 'g'                       ( Двузначное представление года по правилам стандарта ISO-8601:1988 (смотрите описание модификатора %V) )
    Неизвестный формат : 'h'                       ( Сокращённое название месяца на основе локали (псевдоним модификатора %b) )
    Неизвестный формат : 'i'
    Неизвестный формат : 'k'                       ( Двузначное представление часа в 24-часовом формате с пробелом перед одиночной цифрой )
    Неизвестный формат : 'l'                       ( Час в 12-часовом формате с пробелом перед одиночной цифрой )
    Неизвестный формат : 'n'                       ( Символ новой строки "\n" )
    Неизвестный формат : 'o'
    Неизвестный формат : 'q'
    Неизвестный формат : 'r'                       ( То же, что и "%I:%M:%S %p" )
    Неизвестный формат : 's'                       ( Временная метка эпохи Unix )
    Неизвестный формат : 't'                       ( Символ табуляции "\t" )
    Неизвестный формат : 'u'                       ( Числовое представление дня недели по правилам стандарта ISO-8601 )
    Неизвестный формат : 'v'

### Примечания

> Замечание: Модификаторы %G и %V, работа которых основана на днях недели по стандарту ISO 8601:1988, иногда дают неожиданные (хотя и правильные) результаты, если функция не до конца понимает систему нумерации. Смотрите примеры с модификатором %V на этой странице руководства.

### Смотрите также

- IntlDateFormatter::format() - Форматирует значение даты и времени как строку
- DateTimeInterface::format() - Форматирует дату в заданном формате
- » Онлайн-утилита составления времени в формате функции strftime()
- setlocale() - Устанавливает региональные настройки
- mktime() - Получает метку Unix-времени для даты
- strptime() - Разбирает строку даты и времени, которую сгенерировала функция strftime
- gmstrftime() - Форматирует дату и время как время UTC с учётом региональных настроек
- » Спецификация консорциума Open Group для функции strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — Разбирает строку даты и времени, которую сгенерировала функция strftime()

Внимание

Начиная с PHP 8.1.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

Функция strptime() возвращает массив с данными разбора строки `timestamp`, или false, если возникла ошибка.

Названия месяцев и дней недели, и другие строки, которые зависят от языка, соответствуют текущим региональным настройкам, которые установили функцией setlocale() (см. описание константы LC_TIME).

### Список параметров

`timestamp` (string)

  Строка наподобие той, которую возвращает функция strftime() и которую требуется разобрать.

`format` (string)

  Формат строки `timestamp` наподобие того, с которым работает функция strftime(). Обратите внимание, отдельные параметры форматирования, которые доступны функции strftime(), не влияют на форматирование функцией strptime(); набор поддерживаемых символов форматирования зависит от ОС и С-библиотеки.

  Подробнее о параметрах форматирования рассказывает описание функции strftime().

### Возвращаемые значения

Функция возвращает массив или `false`, если возникла ошибка.

Список элементов, которые возвращаются в массиве
параметры | Описание
--- | ---
`"tm_sec"` | Секунды после минут (0-61)
`"tm_min"` | Минуты после часов (0-59)
`"tm_hour"` | Часы после полуночи (0-23)
`"tm_mday"` | День месяца (1-31)
`"tm_mon"` | Месяцы после января (0-11)
`"tm_year"` | Годы после 1900
`"tm_wday"` | Дни после воскресенья (0-6)
`"tm_yday"` | Дни после 1-го января (0-365)
`"unparsed"` | Часть метки `timestamp`, которую не удалось распознать в строке формата `format`

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция устарела. Вместо неё рекомендуют пользоваться функцией date_parse_from_format(), чтобы разобрать дату и время независимо от региональных настроек, или методом IntlDateFormatter::parse(), чтобы разбор зависел от локали.

### Примеры

Пример #1 Пример разбора даты и времени функцией strptime()

    <?php

    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

Вывод приведённого примера будет похож на:

    03/10/2004 15:54:19

    Array
    (
        [tm_sec] => 19
        [tm_min] => 54
        [tm_hour] => 15
        [tm_mday] => 3
        [tm_mon] => 9
        [tm_year] => 104
        [tm_wday] => 0
        [tm_yday] => 276
        [unparsed] =>
    )

### Примечания

> Замечание: Для Windows-платформ функцию не реализовали.

> Замечание:

> Внутренне эта функция вызывает функцию `strptime()` системной библиотеки на языке C. Поведение функции в одной операционной системе иногда значительно отличается от поведения в другой. Функция date_parse_from_format() лишена этого недостатка, поэтому рекомендуют вызывать её.

> Замечание:

> Элемент `"tm_sec"` включает високосные секунды — до двух в год. Подробнее о високосных секунды рассказывает статья » о високосной секунде на сайте Википедии.

### Смотрите также

- IntlDateFormatter::parse() - Преобразовывает строку в значение отметки времени
- DateTime::createFromFormat() - Разбирает строку времени по заданному формату
- checkdate() - Проверяет корректность даты по григорианскому календарю
- strftime() - Форматирует местную дату и время с учётом региональных настроек
- date_parse_from_format() - Разбирает строку с датой по заданному формату

# strtotime

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

strtotime — Преобразовывает текстовое представление даты на английском языке в метку времени Unix

### Описание

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

Первым параметром функция ожидает строку с датой на английском языке, которая будет преобразована в метку времени Unix (количество секунд, прошедших с 1 января 1970 года 00:00:00 UTC) относительно метки времени, переданной в параметр `baseTimestamp`, или текущего времени, если аргумент `baseTimestamp` опущен. Разбор строки даты определён в разделе «Форматы даты и времени» и содержит несколько тонких вопросов. Знание форматов упростит работу с функцией.

Внимание

Метка времени Unix, которую возвращает функция, не содержит данных о часовых поясах. Для расчётов с датой/временем обращаются к инструменту с бо́льшими способностями — классу DateTimeImmutable.

Каждый параметр функции будет использовать часовой пояс по умолчанию, если он не указан в нём. Соблюдают осторожность и не указывают разные метки времени в параметрах, если только так не было задумано. О способах установки часового пояса по умолчанию рассказано в описании функции date_default_timezone_get().

### Список параметров

`datetime`

  Строка даты и времени. Объяснение корректных форматов даёт раздел «Форматы даты и времени».

`baseTimestamp`

  Метка времени, которую функция будет использовать как основу для вычисления относительных дат.

### Возвращаемые значения

Функция возвращает метку времени, если выполнилась успешно, иначе значение `false`.

### Ошибки

Каждый вызов функции для работы с датой и временем генерирует ошибку уровня `E_WARNING` при неправильных настройках часового пояса. Смотрите также описание функции date_default_timezone_set().

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `baseTimestamp` теперь принимает значение `null`.

### Примеры

Пример #1 Пример разбора англоязычного текстового описания даты и времени функцией strtotime()

    <?php

    echo strtotime("now"), "\n";
    echo strtotime("10 September 2000"), "\n";
    echo strtotime("+1 day"), "\n";
    echo strtotime("+1 week"), "\n";
    echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
    echo strtotime("next Thursday"), "\n";
    echo strtotime("last Monday"), "\n";

Пример #2 Проверка ошибок

    <?php

    $str = 'Not Good';

    if (($timestamp = strtotime($str)) === false) {
        echo "Строка ($str) недопустима";
    } else {
        echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### Примечания

> Замечание:

> «Относительная» дата в этом случае также означает, что если конкретный компонент метки даты и времени не указали, функция возьмёт его дословно из параметра `baseTimestamp`. Поэтому вызов `strtotime('February')` при запуске 31 мая 2022 года функция интерпретирует как `31 февраля 2022`, что перенесётся в метку времени `3 марта`, а в високосный год — `2 марта`. Вызов `strtotime('1 February')` или `strtotime('first day of February')` не допустит этой проблемы.

> Замечание:

> При двузначном указании количества лет значения 00-69 функция интерпретирует как 2000-2069, а 70-99 — 1970-1999. Замечания ниже рассказывают о возможных различиях на 32-битных системах (допустимые даты заканчиваются 2038-01-19 03:14:07).

> Замечание:

> Корректный диапазон меток времени 32-битного целого числа со знаком — даты с 13 декабря 1901 20:45:54 по времени UTC по 19 января 2038 03:14:07 по времени UTC.

> В 64-битных версиях PHP корректный диапазон меток времени практически бесконечен, поскольку 64 бита справляются с представлением около 293 миллиардов лет в обоих направлениях.

> Замечание:

> Использовать функцию для математических операций не рекомендуется. Лучше вызывать методы DateTime::add() и DateTime::sub().

### Смотрите также

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Разбирает строку времени по заданному формату
- Форматы даты и времени
- checkdate() - Проверяет корректность даты по григорианскому календарю
- strptime() - Разбирает строку даты и времени, которую сгенерировала функция strftime

# time

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

time — Возвращает метку времени Unix на основе текущего системного времени

### Описание

function time(): int

Функция возвращает текущее время системы в виде метки Unix-времени, которое измеряется в секундах с начала эпохи Unix — 00:00:00 1 января 1970 по времени UTC.

> Замечание:

> Метки времени Unix не дают информации о локальном часовом поясе. Разработчики PHP рекомендуют обрабатывать информацию о дате и времени методами класса DateTimeImmutable, который помогает избегать ошибок, которые возникают при работе только с метками Unix-времени.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает временну́ю метку на основе текущего времени системы.

### Примеры

Пример #1 Пример получения метки времени функцией time()

    <?php

    echo 'С начала Unix-эпохи прошло: '. time() . ' с';

Вывод приведённого примера будет похож на:

    Сейчас: 1660338149

### Примечания

Подсказка

Метка времени начала запроса доступна в глобальной переменной $_SERVER['REQUEST_TIME'].

### Смотрите также

- DateTimeImmutable
- date() - Форматирует метку времени эпохи Unix
- microtime() - Возвращает текущую метку времени Unix с микросекундами

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — Псевдоним DateTimeZone::listAbbreviations()

### Описание

Псевдоним функции DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — Псевдоним DateTimeZone::listIdentifiers()

### Описание

Псевдоним функции DateTimeZone::listIdentifiers().

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — Псевдоним DateTimeZone::getLocation()

### Описание

Псевдоним функции DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Возвращает название часового пояса, угадывая по аббревиатуре и смещению UTC

### Описание

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### Список параметров

`abbr`

  Аббревиатура часового пояса.

`utcOffset`

  Смещение относительно времени UTC в секундах. Значение по умолчанию равно -1, что означает возврат первого найденного часового пояса, который соответствует аббревиатуре `abbr`. В остальных случаях функция выполнит поиск часового пояса с заданным смещением. Функция вернёт ближайший к смещению часовой пояс, если поиск завершится неудачей.

`isDST`

  Поправка на летнее время. Значение по умолчанию равно -1, при котором поправка на летнее время не учитывается. При передаче значения 1 смещение `utcOffset` учитывает действующее летнее время. При передаче значения 0 смещение `utcOffset` рассчитывается с учётом зимнего времени. Определение часового пояса опирается только на смещение `utcOffset` и сезонный переход `isDST`, если список аббревиатур не содержит сокращение `abbr`.

### Возвращаемые значения

Возвращает имя часового пояса или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения названия часового пояса функцией timezone_name_from_abbr()

    <?php

    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

Вывод приведённого примера будет похож на:

    Europe/Berlin
    Europe/Paris

### Смотрите также

- timezone_abbreviations_list() - Псевдоним DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — Псевдоним DateTimeZone::getName()

### Описание

Псевдоним функции DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — Псевдоним DateTimeZone::getOffset()

### Описание

Псевдоним функции DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — Псевдоним DateTimeZone::__construct()

### Описание

Псевдоним функции DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — Псевдоним DateTimeZone::getTransitions()

### Описание

Псевдоним функции DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — Получает номер версии базы данных часовых поясов

### Описание

function timezone_version_get(): string

Функция возвращает номер версии базы данных часовых поясов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает значение string в формате `YYYY.increment`, например `2022.2`.

При устаревании базы данных часовых поясов, которая, например, перестаёт показывать текущий год, информацию о часовых поясах актуализируют либо путём обновления версии PHP, либо устанавливают PECL-пакет the » timezonedb

Отдельные дистрибутивы Linux исправляют поддержку даты и времени в PHP, чтобы получать информацию о часовых поясах из альтернативного источника, тогда функция возвращает `0.system`. Установка PECL-пакета » timezonedb исправляет проблему.

### Примеры

Пример #1 Пример определения версии базы данных часовых поясов

    <?php

    echo timezone_version_get();

Вывод приведённого примера будет похож на:

    2022.2

### Смотрите также

- Список поддерживаемых часовых поясов

## Содержание

- checkdate — Проверяет корректность даты по григорианскому календарю
- date — Форматирует метку времени эпохи Unix
- date_add — Псевдоним DateTime::add
- date_create — Создаёт новый объект DateTime
- date_create_from_format — Псевдоним DateTime::createFromFormat
- date_create_immutable — Создаёт новый объект DateTimeImmutable
- date_create_immutable_from_format — Псевдоним DateTimeImmutable::createFromFormat
- date_date_set — Псевдоним DateTime::setDate
- date_default_timezone_get — Возвращает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
- date_default_timezone_set — Устанавливает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
- date_diff — Псевдоним DateTime::diff
- date_format — Псевдоним DateTime::format
- date_get_last_errors — Псевдоним DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — Псевдоним DateInterval::createFromDateString
- date_interval_format — Псевдоним DateInterval::format
- date_isodate_set — Псевдоним DateTime::setISODate
- date_modify — Псевдоним DateTime::modify
- date_offset_get — Псевдоним DateTime::getOffset
- date_parse — Возвращает ассоциативный массив с подробной информацией о заданной дате/времени
- date_parse_from_format — Разбирает строку с датой по заданному формату
- date_sub — Псевдоним DateTime::sub
- date_sun_info — Возвращает массив с информацией о закате и восходе Солнца, и начале и окончании сумерек
- date_sunrise — Возвращает время рассвета для заданных дня и местоположения
- date_sunset — Возвращает время захода солнца для заданных дня и расположения
- date_time_set — Псевдоним DateTime::setTime
- date_timestamp_get — Псевдоним DateTime::getTimestamp
- date_timestamp_set — Псевдоним DateTime::setTimestamp
- date_timezone_get — Псевдоним DateTime::getTimezone
- date_timezone_set — Псевдоним DateTime::setTimezone
- getdate — Возвращает информацию о дате и времени
- gettimeofday — Возвращает текущее время
- gmdate — Форматирует дату и время как время UTC
- gmmktime — Получает метку Unix-времени для времени UTC
- gmstrftime — Форматирует дату и время как время UTC с учётом региональных настроек
- idate — Форматирует компонент даты или времени местного часового пояса как целое число
- localtime — Получает местное время
- microtime — Возвращает текущую метку времени Unix с микросекундами
- mktime — Получает метку Unix-времени для даты
- strftime — Форматирует местную дату и время с учётом региональных настроек
- strptime — Разбирает строку даты и времени, которую сгенерировала функция strftime
- strtotime — Преобразовывает текстовое представление даты на английском языке в метку времени Unix
- time — Возвращает метку времени Unix на основе текущего системного времени
- timezone_abbreviations_list — Псевдоним DateTimeZone::listAbbreviations
- timezone_identifiers_list — Псевдоним DateTimeZone::listIdentifiers
- timezone_location_get — Псевдоним DateTimeZone::getLocation
- timezone_name_from_abbr — Возвращает название часового пояса, угадывая по аббревиатуре и смещению UTC
- timezone_name_get — Псевдоним DateTimeZone::getName
- timezone_offset_get — Псевдоним DateTimeZone::getOffset
- timezone_open — Псевдоним DateTimeZone::__construct
- timezone_transitions_get — Псевдоним DateTimeZone::getTransitions
- timezone_version_get — Получает номер версии базы данных часовых поясов

# Ошибки и исключения даты и времени

- DateError (наследует Error)
  - DateObjectError DateRangeError
- DateException (наследует Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Допустимые форматы даты и времени

Раздел описывает разные форматы в BNF-подобном синтаксисе, которые принимает парсер: DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse() и strtotime(). Форматы сгруппированы по разделам. В большей части случаев форматы из разных разделов, разделённые пробелом, запятой или точкой, разрешается указывать в одной и той же строке даты и времени. Для каждого поддерживаемого формата приводится один или ряд примеров, и описание формата. Символы в одинарных кавычках нечувствительны к регистру (`'t'` эквивалентно как `t`, так и `T`), символы в двойных кавычках чувствительны к регистру (`"T"` означает только `T`).

О форматировании объектов DateTimeImmutable и DateTime рассказывает документация метода DateTimeInterface::format().

При форматировании дат рекомендуют учитывать общие правила.

1. Парсер разрешает для каждой единицы измерения (год, месяц, день, час, минута, секунда) полный диапазон значений. Для года — 4 цифры, для месяца — 0-12, дня — 0-31, для часа — 0-24, а для минуты — 0-59.
2. Для секунд допускается значение 60, поскольку иногда появляются строки даты с високосной секундой. Но PHP реализует Unix-время, в котором значение "60" недопустимо для числа секунд, и поэтому возникает переполнение.
3. Функция strtotime() возвращает значение `false`, если какое-либо число выходит за пределы диапазонов, а конструктор DateTimeImmutable::__construct() выбрасывает исключение.
4. Каждый элемент времени сбрасывается на 0, если строка содержит дату.
5. Каждый менее значимый элемент времени сбрасывается до 0, если строка содержит какую-либо часть времени.
6. Парсер только разбирает строку и не выполняет проверок, чтобы работать быстро и универсально.
7. Кроме правил для отдельных элементов времени синтаксический анализатор понимает и более специфические комбинированные форматы наподбие разбора меток Unix-времени — `@1690388256` и дат недели в формате ISO — `2008-W28-3`.

8. Неверные даты проверяются отдельно:

       <?php

       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   Результат выполнения приведённого примера:

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. Крайние случаи уже обрабатывают, для этого вызывают метод DateTimeImmutable::createFromFormat() и указывают правильный формат.

       <?php

       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   Результат выполнения приведённого примера:

       object(DateTimeImmutable)#1 (3) {
         ["date"]=>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"]=>
         int(3)
         ["timezone"]=>
         string(13) "Europe/London"
       }

## Форматы времени

Страница описывает форматы даты и времени в BNF-подобном синтаксисе, которые понимает парсер методов DateTimeImmutable и DateTime, и функций date_create(), date_create_immutable() и strtotime().

О форматировании объектов DateTimeImmutable и DateTime рассказывает документация метода DateTimeInterface::format().

Символы форматирования времени
Описание | Формат | Примеры
--- | --- | ---
`frac` (дробная часть) | . [0-9]+ | ".21342", ".85"
`hh` (часы в 12-часовом формате) | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` (часы в 24-часовом формате) | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` (Ante meridiem или Post meridiem) | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` (минуты) | [0-5][0-9] | "00", "12", "59"
`II` (секунды) | [0-5][0-9] | "00", "12", "59"
`space` (символ пробела или табуляции) | [ \t] |
`tz` (часовой пояс) | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` (числовое обозначение смещения часового пояса) | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

12-часовой формат
Описание | Формат | Примеры
--- | --- | ---
Только часы (с Ante meridiem или Post meridiem) | `hh` `space`? `meridian` | "4 am", "5PM"
Часы и минуты (с `Ante meridiem` или `Post meridiem`) | `hh` [.:] `MM` `space`? `meridian` | "4:08 am", "7:19P.M."
Часы, минуты и секунды (с `Ante meridiem` или `Post meridiem`) | `hh` [.:] `MM` [.:] `II` `space`? `meridian` | "4:08:37 am", "7:19:19P.M."
MS SQL (Часы, минуты, секунды и дробная часть с Ante meridiem или Post meridiem) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `meridian` | "4:08:39:12313am"

24-часовой формат
Описание | Формат | Примеры
--- | --- | ---
Часы и минуты | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Часы и минуты (без двоеточия-разделителя) | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Часы, минуты и секунды | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Часы, минуты и секунды (без двоеточия-разделителя) | 't'? `HH` `MM` `II` | "040837", "T191919"
Часы, минуты, секунды и часовой пояс | 't'? `HH` [.:] `MM` [.:] `II` `space`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Часы, минуты, секунды и дробная часть | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Сведения о часовом поясе | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Форматы даты

Эта страница описывает форматы даты в BNF-подобном синтаксисе, которые понимает парсер функций: DateTimeImmutable, DateTime, date_create(), date_create_immutable() и strtotime().

Чтобы отформатировать объекты DateTimeImmutable и DateTime, обратитесь к документации метода DateTimeInterface::format().

Символы форматирования даты
Описание | Формат | Примеры
--- | --- | ---
`daysuf` (суффикс порядкового числительного дня месяца) | "st" | "nd" | "rd" | "th" |
`dd` (день месяца без ведущих нулей) | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` (день месяца, 2 цифры с ведущим нулём) | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` (полное или сокращённое название месяца) | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
`M` (сокращённое название месяца) | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` (порядковый номер месяца) | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` (порядковый номер месяца, 2 цифры с ведущим нулём) | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` (порядковый номер года) | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` (порядковый номер года, 2 цифры) | [0-9]{2} | "00", "08", "78"
`YY` (порядковый номер года, 4 цифры) | [0-9]{4} | "2000", "2008", "1978"
`YYY` | [0-9]{5,19} | "81412", "20192"

Региональные нотации
Описание | Формат | Примеры
--- | --- | ---
Месяц и день в американской нотации | `mm` "/" `dd` | "5/12", "10/27"
Месяц, день и год в американской нотации | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
4 цифры года, месяц и день со слешем-разделителем | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
4 цифры года и месяц (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Год, месяц и день с дефисом-разделителем | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
День, месяц и 4 цифры года с разделителем в виде точки, символа табуляции или дефиса | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
День, месяц и 2 цифры года с разделителем в виде точки или символа табуляции | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22.12.78"
День, название месяца и год | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Название месяца и 4 цифры года (день месяца сбрасывается на 1) | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
4 цифры года и название месяца (день месяца сбрасывается на 1) | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Название месяца, день и год | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Название месяца и день | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
День и название месяца | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Сокращённое название месяца, день и год | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Год, сокращённое название месяца и день | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Только год | `YY` | "1978", "2008"
Год (расширенный, 5-19 цифр со знаком) | [+-] `YYY` | "-81120", "+20192"
Только название месяца | `m` | "March", "jun", "DEC"

Нотации стандарта ISO8601
Описание | Формат | Примеры
--- | --- | ---
8 цифр (год, месяц и день) | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
8 цифр (год, месяц и день) со слешем-разделителем | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
2 цифры года, месяц и день с дефисом-разделителем | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
4 цифры года с необязательным знаком, месяц и день | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Пятизначный год с обязательным знаком, месяцем и днём | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> Замечание:

> Форматы `y` и `yy` для годов меньше 100 обрабатываются в исключительных случаях при использовании символов `y` или `yy`. К году добавляется значение 2000, если год попадает в диапазон 0-69 (включительно). К году добавляется значение 1900, если год принадлежит диапазону 70-99 (включительно). Поэтому дата "00-01-01" интерпретируется как "2000-01-01".

> Замечание:

> Формат "День, месяц и 2 цифры года с разделителем в виде точки или символа табуляции" (`dd` [.\t] `mm` "." `yy`) работает только для годов из диапазона 61-99 (включительно). За пределами этого диапазона отдаётся предпочтение формату времени "`HH` [.:] `MM` [.:] `SS`".

> Замечание:

> Формат «Год (и только год)» надёжно работает, только если метод уже нашёл строку времени, иначе, если четыре цифры года соответствуют формату `HH` `MM`, вместо года устанавливаются эти два элемента даты.

> Для согласованного разбора только года вызывают метод DateTimeImmutable::createFromFormat() со спецификатором `Y`.

Предостережение

Возможен выход за границы диапазона форматов `dd` и `DD`. День месяца с порядковым номером 0 подразумевает последний день предыдущего месяца в результате выхода за границы диапазона. Согласно написанному, "2008-08-00" равносильно "2008-07-31", а "2008-06-31" соответствует "2008-07-01" (в июне всего 30 дней).

Обратите внимание на ограничение диапазона дней: 0-31, как указывает регулярное выражение в предыдущих параграфах. Поэтому дата наподобие "2008-06-32" некорректна.

Допускается также выход за границы диапазона для форматов `mm` и `MM` со значением 0. Значение месяца 0 соответствует декабрю предыдущего года. Например, дата "2008-00-22" равносильна "2007-12-22".

Если учесть два предыдущих замечания и выход за границы диапазона дней и месяцев, получим следующее: дата "2008-00-00" в первую очередь преобразуется в "2007-12-00", которая будет преобразована в "2007-11-30". То же случится с датой "0000-00-00", которая преобразуется к "-0001-11-30" (минус первый год в календаре ISO 8601 и 2 год до н. э. по григорианскому календарю).

## Составные форматы

Страница описывает разные составные форматы даты и времени в BNF-подобном синтаксисе, которые понимает парсер методов DateTimeImmutable и DateTime, и функций date_create(), date_create_immutable() и strtotime().

О форматировании объектов DateTimeImmutable и DateTime рассказывает документация метода DateTimeInterface::format().

Символы составного форматирования
Описание | Форматы | Примеры
--- | --- | ---
`DD` (день месяца с ведущим нулём) | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` (день в году) | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "001", "012", "180", "350", "366"
`frac` (дробная часть) | . [0-9]+ | ".21342", ".85"
`hh` (часы) | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` (часы с ведущим нулём) | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` (Ante meridiem или Post meridiem) | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` (минуты) | [0-5]?[0-9] | "04", "8", "59"
`II` (минуты с ведущим нулём) | [0-5][0-9] | "04", "08", "59"
`M` (сокращённое наименование месяца) | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` (месяц с ведущим нулём) | [0-1][0-9] | "00", "12"
`space` (символ пробела или табуляции) | [ \t] |
`ss` (секунды) | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (дополнительная секунда)
`SS` (секунды с ведущим нулём) | [0-5][0-9] | "04", "08", "59"
`W` (неделя в году) | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` (смещение часового пояса) | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` (4 цифры года) | [0-9]{4} | "2000", "2008", "1978"

Форматы стандартов
Описание | Примеры
--- | ---
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 Extended | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"

Региональные нотации
Описание | Формат | Примеры
--- | --- | ---
Общий формат log-записей | `dd` "/" `M` "/" `YY` : `HH` ":" `II` ":" `SS` `space` `tzcorrection` | "10/Oct/2000:13:55:36 -0700"
EXIF | `YY` ":" `MM` ":" `DD` " " `HH` ":" `II` ":" `SS` | "2008:08:07 18:11:31"
Год и неделя в формате ISO | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
Год, неделя в формате ISO и день недели | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL: год и день в году | `YY` "."? `doy` | "2008.197", "2008197"
SOAP | `YY` "-" `MM` "-" `DD` "T" `HH` ":" `II` ":" `SS` `frac` `tzcorrection`? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Unix Timestamp | "@" "-"? [0-9]+ | "@1215282385"
Метка времени Unix с микросекундами | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (Compact) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> Замечание:

> Символ "W" в форматах "Год и неделя в формате ISO" и "Год, неделя в формате ISO и день недели" чувствителен к регистру, символ "W" указывают только в верхнем регистре.

> Символ "T" в форматах SOAP, XMLRPC и WDDX также чувствителен к регистру, символ "T" указывают только в верхнем регистре.

> Формат "Unix Timestamp" устанавливает часовой пояс в UTC.

## Относительные форматы

Страница описывает относительные форматы даты и времени в BNF-подобном синтаксисе, которые понимает парсер классов DateTimeImmutable и DateTime, и функций date_create(), date_create_immutable(), strtotime().

Объекты даты и времени DateTimeImmutable и DateTime форматируют нотацией, которую описывает документация к методу DateTimeInterface::format().

Символы
Описание | Формат
--- | ---
`dayname` (название дня недели) | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` (будние дни — пн–пт, без учёта праздничных дней) | 'weekday' | 'weekdays'
`number` (числа) | [+-]?[0-9]+
`ordinal` (порядковые числительные и относительные указатели) | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` (относительные указатели) | 'next' | 'last' | 'previous' | 'this'
`space` (символы пробела и табуляции) | [ \t]+
`unit` (единицы измерения) | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Обозначения на основе дней
Формат | Описание | Примеры
--- | --- | ---
'yesterday' | Полночь вчера | "yesterday 14:00"
'midnight' | Время устанавливается в 00:00:00 |
'today' | Время устанавливается в 00:00:00 |
'now' | Текущее время |
'noon' | Время устанавливается в 12:00:00 | "yesterday noon"
'tomorrow' | Полночь завтра |
'back of' `hour` | 15 минут заданного часа | "back of 7pm", "back of 15"
'front of' `hour` | Без 15 минут заданный час | "front of 5am", "front of 23"
'first day of' | Устанавливает первый день текущего месяца. Обычно эту нотацию лучше использовать вместе с названием месяца, следующим за ней, иначе будет учитываться текущий месяц. | "first day of January 2008"
'last day of' | Устанавливает последний день текущего месяца. Обычно эту нотацию лучше использовать вместе с названием месяца, следующим за ней, иначе будет учитываться текущий месяц. | "last day of next month"
`ordinal` `space` `dayname` `space` 'of' | Вычисляет `x` день недели текущего или заданного месяца. | "first sat of July 2008"
'last' `space` `dayname` `space` 'of' | Вычисляет последний день недели текущего или заданного месяца. | "last sat of July 2008"
`number` `space`? (`unit` | 'week') | Вычисляет относительное время при использовании числовых значений периода. | "+5 weeks", "12 day", "-7 weekdays"
(`ordinal` | `reltext`) `space` `unit` | Вычисляет относительное время при использовании строковых значений периода. `last` и `previous` то же, что и `-1`, `this` ни на что не влияет, а `next` – `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Вычитает все значения из последнего полученного момента времени. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago ago"
`dayname` | Перемещается на следующий день указанного дня недели. (Смотрите замечание) | "Monday"
`reltext` `space` 'week' | Разбирает специфичный формат "weekday + last/this/next week". | "Monday next week"

> Замечание:

> Относительные выражения обрабатываются только после неотносительных. Например, "+1 week july 2008" эквивалентно "july 2008 +1 week".

> Исключение из этого правила составляют: "yesterday", "midnight", "today", "noon" и "tomorrow". Записи "tomorrow 11:00" и "11:00 tomorrow" отличаются. Если принять сегодняшнюю дату за "July 23rd, 2008", то первая запись возвращает "2008-07-24 11:00", а вторая "2008-07-24 00:00". Причина такого поведения в том, что эти пять выражений влияют непосредственно на время.

> Ключевые слова наподобие "first day of" зависят от контекста строки относительного формата. Для строк в статическом методе или функции референтом станет текущая системная метка времени, но методе DateTime::modify() или DateTimeImmutable::modify() референтом станет объект, на котором вызывается метод `modify()`.

> Замечание:

> Следует обратить внимание на следующие замечания относительно текущего дня недели и дня недели, который указали в строке даты и времени. Текущий день недели вычисляется из независимой части строки даты и времени.

> 1. "`dayname`" не сдвигает дату на другой день. (Например: "Wed July 23rd, 2008" означает "2008-07-23").
> 2. "`number` `dayname`" не сдвигает дату на другой день. (Например: "1 wednesday july 23rd, 2008" означает "2008-07-23").
> 3. "`number` week `dayname`" добавляет соответствующее число недель, но не сдвигает дату на другой день. В этом случае имеют место два различных блока "`number` week" и "`dayname`". (Например: "+1 week wednesday july 23rd, 2008" означает "2008-07-30").
> 4. "`ordinal` `dayname`" сдвигает дату на другой день. (Например: "last wednesday july 23rd, 2008" означает "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" добавляет число недель, которое соответствует символу числа, а затем сдвигает дату на другой день. В этом случае имеют место два различных блока "`number` week" и "`ordinal` `dayname`". (Например: "+1 week first wednesday july 23rd, 2008" означает "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " не сдвигает дату на другой день. (Например: "first wednesday of july 23rd, 2008" означает "2008-07-02", потому как определённые фразы с 'of' сбрасывают день месяца на '1' и в этом случае игнорируется '23rd').

> Также следует обратить внимание, что "of" в "`ordinal` `space` `dayname` `space` 'of' " и "'last' `space` `dayname` `space` 'of' " имеет особый смысл.

> 1. Устанавливает для дня месяца значение 1.
> 2. "`ordinal` `dayname` 'of' "не сдвигает дату на другой день. (Например: "first tuesday of july 2008" означает "2008-07-01").
> 3. "`ordinal` `dayname`" сдвигает дату на другой день. (Например: "first tuesday july 2008" означает "2008-07-08", смотрите также 4-й пункт предыдущего замечания).
> 4. "'last' `dayname` 'of' " получает последний в месяце `dayname`. (Например: "last wed of july 2008" означает "2008-07-30")
> 5. "'last' `dayname`" получает последний `dayname` перед текущим днём. (Например: "last wed july 2008" означает "2008-06-25"; "july 2008" устанавливает дату в "2008-07-01", а после "last wed" смещает дату к предыдущей среде, а именно к "2008-06-25").

> Замечание:

> Относительные значения в месяцах рассчитываются на основе продолжительности месяца. Например, из "+2 month 2011-11-30" получится "2012-01-30". Это связано с тем, что ноябрь состоит из 30 дней, а декабрь из 31 дня, что составляет 61 день.

> Замечание:

> Под числом (`number`) подразумевается целое число (integer); десятичная точка (или запятая) рассматривается как разделитель, если указали десятичное число. Например, `'+1.5 hours'` посчитается как `'+1 5 hours'`, а не `'+1 hour +30 minutes'`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Символы `number` теперь снова принимают последовательность знаков плюс и минус в записях наподобие `+-2`, и другие комбинации множественных знаков.
8.2.0 | Символы `number` больше не принимают последовательность знаков плюс и минус, поэтому запись наподобие `+-2` недопустима.
7.0.8 | Недели начинаются только с понедельника. Раньше разрешалось определять начало недели с воскресенья.

# Список поддерживаемых часовых поясов

## Содержание

- Африка
- Америка
- Антарктика
- Арктика
- Азия
- Атлантика
- Австралия
- Европа
- Индийский
- Тихоокеанский
- Другие

Страница содержит полный список часовых поясов, передачу которых в функции наподобие date_default_timezone_set() поддерживает PHP.

Предостережение

Поведение часовых поясов вне списка не определено.

> Замечание: Последняя версия базы данных часовых поясов устанавливается с PECL-пакетом » timezonedb.

> Замечание: Список основан на версии базы данных часовых поясов 2026.1.

## Африка

Африка
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | Africa/Bamako | Africa/Bangui | Africa/Banjul
Africa/Bissau | Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura
Africa/Cairo | Africa/Casablanca | Africa/Ceuta | Africa/Conakry
Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti | Africa/Douala
Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare
Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum
Africa/Kigali | Africa/Kinshasa | Africa/Lagos | Africa/Libreville
Africa/Lome | Africa/Luanda | Africa/Lubumbashi | Africa/Lusaka
Africa/Malabo | Africa/Maputo | Africa/Maseru | Africa/Mbabane
Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena
Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo
Africa/Sao_Tome | Africa/Tripoli | Africa/Tunis | Africa/Windhoek

## Америка

Америка
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/Cordoba
America/Argentina/Jujuy | America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos
America/Argentina/Salta | America/Argentina/San_Juan | America/Argentina/San_Luis | America/Argentina/Tucuman
America/Argentina/Ushuaia | America/Aruba | America/Asuncion | America/Atikokan
America/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | America/Costa_Rica | America/Coyhaique
America/Creston | America/Cuiaba | America/Curacao | America/Danmarkshavn
America/Dawson | America/Dawson_Creek | America/Denver | America/Detroit
America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador
America/Fort_Nelson | America/Fortaleza | America/Glace_Bay | America/Goose_Bay
America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala
America/Guayaquil | America/Guyana | America/Halifax | America/Havana
America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo
America/Indiana/Petersburg | America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes
America/Indiana/Winamac | America/Inuvik | America/Iqaluit | America/Jamaica
America/Juneau | America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk
America/La_Paz | America/Lima | America/Los_Angeles | America/Lower_Princes
America/Maceio | America/Managua | America/Manaus | America/Marigot
America/Martinique | America/Matamoros | America/Mazatlan | America/Menominee
America/Merida | America/Metlakatla | America/Mexico_City | America/Miquelon
America/Moncton | America/Monterrey | America/Montevideo | America/Montserrat
America/Nassau | America/New_York | America/Nome | America/Noronha
America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk
America/Ojinaga | America/Panama | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rankin_Inlet | America/Recife | America/Regina
America/Resolute | America/Rio_Branco | America/Santarem | America/Santiago
America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Sitka
America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia
America/St_Thomas | America/St_Vincent | America/Swift_Current | America/Tegucigalpa
America/Thule | America/Tijuana | America/Toronto | America/Tortola
America/Vancouver | America/Whitehorse | America/Winnipeg | America/Yakutat

## Антарктика

Антарктика
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## Арктика

Арктика
Arctic/Longyearbyen

## Азия

Азия
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Colombo | Asia/Damascus | Asia/Dhaka
Asia/Dili | Asia/Dubai | Asia/Dushanbe | Asia/Famagusta
Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh | Asia/Hong_Kong
Asia/Hovd | Asia/Irkutsk | Asia/Jakarta | Asia/Jayapura
Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi
Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata | Asia/Krasnoyarsk
Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macau
Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat
Asia/Nicosia | Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk
Asia/Oral | Asia/Phnom_Penh | Asia/Pontianak | Asia/Pyongyang
Asia/Qatar | Asia/Qostanay | Asia/Qyzylorda | Asia/Riyadh
Asia/Sakhalin | Asia/Samarkand | Asia/Seoul | Asia/Shanghai
Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei | Asia/Tashkent
Asia/Tbilisi | Asia/Tehran | Asia/Thimphu | Asia/Tokyo
Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi | Asia/Ust-Nera
Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk | Asia/Yangon
Asia/Yekaterinburg | Asia/Yerevan |  |

## Атлантика

Атлантика
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## Австралия

Австралия
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## Европа

Европа
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | Europe/Zurich |  |

## Индийский

Индийский
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## Тихоокеанский

Тихоокеанский
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro
Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue
Pacific/Norfolk | Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau
Pacific/Pitcairn | Pacific/Pohnpei | Pacific/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |

## Другие

Внимание

Пожалуйста, не используйте описанные здесь часовые пояса (кроме UTC), они существуют только по причинам обратной совместимости и могут привести к неправильной работе. Кроме того, часовые пояса могут быть удалены из базы данных часовых поясов IANA в любое время.

Внимание

Если игнорируете вышестоящее предупреждение, то учтите, что база данных часовых поясов IANA, которую содержит PHP, поддерживает использование POSIX-стиля знаков, поэтому обозначения часовых поясов Etc/GMT+n и Etc/GMT-n обратные общепринятым.

Например, часовой пояс, который на 8 часов опережает часовой пояс GMT, как в Китае, Западной Австралии и других местах, в действительности записан в базе данных как `Etc/GMT-8`, а не как `Etc/GMT+8`, как ожидалось.

Настоятельно рекомендуется использовать правильные часовые пояса наподобие `Asia/Shanghai` или `Australia/Perth` для приведённого примера.

Другие
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing
Asia/Chungking | Asia/Dacca | Asia/Harbin | Asia/Istanbul
Asia/Kashgar | Asia/Katmandu | Asia/Macao | Asia/Rangoon
Asia/Saigon | Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang
Asia/Ulan_Bator | Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT
Australia/Canberra | Australia/Currie | Australia/LHI | Australia/North
Australia/NSW | Australia/Queensland | Australia/South | Australia/Tasmania
Australia/Victoria | Australia/West | Australia/Yancowinna | Brazil/Acre
Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic
Canada/Central | Canada/Eastern | Canada/Mountain | Canada/Newfoundland
Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET
Chile/Continental | Chile/EasterIsland | CST6CDT | Cuba
EET | Egypt | Eire | EST
EST5EDT | Etc/GMT | Etc/GMT+0 | Etc/GMT+1
Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2
Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6
Etc/GMT+7 | Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0
Etc/GMT-1 | Etc/GMT-10 | Etc/GMT-11 | Etc/GMT-12
Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 | Etc/GMT-3
Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7
Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich
Etc/UCT | Etc/Universal | Etc/UTC | Etc/Zulu
Europe/Belfast | Europe/Kiev | Europe/Nicosia | Europe/Tiraspol
Europe/Uzhgorod | Europe/Zaporozhye | Factory | GB
GB-Eire | GMT | GMT+0 | GMT-0
GMT0 | Greenwich | Hongkong | HST
Iceland | Iran | Israel | Jamaica
Japan | Kwajalein | Libya | MET
Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST
MST7MDT | Navajo | NZ | NZ-CHAT
Pacific/Enderbury | Pacific/Johnston | Pacific/Ponape | Pacific/Samoa
Pacific/Truk | Pacific/Yap | Poland | Portugal
PRC | PST8PDT | ROC | ROK
Singapore | Turkey | UCT | Universal
US/Alaska | US/Aleutian | US/Arizona | US/Central
US/East-Indiana | US/Eastern | US/Hawaii | US/Indiana-Starke
US/Michigan | US/Mountain | US/Pacific | US/Samoa
UTC | W-SU | WET | Zulu

# Ошибка DateError

(PHP 8 >= 8.3.0)

## Введение

Ошибка возникает, если база данных часовых поясов недоступна или содержит недопустимые данные.

Ошибка возникает не из-за кода, а из-за внутренних проблем PHP. Вместо этой ошибки PHP выбрасывает две дочерние: DateObjectError, когда программист допускает ошибки, и DateRangeError, которая возникает из-за проблем с диапазоном дат.

## Обзор класса

class DateError extends Error {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Смотрите также

- DateObjectError
- DateRangeError

# Ошибка DateObjectError

(PHP 8 >= 8.3.0)

## Введение

Ошибка возникает при неправильной инициализации классов даты или времени.

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

## Обзор класса

class DateObjectError extends DateError {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Смотрите также

- DateError
- DateRangeError

# Ошибка DateRangeError

(PHP 8 >= 8.3.0)

## Введение

Ошибка возникает на 32-битных платформах в методах DateTime::getTimestamp(), DateTimeImmutable::getTimestamp() и функции date_timestamp_get(), если объект даты представляет дату за пределами 32-битного знакового диапазона.

## Обзор класса

class DateRangeError extends DateError {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Смотрите также

- DateError
- DateObjectError

# Класс DateException

(PHP 8 >= 8.3.0)

## Введение

Родительский класс исключений даты/времени для проблем, которые возникают из-за ошибок программиста или при проверке текстовых аргументов свободной формы (пользовательского ввода).

Модулем выбрасываются следующие дочерние исключения:

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## Обзор класса

class DateException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс DateInvalidOperationException

(PHP 8 >= 8.3.0)

## Введение

Выбрасывается методами DateTimeImmutable::sub() и DateTime::sub() при попытке выполнения неподдерживаемой операции.

Пример такой неподдерживаемой операции — это попытка отнять хранящийся в объекте DateInterval временной интервал вроде `next weekday` («следующий будний день» — англ.), представляющий относительную характеристику времени, поскольку невозможно построить обратное логическое утверждение.

## Обзор класса

class DateInvalidOperationException extends DateException {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс DateInvalidTimeZoneException

(PHP 8 >= 8.3.0)

## Введение

Выбрасывается при передаче в метод DateTimeZone::__construct() неверного значения.

## Обзор класса

class DateInvalidTimeZoneException extends DateException {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс DateMalformedIntervalStringException

(PHP 8 >= 8.3.0)

## Введение

Выбрасывается при передаче в параметр `duration` метода DateInterval::__construct() недопустимого аргумента.

## Обзор класса

class DateMalformedIntervalStringException extends DateException {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс DateMalformedPeriodStringException

(PHP 8 >= 8.3.0)

## Введение

Выбрасывается при передаче в параметр `isostr` метода DatePeriod::__construct() недопустимого аргумента.

## Обзор класса

class DateMalformedPeriodStringException extends DateException {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс DateMalformedStringException

(PHP 8 >= 8.3.0)

## Введение

Выбрасывается при обнаружении недопустимой строки даты/времени.

Строка даты/времени может передаваться в качестве значения аргумента в методы DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct() или DateTime::modify().

## Обзор класса

class DateMalformedStringException extends DateException {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Примеры
  - Арифметика даты/времени
- DateTime — Класс DateTime
  - DateTime::add — Изменяет объект DateTime, добавляя количество дней, месяцев, лет, часов, минут и секунд
  - DateTime::__construct — Конструктор класса DateTime
  - DateTime::createFromFormat — Разбирает строку времени по заданному формату
  - DateTime::createFromImmutable — Создаёт новый объект DateTime на основе объекта DateTimeImmutable
  - DateTime::createFromInterface — Создаёт новый объект DateTime на основе объекта, совместимого с интерфейсом DateTimeInterface
  - DateTime::createFromTimestamp — Создаёт экземпляр из метки времени Unix
  - DateTime::getLastErrors — Псевдоним DateTimeImmutable::getLastErrors
  - DateTime::modify — Изменяет метку времени
  - DateTime::__set_state — Обработчик __set_state
  - DateTime::setDate — Устанавливает дату
  - DateTime::setISODate — Устанавливает дату в формате ISO
  - DateTime::setMicrosecond — Устанавливает микросекундную часть времени
  - DateTime::setTime — Устанавливает время
  - DateTime::setTimestamp — Устанавливает дату и время на основе метки времени Unix
  - DateTime::setTimezone — Устанавливает часовой пояс для объекта DateTime
  - DateTime::sub — Вычитает дни, месяцы, годы, часы, минуты и секунды из объекта DateTime
- DateTimeImmutable — Класс DateTimeImmutable
  - DateTimeImmutable::add — Возвращает новый объект с добавленным количеством дней, месяцев, лет, часов, минут и секунд
  - DateTimeImmutable::__construct — Возвращает новый объект DateTimeImmutable
  - DateTimeImmutable::createFromFormat — Разбирает строку времени по заданному формату
  - DateTimeImmutable::createFromInterface — Создаёт новый объект DateTimeImmutable на основе объекта, совместимого с интерфейсом DateTimeInterface
  - DateTimeImmutable::createFromMutable — Создаёт новый объект DateTimeImmutable на основе объекта DateTime
  - DateTimeImmutable::createFromTimestamp — Создаёт экземпляр из метки времени Unix
  - DateTimeImmutable::getLastErrors — Возвращает предупреждения и ошибки
  - DateTimeImmutable::modify — Создаёт новый объект с изменённой временной меткой
  - DateTimeImmutable::__set_state — Обработчик метода __set_state
  - DateTimeImmutable::setDate — Устанавливает дату
  - DateTimeImmutable::setISODate — Устанавливает дату в формате ISO
  - DateTimeImmutable::setMicrosecond — Устанавливает микросекундную часть времени
  - DateTimeImmutable::setTime — Устанавливает время
  - DateTimeImmutable::setTimestamp — Устанавливает дату и время на основе метки времени Unix
  - DateTimeImmutable::setTimezone — Устанавливает часовой пояс
  - DateTimeImmutable::sub — Вычитает заданное количество дней, месяцев, лет, часов, минут и секунд
- DateTimeInterface — Интерфейс DateTimeInterface
  - DateTimeInterface::diff — Возвращает разницу между двумя объектами даты и времени
  - DateTimeInterface::format — Форматирует дату в заданном формате
  - DateTimeInterface::getMicrosecond — Получает микросекундную часть метки времени Unix
  - DateTimeInterface::getOffset — Возвращает смещение часового пояса
  - DateTimeInterface::getTimestamp — Возвращает метку времени с начала эпохи Unix
  - DateTimeInterface::getTimezone — Возвращает часовой пояс объекта даты и времени
  - DateTime::__serialize — Подготавливает данные объекта даты и времени для сериализации
  - DateTime::__unserialize — Подготавливает данные для восстановления объекта даты и времени при десериализации
  - DateTime::__wakeup — Обрабатывает событие __wakeup
- DateTimeZone — Класс DateTimeZone
  - DateTimeZone::__construct — Создаёт новый объект DateTimeZone
  - DateTimeZone::getLocation — Возвращает информацию о местоположении для часового пояса
  - DateTimeZone::getName — Возвращает имя часового пояса
  - DateTimeZone::getOffset — Возвращает смещение времени часового пояса относительно времени UTC
  - DateTimeZone::getTransitions — Возвращает информацию о переходах времени для часового пояса
  - DateTimeZone::listAbbreviations — Возвращает ассоциативный массив с флагами перехода на летнее время, смещениями и названиями часовых поясов
  - DateTimeZone::listIdentifiers — Возвращает индексный массив идентификаторов часовых поясов
- DateInterval — Класс DateInterval
  - DateInterval::__construct — Создаёт новый объект DateInterval
  - DateInterval::createFromDateString — Создаёт объект DateInterval из строки с обозначениями времени в относительном формате
  - DateInterval::format — Форматирует интервал
- DatePeriod — Класс DatePeriod
  - DatePeriod::__construct — Инициализирует новый экземпляр класса DatePeriod
  - DatePeriod::createFromISO8601String — Создаёт новый объект DatePeriod из строки в формате стандарта ISO8601
  - DatePeriod::getDateInterval — Возвращает временной интервал
  - DatePeriod::getEndDate — Возвращает конечную дату периода
  - DatePeriod::getRecurrences — Получает количество повторений
  - DatePeriod::getStartDate — Возвращает начальную дату периода
- Функции даты и времени
  - checkdate — Проверяет корректность даты по григорианскому календарю
  - date — Форматирует метку времени эпохи Unix
  - date_add — Псевдоним DateTime::add
  - date_create — Создаёт новый объект DateTime
  - date_create_from_format — Псевдоним DateTime::createFromFormat
  - date_create_immutable — Создаёт новый объект DateTimeImmutable
  - date_create_immutable_from_format — Псевдоним DateTimeImmutable::createFromFormat
  - date_date_set — Псевдоним DateTime::setDate
  - date_default_timezone_get — Возвращает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
  - date_default_timezone_set — Устанавливает часовой пояс по умолчанию для функций работы с датой и временем в скрипте
  - date_diff — Псевдоним DateTime::diff
  - date_format — Псевдоним DateTime::format
  - date_get_last_errors — Псевдоним DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — Псевдоним DateInterval::createFromDateString
  - date_interval_format — Псевдоним DateInterval::format
  - date_isodate_set — Псевдоним DateTime::setISODate
  - date_modify — Псевдоним DateTime::modify
  - date_offset_get — Псевдоним DateTime::getOffset
  - date_parse — Возвращает ассоциативный массив с подробной информацией о заданной дате/времени
  - date_parse_from_format — Разбирает строку с датой по заданному формату
  - date_sub — Псевдоним DateTime::sub
  - date_sun_info — Возвращает массив с информацией о закате и восходе Солнца, и начале и окончании сумерек
  - date_sunrise — Возвращает время рассвета для заданных дня и местоположения
  - date_sunset — Возвращает время захода солнца для заданных дня и расположения
  - date_time_set — Псевдоним DateTime::setTime
  - date_timestamp_get — Псевдоним DateTime::getTimestamp
  - date_timestamp_set — Псевдоним DateTime::setTimestamp
  - date_timezone_get — Псевдоним DateTime::getTimezone
  - date_timezone_set — Псевдоним DateTime::setTimezone
  - getdate — Возвращает информацию о дате и времени
  - gettimeofday — Возвращает текущее время
  - gmdate — Форматирует дату и время как время UTC
  - gmmktime — Получает метку Unix-времени для времени UTC
  - gmstrftime — Форматирует дату и время как время UTC с учётом региональных настроек
  - idate — Форматирует компонент даты или времени местного часового пояса как целое число
  - localtime — Получает местное время
  - microtime — Возвращает текущую метку времени Unix с микросекундами
  - mktime — Получает метку Unix-времени для даты
  - strftime — Форматирует местную дату и время с учётом региональных настроек
  - strptime — Разбирает строку даты и времени, которую сгенерировала функция strftime
  - strtotime — Преобразовывает текстовое представление даты на английском языке в метку времени Unix
  - time — Возвращает метку времени Unix на основе текущего системного времени
  - timezone_abbreviations_list — Псевдоним DateTimeZone::listAbbreviations
  - timezone_identifiers_list — Псевдоним DateTimeZone::listIdentifiers
  - timezone_location_get — Псевдоним DateTimeZone::getLocation
  - timezone_name_from_abbr — Возвращает название часового пояса, угадывая по аббревиатуре и смещению UTC
  - timezone_name_get — Псевдоним DateTimeZone::getName
  - timezone_offset_get — Псевдоним DateTimeZone::getOffset
  - timezone_open — Псевдоним DateTimeZone::__construct
  - timezone_transitions_get — Псевдоним DateTimeZone::getTransitions
  - timezone_version_get — Получает номер версии базы данных часовых поясов
- Ошибки и исключения даты и времени
- Допустимые форматы даты и времени
- Список поддерживаемых часовых поясов
  - Африка
  - Америка
  - Антарктика
  - Арктика
  - Азия
  - Атлантика
  - Австралия
  - Европа
  - Индийский
  - Тихоокеанский
  - Другие
- DateError — Ошибка DateError
- DateObjectError — Ошибка DateObjectError
- DateRangeError — Ошибка DateRangeError
- DateException — Класс DateException
- DateInvalidOperationException — Класс DateInvalidOperationException
- DateInvalidTimeZoneException — Класс DateInvalidTimeZoneException
- DateMalformedIntervalStringException — Класс DateMalformedIntervalStringException
- DateMalformedPeriodStringException — Класс DateMalformedPeriodStringException
- DateMalformedStringException — Класс DateMalformedStringException

# Модуль работы со временем высокого разрешения

# Введение

Модуль HRTime реализует класс StopWatch, который работает со временем с высокой точностью. Класс работает с лучшими из доступных на платформах API-интерфейсами, что помогает оперировать временем с точностью до наносекунд. Класс также делает доступной пользовательскую реализацию секундомера на основе низкоуровневых тактов API-интерфейса нижележащего уровня.

> Замечание: Начиная с PHP 7.3.0 функцию hrtime(), которая связана с высокоточным временем, включили в ядро PHP.

# Установка и настройка

## Содержание

- Установка

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/hrtime.

# Примеры

## Содержание

- Основы использования

## Основы использования

Этот пример демонстрирует базовое использование класса StopWatch

Пример #1 Замеряем время исполнения нескольких блоков кода

    <?php

    $c = new HRTime\StopWatch;

    $c->start();
    /* Замеряем время выполнения этого блока кода */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    /* Тут не замеряем*/
    for ($i = 0; $i < 1024*1024; $i++);

    $c->start();
    /* А тут снова замеряем время выполнения этого блока кода */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    $elapsed_total = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

    ?>

# Класс HRTime\PerformanceCounter

(PECL hrtime >= 0.4.3)

## Введение

## Обзор класса

class HRTime\PerformanceCounter {
/* Методы */
public static function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Частота таймера в тиках в секунду

### Описание

public static function HRTime\PerformanceCounter::getFrequency(): int

Возвращает частоту таймера в тиках в секунду. Это будет постоянным значением после старта системы для большинства операционных систем.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число (int), равное частоте таймера.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Текущее значение тиков системы

### Описание

public static function HRTime\PerformanceCounter::getTicks(): int

Возвращает количество тиков.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число (int), равное количеству тиков.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Количество тиков, прошедших с заданного значения

### Описание

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Возвращает тиков, прошедших с заданного начального значения.

### Список параметров

`start`
  Начальное значение.

### Возвращаемые значения

Возвращает целое число (int), равное количеству тиков.

## Содержание

- HRTime\PerformanceCounter::getFrequency — Частота таймера в тиках в секунду
- HRTime\PerformanceCounter::getTicks — Текущее значение тиков системы
- HRTime\PerformanceCounter::getTicksSince — Количество тиков, прошедших с заданного значения

# Класс HRTime\StopWatch

(PECL hrtime >= 0.4.3)

## Введение

## Обзор класса

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* Методы */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* Наследуемые методы */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Получает количество времени, которое прошло для всех интервалов

### Описание

public function HRTime\StopWatch::getElapsedTicks(): int

Метод возвращает количество тиков, которые прошли для всех ранее закрытых интервалов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает целое число (int), которое указывает прошедшие тики.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Получить суммарное прошедшее время всех интервалов

### Описание

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Возвращает суммарное прошедшее время всех интервалов.

### Список параметров

`unit`
  Единица времени, заданная одной из констант HRTime\Unit. По умолчанию HRTime\Unit::SECOND.

### Возвращаемые значения

Возвращает значение типа float, равное прошедшему времени.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Получить количество прошедших тиков за последний интервал

### Описание

public function HRTime\StopWatch::getLastElapsedTicks(): int

Возвращает количество прошедших тиков за последний закрытый интервал.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, указывающее прошедшие тики.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Получить прошедшее время для последнего интервала

### Описание

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Возвращает прошедшее время для ранее закрытого интервала.

### Список параметров

`unit`
  Единица времени, заданная одной из констант HRTime\Unit. По умолчанию HRTime\Unit::SECOND.

### Возвращаемые значения

Возвращает значение типа float, равное прошедшему времени.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Проверить, выполняется ли измерение

### Описание

public function HRTime\StopWatch::isRunning(): bool

Проверяет, было ли начато измерение.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true` или `false`, в зависимости от того, запущено ли измерение в текущий момент.

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Запустить измерение времени

### Описание

public function HRTime\StopWatch::start(): void

Запускает измерение времени. Если оно уже было запущено ранее, то ничего не произойдёт. Измерение будет продолжено, если оно ранее было остановлено.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Ничего не возвращает.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Остановить измерение

### Описание

public function HRTime\StopWatch::stop(): void

Останавливает измерение для ранее запущенного интервала.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Ничего не возвращает.

## Содержание

- HRTime\StopWatch::getElapsedTicks — Получает количество времени, которое прошло для всех интервалов
- HRTime\StopWatch::getElapsedTime — Получить суммарное прошедшее время всех интервалов
- HRTime\StopWatch::getLastElapsedTicks — Получить количество прошедших тиков за последний интервал
- HRTime\StopWatch::getLastElapsedTime — Получить прошедшее время для последнего интервала
- HRTime\StopWatch::isRunning — Проверить, выполняется ли измерение
- HRTime\StopWatch::start — Запустить измерение времени
- HRTime\StopWatch::stop — Остановить измерение

# Класс HRTime\Unit

(PECL hrtime >= 0.4.3)

## Введение

## Обзор класса

class HRTime\Unit {
/* Константы */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* Методы */
}

## Предопределённые константы

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- Установка и настройка
  - Установка
- Примеры
  - Основы использования
- HRTime\PerformanceCounter — Класс HRTime\PerformanceCounter
  - HRTime\PerformanceCounter::getFrequency — Частота таймера в тиках в секунду
  - HRTime\PerformanceCounter::getTicks — Текущее значение тиков системы
  - HRTime\PerformanceCounter::getTicksSince — Количество тиков, прошедших с заданного значения
- HRTime\StopWatch — Класс HRTime\StopWatch
  - HRTime\StopWatch::getElapsedTicks — Получает количество времени, которое прошло для всех интервалов
  - HRTime\StopWatch::getElapsedTime — Получить суммарное прошедшее время всех интервалов
  - HRTime\StopWatch::getLastElapsedTicks — Получить количество прошедших тиков за последний интервал
  - HRTime\StopWatch::getLastElapsedTime — Получить прошедшее время для последнего интервала
  - HRTime\StopWatch::isRunning — Проверить, выполняется ли измерение
  - HRTime\StopWatch::start — Запустить измерение времени
  - HRTime\StopWatch::stop — Остановить измерение
- HRTime\Unit — Класс HRTime\Unit

- Календарь
  - Установка и настройка
  - Предопределённые константы
  - Календарь
- Дата и время — Модуль работы с датой и временем
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - DateTime — Класс DateTime
  - DateTimeImmutable — Класс DateTimeImmutable
  - DateTimeInterface — Интерфейс DateTimeInterface
  - DateTimeZone — Класс DateTimeZone
  - DateInterval — Класс DateInterval
  - DatePeriod — Класс DatePeriod
  - Функции даты и времени
  - Ошибки и исключения даты и времени
  - Допустимые форматы даты и времени
  - Список поддерживаемых часовых поясов
  - DateError — Ошибка DateError
  - DateObjectError — Ошибка DateObjectError
  - DateRangeError — Ошибка DateRangeError
  - DateException — Класс DateException
  - DateInvalidOperationException — Класс DateInvalidOperationException
  - DateInvalidTimeZoneException — Класс DateInvalidTimeZoneException
  - DateMalformedIntervalStringException — Класс DateMalformedIntervalStringException
  - DateMalformedPeriodStringException — Класс DateMalformedPeriodStringException
  - DateMalformedStringException — Класс DateMalformedStringException
- HRTime — Модуль работы со временем высокого разрешения
  - Установка и настройка
  - Примеры
  - HRTime\PerformanceCounter — Класс HRTime\PerformanceCounter
  - HRTime\StopWatch — Класс HRTime\StopWatch
  - HRTime\Unit — Класс HRTime\Unit

# Модули для работы с файловой системой

# Прямой ввод/вывод (Direct IO)

# Введение

PHP поддерживает функции прямого ввода/вывода, как описано в стандарте Posix (секция 6), для вызова функций ввода/вывода на более низком уровне нежели потоковые функции языка C (fopen(), fread(),..). Эти функции могут быть задействованы только если необходим прямой контроль устройств. Во всех остальных случаях более адекватно будет использовать стандартные функции файловой системы.

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/dio.

## Типы ресурсов

Модуль определяет один тип ресурса: дескриптор файла, который возвращает функция dio_open().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`F_DUPFD` (int)

`F_GETFD` (int)

`F_GETFL` (int)

`F_GETLK` (int)

`F_GETOWN` (int)

`F_RDLCK` (int)

`F_SETFL` (int)

`F_SETLK` (int)

`F_SETLKW` (int)

`F_SETOWN` (int)

`F_UNLCK` (int)

`F_WRLCK` (int)

`O_APPEND` (int)

`O_ASYNC` (int)

`O_CREAT` (int)

`O_EXCL` (int)

`O_NDELAY` (int)

`O_NOCTTY` (int)

`O_NONBLOCK` (int)

`O_RDONLY` (int)

`O_RDWR` (int)

`O_SYNC` (int)

`O_TRUNC` (int)

`O_WRONLY` (int)

`S_IRGRP` (int)

`S_IROTH` (int)

`S_IRUSR` (int)

`S_IRWXG` (int)

`S_IRWXO` (int)

`S_IRWXU` (int)

`S_IWGRP` (int)

`S_IWOTH` (int)

`S_IWUSR` (int)

`S_IXGRP` (int)

`S_IXOTH` (int)

`S_IXUSR` (int)

# Функции прямого ввода/вывода

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — Закрыть файловый дескриптор

### Описание

function dio_close(resource `$fd`): void

Функция dio_close() закрывает файловый дескриптор `fd`.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Закрытие файлового дескриптора

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### Смотрите также

- dio_open() - Открывает или создаёт файл на уровне ниже, чем потоковые функции ввода-вывода библиотеки языка C

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — Вызывает функцию библиотеки C fcntl для файлового дескриптора

### Описание

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

Функция dio_fcntl() вызывает указанную в `cmd` команду для `fd`. Если команда требует дополнительных аргументов, то они задаются в `args`.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

`cmd`

  Может быть одной из следующих операций:

  - `F_SETLK` - Установка или сброс блокировки. Если блокировка кем-либо удерживается, dio_fcntl() вернёт -1.

  - `F_SETLKW` - похожа на `F_SETLK`, но если блокировка кем-либо удерживается, dio_fcntl() будет ждать её освобождения.

  - `F_GETLK` - dio_fcntl() вернёт ассоциативный массив (как описано ниже) если кто-либо мешает получить блокировку. Если никто не мешает, то ключ "type" будет содержать `F_UNLCK`.

  - `F_DUPFD` - ищет наименьший доступный файловый дескриптор, больший или равный `args` и возвращает его.

  - `F_SETFL` - устанавливает файловому дескриптору флаги, заданные в `args`, такие как `O_APPEND`, `O_NONBLOCK` или `O_ASYNC`. Для использования `O_ASYNC` вам необходимо воспользоваться модулем PCNTL.

`args`

  `args` - это ассоциативный массив, если `cmd` установлен в `F_SETLK` или `F_SETLKW`, со следующими ключами:

  - `start` - смещение на начало блокировки

  - `length` - размер заблокированной зоны. 0 означает конец файла

  - `whence` - зависит от l_start: может быть `SEEK_SET`, `SEEK_END` и `SEEK_CUR`

  - `type` - тип блокировки: может быть `F_RDLCK` (чтение), `F_WRLCK` (запись) или `F_UNLCK` (блокировки нет)

### Возвращаемые значения

Возвращает результат вызова C-функции.

### Примеры

Пример #1 Установка и снятие блокировки

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
       // дескриптор файла заблокирован
       echo "Нельзя снять блокировку, она удерживается другим процессом.";
    } else {
       echo "Блокировка успешно установлена/снята";
    }

    dio_close($fd);
    ?>

### Примечания

> Замечание: Для Windows-платформ функцию не реализовали.

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — Открывает или создаёт файл на уровне ниже, чем потоковые функции ввода-вывода библиотеки языка C

### Описание

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

Функция dio_open() открывает файл и возвращает файловый дескриптор.

### Список параметров

`filename`

  Путь к файлу, который требуется открыть.

`flags`

  Параметр `flags` принимает объединённую побитовым оператором ИЛИ комбинацию следующих флагов. В комбинацию обязательно включают константу `O_RDONLY`, `O_WRONLY` или `O_RDWR` и дополнительно указывают произвольную комбинацию других флагов из списка.

  - `O_RDONLY` — открыть файл на чтение.

  - `O_WRONLY` — открыть файл на запись.

  - `O_RDWR` — открыть файл на чтение и запись.

  - `O_CREAT` — создать файл, если не существует.

  - `O_EXCL` — функция dio_open() выдаст ошибку, если установили флаги `O_CREAT` и `O_EXCL`, и файл существует.

  - `O_TRUNC` — при открытии существующего файла на запись функция усечёт файл до нулевой длины.

  - `O_APPEND` — запись в конец файла.

  - `O_NONBLOCK` — установить неблокирующий режим.

  - `O_NOCTTY` — запрещает операционной системе назначать открытый файл как терминал контроля процесса, если открыли файл устройства TTY.

`mode`

  При передаче в параметр `flags` значения `O_CREAT` параметр `mode` установит для файла права доступа с учётом системных ограничений на установку прав для вновь создаваемых файлов. Параметр `mode` требуется для правильной работы функции при передаче в параметр `flags` значения `O_CREAT`, а в остальных случаях игнорируется.

  Фактические разрешения, которые назначаются вновь созданному файлу, стандартно зависят от настройки маски прав доступа umask для процесса.

### Возвращаемые значения

Функция возвращает дескриптор файла или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример открытия файлового дескриптора

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);

### Смотрите также

- dio_close() - Закрыть файловый дескриптор

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — Прочитай байты из файлового дескриптора

### Описание

function dio_read(resource `$fd`, int `$len` = 1024): string

Функция dio_read() читает и возвращает `len` байт из дескриптора `fd`.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

`len`

  Количество байт для чтения. Если не задано, то dio_read() прочитает блок в 1 килобайт.

### Возвращаемые значения

Байты будут читаться из `fd`.

### Смотрите также

- dio_write() - Записывает байты в файл, опционально обрезая до указанной длины

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — Переместить указатель в файловом дескрипторе

### Описание

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

Функция dio_seek() используется для изменения указателя внутри файла.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

`pos`

  Новая позиция.

`whence`

  Указывает, как надо интерпретировать `pos`:

  - `SEEK_SET` (по умолчанию) - указывает, что `pos` отсчитывается от начала файла.

  - `SEEK_CUR` - указывает, что `pos` отсчитывается от текущей позиции. Может быть отрицательным.

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

### Возвращаемые значения

### Примеры

Пример #1 Позиционирование внутри файла

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // Текущая позиция - 10 байт от начала

    dio_seek($fd, -2, SEEK_CUR);
    // Текущая позиция - 8 байт от начала

    dio_seek($fd, -5, SEEK_END);
    // Текущая позиция - 5 байт от конца

    dio_seek($fd, 10, SEEK_END);
    // Текущая позиция - 10 байт дальше конца файла
    // 10 байт от конца файла до текущей позиции заполнены нулями

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — Получить информацию о файловом дескрипторе

### Описание

function dio_stat(resource `$fd`): array

dio_stat() возвращает информацию о заданном дескрипторе.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

### Возвращаемые значения

Возвращает ассоциативный массив с такими ключами:

- "device" - устройство

- "inode" - inode

- "mode" - права доступа

- "nlink" - количество жёстких ссылок

- "uid" - идентификатор пользователя

- "gid" - идентификатор группы

- "device_type" - тип устройства (если оно inode)

- "size" - размер в байтах

- "blocksize" - размер блока

- "blocks" - число выделенных блоков

- "atime" - время последнего доступа

- "mtime" - время последней модификации

- "ctime" - время последнего изменения

В случае возникновения ошибки dio_stat() вернёт `null`.

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — Устанавливает атрибуты терминала и скорость передачи данных для последовательного порта

### Описание

function dio_tcsetattr(resource `$fd`, array `$options`): bool

Функция dio_tcsetattr() устанавливает атрибуты терминала и скорость передачи данных последовательного порта для дескриптора `fd`.

### Список параметров

`fd`

  Файловый дескриптор, который вернула функция dio_open().

`options`

  Доступные опции:

  - 'baud' — скорость передачи для последовательного порта: 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75 или 50. Значение по умолчанию равно 9600.

  - 'bits' — биты данных: 8, 7, 6 или 5. Значение по умолчанию равно 8.

  - 'stop' — стоп-биты: 1 или 2. Значение по умолчанию равно 1.

  - 'parity' — парность: 0, 1 или 2. Значение по умолчанию равно 0.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример установки скорости передачи для последовательного порта

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_fcntl($fd, F_SETFL, O_SYNC);

    dio_tcsetattr($fd, array(
        'baud' => 9600,
        'bits' => 8,
        'stop'  => 1,
        'parity' => 0
    ));

    while (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $data !== '') {
            echo $data;
        }
    }

    ?>

### Примечания

> Замечание: Для Windows-платформ функцию не реализовали.

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — Обрезает файл до заданного количества байт

### Описание

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() обрезает файл до `offset` байт.

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

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

`offset`

  Смещение в байтах.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примечания

> Замечание: Для Windows-платформ функцию не реализовали.

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — Записывает байты в файл, опционально обрезая до указанной длины

### Описание

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

dio_write() записывает максимум `len` байт из `data` в файл `fd`.

### Список параметров

`fd`

  Файловый дескриптор, полученный из dio_open().

`data`

  Записываемые данные.

`len`

  Длина записываемых данных в байтах. Если не задано, то будут записаны все переданные данные.

### Возвращаемые значения

Возвращает количество байт, записанных в `fd`.

### Смотрите также

- dio_read() - Прочитай байты из файлового дескриптора

## Содержание

- dio_close — Закрыть файловый дескриптор
- dio_fcntl — Вызывает функцию библиотеки C fcntl для файлового дескриптора
- dio_open — Открывает или создаёт файл на уровне ниже, чем потоковые функции ввода-вывода библиотеки языка C
- dio_read — Прочитай байты из файлового дескриптора
- dio_seek — Переместить указатель в файловом дескрипторе
- dio_stat — Получить информацию о файловом дескрипторе
- dio_tcsetattr — Устанавливает атрибуты терминала и скорость передачи данных для последовательного порта
- dio_truncate — Обрезает файл до заданного количества байт
- dio_write — Записывает байты в файл, опционально обрезая до указанной длины

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Функции прямого ввода/вывода
  - dio_close — Закрыть файловый дескриптор
  - dio_fcntl — Вызывает функцию библиотеки C fcntl для файлового дескриптора
  - dio_open — Открывает или создаёт файл на уровне ниже, чем потоковые функции ввода-вывода библиотеки языка C
  - dio_read — Прочитай байты из файлового дескриптора
  - dio_seek — Переместить указатель в файловом дескрипторе
  - dio_stat — Получить информацию о файловом дескрипторе
  - dio_tcsetattr — Устанавливает атрибуты терминала и скорость передачи данных для последовательного порта
  - dio_truncate — Обрезает файл до заданного количества байт
  - dio_write — Записывает байты в файл, опционально обрезая до указанной длины

# Каталоги

# Предопределённые константы

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Точка с запятой в Windows, двоеточие в других системах.
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# Класс Directory

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

## Введение

Экземпляры класса Directory создаются при помощи вызова функции dir(), а не при помощи оператора new.

## Обзор класса

final class Directory {
/* Свойства */
public readonly string $path;
public readonly resource $handle;
/* Методы */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## Свойства

path

  Каталог, который был открыт.

handle

  Может быть использовано с другими функциями каталогов, такими, как readdir(), rewinddir() и closedir().

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Класс теперь является окончательным.
8.1.0 | Свойства path и handle теперь доступны только для чтения.

# Directory::close

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

Directory::close — Закрывает дескриптор каталога

### Описание

public function Directory::close(): void

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры не принимаются. Раньше в качестве аргумента можно было передать дескриптор каталога.

# Directory::read

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

Directory::read — Получает элемент из дескриптора каталога

### Описание

public function Directory::read(): string|false

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры не принимаются. Раньше в качестве аргумента можно было передать дескриптор каталога.

# Directory::rewind

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

Directory::rewind — Перемещает дескриптор каталога в начало каталога

### Описание

public function Directory::rewind(): void

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры не принимаются. Раньше в качестве аргумента можно было передать дескриптор каталога.

## Содержание

- Directory::close — Закрывает дескриптор каталога
- Directory::read — Получает элемент из дескриптора каталога
- Directory::rewind — Перемещает дескриптор каталога в начало каталога

# Функции для работы с каталогами

# Смотрите также

За описанием сопутствующих функций, таких как dirname(), is_dir(), mkdir() и rmdir(), обратитесь к главе Файловая система.

# chdir

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

chdir — Изменяет рабочий каталог

### Описание

function chdir(string `$directory`): bool

Функция изменяет текущий рабочий каталог PHP на каталог `directory`.

### Список параметров

`directory`

  Новый текущий каталог.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

В случае неудачного выполнения функция выдаёт ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции chdir()

    <?php

    // Текущий рабочий каталог
    echo getcwd() . "\n";

    chdir('public_html');

    // Текущий рабочий каталог
    echo getcwd() . "\n";

    ?>

Вывод приведённого примера будет похож на:

    /home/vincent
    /home/vincent/public_html

### Примечания

Предостережение

Операционная система не заметит изменений в текущем каталоге, которые сделали через функцию chdir(), если PHP-интерпретатор собрали с поддержкой потокобезопасного режима ZTS (Zend Thread Safety). Все встроенные PHP-функции по-прежнему будут учитывать изменения в текущем каталоге; это не относится к вызываемым функциям внешних библиотек, которые подключили через модуль FFI. Собрали ли PHP с поддержкой ZTS, покажет команда php -i или встроенная константа `PHP_ZTS`.

### Смотрите также

- getcwd() - Получает текущую рабочую директорию

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — Изменяет корневой каталог

### Описание

function chroot(string `$directory`): bool

Функция изменяет корневой каталог текущего процесса на каталог, который указали в параметре `directory`, и изменяет текущий каталог на «/».

Функция доступна только на системах GNU и BSD и только при работе через CLI, CGI или Embed SAPI. Кроме того, функция требует прав суперпользователя.

Вызов функции не изменяет значения магических констант `__DIR__` и `__FILE__`.

### Список параметров

`directory`

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции chroot()

    <?php

    chroot("/path/to/your/chroot/");
    echo getcwd();

    ?>

Результат выполнения приведённого примера:

    /

### Примечания

> Замечание: Для Windows-платформ функцию не реализовали.

> Замечание: Функция недоступна в PHP-интерпретаторах, которые собрали с поддержкой ZTS (англ. Zend Thread Safety — потокобезопасность движка Zend). Команда php -i или встроенная константа `PHP_ZTS` указывает, собрали ли PHP с поддержкой ZTS.

# closedir

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

closedir — Закрывает дескриптор каталога

### Описание

function closedir(?resource `$dir_handle` = `null`): void

Закрывает поток, связанный с каталогом и переданный в качестве параметра `dir_handle`.

### Список параметров

`dir_handle`
  Дескриптор каталога (resource), ранее открытый с помощью opendir(). Если дескриптор каталога не указан, используется последний дескриптор, открытый функцией opendir().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Использование `null` для параметра `dir_handle` теперь не рекомендуется. Вместо этого следует явно указать последний открытый дескриптор каталога.
8.0.0 | Параметр `dir_handle` теперь допускает значение `null`.

### Примеры

Примеры смотрите в документации функции opendir().

### Смотрите также

- opendir() - Открывает дескриптор каталога
- readdir() - Получает элемент каталога по его дескриптору
- rewinddir() - Сбросить дескриптор каталога
- dir() - Возвращает экземпляр класса Directory
- is_dir() - Определяет, указывает ли путь на каталог
- glob() - Находит файловые пути, которые совпадают с шаблоном
- scandir() - Получает список файлов и каталогов, расположенных по указанному пути

# dir

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

dir — Возвращает экземпляр класса Directory

### Описание

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

Псевдо-объектно-ориентированный механизм для чтения каталога. Открывается переданный в параметре `directory` каталог.

### Список параметров

`directory`

  Каталог для открытия

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Возвращает экземпляр класса Directory или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` теперь допускает значение null.

### Примеры

Пример #1 Пример использования dir()

Обратите внимание на способ, которым осуществляется проверка значения, возвращаемого Directory::read() в примере, приведённом ниже. В этом примере явно проводится проверка значения на идентичность (выражения идентичны, когда они равны и являются одного типа - за более подробной информацией обратитесь к главе Операторы сравнения) значению `false`, поскольку в ином случае, любой элемент каталога, чьё имя может быть выражено как `false`, остановит цикл.

    <?php
    $d = dir("/etc/php5");
    echo "Дескриптор: " . $d->handle . "\n";
    echo "Путь: " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

Вывод приведённого примера будет похож на:

    Дескриптор: Resource id #2
    Путь: /etc/php5
    .
    ..
    apache
    cgi
    cli

### Примечания

> Замечание:

> Порядок, в котором метод "read" возвращает элементы каталога, зависит от операционной системы.

# getcwd

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

getcwd — Получает текущую рабочую директорию

### Описание

function getcwd(): string|false

Функция возвращает путь к текущему рабочему каталогу.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает путь к текущему рабочему каталогу, если выполнилась успешно, или значение `false`, если возникла ошибка.

На отдельных Unix-платформах функция getcwd() вернёт значение `false`, если на каком-либо из родительских каталогов не установили режим чтения или поиска, даже если режим установили на текущем каталоге. Подробнее о режимах доступа рассказывает описание функции chmod().

### Примеры

Пример #1 Пример получения пути к текущему рабочему каталогу функцией getcwd()

    <?php

    // Текущий каталог
    echo getcwd() . "\n";

    chdir('cvs');

    // Текущий каталог
    echo getcwd() . "\n";

Вывод приведённого примера будет похож на:

    /home/didou
    /home/didou/cvs

### Примечания

Предостережение

Текущий рабочий каталог, который возвращает функция getcwd(), иногда отличается от каталога, который возвращают интерфейсы операционной системы, если PHP-интерпретатор собрали с поддержкой потокобезопасного режима ZTS (англ. Zend Thread Safety). Это затронет внешние библиотеки, которые вызываются через модуль FFI и которые зависят от текущего рабочего каталога.

### Смотрите также

- chdir() - Изменяет рабочий каталог
- chmod() - Изменяет режим доступа к файлу

# opendir

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

opendir — Открывает дескриптор каталога

### Описание

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

Функция открывает дескриптор каталога, который затем передают как аргумент в функции closedir(), readdir() и rewinddir().

### Список параметров

`directory`
  Путь к каталогу, который требуется открыть.
`context`
  Параметр `context` описывается в разделе руководства «Потоки».

### Возвращаемые значения

Функция возвращает дескриптор каталога в случае успешного выполнения или `false`, если возникла ошибка

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

Ошибка возникает, если в параметр `directory` передали недопустимый путь к каталогу, каталог невозможно открыть из-за ограничений прав доступа или из-за ошибок файловой системы.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `context` теперь допускает значение `null`.

### Примеры

Пример #1 Перечисление всех записей в каталоге, пропуская специальные каталоги `.` и `..`.

Поскольку имена файлов и каталогов могут быть строками, которые PHP считает `false` (например, каталог с именем `"0"`), а функция readdir() возвращает `false` после прочтения всех записей в каталоге, необходимо использовать строгий (`===`) оператор сравнения, чтобы правильно различать запись каталога, имя которое является `false` и прочитать все записи каталога.

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Записи:\n";

        /* Правильная обработка записей в каталоге, которые могут считаться ложными */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

Вывод приведённого примера будет похож на:

    Записи:
    base
    en
    fr
    output.md
    test.php

### Смотрите также

- readdir() - Получает элемент каталога по его дескриптору
- rewinddir() - Сбросить дескриптор каталога
- closedir() - Закрывает дескриптор каталога
- dir() - Возвращает экземпляр класса Directory
- is_dir() - Определяет, указывает ли путь на каталог
- glob() - Находит файловые пути, которые совпадают с шаблоном
- scandir() - Получает список файлов и каталогов, расположенных по указанному пути

# readdir

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

readdir — Получает элемент каталога по его дескриптору

### Описание

function readdir(?resource `$dir_handle` = `null`): string|false

Возвращает имя следующего по порядку элемента каталога. Элементы возвращаются в том порядке, в котором они хранятся в файловой системе.

### Список параметров

`dir_handle`
  Дескриптор каталога (resource), ранее открытый функцией opendir(). Если дескриптор каталога не указан, используется последний дескриптор, открытый функцией opendir().

### Возвращаемые значения

Возвращает имя элемента каталога в случае успешного выполнения или `false`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Использование `null` для параметра `dir_handle` теперь не рекомендуется. Вместо этого следует явно указать последний открытый дескриптор каталога.
8.0.0 | `dir_handle` теперь допускает значение `null`.

### Примеры

Примеры смотрите в документации функции opendir().

### Смотрите также

- opendir() - Открывает дескриптор каталога
- rewinddir() - Сбросить дескриптор каталога
- closedir() - Закрывает дескриптор каталога
- dir() - Возвращает экземпляр класса Directory
- is_dir() - Определяет, указывает ли путь на каталог
- glob() - Находит файловые пути, которые совпадают с шаблоном
- scandir() - Получает список файлов и каталогов, расположенных по указанному пути

# rewinddir

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

rewinddir — Сбросить дескриптор каталога

### Описание

function rewinddir(?resource `$dir_handle` = `null`): void

Сбрасывает поток каталога, переданный в параметре `dir_handle` таким образом, чтобы тот указывал на начало каталога.

### Список параметров

`dir_handle`
  Ресурс (resource) дескриптора каталога, ранее открытый с помощью функции opendir(). Если дескриптор каталога не указан, подразумевается последний дескриптор, который был открыт с помощью opendir().

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Использование `null` для `dir_handle` теперь не рекомендуется. Вместо этого следует явно указать последний открытый дескриптор каталога.
8.0.0 | `dir_handle` теперь допускает значение `null`.

### Примеры

Примеры смотрите в документации функции opendir().

### Смотрите также

- opendir() - Открывает дескриптор каталога
- readdir() - Получает элемент каталога по его дескриптору
- closedir() - Закрывает дескриптор каталога
- dir() - Возвращает экземпляр класса Directory
- is_dir() - Определяет, указывает ли путь на каталог
- glob() - Находит файловые пути, которые совпадают с шаблоном
- scandir() - Получает список файлов и каталогов, расположенных по указанному пути

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — Получает список файлов и каталогов, расположенных по указанному пути

### Описание

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

Возвращает массив (array), содержащий имена файлов и каталогов, расположенных по пути, переданном в параметре `directory`.

### Список параметров

`directory`

  Сканируемый каталог.

`sorting_order`

  По умолчанию сортировка производится в алфавитном порядке по возрастанию. Если необязательный параметр `sorting_order` установлен в значение `SCANDIR_SORT_DESCENDING`, сортировка производится в алфавитном порядке по убыванию. Если же он установлен в значение `SCANDIR_SORT_NONE`, то сортировка не производится.

`context`

  За описанием параметра `context` обратитесь к разделу Потоки данного руководства.

### Возвращаемые значения

Возвращает массив (array) имён файлов в случае успешного выполнения или `false` в случае возникновения ошибки. Если `directory` не является каталогом, возвращается `false` и генерируется сообщение об ошибке уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `context` теперь допускает значение null.

### Примеры

Пример #1 Простой пример использования функции scandir()

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

    print_r($files1);
    print_r($files2);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => somedir
    )
    Array
    (
        [0] => somedir
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### Примечания

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Смотрите также

- opendir() - Открывает дескриптор каталога
- readdir() - Получает элемент каталога по его дескриптору
- glob() - Находит файловые пути, которые совпадают с шаблоном
- is_dir() - Определяет, указывает ли путь на каталог
- sort() - Сортирует массив по возрастанию

## Содержание

- chdir — Изменяет рабочий каталог
- chroot — Изменяет корневой каталог
- closedir — Закрывает дескриптор каталога
- dir — Возвращает экземпляр класса Directory
- getcwd — Получает текущую рабочую директорию
- opendir — Открывает дескриптор каталога
- readdir — Получает элемент каталога по его дескриптору
- rewinddir — Сбросить дескриптор каталога
- scandir — Получает список файлов и каталогов, расположенных по указанному пути

- Предопределённые константы
- Directory — Класс Directory
  - Directory::close — Закрывает дескриптор каталога
  - Directory::read — Получает элемент из дескриптора каталога
  - Directory::rewind — Перемещает дескриптор каталога в начало каталога
- Функции для работы с каталогами
  - chdir — Изменяет рабочий каталог
  - chroot — Изменяет корневой каталог
  - closedir — Закрывает дескриптор каталога
  - dir — Возвращает экземпляр класса Directory
  - getcwd — Получает текущую рабочую директорию
  - opendir — Открывает дескриптор каталога
  - readdir — Получает элемент каталога по его дескриптору
  - rewinddir — Сбросить дескриптор каталога
  - scandir — Получает список файлов и каталогов, расположенных по указанному пути

# Информация о файле

# Введение

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

# Установка и настройка

## Содержание

- Установка
- Типы ресурсов

## Установка

Этот модуль включён по умолчанию.

Windows-пользователи должны подключить идущий в комплекте поставки php_fileinfo.dll DLL файл в php.ini для включения данного модуля.

Библиотека libmagic поставляется в комплекте с PHP, но может содержать специфичные для PHP изменения, которые можно добавлять с помощью патча libmagic.patch. Этот патч поддерживается в актуальном состоянии, его можно найти там же, где находятся файлы модуля fileinfo.

## Типы ресурсов

До PHP 8.1.0 модуль Fileinfo работал с одним ресурсом: «магическим» указателем базы данных, который возвращает функция finfo_open().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`FILEINFO_NONE` (int)
  Нет специальной обработки.
`FILEINFO_SYMLINK` (int)
  Следовать по символическим ссылкам.
`FILEINFO_MIME_TYPE` (int)
  Возвращать mime-тип.
`FILEINFO_MIME_ENCODING` (int)
  Возвращать mime-кодировку файла.
`FILEINFO_MIME` (int)
  Возвращать mime-тип и mime-кодировку по стандарту RFC 2045.
`FILEINFO_COMPRESS` (int)
  Распаковывать запакованные файлы. Отключено по соображениям безопасности.
`FILEINFO_DEVICES` (int)
  Смотреть содержимое блочных и символьных устройств.
`FILEINFO_CONTINUE` (int)
  Возвращать все совпадения, а не только первое.
`FILEINFO_PRESERVE_ATIME` (int)
  По возможности сохранять исходное время доступа.
`FILEINFO_RAW` (int)
  Не переводить непечатные символы в `\ooo` восьмеричное представление.
`FILEINFO_EXTENSION` (int)
  Возвращает расширение файла, которое соответствует MIME-типу этого файла. Для типов, которые имеют несколько расширений файлов наподобие `JPEG`-изображений, возвращаемое значение будет состоять из нескольких расширений, разделённых слешем, например `"jpeg/jpg/jpe/jfif"`. Для неизвестных типов, недоступных в базе данных magic.mime, возвращаемое значение будет `"???"`. Доступно с PHP 7.2.0.
`FILEINFO_APPLE` (int)
  Возвращает создателя Apple и тип.

# Функции модуля Fileinfo

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — Возвращает информацию о строке буфера

### Описание

Процедурный стиль

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Объектно-ориентированный стиль

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Эта функция используется для получения информации о бинарных данных в строке.

### Список параметров

`finfo`
  Экземпляр finfo, который возвращает функция finfo_open().
`string`
  Содержимое проверяемого файла.
`flags`
  Одна или несколько объединённых через бинарное ИЛИ констант Fileinfo.
`context`

### Возвращаемые значения

Возвращает текстовое описание для аргумента `string` или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Параметр `context` объявлен устаревшим, поскольку игнорируется.
8.1.0 | Параметр `finfo` теперь принимает объект finfo; раньше параметр ждал ресурс (resource).
8.0.0 | `context` теперь допускает значение null.

### Примеры

Пример #1 Пример finfo_buffer()

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

Вывод приведённого примера будет похож на:

    application/x-sh; charset=us-ascii

### Смотрите также

- finfo_file() - Возвращает информацию о файле

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — Закрывает экземпляр finfo

Внимание

Начиная с PHP 8.5.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

До PHP 7.4 функция закрывала экземпляр, который открыли функцией finfo_open(), но с момента преобразования ресурса в объект finfo в PHP 8.0 функция перестала выполнять операцию, а с PHP 8.5 функция устарела.

### Список параметров

`finfo`
  Экземпляр finfo, который возвращает функция finfo_open().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Функция устарела.
8.5.0 | Тип значения возврата изменился на `true`; раньше объявление содержало тип bool.
8.1.0 | Функция стала NOP (англ. No Operation) и ни на что не влияет.
8.1.0 | Параметр `finfo` теперь принимает объект finfo; раньше параметр ждал ресурс (resource).

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — Возвращает информацию о файле

### Описание

Процедурный стиль

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Объектно-ориентированный стиль

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

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

### Список параметров

`finfo`
  Экземпляр finfo, который возвращает функция finfo_open().
`filename`
  Название проверяемого файла.
`flags`
  Одна или несколько объединённых через бинарное ИЛИ констант Fileinfo.
`context`
  Для описания `contexts`, смотрите Функции для работы с потоками.

### Возвращаемые значения

Возвращает текстовое описание содержимого файла `filename` или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `finfo` теперь принимает объект finfo; раньше параметр ждал ресурс (resource).
8.0.0 | `context` теперь допускает значение null.

### Примеры

Пример #1 Пример использования finfo_file()

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // возвращает mime-тип
    foreach (glob("*") as $filename) {
        echo finfo_file($finfo, $filename) . "\n";
    }
    finfo_close($finfo);
    ?>

Вывод приведённого примера будет похож на:

    text/html
    image/gif
    application/vnd.ms-excel

### Смотрите также

- finfo_buffer() - Возвращает информацию о строке буфера

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — Создаёт экземпляр finfo

### Описание

Процедурный стиль

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

Объектно-ориентированный стиль (конструктор):

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Данная функция открывает магическую базу данных и возвращает экземпляр.

### Список параметров

`flags`
  Одна или несколько объединённых через бинарное ИЛИ констант Fileinfo.
`magic_database`
  Имя файла магической базы данных, обычно что-то наподобие этого: /path/to/magic.mime. Если не указан полный путь, будет использована переменная окружения `MAGIC`. Если переменная окружения не указана, то будет использоваться встроенная в PHP магическая база данных. Передача `null` или пустой строки эквивалентно значению по умолчанию.

### Возвращаемые значения

(Только процедурный стиль) Возвращает экземпляр finfo в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Возвращает экземпляр finfo; ранее возвращался ресурс (resource).
8.0.3 | `magic_database` теперь допускает значение null.

### Примеры

Пример #1 Объектно-ориентированный стиль

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // возвращает mime-тип а-ля mimetype расширения

    /* получить mime-type для указанного файла */
    $filename = "/usr/local/something.txt";
    echo $finfo->file($filename);

    ?>

Пример #2 Процедурный стиль

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // возвращает mime-тип а-ля mimetype расширения

    if (!$finfo) {
        echo "Открытие базы данных fileinfo не удалось";
        exit();
    }

    /* получить mime-type для указанного файла */
    $filename = "/usr/local/something.txt";
    echo finfo_file($finfo, $filename);

    /* закрыть соединение */
    finfo_close($finfo);
    ?>

Результат выполнения приведённого примера:

    text/plain; charset=us-ascii

### Примечания

> Замечание: Обычно использование встроенной магической базы данных (при неустановленных `magic_database` и `MAGIC`) лучший выбор, если вам не нужна определённая версия магической базы данных.

### Смотрите также

- finfo_close() - Закрывает экземпляр finfo

# finfo_set_flags

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — Устанавливает параметры конфигурации библиотеки libmagic

### Описание

Процедурный стиль

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

Объектно-ориентированный стиль

public function finfo::set_flags(int `$flags`): true

Функция устанавливает параметры экземпляра Fileinfo. Параметры также возможно установить при вызове функции finfo_open() или других функций модуля Fileinfo.

### Список параметров

`finfo`
  Экземпляр finfo, который возвращает функция finfo_open().
`flags`
  Параметр принимает отдельную константу модуля Fileinfo или битовую маску из констант модуля, которые объединили через побитовое ИЛИ.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `finfo` теперь принимает объект finfo; раньше параметр ждал ресурс (resource).

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — Определяет MIME-тип содержимого файла

### Описание

function mime_content_type(resource|string `$filename`): string|false

Возвращает MIME-тип содержимого файла, используя для определения информацию из файла magic.mime.

### Список параметров

`filename`
  Путь к проверяемому файлу.

### Возвращаемые значения

Возвращает тип содержимого в формате MIME, например `text/plain` или `application/octet-stream` или `false`, если возникла ошибка.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример mime_content_type()

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('test.php');
    ?>

Результат выполнения приведённого примера:

    image/gif
    text/plain

### Смотрите также

- finfo_file() - Возвращает информацию о файле
- finfo_buffer() - Возвращает информацию о строке буфера

## Содержание

- finfo_buffer — Возвращает информацию о строке буфера
- finfo_close — Закрывает экземпляр finfo
- finfo_file — Возвращает информацию о файле
- finfo_open — Создаёт экземпляр finfo
- finfo_set_flags — Устанавливает параметры конфигурации библиотеки libmagic
- mime_content_type — Определяет MIME-тип содержимого файла

# Класс finfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## Введение

Этот класс предоставляет объектно-ориентированный интерфейс к функциям fileinfo.

## Обзор класса

class finfo {
/* Методы */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — Псевдоним finfo_buffer()

### Описание

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Псевдоним функции finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — Псевдоним finfo_open()

### Описание

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Псевдоним функции finfo_open()

### Список изменений

Версия | Описание
--- | ---
8.0.3 | `magic_database` теперь допускает значение null.

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — Псевдоним finfo_file()

### Описание

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Псевдоним функции finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — Псевдоним finfo_set_flags()

### Описание

public function finfo::set_flags(int `$flags`): true

Псевдоним функции finfo_set_flags()

## Содержание

- finfo::buffer — Псевдоним finfo_buffer()
- finfo::__construct — Псевдоним finfo_open
- finfo::file — Псевдоним finfo_file()
- finfo::set_flags — Псевдоним finfo_set_flags()

- Установка и настройка
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Функции модуля Fileinfo
  - finfo_buffer — Возвращает информацию о строке буфера
  - finfo_close — Закрывает экземпляр finfo
  - finfo_file — Возвращает информацию о файле
  - finfo_open — Создаёт экземпляр finfo
  - finfo_set_flags — Устанавливает параметры конфигурации библиотеки libmagic
  - mime_content_type — Определяет MIME-тип содержимого файла
- finfo — Класс finfo
  - finfo::buffer — Псевдоним finfo_buffer()
  - finfo::__construct — Псевдоним finfo_open
  - finfo::file — Псевдоним finfo_file()
  - finfo::set_flags — Псевдоним finfo_set_flags()

# Файловая система

# Введение

Этот модуль не требует установки никаких внешних библиотек, но если вам нужна поддержка LFS (больших файлов) в Linux, то вам потребуется современная версия glibc и вам следует собирать PHP с включением следующих флагов в CFLAGS: `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`.

# Установка и настройка

## Содержание

- Настройка во время выполнения
- Типы ресурсов

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Директивы конфигурации файловой системы и потоков
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | Устарела с PHP 7.4.0.
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | Устарела PHP 8.1.0.
sys_temp_dir | "" | `INI_SYSTEM` |

Краткое разъяснение конфигурационных директив.

`allow_url_fopen` bool

  Директива включает поддержку обёрток — обработчиков протоколов, которые умеют взаимодействовать с потоками по URL-адресу: открывают доступ к URL-объектам как к файлам. Обёртки по умолчанию предусматривают доступ к удалённым файлам по FTP- или HTTP-протоколу. Отдельные модули, например zlib, умеют регистрировать дополнительные обёртки.

`allow_url_include` bool

  Директива разрешает использовать URL-совместимые обёртки, которые открывают функцией fopen, с выражениями: include, include_once, require, require_once.

  > Замечание:

  > Опция будет работать, только если включили директиву allow_url_fopen.

`user_agent` string

  Опция определяет, какое значение в заголовке «User-Agent» будет отправлять PHP.

`default_socket_timeout` int

  Значение времени ожидания по умолчанию в секундах для потоков на основе сокетов. Отрицательное значение означает бесконечное время ожидания.

`from` string

  Адрес электронной почты, который будет использоваться при FTP-соединениях без аутентификации, а также как значение заголовка «From» для HTTP-соединений через FTP- и HTTP-обёртки, соответственно.

`auto_detect_line_endings` bool

  При включении директивы PHP будет проверять данные, которые считали функции fgets() и file(), чтобы определить, каким соглашениям о конце строк следуют функции — Unix, MS-Dos или Macintosh.

  Директива разрешает PHP взаимодействовать с системами Macintosh, но по умолчанию для директивы установлено значение «Off», поскольку когда PHP обнаруживает условное обозначение символов конца первой строки, незначительно снижается производительность, а ещё потому, что программисты, которые в Unix-системах пользуются символом возврата каретки как разделителем элементов, столкнутся с обратно-несовместимым поведением.

`sys_temp_dir` string

## Типы ресурсов

Файловая система использует потоки (`streams`) как собственный тип ресурсов. Работу с потоками описывает раздел документации «Потоки».

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

Флаги, доступные для параметра `flags` функции file()
`FILE_USE_INCLUDE_PATH` (int)
  Ищет название файла `filename` в списке путей директивы include_path.
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  Добавить содержимое в конец существующего файла.
`FILE_IGNORE_NEW_LINES` (int)
  Удалить EOL-символы конца строки.
`FILE_SKIP_EMPTY_LINES` (int)
  Пропустить пустые строки.
`FILE_BINARY` (int)

  Двоичный режим.

  Внимание

  Константа устарела с PHP 8.1.0 и ни на что не влияет.

`FILE_TEXT` (int)

  Текстовый режим.

  Внимание

  Константа устарела с PHP 8.1.0 и ни на что не влияет.

Флаги, доступные для параметра `flags` функции glob()
`GLOB_AVAILABLE_FLAGS` (int)
  Флаги семейства `GLOB_*` вместе взятые. Эквивалентно записи `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`.
`GLOB_BRACE` (int)
  Разворачивает шаблон {a,b,c} так, чтобы он соответствовал "a", "b" или "c".

  > Замечание: Флаг `GLOB_BRACE` недоступен на ряде систем наподобие Solaris или Alpine Linux, которые работают не на ядре GNU.

`GLOB_ERR` (int)
  Останавливаться при ошибках считывания наподобие нечитаемых каталогов, по умолчанию ошибки игнорируются.
`GLOB_MARK` (int)
  Добавлять слеши, или обратные слеши в ОС Windows, к каждому каталогу, который возвращает функция.
`GLOB_NOCHECK` (int)
  Вернуть шаблон поиска, если функция не нашла ни одного файла, который соответствует шаблону.
`GLOB_NOESCAPE` (int)
  Не экранировать метасимволы обратными слешами.
`GLOB_NOSORT` (int)
  Возвращать файлы в том виде, в котором файлы лежат в каталоге, без сортировки. Без этого флага названия путей файлов сортируются по алфавиту.
`GLOB_ONLYDIR` (int)
  Возвращать только те записи каталога, которые соответствуют шаблону.

Флаги, доступные для параметра `flags` функции pathinfo()
`PATHINFO_ALL` (int)
  Возвращать части информации о пути в ассоциативном массиве.
`PATHINFO_DIRNAME` (int)
  Путь к каталогу или файлу.
`PATHINFO_BASENAME` (int)
  Название каталога или название и расширение файла.
`PATHINFO_EXTENSION` (int)
  Расширение файла.
`PATHINFO_FILENAME` (int)
  Название каталога или файла без расширения.

Режимы сканирования, доступные для параметра `scanner_mode` функций parse_ini_file() и parse_ini_string()
`INI_SCANNER_NORMAL` (int)
  Обычный режим сканирования INI.
`INI_SCANNER_RAW` (int)
  Режим необработанного (raw) сканирования INI.
`INI_SCANNER_TYPED` (int)
  Режим типизированного сканирования INI.

Флаги, доступные для параметра `flags` функции fnmatch()
`FNM_NOESCAPE` (int)
  Отключает экранирование обратных слешей.
`FNM_PATHNAME` (int)
  Слеши в строках совпадают только со слешами в указанном шаблоне.
`FNM_PERIOD` (int)
  Ведущая точка в строке должна точно совпадать с точкой в заданном шаблоне.
`FNM_CASEFOLD` (int)
  Совпадение без учёта регистра. Часть модуля операционной системы GNU.

PHP-константы загрузки файлов
`UPLOAD_ERR_CANT_WRITE` (int)

  Не получилось записать файл на диск. Значение константы равно `7`.

`UPLOAD_ERR_EXTENSION` (int)

  PHP-модуль остановил загрузку файла на сервер. PHP не даёт способа выяснить, какой модуль вызвал остановку загрузки файла; определить причину иногда помогает проверка списка загруженных модулей функцией phpinfo(). Значение константы равно `8`.

`UPLOAD_ERR_FORM_SIZE` (int)

  Загруженный на сервер файл превысил значение директивы MAX_FILE_SIZE, которую указали в HTML-форме. Значение константы равно `2`.

`UPLOAD_ERR_INI_SIZE` (int)

  Загруженный на сервер файл превысил значение директивы upload_max_filesize файла php.ini. Значение константы равно `1`.

`UPLOAD_ERR_NO_FILE` (int)

  Ни один файл не загрузился на сервер. Значение константы равно `4`.

`UPLOAD_ERR_NO_TMP_DIR` (int)

  Отсутствует временная папка. Значение константы равно `6`.

`UPLOAD_ERR_OK` (int)

  Ошибок не возникло, файл успешно загрузился на сервер. Значение константы равно `0`.

`UPLOAD_ERR_PARTIAL` (int)

  Файл загрузился на сервер только частично. Значение константы равно `3`.

# Функции файловой системы

# Смотрите также

Разделы «Каталоги» и «Выполнение программ» описывают родственные функций.

Глава «Протоколы и обёртки» даёт список URL-обёрток и пояснения для работы с удалёнными файлами.

# basename

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

basename — Возвращает конечный компонент имени пути

### Описание

function basename(string `$path`, string `$suffix` = ""): string

Функция получит строку, которая содержит путь к файлу или каталогу, и вернёт конечный компонент имени пути.

> Замечание:

> Функция basename() наивно работает со входной строкой и не знает действительную файловую систему или компоненты пути наподобие «..».

Предостережение

Функция basename() учитывает региональные настройки. Поэтому, чтобы функция видела правильное базовое имя, путь которого содержит многобайтовые символы, требуется функцией setlocale() устанавливать локаль, которая соответствует этим символам. Функция basename() поведёт себя непредсказуемо, если имя пути `path` содержит неправильные для текущей локали символы.

### Список параметров

`path`

  Путь.

  На платформах Windows как разделитель имён каталогов работает и прямой `/`, и обратный `\` слеш. В других окружениях — прямой слеш `/`.

`suffix`

  Функция также обрежет суффикс `suffix`, если компонент имени заканчивается этим суффиксом.

### Возвращаемые значения

Функция возвращает базовое имя пути `path`.

### Примеры

Пример #1 Пример использования функции basename()

    <?php

    echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
    echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
    echo "3) ".basename("/etc/passwd").PHP_EOL;
    echo "4) ".basename("/etc/").PHP_EOL;
    echo "5) ".basename(".").PHP_EOL;
    echo "6) ".basename("/");

    ?>

Результат выполнения приведённого примера:

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### Смотрите также

- dirname() - Возвращает путь к родительскому каталогу
- pathinfo() - Возвращает информацию о пути к файлу

# chgrp

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

chgrp — Изменяет группу файла

### Описание

function chgrp(string `$filename`, string|int `$group`): bool

Осуществляет попытку смены группы файла `filename` на группу `group`.

Только суперпользователь может произвольно менять группу файла; остальные пользователи могут менять группу файла только на те группы, членами которых они являются.

### Список параметров

`filename`

  Путь к файлу.

`group`

  Название или номер группы.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Изменение группы файла

    <?php
    $filename = 'shared_file.txt';
    $format = "Идентификатор группы файла %s @ %s: %d\n";
    printf($format, $filename, date('r'), filegroup($filename));
    chgrp($filename, 8);
    clearstatcache(); // сбрасываем кеш filegroup()
    printf($format, $filename, date('r'), filegroup($filename));
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: В Windows функция молча завершается ошибкой при применении к обычному файлу.

### Смотрите также

- chown() - Изменяет владельца файла
- chmod() - Изменяет режим доступа к файлу

# chmod

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

chmod — Изменяет режим доступа к файлу

### Описание

function chmod(string `$filename`, int `$permissions`): bool

Осуществляет попытку изменения режима доступа указанного файла на режим, переданный в параметре `permissions`.

### Список параметров

`filename`

  Путь к файлу.

`permissions`

  Обратите внимание, что значение параметра `permissions` не переводится автоматически в восьмеричную систему счисления, поэтому, чтобы удостовериться в том, что режим был установлен верно, предваряйте нулём (0) значение передаваемое в параметре `permissions`. Строки, такие как "g+w", не будут работать должным образом.

      <?php
      chmod("/somedir/somefile", 755);   // десятичное, скорее всего, указано неверно
      chmod("/somedir/somefile", "u+rwx,go+rx"); // строка, неверный способ
      chmod("/somedir/somefile", 0755);  // восьмеричное, верный способ
      ?>

  Значение параметра `permissions` состоит из трёх восьмеричных чисел, определяющих уровень доступа для владельца файла, для группы, в которую входит владелец, и для других пользователей, соответственно. Число, определяющее уровень пользователя, может быть вычислено путём суммирования значений, определяющих права: 1 - доступ на выполнение, 2 - доступ на запись, 4 - доступ на чтение. Сложите эти числа для указания нужного права доступа. Более подробно о системе прав в системах Unix вы можете узнать с помощью команд 'man 1 chmod' и 'man 2 chmod'.

      <?php
      // Доступ на запись и чтение для владельца, нет доступа для других
      chmod("/somedir/somefile", 0600);

      // Доступ на запись и чтение для владельца, доступ на чтение для других
      chmod("/somedir/somefile", 0644);

      // Полный доступ для владельца, доступ на чтение и выполнение для других
      chmod("/somedir/somefile", 0755);

      // Полный доступ для владельца, доступ на чтение и выполнение для группы владельца
      chmod("/somedir/somefile", 0750);
      ?>

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

В случае возникновения ошибки выдаётся ошибка уровня `E_WARNING`.

### Примечания

> Замечание:

> Текущим пользователем является пользователь, от имени которого выполняется PHP. Возможно, что это будет не тот пользователь, под именем которого вы получаете доступ к командной оболочке или учётной записи FTP. На большинстве систем режим доступа к файлу может быть изменён только его владельцем.

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

### Смотрите также

- chown() - Изменяет владельца файла
- chgrp() - Изменяет группу файла
- fileperms() - Возвращает информацию о правах на файл
- stat() - Возвращает информацию о файле

# chown

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

chown — Изменяет владельца файла

### Описание

function chown(string `$filename`, string|int `$user`): bool

Осуществляет попытку изменения владельца файла с именем `filename` на владельца, чьё имя передано в параметре `user` (в виде числа или строки). Только суперпользователь может изменять владельца файла.

### Список параметров

`filename`

  Путь к файлу.

`user`

  Имя пользователя или число.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример простого использования chown()

    <?php

    // Используемое имя файла и имя пользователя
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // Устанавливаем пользователя
    chown($path, $user_name);

    // Проверяем результат
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: В Windows функция молча завершается ошибкой при применении к обычному файлу.

### Смотрите также

- chmod() - Изменяет режим доступа к файлу
- chgrp() - Изменяет группу файла

# clearstatcache

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

clearstatcache — Очищает кеш состояния файлов

### Описание

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

Чтобы повысить производительность при вызове функций stat(), lstat() или любой другой функции из списка, который приводит эта страница, PHP кеширует результаты выполнения этих функций. Однако иногда требуется очистка этого кеша. Например, когда скрипт несколько раз проверяет состояние одного и того же файла, который может быть изменён или удалён во время выполнения скрипта, может потребоваться очистка кеша состояния. Тогда для очистки в PHP кешированной информации о файле вызывают функцию clearstatcache().

Обратите внимание, что PHP не кеширует информацию о несуществующих файлах. Поэтому, если вызывать функцию file_exists() на несуществующем файле, функция будет возвращать `false` до тех пор, пока вы не создадите этот файл. Если же вы создадите файл, функция будет возвращать `true`, даже если затем вы удалите файл. Однако функция unlink() очистит этот кеш автоматически.

> Замечание:

> Эта функция кеширует информацию об отдельных файлах, поэтому имеет смысл вызывать функцию clearstatcache(), только если вы совершаете несколько операций с одним и тем же файлом и не хотите получать кешированную информацию об этом файле.

Список функций, результаты выполнения которых кешируются: stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype() и fileperms().

### Список параметров

`clear_realpath_cache`

  Нужно ли также очищать кеш realpath.

`filename`

  Очистить кеш realpath только для определённого имени файла; используется только в том случае, если у параметра `clear_realpath_cache` установлено значение `true`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования функции clearstatcache()

    <?php

    $file = 'output_log.txt';

    function get_owner($file)
    {
        $stat = stat($file);
        $user = posix_getpwuid($stat['uid']);
        return $user['name'];
    }

    $format = "UID @ %s: %s\n";

    printf($format, date('r'), get_owner($file));

    chown($file, 'ross');
    printf($format, date('r'), get_owner($file));

    clearstatcache();
    printf($format, date('r'), get_owner($file));

    ?>

Вывод приведённого примера будет похож на:

    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross

# copy

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

copy — Копирует файл

### Описание

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Функция копирует исходный файл из источника `from` в целевой файл по пути `to`.

Для переименования файла вызывают функцию rename().

### Список параметров

`from`

  Исходный файл — путь или URL-адрес.

`to`

  Путь к целевому файлу. При передаче в параметр `to` URL-адреса операция копирования завершится ошибкой, если потоковая обёртка не поддерживает перезапись файлов.

  Внимание

  Функция перезаписывает целевой файл.

`context`

  Корректный ресурс контекста, который создала функция stream_context_create().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример копирования файла функцией copy()

    <?php

    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "Невозможно скопировать файл $file...\n";
    }

### Смотрите также

- move_uploaded_file() - Перемещает загруженный файл в новое место
- rename() - Переименовывает файл или директорию
- Раздел руководства "Загрузка файлов"

# delete

delete — Смотрите описание функции unlink() или unset()

### Описание

В PHP отсутствует функция с именем delete. Если вы попали на эту страницу в поисках функции удаления файла, то вам стоит воспользоваться функцией unlink(). Если же вам надо удалить переменную в локальной области видимости, то вам нужна функция unset().

### Смотрите также

- unlink() - Удаляет файл
- unset() - Удаляет переменную синтаксисом unset

# dirname

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

dirname — Возвращает путь к родительскому каталогу

### Описание

function dirname(string `$path`, int `$levels` = 1): string

Функция получит строку, которая содержит путь к файлу или каталогу, и вернёт путь к родительскому каталогу на столько уровней выше текущего каталога, сколько указали в параметре `levels`.

> Замечание:

> Функция dirname() наивно работает со входной строкой и не знает действительную файловую систему или компоненты пути наподобие «`..`».

Предостережение

В ОС Windows функция dirname() принимает установленную кодовую страницу. Поэтому, чтобы функция видела правильное имя каталога, путь которого содержит многобайтовые символы, требуется устанавливать кодовую страницу, которая соответствует кодировке этих символов. Функция dirname() поведёт себя непредсказуемо, если имя пути `path` содержит неправильные для текущей кодовой страницы символы.

В других системах функция dirname() предполагает, что путь `path` закодировали в ASCII-совместимой кодировке, иначе функция ведёт себя непредсказуемо.

### Список параметров

`path`

  Путь.

  На платформах Windows как разделитель имён каталогов работает и прямой `/`, и обратный `\` слеш. В других окружениях — прямой слеш `/`.

`levels`

  На сколько уровней вложенности вверх требуется пройти.

  Значение должно быть целым числом больше 0.

### Возвращаемые значения

Функция возвращает путь к родительской директории. Функция возвращает точку «`.`», которая указывает на текущую директорию, если путь `path` не содержит слешей, иначе возвращает путь `path` без последнего компонента `/component`.

Предостережение

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

    <?php

    dirname('.');    // Вернёт «.».
    dirname('/');    // Вернёт «\» в ОС Windows и «/» в *nix-системах.
    dirname('\\');   // Вернёт «\» в ОС Windows и «.» в *nix-системах.
    dirname('C:\\'); // Вернёт «C:\» в ОС Windows и «.» в *nix-системах.

    ?>

### Примеры

Пример #1 Пример использования функции dirname()

    <?php

    echo dirname("/etc/passwd") . PHP_EOL;
    echo dirname("/etc/") . PHP_EOL;
    echo dirname(".") . PHP_EOL;
    echo dirname("C:\\") . PHP_EOL;
    echo dirname("/usr/local/lib", 2);

    ?>

Вывод приведённого примера будет похож на:

    /etc
    / (или \ в Windows)
    .
    C:\
    /usr

### Смотрите также

- basename() - Возвращает конечный компонент имени пути
- pathinfo() - Возвращает информацию о пути к файлу
- realpath() - Возвращает канонизированный абсолютный путь к файлу

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — Возвращает размер доступного пространства в каталоге или файловой системе

### Описание

function disk_free_space(string `$directory`): float|false

Функция возвращает размер свободного пространства в байтах, доступного для использования в указанном каталоге или файловой системе.

### Список параметров

`directory`

  Директория или раздел диска.

  > Замечание:

  > Если вместо директории будет передано имя файла, то поведение данной функции неизвестно и может отличаться на разных операционных системах и версиях PHP.

### Возвращаемые значения

Возвращает количество свободных байт в виде числа с плавающей точкой или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции disk_free_space()

    <?php
    // $df содержит размер свободного места в каталоге "/"
    $df = disk_free_space("/");

    // В Windows:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

### Смотрите также

- disk_total_space() - Возвращает общий размер файловой системы или раздела диска

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — Возвращает общий размер файловой системы или раздела диска

### Описание

function disk_total_space(string `$directory`): float|false

Функция возвращает общий размер в байтах указанного раздела диска или каталога.

### Список параметров

`directory`

  Директория файловой системы или раздел диска.

### Возвращаемые значения

Возвращает общий размер в байтах в виде числа с плавающей точкой или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования disk_total_space()

    <?php
    // $df содержит общий размер диска "/" в байтах
    $ds = disk_total_space("/");

    // В Windows:
    $ds = disk_total_space("C:");
    $ds = disk_total_space("D:");
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

### Смотрите также

- disk_free_space() - Возвращает размер доступного пространства в каталоге или файловой системе

# diskfreespace

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

diskfreespace — Псевдоним disk_free_space()

### Описание

Псевдоним функции disk_free_space().

# fclose

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

fclose — Закрывает открытый дескриптор файла

### Описание

function fclose(resource `$stream`): bool

Функция закрывает файл, на который указывает дескриптор `stream`.

### Список параметров

`stream`

  Дескриптор должен быть корректным и указывать на файл, открытый ранее с помощью функции fopen() или fsockopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Простой пример использования функции fclose()

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### Смотрите также

- fopen() - Открывает файл или URL-адрес
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — Синхронизирует данные (но не метаданные) с файлом

### Описание

function fdatasync(resource `$stream`): bool

Функция синхронизирует содержимое `stream` с накопителем, как и fsync(), но не синхронизирует метаданные файла. Стоит обратить внимание, что данная функция фактически отличается только в системах POSIX. В Windows она является псевдонимом fsync().

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования fdatasync()

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'тестовые данные');
    fwrite($stream, "\r\n");
    fwrite($stream, 'дополнительные данные');

    fdatasync($stream);
    fclose($stream);
    ?>

### Смотрите также

- fflush() - Сбрасывает буфер вывода в файл
- fsync() - Синхронизирует изменения в файле (включая метаданные)

# feof

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

feof — Проверяет, достигнут ли конец файла

### Описание

function feof(resource `$stream`): bool

Функция проверяет, наступило ли событие EOF в указателе на файл.

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Функция возвращает `true`, если для файлового указателя наступило событие EOF или возникла ошибка (включая превышение времени ожидания сокета), иначе возвращает `false`.

### Примечания

Внимание

Функция feof() зависнет, если сервер не закрыл подключение, открытое функцией fsockopen(). Следующий пример показывает, как этого избежать:

Пример #1 Обработка времени ожидания с функцией feof()

    <?php

    function safe_feof($fp, &$start = NULL)
    {
        $start = microtime(true);

        return feof($fp);
    }

    /* Предположим, что файловый указатель $fp уже открыли функцией fsockopen() */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while (!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout) {
        /* Обработка */
    }

    ?>

Внимание

Код рискует уйти в бесконечный цикл, если в функцию передали недопустимый файловый указатель, поскольку функция feof() не сумеет вернуть `true`.

Пример #2 Пример поведения функции feof() с недопустимым указателем на файл

    <?php

    // Если функция не сумеет прочитать файл или файл не существует, функция fopen возвращает FALSE
    $file = @fopen("no_such_file", "r");

    // Значение FALSE, которое вернула функция fopen, вызовет предупреждение и следующий цикл станет бесконечным
    while (!feof($file)) {
    }

    fclose($file);

    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — Сбрасывает буфер вывода в файл

### Описание

function fflush(resource `$stream`): bool

Данная функция осуществляет сброс буферизованных данных в файл, на который указывает `stream`.

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример записи файла с помощью fflush()

    <?php
    $filename = 'bar.txt';

    $file = fopen($filename, 'r+');
    rewind($file);
    fwrite($file, 'Foo');
    fflush($file);
    ftruncate($file, ftell($file));
    fclose($file);
    ?>

### Смотрите также

- clearstatcache() - Очищает кеш состояния файлов
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме

# fgetc

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

fgetc — Считывает символ из файла

### Описание

function fgetc(resource `$stream`): string|false

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

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Возвращает строку с одним символом, прочтённым из файла, на который указывает `stream`. Возвращает `false` при достижении EOF.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Примеры

Пример #1 Пример использования функции fgetc()

    <?php
    $fp = fopen('somefile.txt', 'r');
    if (!$fp) {
        echo 'Ошибка при открытии файла somefile.txt';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### Примечания

> Замечание: Функция безопасна для обработки данных в двоичной форме.

### Смотрите также

- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fopen() - Открывает файл или URL-адрес
- popen() - Открывает файловый указатель процесса
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- fgets() - Получает строку из указателя на файл

# fgetcsv

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

fgetcsv — Получает строку из файлового указателя и разбирает по CSV-полям

### Описание

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

Функция похожа на функцию fgets(), за исключением того, что функция fgetcsv() анализирует строку на наличие полей в формате CSV и возвращает массив с прочитанными полями.

> Замечание: Функция учитывает региональный настройки. Поэтому функция иногда неправильно разбирает данные в отдельных однобайтовых кодировках, если значение константы `LC_CTYPE` равно `en_US.UTF-8`.

### Список параметров

`stream`

  Корректный указатель на файл, который успешно открыли функции fopen(), popen() или fsockopen().

`length`

  Для параметра `length` устанавливают значение, которое больше самой длинной строки в CSV-файле, иначе строка разбивается на части заданной длины, если только место разделения не встретится внутри символов-ограничителей. Длина строк измеряется в символах с учётом символов конца строки, которыми завершаются строки.

  Функция снимет ограничение на длину строки, но замедлит работу, если параметр пропустили или начиная с PHP 8.0.0 установили для параметра значение 0 или `null`.

`separator`

  Параметр `separator` устанавливает символ-разделитель полей и принимает только один однобайтовый символ.

`enclosure`

  Параметр `enclosure` устанавливает символ-ограничитель значения поля и принимает только один однобайтовый символ.

`escape`

  Параметр `escape` устанавливает символ экранирования и принимает только один однобайтовый символ или пустую строку. Пустая строка `""` отключает внутренний механизм экранирования.

  Внимание

  Обычно символ ограничителя значений — `enclosure` экранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранирования `escape`. Поэтому для стандартных значений параметра смысл значений `""` и `\"` одинаков. Символ экранирования — `escape` не несёт отдельного смысла, кроме экранирования символа ограничителя значений — `enclosure`; он даже не экранирует сам себя.

  Внимание

  Начиная с PHP 8.4.0 полагаться на значение по умолчанию, которое содержит параметр `escape`, не рекомендуют. Значение потребуется указать явно, позиционно или как именованный аргумент.

Внимание

Строка в CSV-формате иногда перестаёт соответствовать стандарту » RFC 4180 или не выдерживает обмена информацией с PHP-функциями для работы с CSV-строками, если для символа экранирования `escape` устанавливают значение, которое отличается от пустой строки `""`. Значение по умолчанию для параметра `escape` — `"\\"`, поэтому рекомендуют явно указывать пустую строку. Значение по умолчанию изменят в будущей версии PHP, но не раньше PHP 9.0.

### Возвращаемые значения

В случае успешного выполнения функция возвращает индексный массив с полями, которые прочитала из файла, или `false`, если возникла ошибка.

> Замечание:

> Пустую строку в CSV-файле функция возвращает как массив с единственным элементом null и не рассматривает как ошибку.

> Замечание: Включение опции auto_detect_line_endings во время выполнения иногда помогает исправить неправильное распознавание языком PHP концов строк при чтении файлов на Macintosh-совместимом компьютере или файлов, которые создали на Макинтоше.

### Ошибки

Функция выбрасывает ошибку ValueError, если аргументы для разделителя полей `separator` или ограничителя значений `enclosure` содержат значение короче одного байта.

Функция выбрасывает ошибку ValueError, если длина значения аргумента `escape` не равна одному байту или передали пустую строку.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вызов функции без явной передачи значения в параметр `escape` устарел.
8.3.0 | Вместо строки с одним нулевым байтом возвращается пустая строка, если последнее поле содержит только незавершённый символ ограничения значения поля. enclosure.
8.0.0 | Параметр `length` теперь принимает значение `null`.
7.4.0 | Параметр `escape` теперь также принимает пустую строку для отключения встроенного механизма экранирования.

### Примеры

Пример #1 Пример считывания и вывода на экран содержимого CSV-файла

    <?php

    $row = 1;

    if (($handle = fopen("test.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);

            echo "<p> $num полей в строке $row: <br /></p>\n";
            $row++;

            for ($c = 0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }

        fclose($handle);
    }

    ?>

### Смотрите также

- fputcsv() - Формирует строку в CSV-формате и записывает строку в файловый указатель
- str_getcsv() - Разбирает CSV-строку в массив
- SplFileObject::fgetcsv() - Получает строку из файлового указателя и разбирает по CSV-полям
- SplFileObject::fputcsv() - Записывает массив полей как CSV-строки
- SplFileObject::setCsvControl() - Устанавливает символы разделителя, ограничителя и экранирования для CSV-полей
- SplFileObject::getCsvControl() - Получает символы разделителя, ограничителя и экранирования CSV-полей
- explode() - Разбивает строку разделителем
- file() - Читает содержимое файла и помещает его в массив
- pack() - Упаковывает данные в двоичную строку

# fgets

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

fgets — Получает строку из указателя на файл

### Описание

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

Функция получает строку из файлового указателя.

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().
`length`

  Чтение заканчивается, когда: а) функция прочитала `length` - 1 байтов, б) встретился конец строки (который функция включает в возвращаемое значение) или в) наступило состояние EOF (функция достигла конца файла) — в зависимости от того, что наступит раньше. Чтение из потока будет продолжаться до тех пор, пока функция не достигнет конца строки, если длину не указали.

### Возвращаемые значения

Функция возвращает строку размером до `length` - 1 байтов, которую функция прочитала из дескриптора файла, на который указывает параметр `stream`. Функция возвращает `false`, если данных для чтения не осталось.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример построчного чтения файла

    <?php

    $fp = @fopen("/tmp/inputfile.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }

        if (!feof($fp)) {
            echo "Ошибка: неожиданный сбой функций fgets()\n";
        }

        fclose($fp);
    }

    ?>

### Примечания

> Замечание: Включение опции auto_detect_line_endings во время выполнения иногда помогает исправить неправильное распознавание языком PHP концов строк при чтении файлов на Macintosh-совместимом компьютере или файлов, которые создали на Макинтоше.

> Замечание:

> Программистам, которые привыкли к семантике функции fgets() языка C, требуется принять во внимание разницу в том, как возвращается признак конца файла (`EOF`).

### Смотрите также

- fgetss() - Читает строку из файла и удаляет HTML-теги
- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fgetc() - Считывает символ из файла
- stream_get_line() - Получает строку из потокового ресурса до указанного разделителя
- fopen() - Открывает файл или URL-адрес
- popen() - Открывает файловый указатель процесса
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- stream_set_timeout() - Устанавливает значение времени ожидания для потока

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — Читает строку из файла и удаляет HTML-теги

Внимание

Начиная с PHP 7.3.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

Функция идентична функции fgets(), за исключением того, что fgetss() удаляет любые NULL-байты, HTML- и PHP-теги из прочитанной строки. Функция сохраняет состояние синтаксического анализа от вызова к вызову и поэтому не эквивалентна вызову функции strip_tags() для возвращаемого значения функции fgets().

### Список параметров

`handle`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().
`length`

  Длина получаемых данных.

`allowable_tags`

  Допускается использовать третий необязательный параметр, чтобы указать теги, которые не нужно вырезать. Дополнительную информации о параметре `allowable_tags` даёт описание функции strip_tags().

### Возвращаемые значения

Функция возвращает строку длиной до `length` - 1 байтов, которые функция прочитала из файла, на который указывает дескриптор `handle`, с вырезанными HTML- и PHP-тегами.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример построчного чтения PHP-файла

    <?php

    $str = <<<EOD
    <html><body>
     <p>Добро пожаловать! Сегодня <?php echo(date('jS F')); ?>.</p>
    </body></html>
    Текст вне HTML-блока.
    EOD;
    file_put_contents('sample.php', $str);

    $handle = @fopen("sample.php", "r");

    if ($handle) {
        while (!feof($handle)) {
            $buffer = fgetss($handle, 4096);
            echo $buffer;
        }
        fclose($handle);
    }

    ?>

Вывод приведённого примера будет похож на:

    Добро пожаловать! Сегодня .

    Текст вне HTML-блока.

### Примечания

> Замечание: Включение опции auto_detect_line_endings во время выполнения иногда помогает исправить неправильное распознавание языком PHP концов строк при чтении файлов на Macintosh-совместимом компьютере или файлов, которые создали на Макинтоше.

### Смотрите также

- fgets() - Получает строку из указателя на файл
- fopen() - Открывает файл или URL-адрес
- popen() - Открывает файловый указатель процесса
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- strip_tags() - Удаляет HTML- и PHP-теги из строки
- SplFileObject::fgetss() - Получает строку из файла и удаляет HTML-теги
- Фильтр string.strip_tags

# file

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

file — Читает содержимое файла и помещает его в массив

### Описание

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

Функция читает содержимое файла и помещает его в массив.

> Замечание:

> Файл в виде строки также возвращает функция file_get_contents().

### Список параметров

`filename`

  Путь к файлу.

  Подсказка

  Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

`flags`

  Необязательный параметр `flags` принимает константу из следующего списка:

  `FILE_USE_INCLUDE_PATH`
    Искать файл в списке путей директивы include_path.
  `FILE_IGNORE_NEW_LINES`
    Пропускать новую строку в конце каждого элемента массива.
  `FILE_SKIP_EMPTY_LINES`
    Пропускать пустые строки.
  `FILE_NO_DEFAULT_CONTEXT`
    Не использовать контекст по умолчанию.
`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает файл в виде массива. Каждый элемент массива соответствует строке файла, с символами новой строки включительно. Функция file() возвращает `false`, если возникла ошибка.

> Замечание:

> Каждая строка в массиве будет завершаться символами конца строки, если только не указали флаг `FILE_IGNORE_NEW_LINES`).

> Замечание: Включение опции auto_detect_line_endings во время выполнения иногда помогает исправить неправильное распознавание языком PHP концов строк при чтении файлов на Macintosh-совместимом компьютере или файлов, которые создали на Макинтоше.

### Ошибки

Начиная с PHP 8.3.0 функция выбрасывает ошибку ValueError, если параметр `flags` содержит недопустимое значение наподобие флага `FILE_APPEND`.

Функция выдаёт ошибку уровня `E_WARNING`, если файл не существует.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция выбрасывает ошибку ValueError при передаче в параметр `flags` недопустимого флага.

### Примеры

Пример #1 Пример использования функции file()

    <?php

    // Получаем содержимое файла в виде массива. Обращаемся
    // по HTTP-протоколу, чтобы получить HTML-код с удалённого сервера
    $lines = file('http://www.example.com/');

    // Обходим элементы массива и выводим содержимое как HTML-код с номерами строк
    foreach ($lines as $line_num => $line) {
        echo "Строка #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // Передаём необязательный параметр flags
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);

    ?>

### Примечания

Внимание

При работе с сервером Microsoft IIS по SSL-протоколу разработчик сталкивается с тем, что IIS-сервер нарушает протокол путём закрытия соединения без отправки индикатора `close_notify`. PHP выдаст ошибку в виде сообщения «SSL: Fatal Protocol Error» при достижении конца данных. Чтобы избежать такого поведения, значение директивы error_reporting снижают до уровня, который не включает предупреждений уровня E_WARNING. PHP умеет обнаруживать ошибочное программное обеспечение IIS-сервера при открытии потока через обёртку `https://`, и подавляет предупреждение. За обнаружение и подавление предупреждения отвечает разработчик, который вызывает функцию fsockopen(), чтобы создать сокет `ssl://`.

### Смотрите также

- file_get_contents() - Считывает содержимое файла в строку
- readfile() - Выводит файл
- fopen() - Открывает файл или URL-адрес
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- popen() - Открывает файловый указатель процесса
- include - include
- stream_context_create() - Создаёт контекст потока

# file_exists

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

file_exists — Проверяет, содержит ли файловая система файл или каталог

### Описание

function file_exists(string `$filename`): bool

Функция проверяет, содержит ли файловая система файл или каталог.

### Список параметров

`filename`

  Путь к файлу или каталогу.

  Функция корректно обрабатывает пути к общедоступным сетевым ресурсам ОС Windows как с прямыми — //computername/share/filename, — так и с обратными слешами: \\computername\share\filename.

### Возвращаемые значения

Функция возвращает `true`, если файловая система содержит файл или каталог по пути `filename`, иначе возвращает `false`.

> Замечание:

> Функция вернёт `false`, если символическая ссылка указывает на файл, который не содержится в файловой системе.

> Замечание:

> Функция игнорирует текущие SUID- и GUID-биты файла или каталога и проверяет пути по реальным идентификаторам пользователя и группы PHP-процесса — UID и GID.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример проверки существования файла

    <?php

    $filename = '/path/to/foo.txt';

    if (file_exists($filename)) {
        echo "Файл $filename существует";
    } else {
        echo "Файл $filename не существует";
    }

    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- is_readable() - Определяет существование файла и доступен ли он для чтения
- is_writable() - Определяет, доступен ли файл для записи
- is_file() - Сообщает, ведёт ли путь к стандартному файлу
- file() - Читает содержимое файла и помещает его в массив
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — Считывает содержимое файла в строку

### Описание

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

Функция похожа на функцию file(), за исключением того, что функция file_get_contents() возвращает содержимое файла в строке длиной `length` байтов со смещения `offset`. Функция file_get_contents() вернёт `false`, если возникнет ошибка.

Вызов функции file_get_contents() наиболее предпочтителен, когда требуется получить содержимое файла целиком, поскольку для улучшения производительности функция использует технику отображения файла в памяти (memory mapping), если операционная система её поддерживает.

> Замечание:

> При открытии URI, который содержит спецсимволы наподобие пробела, URI-идентификатор кодируют функцией urlencode().

### Список параметров

`filename`

  Имя читаемого файла.

`use_include_path`

  > Замечание:

  > Для поиска файла в списке путей директивы include path в параметр перадают константу `FILE_USE_INCLUDE_PATH`. Обратите внимание, в коде со строгой типизацией так сделать не получится, потому что значение константы `FILE_USE_INCLUDE_PATH` принадлежит типу int. В строгом режиме лучше установить значение `true`.

`context`

  Корректный ресурс контекста, который возвращает функция stream_context_create(). В параметр передают значение `null`, если специфичный контекст не требуется.

`offset`

  Смещение, с которого начнётся чтение оригинального потока. Отрицательное значение смещения отсчитывается с конца потока.

  Поиск смещения `offset` не поддерживается при работе с удалёнными файлами. Попытка поиска смещения на нелокальных файлах иногда работает при небольших смещениях, но результат будет непредсказуемым, поскольку функция работает на буферизованном потоке.

`length`

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

### Возвращаемые значения

Функция возвращает данные, которые считала, или `false`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Ошибки

Функция выдаст ошибку уровня `E_WARNING`, если не найдёт файл `filename`, для параметра `length` установили значение меньше нуля или поиск по смещению `offset` в потоке завершится неудачно.

При вызове функции file_get_contents() на каталоге в ОС Windows генерируется ошибка уровня `E_WARNING`, а с PHP 7.4 и в других операционных системах.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `length` теперь принимает значение `null`.
7.1.0 | Добавили поддержку отрицательных значений для смещения `offset`.

### Примеры

Пример #1 Пример получения и вывода исходного кода домашней страницы сайта

    <?php

    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;

    ?>

Пример #2 Поиск файлов в include_path

    <?php

    // Если включили строгую типизацию, то есть объявили (strict_types=1);
    $file = file_get_contents('./people.txt', true);

    // Иначе
    $file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);

    ?>

Пример #3 Чтение секции файла

    <?php

    // Читаем 14 символов, начиная с 21 символа
    $section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);

    var_dump($section);

    ?>

Вывод приведённого примера будет похож на:

    string(14) "lle Bjori Ro"

Пример #4 Работа функции с потоковыми контекстами

    <?php

    // Создаём поток
    $opts = [
      'http' => [
        'method' => "GET",
        'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar",
      ]
    ];

    $context = stream_context_create($opts);

    // Открываем файл с установленными HTTP-заголовками
    $file = file_get_contents('http://www.example.com/', false, $context);

    ?>

### Примечания

> Замечание: Функция безопасна для обработки данных в двоичной форме.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

Внимание

При работе с сервером Microsoft IIS по SSL-протоколу разработчик сталкивается с тем, что IIS-сервер нарушает протокол путём закрытия соединения без отправки индикатора `close_notify`. PHP выдаст ошибку в виде сообщения «SSL: Fatal Protocol Error» при достижении конца данных. Чтобы избежать такого поведения, значение директивы error_reporting снижают до уровня, который не включает предупреждений уровня E_WARNING. PHP умеет обнаруживать ошибочное программное обеспечение IIS-сервера при открытии потока через обёртку `https://`, и подавляет предупреждение. За обнаружение и подавление предупреждения отвечает разработчик, который вызывает функцию fsockopen(), чтобы создать сокет `ssl://`.

### Смотрите также

- file() - Читает содержимое файла и помещает его в массив
- fgets() - Получает строку из указателя на файл
- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- readfile() - Выводит файл
- file_put_contents() - Записывает данные в файл
- stream_get_contents() - Читает оставшуюся часть потока в строку
- stream_context_create() - Создаёт контекст потока
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — Записывает данные в файл

### Описание

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

Функция работает так же, как последовательный вызов функций fopen(), fwrite() и fclose() для записи данных в файл.

Если путь `filename` не существует, функция создаст файл. В противном случае она перезапишет существующий файл, если не установлен флаг `FILE_APPEND`.

### Список параметров

`filename`

  Путь к файлу, в который функция будет записывать данные.

`data`

  Записываемые данные. Разрешено передавать строку (string), массив (array) или ресурс потока.

  Если данные `data` — ресурс потока (stream), функция скопирует оставшийся буфер потока в файл. Это похоже на работу функции stream_copy_to_stream().

  Допустимо определять параметр `data` как одномерный массив. Это будет эквивалентно вызову `file_put_contents($filename, implode('', $array))`.

`flags`

  В параметр `flags` разрешено передавать произвольные комбинации следующих флагов, соединяя их бинарным оператором ИЛИ (`|`).

  Доступные флаги
  Флаг | Описание
  --- | ---
  `FILE_USE_INCLUDE_PATH` | Ищет файл `filename` во включённых каталогах. Параграф include_path даёт дополнительную информацию.
  `FILE_APPEND` | Функция допишет данные в конец файла вместо того, чтобы перезаписать его, если файл `filename` уже существует.
  `LOCK_EX` | Получает эксклюзивную блокировку файла на время записи. Другими словами, между вызовами функций fopen() и fwrite() произойдёт вызов функции flock(). Это не тождественно вызову функции fopen() с флагом «x».

`context`

  Допустимый ресурс контекста, который создан функцией stream_context_create().

### Возвращаемые значения

Функция возвращает количество байтов, которые процесс записал в файл, или `false` в случае ошибки.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Примеры

Пример #1 Пример простого использования

    <?php

    $file = 'people.txt';

    // Открываем файл, чтобы получить существующее содержимое
    $current = file_get_contents($file);

    // Добавляем нового человека в файл
    $current .= "Джон Смит\n";

    // Записываем содержимое обратно в файл
    file_put_contents($file, $current);

    ?>

Пример #2 Использование флагов

    <?php

    $file = 'people.txt';

    // Новый человек, которого нужно добавить в файл
    $person = "Джон Смит\n";

    // Записываем содержимое в файл
    // с флагом FILE_APPEND, чтобы дописать содержимое в конец файла,
    // и флагом LOCK_EX, чтобы никто другой не мог записывать данные в файл в то же самое время
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);

    ?>

### Примечания

> Замечание: Функция безопасна для обработки данных в двоичной форме.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Смотрите также

- fopen() - Открывает файл или URL-адрес
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме
- file_get_contents() - Считывает содержимое файла в строку
- stream_context_create() - Создаёт контекст потока

# fileatime

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

fileatime — Возвращает время последнего доступа к файлу

### Описание

function fileatime(string `$filename`): int|false

Возвращает время последнего доступа к файлу.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает время, когда в последний раз был осуществлён доступ к указанному файлу или `false`, если возникла ошибка. Время возвращается в виде временной метки Unix.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции fileatime()

    <?php

    // Пример вывода: В последний раз обращение к файлу somefile.txt было произведено: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "В последний раз обращение к файлу $filename было произведено: " . date("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### Примечания

> Замечание:

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

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

> Замечание: Обратите внимание, файловые системы обрабатывают время по-разному.

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- filemtime() - Получает время последнего изменения файла
- fileinode() - Возвращает индексный дескриптор файла
- date() - Форматирует метку времени эпохи Unix

# filectime

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

filectime — Возвращает время изменения индексного дескриптора файла

### Описание

function filectime(string `$filename`): int|false

Возвращает время изменения индексного дескриптора (inode) файла.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает время последнего изменения файла или `false`, если возникла ошибка. Время возвращается в формате временной метки Unix.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции filectime()

    <?php

    // Пример вывода: Файл somefile.txt в последний раз был изменён: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "Файл $filename в последний раз был изменён: " . date("F d Y H:i:s.", filectime($filename));
    }

    ?>

### Примечания

> Замечание:

> Примечание. На большинстве платформ Unix, файл считается изменённым, если изменены данные его индексного дескриптора, что включает информацию о правах на файл, о его владельце, группе и другие метаданные, содержащиеся в индексном дескрипторе. Обратитесь также к описаниям функций filemtime() (данная функция полезна для создания сообщений типа: "Последнее обновление от ..." на веб-страницах) и fileatime().

> Замечание:

> Учтите также, что в некоторых описаниях работы Unix ctime представляется как время создания файла. Это неверно. В большинстве файловых систем Unix понятие времени создания файла отсутствует.

> Замечание: Обратите внимание, файловые системы обрабатывают время по-разному.

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- filemtime() - Получает время последнего изменения файла

# filegroup

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

filegroup — Получает идентификатор группы файла

### Описание

function filegroup(string `$filename`): int|false

Возвращает идентификатор группы файла в виде числа. Для получения имени группы в виде строки используйте функцию posix_getgrgid().

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает идентификатор группы файла или `false` в случае ошибки. Идентификатор группы возвращается в виде числа, для получения имени группы в виде строки используйте функцию posix_getgrgid(). В случае возникновения ошибки возвращается `false`.

### Ошибки

В случае возникновения ошибки будет сгенерирована ошибка уровня `E_WARNING`.

### Примеры

Пример #1 Поиск группы файла

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- fileowner() - Возвращает идентификатор владельца файла
- posix_getgrgid() - Возвращает информацию о группе по её ID

# fileinode

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

fileinode — Возвращает индексный дескриптор файла

### Описание

function fileinode(string `$filename`): int|false

Возвращает индексный дескриптор файла.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает номер индексного дескриптора файла или `false`, если возникла ошибка.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Сравнение индексного дескриптора файла с текущим файлом

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'Вы проверяете текущий файл.';
    }
    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- getmyinode() - Получает значение inode текущего скрипта
- stat() - Возвращает информацию о файле

# filemtime

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

filemtime — Получает время последнего изменения файла

### Описание

function filemtime(string `$filename`): int|false

Функция возвращает время последней записи блоков данных файла, то есть время изменения содержания файла.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Функция возвращает время последнего изменения файла или `false`, если возникла ошибка. Время возвращается в формате метки времени Unix, который соответствует формату значения аргумента для функции date().

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции filemtime()

    <?php

    // Пример вывода: В последний раз файл somefile.txt изменялся: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "В последний раз файл $filename изменялся: " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### Примечания

> Замечание: Обратите внимание, файловые системы обрабатывают время по-разному.

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- filectime() - Возвращает время изменения индексного дескриптора файла
- stat() - Возвращает информацию о файле
- touch() - Устанавливает время доступа и модификации файла
- getlastmod() - Получает время последней модификации страницы

# fileowner

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

fileowner — Возвращает идентификатор владельца файла

### Описание

function fileowner(string `$filename`): int|false

Возвращает идентификатор владельца файла

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает числовой идентификатор владельца указанного файла или `false`, если возникла ошибка. Чтобы получить имя владельца в виде строки, используйте функцию posix_getpwuid().

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Находим владельца файла

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- filegroup() - Получает идентификатор группы файла
- stat() - Возвращает информацию о файле
- posix_getpwuid() - Возвращает информацию о пользователе, используя его ID

# fileperms

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

fileperms — Возвращает информацию о правах на файл

### Описание

function fileperms(string `$filename`): int|false

Возвращает информацию о правах доступа на файл.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает права доступа на указанный файл в числовом виде. Младшие биты этого значения такие же, как и биты прав доступа для использования в функции chmod(), однако, на большинстве платформ, возвращаемое значение будет также включать информацию о типе файла, который передан в качестве параметра `filename`. Примеры ниже демонстрируют как проверить возвращаемое значение на наличие определённых прав и типа файла на POSIX-системах, включая Linux и macOS.

Для локальных файлов, возвращаемое значение является частью структуры `st_mode`, которая возвращается функцией С-библиотеки stat(). Какие в точности биты установлены может варьироваться от платформы к платформе. Рекомендуется поискать документацию к вашей платформе, если требуется обработка битов возвращаемого значения, не относящихся к правам доступа.

Возвращает `false` в случае возникновения ошибки.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Отображение прав доступа в виде восьмеричного числа

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

Результат выполнения приведённого примера:

    1777
    0644

Пример #2 Отображение полных прав доступа

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // сокет
            $info = 's';
            break;
        case 0xA000: // символическая ссылка
            $info = 'l';
            break;
        case 0x8000: // обычный
            $info = 'r';
            break;
        case 0x6000: // файл блочного устройства
            $info = 'b';
            break;
        case 0x4000: // каталог
            $info = 'd';
            break;
        case 0x2000: // файл символьного устройства
            $info = 'c';
            break;
        case 0x1000: // FIFO канал
            $info = 'p';
            break;
        default: // неизвестный
            $info = 'u';
    }

    // Владелец
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // Группа
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // Мир
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

Результат выполнения приведённого примера:

    -rw-r--r--

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- chmod() - Изменяет режим доступа к файлу
- is_readable() - Определяет существование файла и доступен ли он для чтения
- stat() - Возвращает информацию о файле

# filesize

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

filesize — Возвращает размер файла

### Описание

function filesize(string `$filename`): int|false

Возвращает размер указанного файла.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает размер указанного файла в байтах или `false` (и генерирует ошибку уровня `E_WARNING`) в случае возникновения ошибки.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции filesize()

    <?php

    // Пример вывода: Размер файла somefile.txt: 1024 байтов

    $filename = 'somefile.txt';
    echo 'Размер файла ' . $filename . ': ' . filesize($filename) . ' байтов';

    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- file_exists() - Проверяет, содержит ли файловая система файл или каталог

# filetype

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

filetype — Возвращает тип файла

### Описание

function filetype(string `$filename`): string|false

Возвращает тип указанного файла.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает тип файла. Возможными значениями являются fifo, char, dir, block, link, file, socket и unknown.

Возвращает `false` в случае возникновения ошибки. filetype() также вызовет ошибку уровня `E_NOTICE`, если системный вызов stat завершится ошибкой или тип файла неизвестен.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции filetype()

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');
    ?>

Результат выполнения приведённого примера:

    file
    dir

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- is_dir() - Определяет, указывает ли путь на каталог
- is_file() - Сообщает, ведёт ли путь к стандартному файлу
- is_link() - Сообщает, указывает ли путь на символическую ссылку
- file_exists() - Проверяет, содержит ли файловая система файл или каталог
- mime_content_type() - Определяет MIME-тип содержимого файла
- pathinfo() - Возвращает информацию о пути к файлу
- stat() - Возвращает информацию о файле

# flock

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

flock — Блокирует файл методом переносимой рекомендательной блокировки

### Описание

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

Функция flock() разрешает выполнять простую модель чтения-записи, которая будет работать на большей части Unix-платформ и даже на платформах семейства Windows.

Блокировку также снимает функция fclose() или сборщик мусора, когда уничтожает поток `stream`.

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

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`operation`

  `operation` принимает следующие значения:

  - `LOCK_SH` для получения разделяемой блокировки (чтение).
  - `LOCK_EX` для получения эксклюзивной блокировки (запись).
  - `LOCK_UN` для снятия блокировки (разделяемой или эксклюзивной).

  Флаг `LOCK_NB` добавляют как битовую маску к одной операции из списка выше, если функция flock() не должна блокироваться во время попытки блокировки файла.

`would_block`

  Необязательный третий параметр получает значение 1, если блокировка будет блокирующей (в переменную errno будет записан код ошибки EWOULDBLOCK).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции flock()

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) { // Выполняем эксклюзивную блокировку
        ftruncate($fp, 0); // Очищаем файл
        rewind($fp);
        fwrite($fp, "Пишем что-нибудь сюда\n");
        fflush($fp);        // Очищаем вывод перед отменой блокировки
        flock($fp, LOCK_UN); // Снимаем блокировку
    } else {
        echo "Не удалось получить блокировку!";
    }

    fclose($fp);

    ?>

Пример #2 Использование функции flock() с параметром `LOCK_NB`

    <?php

    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Включаем опцию LOCK_NB в операцию LOCK_EX */
    if (!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'Не удалось получить блокировку';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### Примечания

> Замечание:

> В системах Windows функция flock() включает обязательную блокировку вместо рекомендательной. Обязательная блокировка также поддерживается в операционных системах на базе Linux и System V через стандартный механизм, который поддерживает системный вызов fcntl(): то есть, если для файла установлен бит разрешения setgid и сброшен бит группового выполнения. Чтобы схема работала корректно в Linux, файловую систему также нужно смонтировать с опцией mand.

> Замечание:

> Поскольку функция flock() требует указатель на файл, возможно, придётся использовать специальный файл блокировки, чтобы защитить доступ к файлу, который вы собираетесь обрезать, открыв в режиме записи (в режимах «w» или «w+» в качестве аргумента функции fopen()).

> Замечание:

> Функцию разрешено вызывать только на дескрипторах локальных файлов, которые возвращает функция fopen(), или файловых дескрипторах пользовательских потоков, которые реализуют метод streamWrapper::stream_lock().

Внимание

Присвоение другого значения параметру `stream` в следующем дальше коде снимет текущую блокировку.

Внимание

В ряде операционных систем функция flock() работает на уровне процессов. При работе с многопоточными серверными API, например, ISAPI, нельзя полагаться на функцию flock(), чтобы защитить файлы от других PHP-скриптов, которые работают в параллельном потоке на том же сервере!

Функцию flock() не поддерживают старые файловые системы наподобие `FAT` и её производные, поэтому функцию будет возвращать `false` в этих окружениях.

> Замечание:

> Если в Windows процесс блокировки открывает файл во второй раз, он не может получить доступ к файлу через второй дескриптор, пока не разблокирует файл.

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — Проверяет совпадение имени файла с шаблоном

### Описание

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

Функция fnmatch() проверяет, совпадает ли название файла или другая строка в аргументе `filename` с шаблоном `pattern`, который поддерживает подстановочные знаки командной оболочки.

### Список параметров

`pattern`

  Шаблон `pattern`, с которым требуется сопоставить строку. В аргумент `pattern` часто включают подстановочные знаки наподобие `'?'` и `'*'`.

  Подстановочные знаки параметра `pattern`
  Подстановочный знак | Описание
  --- | ---
  `?` | Вопросительный знак соответствует одному произвольному символу. Шаблон `"file?.txt"` совпадёт с названиями файлов `"file1.txt"` и `"fileA.txt"`, но не совпадёт с названем `"file10.txt"`.
  `*` | Звёздочка соответствует нулю или большему количеству символов. Шаблон `"foo*.xml"` совпадёт и с названием файла `"foo.xml"`, и с названием `"foobar.xml"`.
  `[ ]` | Квадратные скобки задают диапазоны или наборы отдельных символов в границах кодовых точек стандарта ASCII. Шаблон `"index.php[45]"` совпадёт с названиями файлов `"index.php4"` и `"index.php5"`, но не совпадёт с названием `"index.phpt"`. Популярные символьные группы: `[0-9]`, `[a-z]` и `[A-Z]`. Квадратные скобки поддерживают комбинации диапазонов и наборов символов: `[0-9a-zABC]`.
  `!` | Восклицательный знак указывают для отрицания символов внутри квадратных скобок. Шаблон `"[!A-Z]*.html"` совпадёт с названием файла `"demo.html"`, но не совпадёт с названием `"Demo.html"`.
  `\` | Обратный слеш экранирует специальные символы. Шаблон `"Name\?"` совпадёт со строкой `"Name?"`, не совпадёт со строкой `"Names"`.

`filename`

  Проверяемая строка. Функцией чаще проверяют названия файлов, но также проверяют строки.

  Среднестатистический пользователь сайта или приложения привык строить шаблоны в стиле командной оболочки, по крайней мере с простейшими подстановками наподобие `'?'` и `'*'`. Поэтому незнакомым с программированием пользователям проще вводить поисковые запросы с подстановочными символами, а не с регулярными выражениями, а программисту обрабатывать функцией fnmatch(), а не preg_match().

`flags`

  Параметр `flags` принимает комбинации следующих флагов, которые объединяют оператором | — побитового ИЛИ.

  Список флагов, которые поддерживает функция fnmatch()
  `Флаг` | Описание
  --- | ---
  `FNM_NOESCAPE` | Отключить экранирование обратным слешем — интерпретировать как обыкновенный символ.
  `FNM_PATHNAME` | Исключить совпадение слеша в строке с подстановочными символами шаблона.
  `FNM_PERIOD` | Исключить совпадение точки в начале строки с подстановочными символами шаблона.
  `FNM_CASEFOLD` | Сопоставлять строки без учёта регистра. Флаг — часть расширения поведения функции в наборе инструментов GNU.

### Возвращаемые значения

Функция возвращает `true`, если строка совпадает с шаблоном, иначе `false`.

### Примеры

Пример #1 Проверка соответствия названия цвета шаблону с подстановочными символами командной оболочки

    <?php

    if (fnmatch("*gr[ae]y", $color)) {
        echo "Какая-то форма серого цвета...";
    }

### Примечания

Внимание

Функция пока доступна только на POSIX-совместимых системах и в ОС Windows.

### Смотрите также

- glob() - Находит файловые пути, которые совпадают с шаблоном
- preg_match() - Выполняет проверку на соответствие регулярному выражению
- sscanf() - Разбирает строку по условиям формата
- printf() - Выводит отформатированную строку
- sprintf() - Возвращает отформатированную строку

# fopen

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

fopen — Открывает файл или URL-адрес

### Описание

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

Функция fopen() связывает именованный ресурс `filename` с потоком.

### Список параметров

`filename`

  При передаче в параметр `filename` аргумента в форме "scheme://..." функция распознает значение как URL-адрес, и PHP выполнит поиск обработчика протокола — «обёртки» — для этой схемы. Если для этого протокола не зарегистрировали ни одной обёртки, PHP выдаст замечание, чтобы помочь отследить потенциальную проблему в скрипте, а затем продолжит выполнение так, как если бы параметр `filename` указывал на обыкновенный файл.

  PHP попытается открыть поток для файла, если оценит путь `filename` как указатель на локальный файл. PHP считает файл, только если права доступа к файлу разрешают такой доступ. PHP применит дополнительные ограничения, если включили директиву open_basedir.

  PHP проверит, включили ли директиву allow_url_fopen, если оценит параметр `filename` как указатель на зарегистрированный протокол и этот протокол зарегистрировали как сетевой URL-адрес. PHP выдаст предупреждение и вызов функции fopen() завершится ошибкой, если директиву выключили.

  > Замечание:

  > Список поддерживаемых протоколов перечисляет раздел «Протоколы и обёртки». Отдельные протоколы, или `обёртки`, поддерживают опции `контекста` и (или) файла php.ini. Обратитесь к странице с описанием протокола, чтобы получить список опций, которые можно установить (например, значение директивы `user_agent` в файле php.ini использует обёртка `http`).

  На платформе Windows требуется экранировать обратные слеши в пути к файлу или указывать прямые слеши.

      <?php

      $handle = fopen("c:\\folder\\resource.txt", "r");

      ?>

`mode`

  Параметр `mode` указывает тип доступа к потоку. Доступны следующие режимы:

  Список возможных режимов для параметра `mode` функции fopen()
  `mode` | Описание
  --- | ---
  `'r'` | Открывает файл только для чтения; помещает указатель в начало файла.
  `'r+'` | Открывает файл для чтения и записи; помещает указатель в начало файла.
  `'w'` | Открывает файл только для записи; помещает указатель в начало файла и обрезает файл до нулевой длины. Функция пытается создать файл, если файл не существует.
  `'w+'` | Открывает файл для чтения и записи; в остальном ведёт себя аналогично флагу `'w'`.
  `'a'` | Открывает файл только для записи; помещает указатель в конец файла. Функция пытается создать файл, если файл не существует. В этом режиме функция fseek() не влияет на положение указателя, записи каждый раз добавляются в конец.
  `'a+'` | Открывает файл для чтения и записи; помещает указатель в конец файла. Функция пытается создать файл, если файл не существует. В этом режиме функция fseek() влияет только на позицию считывания, записи каждый раз добавляются в конец.
  `'x'` | Создаёт и открывает файл только для записи; помещает указатель в начало файла. Вызов функции fopen() закончится неудачей, вернёт `false` и выдаст ошибку уровня `E_WARNING`, если файл уже существует. Функция пытается создать файл, если файл не существует. Это эквивалентно указанию флагов `O_EXCL|O_CREAT` для внутреннего системного вызова `open(2)`.
  `'x+'` | Создаёт и открывает файл для чтения и записи; в остальном ведёт себя аналогично флагу `'x'`.
  `'c'` | Открывает файл только для записи. Функция создаст файл, если файл не существует. Файл не обрезается — в отличие от режима `'w'`, — а вызов этой функции не вызывает ошибку, как и в режиме `'x'`, если файл существует. Функция передвинет указатель в начало файла. Это полезно, если требуется получить рекомендательную блокировку (см. описание функции flock()) перед попыткой изменения файла, поскольку режим `'w'` иногда обрезает файл ещё до получения блокировки. Для обрезки файла вызывают функцию ftruncate() после запроса на блокировку, если требуется.
  `'c+'` | Открывает файл для чтения и записи; в остальном ведёт себя аналогично флагу `'c'`.
  `'e'` | Устанавливает флаг close-on-exec (закрытия при исполнении) для открытого дескриптора файла. Флаг доступен только в PHP, который скомпилировали на системах с поддержкой стандарта POSIX.1-2008.
  `'n'` | Устанавливает неблокирующий флаг для открытого файлового дескриптора. Флаг доступен только в PHP, который скомпилировали на системах с поддержкой стандарта POSIX.1-2008.

  > Замечание:

  > В разных семействах операционных систем действуют разные соглашения о завершении строк. Когда при записи текстового файла требуется вставить разрыв строки, необходимо использовать правильный для операционной системы символ (или символы). Системы на базе Unix в качестве символа конца строки используют символ `\n`, системы семейства Windows в качестве символов окончания строки используют последовательность символов `\r\n`, а системы семейства Macintosh (Mac OS Classic) — символ `\r`.

  > Файлы, в которые записали неправильные символы конца строк, «выглядят странно», когда такие файлы открывают в других приложениях.

  > ОС Windows предлагает флаг перевода в текстовый режим (`'t'`), который во время работы с файлом автоматически переведёт символ `\n` в символы `\r\n`. И наоборот — можно также использовать флаг `'b'`, чтобы принудительно включить двоичный режим, который не будет переводить данные. Чтобы использовать эти флаги, значение `'b'` или `'t'` указывают последним символом параметра `mode`.

  > Режим перевода по умолчанию — флаг `'b'`. При работе с простыми текстовыми файлами можно указать режим `'t'`, а для обозначения концов строк в скрипте использовать режим `\n`, но помнить, что файлы будут использоваться в приложениях наподобие старых версий «Блокнота». В остальных случаях лучше указывать флаг `'b'`.

  > Иногда при работе с двоичными файлами, для которых указали флаг 't', возникают странные проблемы с данными, включая повреждённые файлы изображений и проблемы с символами `\r\n`.

  > Замечание:

  > В целях переносимости также настоятельно рекомендуется переписать код, который использует или полагается на режим `'t'`, чтобы вместо этого режима использовались правильные окончания строк и режим `'b'`.

  > Замечание: Функция игнорирует параметр `mode` при работе с обёртками потоков php://output, php://input, php://stdin, php://stdout, php://stderr и php://fd.

`use_include_path`

  Для необязательного третьего параметра `use_include_path` разрешается устанавливать значение `true`, если также требуется искать файл в списке путей директивы include_path.

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает указатель на файл в случае успешного выполнения или `false`, если возникла ошибка

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
7.0.16, 7.1.2 | Добавили флаг `'e'`.

### Примеры

Пример #1 Примеры использования функции fopen()

    <?php

    $handle = fopen("/home/rasmus/file.txt", "r");
    $handle = fopen("/home/rasmus/file.gif", "wb");
    $handle = fopen("http://www.example.com/", "r");
    $handle = fopen("ftp://user:password@example.com/somefile.txt", "w");

    ?>

### Примечания

Внимание

При работе с сервером Microsoft IIS по SSL-протоколу разработчик сталкивается с тем, что IIS-сервер нарушает протокол путём закрытия соединения без отправки индикатора `close_notify`. PHP выдаст ошибку в виде сообщения «SSL: Fatal Protocol Error» при достижении конца данных. Чтобы избежать такого поведения, значение директивы error_reporting снижают до уровня, который не включает предупреждений уровня E_WARNING. PHP умеет обнаруживать ошибочное программное обеспечение IIS-сервера при открытии потока через обёртку `https://`, и подавляет предупреждение. За обнаружение и подавление предупреждения отвечает разработчик, который вызывает функцию fsockopen(), чтобы создать сокет `ssl://`.

> Замечание:

> Не забудьте проверить, что у серверного процесса есть доступ к файлам и каталогам, если при работе PHP в качестве версии серверного модуля возникли ошибки чтения или записи файлов.

> Замечание:

> Функция умеет принимать каталог как аргумент для параметра `filename`. До вызова функции fopen() иногда требуется вызов функции is_dir(), когда неизвестно, параметр `filename` — файл или каталог.

### Смотрите также

- Протоколы и обёртки
- fclose() - Закрывает открытый дескриптор файла
- fgets() - Получает строку из указателя на файл
- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- file() - Читает содержимое файла и помещает его в массив
- file_exists() - Проверяет, содержит ли файловая система файл или каталог
- is_readable() - Определяет существование файла и доступен ли он для чтения
- stream_set_timeout() - Устанавливает значение времени ожидания для потока
- popen() - Открывает файловый указатель процесса
- stream_context_create() - Создаёт контекст потока
- umask() - Изменяет текущую маску прав доступа для вновь созданных файлов и каталогов (umask)
- SplFileObject

# fpassthru

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

fpassthru — Выводит все оставшиеся данные из файлового указателя

### Описание

function fpassthru(resource `$stream`): int

Читает указанный файловый указатель с текущей позиции до EOF (конца файла) и записывает результат в буфер вывода.

Вам может понадобиться вызвать rewind(), чтобы сбросить файловый указатель на начало файла, если вы уже записывали данные в файл.

Если вы хотите просто сбросить содержимое файла в буфер вывода, предварительно не модифицируя его и не начиная с определённого смещения, вы можете воспользоваться readfile(), которая избавит вас от лишнего вызова fopen().

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Возвращает количество символов, прочтённых из `stream` и переданных на вывод.

### Примеры

Пример #1 Использование fpassthru() с бинарными файлами

    <?php

    // открываем файл в бинарном режиме
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // отправляем нужные заголовки
    header("Content-Type: image/png");
    header("Content-Length: " . filesize($name));

    // сбрасываем картинку и останавливаем выполнение скрипта
    fpassthru($fp);
    exit;

    ?>

### Примечания

> Замечание:

> При использовании fpassthru() на бинарном файле в Windows, вы должны убедиться в том, что открыли файл в бинарном режиме при помощи добавления `b` к режиму открытия файла, использованному в fopen().

> Рекомендуется использовать флаг `b` при работе с бинарными файлами, даже если ваша система этого не требует, чтобы обеспечить более высокую портируемость скриптов.

### Смотрите также

- readfile() - Выводит файл
- fopen() - Открывает файл или URL-адрес
- popen() - Открывает файловый указатель процесса
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — Формирует строку в CSV-формате и записывает строку в файловый указатель

### Описание

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

Функция fputcsv() формирует из массива полей `fields` строку в CSV-формате, завершает её символом перевода строки и записывает строку в файловый указатель `stream`.

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().
`fields`

  Массив строк (string).

`separator`

  Параметр `separator` устанавливает символ-разделитель полей и принимает только один однобайтовый символ.

`enclosure`

  Параметр `enclosure` устанавливает символ-ограничитель значения поля и принимает только один однобайтовый символ.

`escape`

  Параметр `escape` устанавливает символ экранирования и принимает только один однобайтовый символ или пустую строку. Пустая строка `""` отключает внутренний механизм экранирования.

  Внимание

  Обычно символ ограничителя значений — `enclosure` экранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранирования `escape`. Поэтому для стандартных значений параметра смысл значений `""` и `\"` одинаков. Символ экранирования — `escape` не несёт отдельного смысла, кроме экранирования символа ограничителя значений — `enclosure`; он даже не экранирует сам себя.

  Внимание

  Начиная с PHP 8.4.0 полагаться на значение по умолчанию, которое содержит параметр `escape`, не рекомендуют. Значение потребуется указать явно, позиционно или как именованный аргумент.

`eol`

  Необязательный параметр `eol` устанавливает пользовательскую последовательность конца строки.

Внимание

Строка в CSV-формате иногда перестаёт соответствовать стандарту » RFC 4180 или не выдерживает обмена информацией с PHP-функциями для работы с CSV-строками, если для символа экранирования `escape` устанавливают значение, которое отличается от пустой строки `""`. Значение по умолчанию для параметра `escape` — `"\\"`, поэтому рекомендуют явно указывать пустую строку. Значение по умолчанию изменят в будущей версии PHP, но не раньше PHP 9.0.

> Замечание:

> Функция заэкранирует символ ограничителя полей путём удвоения, если поле содержит символ ограничителя полей `enclosure`, если только перед ограничителем, который функция встретила в поле, не идёт символ экранирования `escape`.

### Возвращаемые значения

Функция возвращает длину строки, которую записала, или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если аргументы для разделителя полей `separator` или ограничителя значений `enclosure` содержат значение короче одного байта.

Функция выбрасывает ошибку ValueError, если длина значения аргумента `escape` не равна одному байту или передали пустую строку.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вызов функции без явной передачи значения в параметр `escape` устарел.
8.1.0 | Добавили необязательный параметр `eol`.
7.4.0 | Теперь параметр `escape` принимает пустую строку для отключения внутреннего механизма экранирования.

### Примеры

Пример #1 Пример форматирования и записи CSV-строки в файл функцией fputcsv()

    <?php

    $list = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"aaa"', '"bbb"']
    ];

    $fp = fopen('file.csv', 'w');

    foreach ($list as $fields) {
        fputcsv($fp, $fields, ',', '"', '');
    }

    fclose($fp);

    ?>

Пример запишет в файл `file.csv` следующие строки:

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### Смотрите также

- fgetcsv() - Получает строку из файлового указателя и разбирает по CSV-полям
- str_getcsv() - Разбирает CSV-строку в массив
- SplFileObject::fgetcsv() - Получает строку из файлового указателя и разбирает по CSV-полям
- SplFileObject::fputcsv() - Записывает массив полей как CSV-строки
- SplFileObject::setCsvControl() - Устанавливает символы разделителя, ограничителя и экранирования для CSV-полей
- SplFileObject::getCsvControl() - Получает символы разделителя, ограничителя и экранирования CSV-полей

# fputs

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

fputs — Псевдоним fwrite()

### Описание

Псевдоним функции fwrite().

# fread

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

fread — Читает файл в бинарно-безопасном режиме: как последовательность байтов

### Описание

function fread(resource `$stream`, int `$length`): string|false

Функция fread() считывает заданное параметром `length` количество байтов из файлового указателя, на который ссылается поток `stream`. Чтение останавливается, как только выполнилось одно из следующих условий:

- функция прочитала количество байтов, которое указали в параметре `length`
- наступило состояние EOF — конец файла
- при чтении сетевых потоков: функция получила доступ к пакету или истекло время ожидания сокета
- если читается буферизованный поток, который не представляет обычный файл, функция выполняет не больше одного чтения данных, размер которых в байтах равен размеру порции (обычно это 8192); в зависимости от ранее буферизованных данных размер возвращаемых данных может быть больше размера одной порции данных.

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`length`

  Параметр `length` указывает размер данных в байтах, которые считает функция.

### Возвращаемые значения

Функция возвращает прочитанную строку или `false`, если возникла ошибка.

### Примеры

Пример #1 Простой пример использования функции fread()

    <?php

    // Получаем содержимое файла в строку
    $filename = "/usr/local/something.txt";
    $handle = fopen($filename, "r");
    $contents = fread($handle, filesize($filename));
    fclose($handle);

    ?>

Пример #2 Пример побайтового чтения функцией fread()

Внимание

В системах, которые различают двоичные и текстовые файлы (например, ОС Windows), файл требуется открывать с включением флага «b» в параметр mode функции fopen().

    <?php

    $filename = "c:\\files\\somepic.gif";
    $handle = fopen($filename, "rb");
    $contents = fread($handle, filesize($filename));
    fclose($handle);

    ?>

Пример #3 Примеры удалённого чтения функцией fread()

Внимание

При чтении не из обычного локального файла, а, например, из потоков, которые возвращаются при чтении удалённых файлов или функциями popen() и fsockopen(), чтение остановится после получения функцией доступа к пакету. То есть данные лучше собирать порциями, как показывают примеры в следующих параграфах.

    <?php

    $handle = fopen("http://www.example.com/", "rb");
    $contents = stream_get_contents($handle);
    fclose($handle);

    ?>

    <?php

    $handle = fopen("http://www.example.com/", "rb");

    if (FALSE === $handle) {
        exit("Не удалось открыть поток по url адресу");
    }

    $contents = '';

    while (!feof($handle)) {
        $contents .= fread($handle, 8192);
    }

    fclose($handle);

    ?>

### Примечания

> Замечание:

> Когда требуется просто получить содержимое файла в виде строки, вызывают функцию file_get_contents(), поскольку её производительность выше, чем у кода в приведённых примерах.

> Замечание:

> Обратите внимание, функция fread() считывает данные с текущей позиции указателя файла. Пользуйтесь функцией ftell(), чтобы найти текущую позицию указателя и функцией rewind(), чтобы перемотать позицию указателя в начало.

### Смотрите также

- fwrite() - Записывает данные в файл в бинарно-безопасном режиме
- fopen() - Открывает файл или URL-адрес
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- popen() - Открывает файловый указатель процесса
- fgets() - Получает строку из указателя на файл
- fgetss() - Читает строку из файла и удаляет HTML-теги
- fscanf() - Обрабатывает данные из файла по условиям формата
- file() - Читает содержимое файла и помещает его в массив
- fpassthru() - Выводит все оставшиеся данные из файлового указателя
- fseek() - Перемещает позицию файлового указателя
- ftell() - Возвращает текущую позицию указателя чтения/записи файла
- rewind() - Отматывает позицию файлового указателя
- unpack() - Распаковывает данные из бинарной строки

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — Обрабатывает данные из файла по условиям формата

### Описание

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

Функция fscanf() аналогична функции sscanf(), но берёт входные данные из файла, который связан с потоком `stream`, и интерпретирует входные данные по условиям формата `format`.

Любой пробельный символ в строке формата эквивалентен любому пробельному символу во входящем потоке. Это означает, что даже символ табуляции (`\t`) в строке формата может соответствовать одному символу пробела в потоке входных данных.

Каждый вызов функции fscanf() считывает одну строку из файла.

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`format`

  Формат интерпретации строки `string`, который описывает документация к функции sprintf() со следующими отличиями:

  - Функция не учитывает языковые настройки.
  - Параметр не поддерживает флаги `F`, `g`, `G` и `b`.
  - Флаг `D` обозначает десятичное число.
  - Флаг `i` обозначает целое число с определением системы счисления.
  - Флаг `n` обозначает количество символов, которые функция уже обработала.
  - Флаг `s` останавливает чтение при любом пробельном символе.
  - Символ `*` вместо спецификатора преобразования `argnum$` подавляет присваивание этого спецификатора преобразования.
`vars`
  Необязательные переменные, которым функция присвоит значения.

### Возвращаемые значения

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

Если параметр `format` ожидает больше подстрок, чем доступно в параметре `string`, вернётся значение `null`. Функция вернёт `false`, если возникнут другие ошибки.

Функция возвращает `-1`, если переданы необязательные аргументы и достигнут конец входных данных, считанных из `stream`, до того, как удалось разобрать хотя бы одно значение.

### Примеры

Пример #1 Пример использования функции fscanf()

    <?php

    $handle = fopen("users.txt", "r");

    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        //... совершаем какие-либо действия над значениями
    }

    fclose($handle);

    ?>

Пример #2 Содержимое файла users.txt

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### Смотрите также

- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fgets() - Получает строку из указателя на файл
- fgetss() - Читает строку из файла и удаляет HTML-теги
- sscanf() - Разбирает строку по условиям формата
- printf() - Выводит отформатированную строку
- sprintf() - Возвращает отформатированную строку

# fseek

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

fseek — Перемещает позицию файлового указателя

### Описание

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Функция устанавливает положение указателя в файле, на который ссылается поток `stream`. Новое положение указателя измеряется в байтах от начала файла и рассчитывается путём прибавления значения параметра `offset` к позиции параметра `whence`.

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

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`offset`

  Смещение.

  В параметр `offset` передают отрицательное значение, а для параметра `whence` устанавливают значение `SEEK_END`, чтобы перейти к позиции перед концом файла.

`whence`

  Параметр `whence` принимает следующие значения:

  - `SEEK_SET` — Перемещает указатель в положение, равное количеству байтов смещения `offset` от начала файла.
  - `SEEK_CUR` — Перемещает указатель вперёд — в положение, равное количеству байтов смещения `offset` от текущей позиции.
  - `SEEK_END` — Перемещает указатель за пределы конца файла — в положение, равное количеству байтов смещения `offset` от конца файла.

### Возвращаемые значения

Функция возвращает `0`, если выполнилась успешно; иначе возвращает значение `-1`.

Внимание

Функция имитирует поведение функции языка C с тем же названием и возвращает нестандартные значения, непохожие на те, которые ожидались бы в PHP.

### Примеры

Пример #1 Пример использования функции fseek()

    <?php

    $fp = fopen('somefile.txt', 'r');

    // Читаем фрагмент данных
    $data = fgets($fp, 4096);

    // Перемещаемся назад к началу файла —
    // то же, что и вызов rewind($fp);
    fseek($fp, 0);

    ?>

### Примечания

> Замечание:

> Функция будет только дописывать данные в конец файла, независимо от позиции указателя в файле, а результат вызова функции fseek() будет неопределённым, если файл открыли в режиме `a` — только для чтения или в режиме `a+` — для чтения или добавления данных в конец файла.

> Замечание:

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

### Смотрите также

- ftell() - Возвращает текущую позицию указателя чтения/записи файла
- rewind() - Отматывает позицию файлового указателя

# fstat

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

fstat — Получает информацию о файле по указателю открытого файла

### Описание

function fstat(resource `$stream`): array|false

Функция собирает статистическую информацию об открытом файле по файловому указателю `stream`. Эта функция работает как функция stat(), за исключением того, что эта функция работает с открытым файловым указателем, а не с именем файла.

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().

### Возвращаемые значения

Функция возвращает массив со статистической информацией файла; формат массива подробно описывает страница функции stat(). Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции fstat()

    <?php

    // Открываем файл
    $fp = fopen("/etc/passwd", "r");

    // Собираем статистику
    $fstat = fstat($fp);

    // Закрываем файл
    fclose($fp);

    // Отображаем только ассоциативную часть
    print_r(array_slice($fstat, 13));

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [dev] => 771
        [ino] => 488704
        [mode] => 33188
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 1114
        [atime] => 1061067181
        [mtime] => 1056136526
        [ctime] => 1056136526
        [blksize] => 4096
        [blocks] => 8
    )

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

# fsync

(PHP 8 >= 8.1.0)

fsync — Синхронизирует изменения в файле (включая метаданные)

### Описание

function fsync(resource `$stream`): bool

Функция синхронизирует изменения в файле, включая его метаданные. Она похожа на fflush(), но помимо этого даёт инструкции операционной системе о записи на накопитель.

### Список параметров

`stream`
  Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования fsync()

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'тестовые данные');
    fwrite($stream, "\r\n");
    fwrite($stream, 'дополнительные данные');

    fsync($stream);
    fclose($stream);
    ?>

### Смотрите также

- fdatasync() - Синхронизирует данные (но не метаданные) с файлом
- fflush() - Сбрасывает буфер вывода в файл

# ftell

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

ftell — Возвращает текущую позицию указателя чтения/записи файла

### Описание

function ftell(resource `$stream`): int|false

Возвращает позицию файлового указателя `stream`.

### Список параметров

`stream`

  Файловый указатель должен быть действующим указателем на поток, открытый функциями fopen() или popen(). ftell() возвращает неопределённые результаты для потоков, разрешающих только запись в конец (открытых с флагом "a").

### Возвращаемые значения

Возвращает позицию файлового указателя `stream` в виде целого числа, то есть его смещение в файловом потоке.

При возникновении ошибки возвращает `false`.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Примеры

Пример #1 Пример использования функции ftell()

    <?php

    // открываем файл и читаем немного данных
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // где же мы ?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### Смотрите также

- fopen() - Открывает файл или URL-адрес
- popen() - Открывает файловый указатель процесса
- fseek() - Перемещает позицию файлового указателя
- rewind() - Отматывает позицию файлового указателя

# ftruncate

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

ftruncate — Урезает файл до указанной длины

### Описание

function ftruncate(resource `$stream`, int `$size`): bool

Принимает файловый указатель `stream` и урезает соответствующий файл до размера `size`.

### Список параметров

`stream`

  Файловый указатель.

  > Замечание:

  > `stream` должен быть открыт для записи.

`size`

  Размер файла, до которого он будет обрезан.

  > Замечание:

  > Если `size` больше текущего размера файла, то файл будет дополнен нулевыми байтами.

  > Если `size` меньше текущего размера файла, то файл будет обрезан до этого размера.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример обрезания файла

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### Примечания

> Замечание:

> Файловый указатель не меняется.

### Смотрите также

- fopen() - Открывает файл или URL-адрес
- fseek() - Перемещает позицию файлового указателя

# fwrite

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

fwrite — Записывает данные в файл в бинарно-безопасном режиме

### Описание

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

Функция fwrite() записывает содержимое `data` в файловый поток `stream`.

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`data`

  Строка, которую нужно записать.

`length`

  Функция остановит запись через `length` байтов, если значение `length` — целое число (int), или когда достигнет конца строки `data`, в зависимости от того, что произойдёт раньше.

### Возвращаемые значения

Функция fwrite() возвращает количество записанных байтов или `false`, если возникла ошибка.

### Ошибки

Функция fwrite() выдаёт ошибку уровня `E_WARNING` в случае ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `length` теперь принимает значение `null`.

### Примеры

Пример #1 Простой пример использования функции fwrite()

    <?php

    $filename = 'test.txt';
    $somecontent = "Добавить это к файлу\n";

    // Вначале убедимся, что файл существует и доступен для записи.
    if (is_writable($filename)) {

        // В примере мы открываем $filename в режиме «записи в конец».
        // Поэтому смещение установлено в конец файла и
        // значение переменной $somecontent допишется в конец файла при вызове функции fwrite().
        if (!$fp = fopen($filename, 'a')) {
             echo "Не могу открыть файл ($filename)";
             exit;
        }

        // Записываем значение переменной $somecontent в открытый файл.
        if (fwrite($fp, $somecontent) === FALSE) {
            echo "Не могу произвести запись в файл ($filename)";
            exit;
        }

        echo "Ура! Записали ($somecontent) в файл ($filename)";

        fclose($fp);
    } else {
        echo "Файл $filename недоступен для записи";
    }

    ?>

### Примечания

> Замечание:

> Запись в сетевой поток может прекратиться до завершения записи строки. Значение, которое возвращает функция fwrite(), можно проверить:

>     <?php

>     function fwrite_stream($fp, $string) {
>         for ($written = 0; $written < strlen($string); $written += $fwrite) {
>             $fwrite = fwrite($fp, substr($string, $written));
>             if ($fwrite === false) {
>                 return $written;
>             }
>         }
>         return $written;
>     }

>     ?>

> Замечание:

> В системах, которые различают двоичные и текстовые файлы (например, операционные системы Windows), файл должен быть открыт с флагом «b» в конце аргумента mode функции fopen().

> Замечание:

> Если функция fopen() открыла дескриптор `stream` в режиме «добавление в конец», вызовы функции fwrite() будут атомарными (если размер `data` не превышает размер блока файловой системы, на некоторых платформах, и пока файл хранится в локальной файловой системе). То есть не нужно блокировать ресурс функцией flock() перед вызовом функции fwrite(); данные будут записаны без прерываний.

> Замечание:

> При повторной записи в файловый указатель, данные будут добавлены в конец файла:

>     <?php

>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // Теперь файл 'data.txt' содержит 123, а не 23!

>     ?>

### Смотрите также

- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fopen() - Открывает файл или URL-адрес
- fsockopen() - Открывает соединение с сокетом интернет- или Unix-домена
- popen() - Открывает файловый указатель процесса
- file_get_contents() - Считывает содержимое файла в строку
- pack() - Упаковывает данные в двоичную строку

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — Находит файловые пути, которые совпадают с шаблоном

### Описание

function glob(string `$pattern`, int `$flags` = 0): array|false

Функция glob() ищет в текущей файловой системе пути, которые совпали с шаблоном `pattern` по правилам функции glob() стандартной C-библиотеки libc, которые аналогичны правилам стандартных командных оболочек.

Поведение функции в системах Unix и macOS определяется реализацией функции glob() в системе. В ОС Windows реализация функции соответствует определению 1003.2 стандарта POSIX для функции glob() и включает расширение для обработки соглашения `[!...]` для отрицания диапазона.

### Список параметров

`pattern`

  Шаблон. Параметр не раскрывает символы тильды и не подставляет параметры.

  Специальные символы:

  - `*` — Соответствует нулю или большему количеству символов.
  - `?` — Соответствует ровно одному символу (любому символу).
  - `[...]` — Соответствует одному символу из группы символов. Символ соответствует символу, который не входит в группу, если первый символ `!`.
  - `{a,b,c}` — Соответствует одной строке из группы строк, разделённых запятой, если указали флаг `GLOB_BRACE`.
  - `\` — Экранирует следующий символ, если только не указали флаг `GLOB_NOESCAPE`.
`flags`

  Константа семейства `GLOB_*`.

### Возвращаемые значения

Функция возвращает массив с совпадениями путей файлов или директорий, пустой массив, если файлы не совпали, или `false`, если возникла ошибка. Названия отсортируются в буквенно-цифровом порядке, если только не указали флаг `GLOB_NOSORT`.

### Примеры

Пример #1 Способ подмены функцией glob() функции opendir() и дружественных функции

    <?php

    foreach (glob("*.txt") as $filename) {
        echo "Размер файла $filename в байтах — " . filesize($filename) . "\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    Размер файла funclist.txt в байтах — 44686
    Размер файла funcsummary.txt в байтах — 267625
    Размер файла quickref.txt в байтах — 137820

Пример #2 Пример с усложнённым шаблоном

    <?php

    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: Функция недоступна в системах наподобие старой Sun OS.

### Смотрите также

- opendir() - Открывает дескриптор каталога
- readdir() - Получает элемент каталога по его дескриптору
- closedir() - Закрывает дескриптор каталога
- fnmatch() - Проверяет совпадение имени файла с шаблоном

# is_dir

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

is_dir — Определяет, указывает ли путь на каталог

### Описание

function is_dir(string `$filename`): bool

Функция определяет, ведёт ли путь к каталогу.

### Список параметров

`filename`

  Путь к файлу. При передаче в параметр `filename` относительного пути функция проверит путь относительно текущей рабочей директории. При передаче в параметр `filename` символической или жёсткой ссылки функция разрешит ссылку и проверит, указывает ли на каталог целевой путь ссылки. Директива open_basedir дополнительно ограничит для PHP доступ к дереву каталогов, если настройку включили в файле конфигурации.

### Возвращаемые значения

Функция возвращает `true`, если путь ведёт к каталогу, иначе возвращает `false`.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример проверки пути к каталогу функцией is_dir()

    <?php

    var_dump(is_dir('a_file.txt'));
    var_dump(is_dir('bogus_dir/abc'));

    var_dump(is_dir('..')); // Проверить, указывает ли на каталог путь уровнем выше

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(true)

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- chdir() - Изменяет рабочий каталог
- dir() - Возвращает экземпляр класса Directory
- opendir() - Открывает дескриптор каталога
- is_file() - Сообщает, ведёт ли путь к стандартному файлу
- is_link() - Сообщает, указывает ли путь на символическую ссылку

# is_executable

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

is_executable — Определяет, является ли файл исполняемым

### Описание

function is_executable(string `$filename`): bool

Определяет, является ли файл исполняемым.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает `true`, если файл существует и является исполняемым, или `false` в случае возникновения ошибки. В POSIX-системах файл является исполняемым, если установлен исполняемый бит прав доступа к файлу. Для Windows смотрите примечание ниже.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции is_executable()

    <?php

    $file = '/home/vincent/somefile.sh';

    if (is_executable($file)) {
        echo $file.' является исполняемым';
    } else {
        echo $file.' не является исполняемым';
    }

    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

> Замечание: В Windows файл считается исполняемым, если это по-настоящему исполняемый файл, как сообщает Win API `GetBinaryType()`; Для обратной совместимости файлы с расширением .bat или .cmd также считаются исполняемыми. До PHP 7.4.0 любой непустой файл с расширением .exe или .com считался исполняемым. Обратите внимание, что PATHEXT не имеет отношения к is_executable().

### Смотрите также

- is_file() - Сообщает, ведёт ли путь к стандартному файлу
- is_link() - Сообщает, указывает ли путь на символическую ссылку

# is_file

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

is_file — Сообщает, ведёт ли путь к стандартному файлу

### Описание

function is_file(string `$filename`): bool

Функция определяет, ведёт ли путь к стандартному файлу. Функция разрешит символическую ссылку и вернёт информацию о файле, на который указывает ссылка, если в аргументе `filename` указали путь к символической ссылке.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если локальная система содержит стандартный файл по заданному пути, иначе возвращает `false`.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример проверки пути к стандартному файлу функцией is_file()

    <?php

    var_dump(is_file('a_file.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- is_dir() - Определяет, указывает ли путь на каталог
- is_link() - Сообщает, указывает ли путь на символическую ссылку
- SplFileInfo

# is_link

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

is_link — Сообщает, указывает ли путь на символическую ссылку

### Описание

function is_link(string `$filename`): bool

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

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Функция возвращает `true`, если файл по заданному пути существует и путь указывает на символическую ссылку, иначе возвращает `false`.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Создаём путь к файлу и проверяем, указывает ли путь на символическую ссылку

    <?php

    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }

    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- is_dir() - Определяет, указывает ли путь на каталог
- is_file() - Сообщает, ведёт ли путь к стандартному файлу
- readlink() - Возвращает файл, на который указывает символическая ссылка
- symlink() - Создаёт символическую ссылку

# is_readable

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

is_readable — Определяет существование файла и доступен ли он для чтения

### Описание

function is_readable(string `$filename`): bool

Возвращает `true`, если файл существует и доступен для чтения.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Возвращает `true`, если файл или директория, указанная в `filename` существует и доступна для чтения, иначе возвращает `false`.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции is_readable()

    <?php
    $filename = 'test.txt';
    if (is_readable($filename)) {
        echo 'Файл доступен для чтения';
    } else {
        echo 'Файл недоступен для чтения';
    }
    ?>

### Примечания

Не забывайте, что PHP может обращаться к файлам от имени пользователя, от которого запущен веб-сервер (часто 'nobody').

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

> Замечание:

> Проверка производится с использованием реальных UID/GID вместо эффективных.

Эта функция может возвращать `true` для директорий. Чтобы отличить файл от директории можно воспользоваться функцией is_dir().

### Смотрите также

- is_writable() - Определяет, доступен ли файл для записи
- file_exists() - Проверяет, содержит ли файловая система файл или каталог
- fgets() - Получает строку из указателя на файл

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — Определяет, был ли файл загружен при помощи HTTP POST

### Описание

function is_uploaded_file(string `$filename`): bool

Возвращает `true`, если файл `filename` был загружен при помощи HTTP POST. Это полезно для удостоверения того, что злонамеренный пользователь не пытается обмануть скрипт так, чтобы он работал с файлами, с которыми работать не должен - к примеру, /etc/passwd.

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

Для правильной работы функции is_uploaded_file() нужен аргумент вида $_FILES['userfile']['tmp_name'], - имя загруженного файла на клиентской машине $_FILES['userfile']['name'] не подходит.

### Список параметров

`filename`

  Имя проверяемого файла.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции is_uploaded_file()

    <?php

    if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
       echo "Файл ". $_FILES['userfile']['name'] ." успешно загружен.\n";
       echo "Отображаем содержимое\n";
       readfile($_FILES['userfile']['tmp_name']);
    } else {
       echo "Возможная атака с участием загрузки файла: ";
       echo "файл '". $_FILES['userfile']['tmp_name'] . "'.";
    }

    ?>

### Смотрите также

- move_uploaded_file() - Перемещает загруженный файл в новое место
- $_FILES
- Простой пример использования можно найти в разделе "Загрузка файлов на сервер".

# is_writable

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

is_writable — Определяет, доступен ли файл для записи

### Описание

function is_writable(string `$filename`): bool

Возвращает `true`, если файл `filename` существует и доступен для записи. Аргумент filename может быть именем директории, что позволяет вам проверять директории на доступность для записи.

Не забывайте, что PHP может обращаться к файлу от имени того пользователя, от которого запущен веб-сервер (обычно 'nobody').

### Список параметров

`filename`

  Проверяемый файл.

### Возвращаемые значения

Возвращает `true`, если `filename` существует и доступен для записи.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования is_writable()

    <?php
    $filename = 'test.txt';
    if (is_writable($filename)) {
        echo 'Файл доступен для записи';
    } else {
        echo 'Файл недоступен для записи';
    }
    ?>

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- is_readable() - Определяет существование файла и доступен ли он для чтения
- file_exists() - Проверяет, содержит ли файловая система файл или каталог
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме

# is_writeable

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

is_writeable — Псевдоним is_writable()

### Описание

Псевдоним функции is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — Изменяет группу, которой принадлежит символическая ссылка

### Описание

function lchgrp(string `$filename`, string|int `$group`): bool

Пытается изменить группу, которой принадлежит символическая ссылка `filename` на указанную в `group`.

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

### Список параметров

`filename`

  Путь к ссылке.

`group`

  Группа, указанная по имени или номеру.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример изменения группы символической ссылки

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: Для Windows-платформ функцию не реализовали.

### Смотрите также

- chgrp() - Изменяет группу файла
- lchown() - Изменяет владельца символической ссылки
- chown() - Изменяет владельца файла
- chmod() - Изменяет режим доступа к файлу

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — Изменяет владельца символической ссылки

### Описание

function lchown(string `$filename`, string|int `$user`): bool

Пытается изменить владельца символической ссылки `filename` на указанного в `user` пользователя.

Только суперпользователь может изменять владельца символической ссылки.

### Список параметров

`filename`

  Путь к файлу.

`user`

  Имя пользователя или номер.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Изменение владельца символической ссылки

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: Для Windows-платформ функцию не реализовали.

### Смотрите также

- chown() - Изменяет владельца файла
- lchgrp() - Изменяет группу, которой принадлежит символическая ссылка
- chgrp() - Изменяет группу файла
- chmod() - Изменяет режим доступа к файлу

# link

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

link — Создаёт жёсткую ссылку

### Описание

function link(string `$target`, string `$link`): bool

link() создаёт жёсткую ссылку.

### Список параметров

`target`

  Цель ссылки.

`link`

  Имя ссылки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция завершается с ошибкой и выдаёт `E_WARNING`, если `link` уже существует или если `target` не существует.

### Примеры

Пример #1 Создание простой жёсткой ссылки

    <?php
    $target = 'source.ext'; // Это уже существующий файл
    $link = 'newfile.ext'; // Это файл, который вы хотите привязать к первому

    link($target, $link);
    ?>

### Примечания

> Замечание: Функция неприменима для работы с удалёнными файлами, поскольку файл должен быть доступен через файловую систему сервера.

> Замечание: Только для Windows: Для данной функции необходимо, чтобы PHP был запущен в привилегированном режиме или с отключённым UAC.

### Смотрите также

- symlink() - Создаёт символическую ссылку
- readlink() - Возвращает файл, на который указывает символическая ссылка
- linkinfo() - Возвращает информацию о ссылке
- unlink() - Удаляет файл

# linkinfo

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

linkinfo — Возвращает информацию о ссылке

### Описание

function linkinfo(string `$path`): int|false

Возвращает информацию о ссылке.

Эта функция используется для определения, существует ли ссылка (на которую указывает `path`) на самом деле (используя тот же метод, что и макрос S_ISLNK, определённый в stat.h).

### Список параметров

`path`

  Путь к ссылке.

### Возвращаемые значения

linkinfo() возвращает поле `st_dev` структуры stat из Unix C, которую возвращает системный вызов `lstat`. Возвращает неотрицательное целое число в случае успешного выполнения, -1 в случае, если ссылка не была найдена, или `false` в случае возникновения ошибки open.base_dir.

### Примеры

Пример #1 Пример использования функции linkinfo()

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### Смотрите также

- symlink() - Создаёт символическую ссылку
- link() - Создаёт жёсткую ссылку
- readlink() - Возвращает файл, на который указывает символическая ссылка

# lstat

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

lstat — Возвращает информацию о файле или символической ссылке

### Описание

function lstat(string `$filename`): array|false

Собирает статистику на файл или символическую ссылку с именем `filename`.

### Список параметров

`filename`

  Путь к файлу или символической ссылке.

### Возвращаемые значения

Обратитесь к странице руководства функции stat() для получения информации о структуре массива, который возвращает lstat(). Эта функция идентична функции stat(), за исключением того, что если `filename` является символической ссылкой, возвращается статус символической ссылки, а не того файла, на который она указывает.

Возвращает `false` в случае возникновения ошибки.

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Сравнение функций stat() и lstat()

    <?php
    symlink('uploads.php', 'uploads');

    // Отличия между uploads.php и uploads
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

Вывод приведённого примера будет похож на:

Отличия в возвращаемых результатах между этими файлами.

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### Примечания

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- stat() - Возвращает информацию о файле

# mkdir

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

mkdir — Создаёт директорию

### Описание

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

Пытается создать директорию, заданную в `directory`.

### Список параметров

`directory`

  Путь к директории.

  Подсказка

  Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

`permissions`

  По умолчанию принимает значение 0777, что означает самые широкие права. Больше информации о правах доступа можно узнать на странице руководства функции chmod().

  > Замечание:

  > Аргумент `permissions` игнорируется в Windows.

  Обратите внимание, что аргумент `permissions` необходимо задавать в виде восьмеричного числа (первой цифрой должен быть ноль). На аргумент `permissions` также влияет текущее значение umask, которое можно изменить при помощи umask().

`recursive`

  Если указано значение `true`, то все родительские каталоги для указанного параметра `directory` также будут созданы, с теми же разрешениями.

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

> Замечание:

> Если создаваемый каталог уже существует, это считается ошибкой и будет возвращено значение `false`. Используйте функцию is_dir() или file_exists(), чтобы проверить, существует ли уже каталог, прежде чем пытаться его создать.

### Ошибки

Выдаёт ошибку уровня `E_WARNING`, если директория уже существует.

Выдаёт ошибку уровня `E_WARNING`, если соответствующие права доступа блокируют создание директории.

### Примеры

Пример #1 Пример использования функции mkdir()

    <?php
    mkdir("/path/to/my/dir", 0700);
    ?>

Пример #2 Использование mkdir() с параметром `recursive`

    <?php
    // Желаемая структура папок
    $structure = './depth1/depth2/depth3/';

    // Для создания вложенной структуры необходимо указать параметр
    // $recursive в mkdir().

    if (!mkdir($structure, 0777, true)) {
        die('Не удалось создать директории...');
    }

    // ...
    ?>

### Смотрите также

- is_dir() - Определяет, указывает ли путь на каталог
- rmdir() - Удаляет директорию
- umask() - Изменяет текущую маску прав доступа для вновь созданных файлов и каталогов (umask)

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — Перемещает загруженный файл в новое место

### Описание

function move_uploaded_file(string `$from`, string `$to`): bool

Эта функция проверяет, является ли файл `from` загруженным на сервер (переданным по протоколу HTTP POST). Если файл действительно загружен на сервер, он будет перемещён в место, указанное в аргументе `to`.

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

### Список параметров

`from`

  Путь к загруженному файлу.

`to`

  Путь, по которому необходимо переместить файл.

### Возвращаемые значения

В случае успешного выполнения возвращает `true`.

Если `from` не является загруженным файлом, никаких действий не предпринимается и move_uploaded_file() возвращает `false`.

Если `from` является загруженным файлом, но не может быть перемещён по каким-либо причинам, никаких действий не предпринимается и move_uploaded_file() возвращает `false`. Кроме того, отображается предупреждение.

### Примеры

Пример #1 Загрузка нескольких файлов

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() может предотвратить атаку на файловую систему;
            // может быть целесообразным дополнительно проверить имя файла
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### Примечания

> Замечание:

> Функция move_uploaded_file() принимает во внимание open_basedir. Тем не менее, ограничения накладываются лишь на параметр `to`, чтобы разрешить перемещение загруженных файлов, так как параметр `from` может конфликтовать с этими ограничениями. move_uploaded_file() гарантирует безопасность этой операции, работая лишь с теми файлами, которые были загружены через PHP.

Внимание

Если результирующий файл уже существует, он будет перезаписан.

### Смотрите также

- is_uploaded_file() - Определяет, был ли файл загружен при помощи HTTP POST
- rename() - Переименовывает файл или директорию
- Простой пример использования этой функции можно найти в разделе "Загрузка файлов на сервер"

# parse_ini_file

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

parse_ini_file — Обрабатывает конфигурационный файл

### Описание

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() загружает ini-файл, указанный в аргументе `filename`, и возвращает его настройки в виде ассоциативного массива.

Структура ini-файла похожа на структуру php.ini.

Внимание

Функция не должна использоваться с недоверенными входными данными, за исключением случаев, когда значение параметра `scanner_mode` равно `INI_SCANNER_RAW`, поскольку обработанные данные могут содержать значения конфиденциальных констант, таких как константы, содержащие пароль базы данных.

### Список параметров

`filename`

  Имя обрабатываемого ini-файла. Если используется относительный путь, он оценивается относительно текущего рабочего каталога, а затем include_path.

`process_sections`

  Установив параметр `process_sections` в `true`, вы получаете многомерный массив, который включает как название отдельных настроек, так и секции. По умолчанию `process_sections` равен `false`

`scanner_mode`

  Может принимать следующие значения: `INI_SCANNER_NORMAL` (по умолчанию) или `INI_SCANNER_RAW`. Если указано значение `INI_SCANNER_RAW`, то значения опций не будут обрабатываться.

  С PHP 5.6.1 также доступен режим `INI_SCANNER_TYPED`. В этом режиме типы boolean, null и integer сохраняются, если возможно. Строковые значения `"true"`, `"on"` и `"yes"` преобразуются в `true`, а значения `"false"`, `"off"`, `"no"` и `"none"` — в `false`. Значение `"null"` преобразовывается в `null`. Кроме этого, числовые строки преобразуются в целые числа, если возможно.

### Возвращаемые значения

В случае успешного выполнения, настройки возвращаются в виде ассоциативного массива (array). В случае возникновения ошибки возвращается `false`.

### Примеры

Пример #1 Содержимое sample.ini

    ; Это пример файла настроек
    ; Комментарии начинаются с ';', как в php.ini

    [first_section]
    one = 1
    five = 5
    animal = BIRD

    [second_section]
    path = "/usr/local/bin"
    URL = "http://www.example.com/~username"

    [third_section]
    phpversion[] = "5.0"
    phpversion[] = "5.1"
    phpversion[] = "5.2"
    phpversion[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

Пример #2 Пример использования функции parse_ini_file()

Константы (но не "магические константы" вроде `__FILE__`) также могут обрабатываться в ini-файлах, так что если вы объявите константу в виде значения для ini-файла до вызова parse_ini_file(), то константа будет корректно обработана. Только значения опций будут обрабатываться и значение должно быть просто константой. Например:

    <?php

    define('BIRD', 'Птица додо');

    // Обрабатываем без секций
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Обрабатываем с секциями
    $ini_array = parse_ini_file("sample.ini", true);
    print_r($ini_array);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [one] => 1
        [five] => 5
        [animal] => Птица додо
        [path] => /usr/local/bin
        [URL] => http://www.example.com/~username
        [phpversion] => Array
            (
                [0] => 5.0
                [1] => 5.1
                [2] => 5.2
                [3] => 5.3
            )

        [urls] => Array
            (
                [svn] => http://svn.php.net
                [git] => http://git.php.net
            )

    )
    Array
    (
        [first_section] => Array
            (
                [one] => 1
                [five] => 5
                [animal] => Птица додо
            )

        [second_section] => Array
            (
                [path] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [third_section] => Array
            (
                [phpversion] => Array
                    (
                        [0] => 5.0
                        [1] => 5.1
                        [2] => 5.2
                        [3] => 5.3
                    )

                [urls] => Array
                    (
                        [svn] => http://svn.php.net
                        [git] => http://git.php.net
                    )

            )

    )

Пример #3 Обработка файла php.ini функцией parse_ini_file()

    <?php
    // Простая функция для сравнения результатов
    function yesno($expression)
    {
        return($expression ? 'Да' : 'Нет');
    }

    // Получаем путь к php.ini с помощью функции php_ini_loaded_file()
    $ini_path = php_ini_loaded_file();

    // Обрабатываем php.ini
    $ini = parse_ini_file($ini_path);

    // Выводим и сравниваем значения, учтите, что использование get_cfg_var()
    // даст одинаковые результаты для используемых здесь значений parsed (загруженное из файла) и loaded (используемое в данный момент)
    echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

Вывод приведённого примера будет похож на:

    (parsed) magic_quotes_gpc = Да
    (loaded) magic_quotes_gpc = Да

Пример #4 Интерполяция значений

Помимо оценки констант, некоторые символы имеют особое значение в значении ini-файлах. Кроме того, переменные среды и ранее определённые параметры конфигурации (смотрите get_cfg_var()) могут быть прочитаны с использованием синтаксиса `${}`.

    ; | используется для побитового ИЛИ
    three = 2|3

    ; & используется для побитового AND
    four = 6&5

    ; ^ используется для побитового XOR
    five = 3^6

    ; ~ используется для побитового отрицания
    negative_two = ~1

    ; () используется для группировки
    seven = (8|7)&(6|5)

    ; Интерполируйте переменную окружения PATH
    path = ${PATH}

    ; Интерполируйте параметр конфигурации 'memory_limit'
    configured_memory_limit = ${memory_limit}

Пример #5 Экранирование символов

Некоторые символы имеют особое значение в строках с двойными кавычками и должны быть экранированы префиксом обратной косой черты. Прежде всего, это двойная кавычка `"` в качестве маркера границы и сама обратная косая черта `\` (если за ней следует один из специальных символов):

    quoted = "Она сказала \"Именно моя точка зрения\"." ; Результатом является строка с кавычками.
    hint = "Используйте \\\", чтобы избежать двойных кавычек" ; Результат: Используйте \", чтобы избежать двойных кавычек

Для путей, подобных Windows, сделано исключение: можно не экранировать обратную косую черту в конце, если за строкой в кавычках следует разрыв строки:

    save_path = "C:\Temp\"

Если нужно экранировать двойные кавычки, за которыми следует перенос строки в многострочном значении, можно использовать конкатенацию значений следующим образом (за одной строкой в двойных кавычках непосредственно следует другая):

    long_text = "Lorem \"ipsum\"""
     dolor" ; Результат: Lorem "ipsum"\n dolor

Другой символ со специальным значением - это `$` (знак доллара). Он должен быть экранирован, если за ним следует открытая фигурная скобка:

    code = "\${test}"

Экранирующие символы не поддерживаются в режиме `INI_SCANNER_RAW` (в этом режиме все символы обрабатываются "как есть").

Обратите внимание, что синтаксический анализатор ini не поддерживает стандартные последовательности экранирования (`\n`, `\t` и т.д.). При необходимости выполните постобработку результата parse_ini_file() с помощью функции stripcslashes().

### Примечания

> Замечание:

> Эта функция не имеет никакого отношения к файлу php.ini. К моменту выполнения вашего скрипта, он уже обработан. Эта функция может быть использована для загрузки настроек вашего собственного приложения.

> Замечание:

> Если значение в ini-файле содержит прочие символы, кроме букв и цифр, оно должно заключаться в двойные кавычки (").

> Замечание: Существует зарезервированные слова, которые нельзя использовать в качестве ключей в ini-файлах. Такими словами являются: `null`, `yes`, `no`, `true`, `false`, `on`, `off`, `none`. Значения `null`, `off`, `no` и `false` преобразуются в `""`, а значения `on`, `yes` и `true` в `"1"` , но только если не используется режим `INI_SCANNER_TYPED`. Символы `?{}|&~!()^"` не должны использоваться в ключах и иметь какой-либо особый смысл в значениях.

> Замечание:

> Записи без знака равенства игнорируются. Например, "foo" игнорируется, тогда как "bar =" обрабатывается и добавляется с пустым значением. Например, в MySQL есть опция "no-auto-rehash", устанавливаемая в my.cnf, которая не имеет значения и игнорируется.

> Замечание:

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

### Смотрите также

- parse_ini_string() - Разбирает строку конфигурации

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — Разбирает строку конфигурации

### Описание

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() возвращает настройки из строки `ini_string` в виде ассоциативного массива.

Структура INI-строки такая же, как и в php.ini.

Внимание

Функция не должна использоваться с недоверенными входными данными, за исключением случаев, когда значение параметра `scanner_mode` равно `INI_SCANNER_RAW`, поскольку обработанные данные могут содержать значения конфиденциальных констант, таких как константы, содержащие пароль базы данных.

### Список параметров

`ini_string`

  Содержимое разбираемого INI-файла.

`process_sections`

  Установив в параметр `process_sections` `true`, можно получить многомерный массив, который включает названия секций и настроек. По умолчанию `process_sections` равен `false`

`scanner_mode`

  Может принимать следующие значения: `INI_SCANNER_NORMAL` (по умолчанию) или `INI_SCANNER_RAW`. Если указано значение `INI_SCANNER_RAW`, то значения опций не будут обрабатываться.

  С PHP 5.6.1 также доступен режим `INI_SCANNER_TYPED`. В этом режиме типы boolean, null и integer сохраняются, если возможно. Строковые значения `"true"`, `"on"` и `"yes"` преобразуются в `true`, а значения `"false"`, `"off"`, `"no"` и `"none"` — в `false`. Значение `"null"` преобразовывается в `null`. Кроме этого, числовые строки преобразуются в целые числа, если возможно.

### Возвращаемые значения

В случае успешного выполнения, настройки возвращаются в виде ассоциативного массива (array). В случае возникновения ошибки, возвращается `false`.

### Примечания

> Замечание: Существует зарезервированные слова, которые нельзя использовать в качестве ключей в ini-файлах. Такими словами являются: `null`, `yes`, `no`, `true`, `false`, `on`, `off`, `none`. Значения `null`, `off`, `no` и `false` преобразуются в `""`, а значения `on`, `yes` и `true` в `"1"` , но только если не используется режим `INI_SCANNER_TYPED` (доступен с PHP 5.6.1). Символы `?{}|&~!()^"` не должны использоваться в ключах и иметь какой-либо особый смысл в значениях.

### Смотрите также

- parse_ini_file() - Обрабатывает конфигурационный файл

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — Возвращает информацию о пути к файлу

### Описание

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

Функция pathinfo() возвращает информацию о пути `path` в виде ассоциативного массива или строки, в зависимости от значения параметра `flags`.

> Замечание:

> Подробнее о получении информации о текущем пути рассказывает раздел «Предопределённые зарезервированные переменные».

> Замечание:

> Функция pathinfo() наивно оперирует входной строкой и не знает фактическую файловую систему или компоненты пути наподобие «`..`».

> Замечание:

> Только в системах Windows символ `\` будет интерпретироваться как разделитель каталогов. В других системах символ будет рассматриваться как любой другой символ.

Предостережение

Функция pathinfo() учитывает региональные настройки, поэтому для правильного разбора пути, который содержит многобайтовые символы, необходимо функцией setlocale() установить локаль, которая соответствует символам пути.

### Список параметров

`path`

  Анализируемый путь.

`flags`

  Параметр, если установили, указывает конкретный элемент пути, который вернёт функция: `PATHINFO_DIRNAME`, `PATHINFO_BASENAME`, `PATHINFO_EXTENSION` и `PATHINFO_FILENAME`.

  Если флаг `flags` не указали, то возвращаются все доступные элементы.

### Возвращаемые значения

Если аргумент `flags` не передали, возвращается ассоциативный массив (array) со следующими элементами: `dirname`, `basename`, `extension` (если есть) и `filename`.

> Замечание:

> Если путь `path` содержит больше одного расширения, флаг `PATHINFO_EXTENSION` возвращает только последнее, а флаг `PATHINFO_FILENAME` только удаляет последнее расширение (смотрите первый пример).

> Замечание:

> Если путь `path` не содержит расширения, функция не вернёт элемент расширения `extension` (смотрите второй пример).

> Замечание:

> Если основное имя `basename` пути `path` начинается с точки, следующие символы интерпретируются как расширение файла (`extension`), а имя файла `filename` как пустое (смотрите третий пример).

Если флаги `flags` указали, функция возвращает строку (string), которая содержит запрошенный элемент.

### Примеры

Пример #1 Пример использования функции pathinfo()

    <?php

    $path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

    echo $path_parts['dirname'], "\n";
    echo $path_parts['basename'], "\n";
    echo $path_parts['extension'], "\n";
    echo $path_parts['filename'], "\n";

    ?>

Результат выполнения приведённого примера:

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

Пример #2 Пример работы функции pathinfo(), который показывает разницу между null и отсутствием расширения

    <?php

    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);

    ?>

Вывод приведённого примера будет похож на:

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

Пример #3 Пример работы функции pathinfo() для файла, имя которого начинается с точки

    <?php

    print_r(pathinfo('/some/path/.test'));

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

Пример #4 Пример использования функции pathinfo() с разыменованием массива

Параметр `flags` — не битовая маска. Разрешается только одно значение. Чтобы выбрать только ограниченный набор значений, которые проанализировала функция, массив деструктурируют следующим образом:

    <?php

    ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

    var_dump($basename, $dirname);

    ?>

Вывод приведённого примера будет похож на:

    string(11) "lib.inc.php"
    string(15) "/www/htdocs/inc"

### Смотрите также

- dirname() - Возвращает путь к родительскому каталогу
- basename() - Возвращает конечный компонент имени пути
- parse_url() - Разбирает URL-адрес и возвращает компоненты адреса
- realpath() - Возвращает канонизированный абсолютный путь к файлу

# pclose

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

pclose — Закрывает файловый указатель процесса

### Описание

function pclose(resource `$handle`): int

Закрывает файловый указатель на поток, открытый при помощи popen().

### Список параметров

`handle`

  Файловый указатель должен быть действующим и должен быть получен успешным вызовом функции popen().

### Возвращаемые значения

Возвращает статус выхода завершающегося процесса. В случае возникновения ошибки возвращается `-1`.

> Замечание: Значение возврата функции останется неопределённым, если PHP собрали с опцией --enable-sigchild.

### Примеры

Пример #1 Пример использования pclose()

    <?php
    $handle = popen('/bin/ls', 'r');
    pclose($handle);
    ?>

### Примечания

> Замечание: Только для Unix:

> pclose() внутренне реализована с помощью системного вызова `waitpid(3)`. Для получения реального кода выхода используйте вместо этого функцию pcntl_wexitstatus().

### Смотрите также

- popen() - Открывает файловый указатель процесса

# popen

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

popen — Открывает файловый указатель процесса

### Описание

function popen(string `$command`, string `$mode`): resource|false

Открывает поток к процессу, выполняемый при помощи форка команды, заданной в параметре `command`.

### Список параметров

`command`

  Команда

`mode`

  Режим. Либо `'r'` для чтения, либо `'w'` для записи.

  В Windows для popen() по умолчанию используется текстовый режим, т.е. любые символы `\n`, записанные в канал или прочитанные из него, будут преобразованы в `\r\n`. Если это нежелательно, можно принудительно использовать двоичный режим, установив для `mode` значение `'rb'` и `'wb'` соответственно.

### Возвращаемые значения

Возвращает файловый указатель, идентичный возвращаемому функцией fopen(), за исключением того, что он односторонний (может быть использован только для чтения или записи) и должен быть закрыт при помощи pclose(). Этот указатель может быть использован с fgets(), fgetss() и fwrite(). Если в качестве режима указано 'r', файловый указатель аналогичен потоку вывода (STDOUT) команды, если же указано 'w', то файловый указатель аналогичен потоку ввода (STDIN) команды.

В случае возникновения ошибки возвращает `false`.

### Примеры

Пример #1 Пример использования функции popen()

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

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

Пример #2 Пример использования функции popen()

    <?php
    error_reporting(E_ALL);

    /* Добавляем перенаправление, чтобы прочитать stderr. */
    $handle = popen('/path/to/executable 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### Примечания

> Замечание:

> Если вам нужна двухсторонняя передача (в обе стороны одновременно), используйте proc_open().

### Смотрите также

- pclose() - Закрывает файловый указатель процесса
- fopen() - Открывает файл или URL-адрес
- proc_open() - Выполняет команду и открывает указатель на файл для ввода или вывода

# readfile

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

readfile — Выводит файл

### Описание

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

Функция считывает файл и записывает содержимое в буфер вывода.

### Список параметров

`filename`

  Название файла, который требуется прочитать.

`use_include_path`

  При установке для необязательного второго параметра значения `true` функция также ищет файлы в списке путей директивы include_path.

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает количество байтов, которые считала из файла, если выполнилась успешно, или `false`, если возникла ошибка

### Ошибки

При сбое функция генерирует ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример принудительного скачивания файла функцией readfile()

    <?php

    $file = 'monkey.gif';

    if (file_exists($file)) {
        header('Content-Description: File Transfer');
        header('Content-Type: application/octet-stream');
        header('Content-Disposition: attachment; filename="'.basename($file).'"');
        header('Expires: 0');
        header('Cache-Control: must-revalidate');
        header('Pragma: public');
        header('Content-Length: ' . filesize($file));
        readfile($file);
        exit;
    }

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание:

> Сама функция readfile() не вызовет проблем с памятью, даже при отправке больших файлов. При ошибках нехватки памяти буферизацию вывода отключают функцией ob_get_level().

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Смотрите также

- fpassthru() - Выводит все оставшиеся данные из файлового указателя
- file() - Читает содержимое файла и помещает его в массив
- fopen() - Открывает файл или URL-адрес
- include - include
- require - require
- virtual() - Выполняет подзапрос Apache
- file_get_contents() - Считывает содержимое файла в строку
- Протоколы и обёртки

# readlink

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

readlink — Возвращает файл, на который указывает символическая ссылка

### Описание

function readlink(string `$path`): string|false

Функция readlink() делает то же самое, что и функция readlink в языке C.

### Список параметров

`path`

  Путь к символической ссылке.

### Возвращаемые значения

Функция возвращает путь, на который указывает символическая ссылка, или `false`, если возникла ошибка.

> Замечание: Функция завершается ошибкой, если путь `path` указывает не на символическую ссылку, за исключением ОС Windows, в которой возвращается нормализованный путь.

### Примеры

Пример #1 Пример получения пути символической ссылки функцией readlink()

    <?php

    // Выводится что-то вроде /boot/vmlinux-2.4.20-xfs
    echo readlink('/vmlinuz');

    ?>

### Смотрите также

- is_link() - Сообщает, указывает ли путь на символическую ссылку
- symlink() - Создаёт символическую ссылку
- linkinfo() - Возвращает информацию о ссылке

# realpath

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

realpath — Возвращает канонизированный абсолютный путь к файлу

### Описание

function realpath(string `$path`): string|false

Функция realpath() разворачивает символические ссылки, а также разрешает ссылки на относительные пути вида `/./`, `/../` и убирает лишние символы `/` во входном пути `path`, а затем возвращает канонизированный абсолютный путь к файлу или каталогу.

### Список параметров

`path`

  Проверяемый путь.

  > Замечание:

  > Параметр пути хотя и обязательный, но принимает пустую строку, которую функция интерпретирует как текущий каталог.

### Возвращаемые значения

При успешном выполнении функция возвращает канонизированный абсолютный путь, который получился после преобразования символической ссылки, разрешения компонентов `/./` или `/../` и удаления разделителей `\` или `/` в конце пути.

Функция realpath() возвращает значение `false`, если возникла ошибка, например если файловая система не содержит файл или каталог.

> Замечание:

> Для запускаемого скрипта потребуются права на выполнение для каждого каталога в иерархии, иначе функция realpath() вернёт значение `false`.

> Замечание:

> В регистронезависимых файловых системах функция realpath() возвращает абсолютный путь с непредсказуемым регистром символов, поскольку за нормализацию регистра отвечает операционная система, а не функция.

> Замечание:

> Функция realpath() не работает с файлами внутри Phar-архива, поскольку пути в таком архиве виртуальны, а не реальны.

> Замечание:

> В ОС Windows точки соединения для каталогов и символические ссылки на каталоги разворачиваются только на один уровень.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Примеры

Пример #1 Пример преобразования относительного пути в абсолютный функцией realpath()

    <?php

    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    /etc/passwd
    /tmp

Пример #2 Пример работы функции realpath() в ОС Windows

В системах Windows функция realpath() изменит пути в стиле Unix на стиль Windows.

    <?php

    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    C:\WINDOWS\System32
    C:\Program Files

### Смотрите также

- basename() - Возвращает конечный компонент имени пути
- dirname() - Возвращает путь к родительскому каталогу
- pathinfo() - Возвращает информацию о пути к файлу

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — Получает записи из кеша realpath

### Описание

function realpath_cache_get(): array

Функция получает содержимое realpath-кеша.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает массив записей из кеша realpath. Ключи — записи исходных путей, а значения — массивы элементов данных, которые содержат путь, который разрешила функция, время жизни кеша и другие параметры, которые хранятся в кеше.

### Примеры

Пример #1 Пример использования функции realpath_cache_get()

    <?php

    var_dump(realpath_cache_get());

    ?>

Вывод приведённого примера будет похож на:

    array(2) {
      ["/test"] => array(4) {
        ["key"] => int(123456789)
        ["is_dir"] => bool(true)
        ["realpath"] => string(5) "/test"
        ["expires"] => int(1260318939)
      }
      ["/test/test.php"] => array(4) {
        ["key"] => int(987654321)
        ["is_dir"] => bool(false)
        ["realpath"] => string(12) "/root/test.php"
        ["expires"] => int(1260318939)
      }
    }

### Смотрите также

- realpath_cache_size() - Получает размер кеша realpath

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — Получает размер кеша realpath

### Описание

function realpath_cache_size(): int

Получает объем памяти, используемый кешем realpath.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает, сколько используется кеш-памяти realpath.

### Примеры

Пример #1 Пример использования realpath_cache_size()

    <?php
    var_dump(realpath_cache_size());
    ?>

Вывод приведённого примера будет похож на:

    int(412)

### Смотрите также

- realpath_cache_get() - Получает записи из кеша realpath
- Конфигурационная опция realpath_cache_size

# rename

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

rename — Переименовывает файл или директорию

### Описание

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Пытается переименовать `from` в `to`, перенося файл между директориями, если необходимо. Если `to` существует, то он будет перезаписан. При переименовании директории с существующим `to` будет выведено предупреждение.

### Список параметров

`from`

  Старое имя.

  > Замечание:

  > Обёртка, используемая в `from` должна совпадать с обёрткой, используемой в `to`.

`to`

  Новое имя.

  > Замечание: В Windows, если `to` уже существует, он должен быть доступен для записи. В противном случае rename() завершится ошибкой и выдаст `E_WARNING`.

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции rename()

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### Смотрите также

- copy() - Копирует файл
- unlink() - Удаляет файл
- move_uploaded_file() - Перемещает загруженный файл в новое место

# rewind

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

rewind — Отматывает позицию файлового указателя

### Описание

function rewind(resource `$stream`): bool

Функция устанавливает курсор файлового указателя `stream` в начало файлового потока.

> Замечание:

> Если файл открыли в режиме «записи в конец» («a» или «a+»), любые данные, которые записывают в файл, будут дописаны в конец файла, независимо от положения курсора.

### Список параметров

`stream`

  Файловый указатель должен быть допустимым и указывать на файл, который успешно открыла функция fopen().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример перезаписи с применением функции rewind()

    <?php

    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Ужасно длинное предложение.');
    rewind($handle);
    fwrite($handle, 'Оп');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);

    ?>

Вывод приведённого примера будет похож на:

    Опасно длинное предложение.

### Смотрите также

- fread() - Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fseek() - Перемещает позицию файлового указателя
- ftell() - Возвращает текущую позицию указателя чтения/записи файла
- fwrite() - Записывает данные в файл в бинарно-безопасном режиме

# rmdir

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

rmdir — Удаляет директорию

### Описание

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

Пытается удалить директорию с именем `directory`. Директория должна быть пустой и должны иметься необходимые для этого права. При неудачном выполнении будет сгенерирована ошибка уровня `E_WARNING`.

### Список параметров

`directory`

  Путь к директории.

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования rmdir()

    <?php
    if (!is_dir('examples')) {
        mkdir('examples');
    }

    rmdir('examples');
    ?>

### Смотрите также

- is_dir() - Определяет, указывает ли путь на каталог
- mkdir() - Создаёт директорию
- unlink() - Удаляет файл

# set_file_buffer

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

set_file_buffer — Псевдоним stream_set_write_buffer()

### Описание

Псевдоним функции stream_set_write_buffer().

# stat

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

stat — Возвращает информацию о файле

### Описание

function stat(string `$filename`): array|false

Собирает статистическую информацию о файле `filename`. Если `filename` является символической ссылкой, информация собирается о самом файле, а не ссылке. До PHP 7.4.0 в Windows NTS в данном случае строил статистику `size`, `atime`, `mtime` и `ctime` из символьной ссылки.

Функция lstat() идентична функции stat() за исключением того, что в данном случае она вернёт информацию о самой символической ссылке.

### Список параметров

`filename`

  Путь к файлу.

### Возвращаемые значения

Формат результата работы функций stat() и fstat()
Числовой | Ассоциативный | Описание
--- | --- | ---
0 | dev | номер устройства ***
1 | ino | номер inode ****
2 | mode | режим защиты inode *****
3 | nlink | количество ссылок
4 | uid | userid владельца *
5 | gid | groupid владельца *
6 | rdev | тип устройства, если устройство inode
7 | size | размер в байтах
8 | atime | время последнего доступа (временная метка Unix)
9 | mtime | время последней модификации (временная метка Unix)
10 | ctime | время последнего изменения inode (временная метка Unix)
11 | blksize | размер блока ввода-вывода файловой системы **
12 | blocks | количество используемых 512-байтных блоков **

* В Windows это всегда будет `0`.

** Доступен только на системах, поддерживающих тип st_blksize - другие системы (например, Windows) вернут `-1`.

*** В Windows, начиная с PHP 7.4.0, это серийный номер тома, содержащего файл, который представляет собой 64-разрядное целое число без знака, поэтому может переполниться в 32-разрядных системах. Ранее это было числовое представление буквы диска (например, `2` для `C:`) для stat() и `0` для lstat().

**** В Windows, начиная с PHP 7.4.0, идентификатор, связанный с файлом, который представляет собой 64-разрядное целое число без знака, может переполниться в 32-разрядных системах. Ранее он всегда был `0`.

***** В Windows бит разрешения на запись устанавливается в соответствии с атрибутом файла только для чтения, одно и то же значение сообщается для всех пользователей, группы и владельца. ACL не учитывается, в отличие от is_writable().

Значение `mode` содержит информацию, читаемую несколькими функциями. При записи в восьмеричном виде, начиная справа, первые три цифры возвращаются функцией chmod(). Следующая цифра игнорируется PHP. Следующие две цифры указывают тип файла:

`mode` типов файлов
`mode` в восьмеричном виде | Значение
--- | ---
`0140000` | сокет
`0120000` | символическая ссылка
`0100000` | обычный файл
`0060000` | блочное устройство
`0040000` | директория
`0020000` | символьное устройство
`0010000` | fifo

Так, например, обычный файл может быть `0100644`, а директория может быть `0040755`.

В случае возникновения ошибки stat() возвращает `false`.

> Замечание: На 32-разрядных платформах отдельные PHP-функции для работы с файловой системой иногда возвращают неожиданные результаты для файлов размером больше 2 ГБ, поскольку в PHP тип integer хранит числа со знаком, а архитектура платформы ограничивает диапазон положительных значений типа.

### Ошибки

В случае возникновения ошибки будет сгенерирована ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | В Windows номер устройства теперь является серийным номером тома, содержащего файл и номер inode - это идентификатор, связанный с файлом.
7.4.0 | Статистика символьных ссылок `size`, `atime`, `mtime` и `ctime` всегда соответствует статистике целевого объекта. Это было ранее не характерно для NTS-сборки на Windows.

### Примеры

Пример #1 Пример использования stat()

    <?php
    /* Получаем статистику файла */
    $stat = stat('C:\php\php.exe');

    /*
     * Выводим последнее время доступа к файлу, это то же самое, что и
     * вызов fileatime()
     */
    echo 'Последнее время доступа: ' . $stat['atime'];

    /*
     * Выводим время изменения файла, это то же самое, что и
     * вызов filemtime()
     */
    echo 'Время изменения: ' . $stat['mtime'];

    /* Выводим номер устройства */
    echo 'Номер устройства: ' . $stat['dev'];
    ?>

Пример #2 Использование информации из stat() вместе с touch()

    <?php
    /* Получаем статистику файла */
    $stat = stat('C:\php\php.exe');

    /* Удалось получить эту статистику? */
    if (!$stat) {
        echo 'вызов stat() не удался...';
    } else {
        /*
         * Мы хотим увеличить время последнего доступа к файлу
         * на 1 неделю вперёд.
         */
        $atime = $stat['atime'] + 604800;

        /* Касаемся файла */
        if (!touch('some_file.txt', time(), $atime)) {
            echo 'Не удалось коснуться файла...';
        } else {
            echo 'touch() выполнился успешно...';
        }
    }
    ?>

### Примечания

> Замечание: Обратите внимание, файловые системы обрабатывают время по-разному.

> Замечание: Результаты функции кешируются. Подробнее о кешировании рассказывает описание функции clearstatcache().

Подсказка

Начиная с PHP 5.0.0 функция научилась работать с отдельными URL-обёртками. Список обёрток, которые поддерживаются семейством функций stat(), приводит раздел «Протоколы и обёртки».

### Смотрите также

- lstat() - Возвращает информацию о файле или символической ссылке
- fstat() - Получает информацию о файле по указателю открытого файла
- filemtime() - Получает время последнего изменения файла
- filegroup() - Получает идентификатор группы файла
- SplFileInfo

# symlink

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

symlink — Создаёт символическую ссылку

### Описание

function symlink(string `$target`, string `$link`): bool

Функция symlink() создаёт символическую ссылку с названием `link`, которая указывает на файл `target`.

### Список параметров

`target`

  Цель ссылки.

`link`

  Название ссылки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция завершается ошибкой и выдаёт предупреждение уровня `E_WARNING`, если файловая система уже содержит ссылку с названием `link`. В Windows дополнительно возникает ошибка уровня `E_WARNING`, если файловая система не содержит целевой файл по пути `target`.

### Примеры

Пример #1 Пример создания символической ссылки

    <?php

    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);

    ?>

### Смотрите также

- is_link() - Сообщает, указывает ли путь на символическую ссылку
- link() - Создаёт жёсткую ссылку
- readlink() - Возвращает файл, на который указывает символическая ссылка
- linkinfo() - Возвращает информацию о ссылке
- unlink() - Удаляет файл

# tempnam

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

tempnam — Создаёт файл с уникальным именем

### Описание

function tempnam(string `$directory`, string `$prefix`): string|false

Создаёт файл с уникальным именем в определённой директории с правами 0600. Если эта директория не существует или недоступна для записи, tempnam() может создать файл во временной директории системы и вернуть полный путь к этому файлу, включая его имя.

### Список параметров

`directory`

  Директория, где будет создан временный файл.

`prefix`

  Префикс имени генерируемого файла.

  > Замечание: Используются только первые 63 символа префикса, остальные игнорируются. В Windows используются только первые три символа префикса.

### Возвращаемые значения

Возвращает имя нового временного файла (вместе с путём) или `false` в случае неудачи.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Имена файлов, которые создаёт функция tempnam(), теперь длиннее на 13 байтов. Общая длина по-прежнему зависит от платформы.
7.1.0 | tempnam() теперь выдаёт уведомление при возврате во временный каталог системы.

### Примеры

Пример #1 Пример использования функции tempnam()

    <?php
    $tmpfname = tempnam("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "записываем в во временный файл");
    fclose($handle);

    // здесь мы чего-нибудь делаем

    unlink($tmpfname);
    ?>

### Примечания

> Замечание: Если PHP не может создать файл в указанной директории `directory`, он возвращается к директории по умолчанию вашей системы. На NTFS это также происходит в случае, если указанная директория `directory` содержит более 65534 файлов.

### Смотрите также

- tmpfile() - Создаёт временный файл
- sys_get_temp_dir() - Возвращает путь к директории временных файлов
- unlink() - Удаляет файл

# tmpfile

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

tmpfile — Создаёт временный файл

### Описание

function tmpfile(): resource|false

Создаёт временный файл с уникальным именем, открывая его в режиме бинарного чтения и записи (w+b) и возвращает файловый указатель.

Этот файл автоматически удаляется после закрытия (например, путём вызова функции fclose() или если не осталось ни одной ссылки на указатель файла, возвращаемый tmpfile()), или при завершении работы скрипта.

Предостережение

Если скрипт неожиданно завершится, временный файл не может быть удалён.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дескриптор файла, аналогичный тому, который возвращает функция fopen() для новых файлов или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции tmpfile()

    <?php
    $temp = tmpfile();
    fwrite($temp, "записываем во временный файл");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // происходит удаление файла
    ?>

Результат выполнения приведённого примера:

    записываем во временный файл

### Смотрите также

- tempnam() - Создаёт файл с уникальным именем
- sys_get_temp_dir() - Возвращает путь к директории временных файлов

# touch

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

touch — Устанавливает время доступа и модификации файла

### Описание

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

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

Если файл не существует, он будет создан.

### Список параметров

`filename`

  Имя изменяемого файла.

`mtime`

  Время изменения. Если аргумент `mtime` равен `null`, используется текущее системное время (time()).

`atime`

  Если значение параметра не `null`, время доступа указанного файла будет установлено в значение `atime`. В обратном случае оно будет установлено в значение параметра `mtime`. Если же оба этих параметра равны `null`, то будет использовано текущее системное время.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `mtime` и `atime` теперь допускают значение `null`.

### Примеры

Пример #1 Пример использования функции touch()

    <?php
    if (touch($filename)) {
        echo "Время модификации файла $filename было изменено на текущее";
    } else {
        echo 'Простите, не удалось изменить время модификации файла ' . $filename;
    }
    ?>

Пример #2 Использование touch() с параметром `mtime`

    <?php
    // Это время касания, установим его на час назад.
    $time = time() - 3600;

    // Изменяем файл
    if (!touch('some_file.txt', $time)) {
        echo 'Упс, что-то пошло не так...';
    } else {
        echo 'Изменение модификации файла прошло успешно';
    }
    ?>

### Примечания

> Замечание: Обратите внимание, файловые системы обрабатывают время по-разному.

# umask

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

umask — Изменяет текущую маску прав доступа для вновь созданных файлов и каталогов (umask)

### Описание

function umask(?int `$mask` = `null`): int

Функция umask() устанавливает применяемую PHP по умолчанию umask в значение параметра `mask` & 0777 и возвращает старую umask. Если PHP работает как серверный модуль, umask будет восстанавливаться после окончания каждого запроса.

### Список параметров

`mask`

  Новая umask.

### Возвращаемые значения

Если параметр `mask` равен `null`, функция umask() просто возвращает текущую umask, иначе возвращается старая umask.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `mask` теперь может принимать значение `null`.

### Примеры

Пример #1 Пример использования функции umask()

    <?php
    $old = umask(0);
    chmod("/path/some_dir/some_file.txt", 0755);
    umask($old);

    // Проверка
    if ($old != umask()) {
        die('При восстановлении umask произошла ошибка');
    }
    ?>

### Примечания

> Замечание:

> Избегайте вызова этой функции на многопоточных веб-серверах. Лучше изменить права созданного файла функцией chmod(). Функция umask() может вызвать неожиданное поведение одновременно работающих скриптов и самого веб-сервера, т. к. они все будут использовать одну и ту же umask.

# unlink

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

unlink — Удаляет файл

### Описание

function unlink(string `$filename`, ?resource `$context` = `null`): bool

Функция удаляет файл `filename`. Функция похожа на функцию unlink() в языке C на системах Unix. При неудачном выполнении функция вызовет ошибку уровня `E_WARNING`.

### Список параметров

`filename`

  Путь к файлу.

  Функция удалит символическую ссылку, если файл — символическая ссылка. Чтобы удалить символическую ссылку на каталог в ОС Windows, вместо этой функции вызывают функцию rmdir().

`context`
  Ресурс (resource) контекста потока.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.3.0 | В ОС Windows теперь можно удалить файлы функцией unlink() через дескрипторы, хотя раньше это не удавалось. Тем не менее, всё ещё невозможно повторно создать удалённый файл, пока все дескрипторы к нему не будут закрыты.

### Примеры

Пример #1 Пример простого использования функции unlink()

    <?php

    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Привет, мир!</h1>');
    fclose($fh);

    unlink('test.html');

    ?>

### Смотрите также

- rmdir() - Удаляет директорию

## Содержание

- basename — Возвращает конечный компонент имени пути
- chgrp — Изменяет группу файла
- chmod — Изменяет режим доступа к файлу
- chown — Изменяет владельца файла
- clearstatcache — Очищает кеш состояния файлов
- copy — Копирует файл
- delete — Смотрите описание функции unlink или unset
- dirname — Возвращает путь к родительскому каталогу
- disk_free_space — Возвращает размер доступного пространства в каталоге или файловой системе
- disk_total_space — Возвращает общий размер файловой системы или раздела диска
- diskfreespace — Псевдоним disk_free_space
- fclose — Закрывает открытый дескриптор файла
- fdatasync — Синхронизирует данные (но не метаданные) с файлом
- feof — Проверяет, достигнут ли конец файла
- fflush — Сбрасывает буфер вывода в файл
- fgetc — Считывает символ из файла
- fgetcsv — Получает строку из файлового указателя и разбирает по CSV-полям
- fgets — Получает строку из указателя на файл
- fgetss — Читает строку из файла и удаляет HTML-теги
- file — Читает содержимое файла и помещает его в массив
- file_exists — Проверяет, содержит ли файловая система файл или каталог
- file_get_contents — Считывает содержимое файла в строку
- file_put_contents — Записывает данные в файл
- fileatime — Возвращает время последнего доступа к файлу
- filectime — Возвращает время изменения индексного дескриптора файла
- filegroup — Получает идентификатор группы файла
- fileinode — Возвращает индексный дескриптор файла
- filemtime — Получает время последнего изменения файла
- fileowner — Возвращает идентификатор владельца файла
- fileperms — Возвращает информацию о правах на файл
- filesize — Возвращает размер файла
- filetype — Возвращает тип файла
- flock — Блокирует файл методом переносимой рекомендательной блокировки
- fnmatch — Проверяет совпадение имени файла с шаблоном
- fopen — Открывает файл или URL-адрес
- fpassthru — Выводит все оставшиеся данные из файлового указателя
- fputcsv — Формирует строку в CSV-формате и записывает строку в файловый указатель
- fputs — Псевдоним fwrite
- fread — Читает файл в бинарно-безопасном режиме: как последовательность байтов
- fscanf — Обрабатывает данные из файла по условиям формата
- fseek — Перемещает позицию файлового указателя
- fstat — Получает информацию о файле по указателю открытого файла
- fsync — Синхронизирует изменения в файле (включая метаданные)
- ftell — Возвращает текущую позицию указателя чтения/записи файла
- ftruncate — Урезает файл до указанной длины
- fwrite — Записывает данные в файл в бинарно-безопасном режиме
- glob — Находит файловые пути, которые совпадают с шаблоном
- is_dir — Определяет, указывает ли путь на каталог
- is_executable — Определяет, является ли файл исполняемым
- is_file — Сообщает, ведёт ли путь к стандартному файлу
- is_link — Сообщает, указывает ли путь на символическую ссылку
- is_readable — Определяет существование файла и доступен ли он для чтения
- is_uploaded_file — Определяет, был ли файл загружен при помощи HTTP POST
- is_writable — Определяет, доступен ли файл для записи
- is_writeable — Псевдоним is_writable
- lchgrp — Изменяет группу, которой принадлежит символическая ссылка
- lchown — Изменяет владельца символической ссылки
- link — Создаёт жёсткую ссылку
- linkinfo — Возвращает информацию о ссылке
- lstat — Возвращает информацию о файле или символической ссылке
- mkdir — Создаёт директорию
- move_uploaded_file — Перемещает загруженный файл в новое место
- parse_ini_file — Обрабатывает конфигурационный файл
- parse_ini_string — Разбирает строку конфигурации
- pathinfo — Возвращает информацию о пути к файлу
- pclose — Закрывает файловый указатель процесса
- popen — Открывает файловый указатель процесса
- readfile — Выводит файл
- readlink — Возвращает файл, на который указывает символическая ссылка
- realpath — Возвращает канонизированный абсолютный путь к файлу
- realpath_cache_get — Получает записи из кеша realpath
- realpath_cache_size — Получает размер кеша realpath
- rename — Переименовывает файл или директорию
- rewind — Отматывает позицию файлового указателя
- rmdir — Удаляет директорию
- set_file_buffer — Псевдоним stream_set_write_buffer
- stat — Возвращает информацию о файле
- symlink — Создаёт символическую ссылку
- tempnam — Создаёт файл с уникальным именем
- tmpfile — Создаёт временный файл
- touch — Устанавливает время доступа и модификации файла
- umask — Изменяет текущую маску прав доступа для вновь созданных файлов и каталогов (umask)
- unlink — Удаляет файл

- Установка и настройка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Функции файловой системы
  - basename — Возвращает конечный компонент имени пути
  - chgrp — Изменяет группу файла
  - chmod — Изменяет режим доступа к файлу
  - chown — Изменяет владельца файла
  - clearstatcache — Очищает кеш состояния файлов
  - copy — Копирует файл
  - delete — Смотрите описание функции unlink или unset
  - dirname — Возвращает путь к родительскому каталогу
  - disk_free_space — Возвращает размер доступного пространства в каталоге или файловой системе
  - disk_total_space — Возвращает общий размер файловой системы или раздела диска
  - diskfreespace — Псевдоним disk_free_space
  - fclose — Закрывает открытый дескриптор файла
  - fdatasync — Синхронизирует данные (но не метаданные) с файлом
  - feof — Проверяет, достигнут ли конец файла
  - fflush — Сбрасывает буфер вывода в файл
  - fgetc — Считывает символ из файла
  - fgetcsv — Получает строку из файлового указателя и разбирает по CSV-полям
  - fgets — Получает строку из указателя на файл
  - fgetss — Читает строку из файла и удаляет HTML-теги
  - file — Читает содержимое файла и помещает его в массив
  - file_exists — Проверяет, содержит ли файловая система файл или каталог
  - file_get_contents — Считывает содержимое файла в строку
  - file_put_contents — Записывает данные в файл
  - fileatime — Возвращает время последнего доступа к файлу
  - filectime — Возвращает время изменения индексного дескриптора файла
  - filegroup — Получает идентификатор группы файла
  - fileinode — Возвращает индексный дескриптор файла
  - filemtime — Получает время последнего изменения файла
  - fileowner — Возвращает идентификатор владельца файла
  - fileperms — Возвращает информацию о правах на файл
  - filesize — Возвращает размер файла
  - filetype — Возвращает тип файла
  - flock — Блокирует файл методом переносимой рекомендательной блокировки
  - fnmatch — Проверяет совпадение имени файла с шаблоном
  - fopen — Открывает файл или URL-адрес
  - fpassthru — Выводит все оставшиеся данные из файлового указателя
  - fputcsv — Формирует строку в CSV-формате и записывает строку в файловый указатель
  - fputs — Псевдоним fwrite
  - fread — Читает файл в бинарно-безопасном режиме: как последовательность байтов
  - fscanf — Обрабатывает данные из файла по условиям формата
  - fseek — Перемещает позицию файлового указателя
  - fstat — Получает информацию о файле по указателю открытого файла
  - fsync — Синхронизирует изменения в файле (включая метаданные)
  - ftell — Возвращает текущую позицию указателя чтения/записи файла
  - ftruncate — Урезает файл до указанной длины
  - fwrite — Записывает данные в файл в бинарно-безопасном режиме
  - glob — Находит файловые пути, которые совпадают с шаблоном
  - is_dir — Определяет, указывает ли путь на каталог
  - is_executable — Определяет, является ли файл исполняемым
  - is_file — Сообщает, ведёт ли путь к стандартному файлу
  - is_link — Сообщает, указывает ли путь на символическую ссылку
  - is_readable — Определяет существование файла и доступен ли он для чтения
  - is_uploaded_file — Определяет, был ли файл загружен при помощи HTTP POST
  - is_writable — Определяет, доступен ли файл для записи
  - is_writeable — Псевдоним is_writable
  - lchgrp — Изменяет группу, которой принадлежит символическая ссылка
  - lchown — Изменяет владельца символической ссылки
  - link — Создаёт жёсткую ссылку
  - linkinfo — Возвращает информацию о ссылке
  - lstat — Возвращает информацию о файле или символической ссылке
  - mkdir — Создаёт директорию
  - move_uploaded_file — Перемещает загруженный файл в новое место
  - parse_ini_file — Обрабатывает конфигурационный файл
  - parse_ini_string — Разбирает строку конфигурации
  - pathinfo — Возвращает информацию о пути к файлу
  - pclose — Закрывает файловый указатель процесса
  - popen — Открывает файловый указатель процесса
  - readfile — Выводит файл
  - readlink — Возвращает файл, на который указывает символическая ссылка
  - realpath — Возвращает канонизированный абсолютный путь к файлу
  - realpath_cache_get — Получает записи из кеша realpath
  - realpath_cache_size — Получает размер кеша realpath
  - rename — Переименовывает файл или директорию
  - rewind — Отматывает позицию файлового указателя
  - rmdir — Удаляет директорию
  - set_file_buffer — Псевдоним stream_set_write_buffer
  - stat — Возвращает информацию о файле
  - symlink — Создаёт символическую ссылку
  - tempnam — Создаёт файл с уникальным именем
  - tmpfile — Создаёт временный файл
  - touch — Устанавливает время доступа и модификации файла
  - umask — Изменяет текущую маску прав доступа для вновь созданных файлов и каталогов (umask)
  - unlink — Удаляет файл

# Inotify

# Введение

Модуль inotify предоставляет функции inotify_init(), inotify_add_watch() и inotify_rm_watch().

В то время как функция языка C inotify_init() возвращает дескриптор файла, функция inotify_init() в PHP возвращает потоковый ресурс, который можно использовать в стандартных функциях, например, stream_select(), stream_set_blocking() и fclose(). Функция inotify_read() замещает способ чтения событий inotify в C.

# Установка и настройка

## Содержание

- Установка и настройка
- Типы ресурсов

## Установка и настройка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/inotify.

## Типы ресурсов

Модуль определяет потоковый ресурс, который возвращает функция inotify_init().

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Константы Inotify, которые принимает функция inotify_add_watch() и (или) возвращает функция inotify_read()
`IN_ACCESS` (int)
  К файлу получен доступ (чтение) (*)
`IN_MODIFY` (int)
  Файл был изменён (*)
`IN_ATTRIB` (int)
  Изменены метаданные (например, permissions, mtime, и т. д.) (*)
`IN_CLOSE_WRITE` (int)
  Открытый для записи файл был закрыт (*)
`IN_CLOSE_NOWRITE` (int)
  Открытый не для записи файл был закрыт (*)
`IN_OPEN` (int)
  Файл был открыт (*)
`IN_MOVED_TO` (int)
  Файл перемещён в наблюдаемый каталог (*)
`IN_MOVED_FROM` (int)
  Файл перемещён из наблюдаемого каталога (*)
`IN_CREATE` (int)
  В наблюдаемом каталоге создан файл или каталог (*)
`IN_DELETE` (int)
  Из наблюдаемого каталога удалён файл или каталог (*)
`IN_DELETE_SELF` (int)
  Наблюдаемый файл или каталог удалён
`IN_MOVE_SELF` (int)
  Наблюдаемый файл или каталог перемещён
`IN_CLOSE` (int)
  Сокращение побитовой комбинации IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
`IN_MOVE` (int)
  Сокращение побитовой комбинации IN_MOVED_FROM | IN_MOVED_TO
`IN_ALL_EVENTS` (int)
  Сокращеная битовая маска для объединения перечисленных констант
`IN_UNMOUNT` (int)
  Файловая система, которая содержала наблюдаемый элемент, была размонтирована
`IN_Q_OVERFLOW` (int)
  Очередь событий переполнена (значение дескриптора наблюдения wd для события равно -1)
`IN_IGNORED` (int)
  Элемент был удалён из списка наблюдения (вызовом функции inotify_rm_watch() или потому, что файл был удалён или файловая система размонтирована)
`IN_ISDIR` (int)
  Событие произошло с каталогом
`IN_ONLYDIR` (int)
  Отслеживать путь, только если это каталог (начиная с Linux 2.6.15)
`IN_DONT_FOLLOW` (int)
  Не разыменовывать путь, если это символическая ссылка (начиная с Linux 2.6.15)
`IN_MASK_ADD` (int)
  Добавляет события в маску отслеживаемых событий для элемента по заданному пути, если элемент раньше добавили в список наблюдения (вместо замены маски событий наблюдения)
`IN_ONESHOT` (int)
  Отслеживать путь для одного события, затем удалить его из списка наблюдения

> Замечание: События со звёздочкой (*) распространяются и на файлы в наблюдаемых каталогах.

# Функции Inotify

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — Добавляет элемент наблюдения для объекта inotify

### Описание

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

Функция inotify_add_watch() добавляет в список или заменяет в списке наблюдения файл или каталог, который определили в параметре `pathname`.

Функция inotify_add_watch() заменяет наблюдение, которое добавили раньше. Константа `IN_MASK_ADD` добавляет (как побитовое ИЛИ) события для отслеживания, которые будут происходить с элементом списка наблюдения.

### Список параметров

`inotify_instance`
  Ресурс, который возвращает функция inotify_init().
`pathname`
  Файл или каталог для отслеживания.
`mask`
  События, которые будет отслеживать наблюдатель. Смотрите «Предопределённые константы».

### Возвращаемые значения

Возвращает уникальный (в контексте экземпляра inotify) дескриптор наблюдения, или `false`, если возникла ошибка.

### Смотрите также

- inotify_init() - Инициализирует экземпляр inotify

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — Инициализирует экземпляр inotify

### Описание

function inotify_init(): resource|false

Инициализирует экземпляр inotify для работы с функцией inotify_add_watch().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ресурс потока или `false`.

### Примеры

Пример #1 Пример использования функции inotify

    <?php

    // Создаём экземпляр inotify
    $fd = inotify_init();

    // Отслеживаем изменение метаданных файла __FILE__ (например, метки mtime)
    $watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

    // Генерируем событие
    touch(__FILE__);

    // Читаем события
    $events = inotify_read($fd);
    print_r($events);

    // Следующие методы разрешают использовать функции объекта inotify без блокировки при чтении событий функцией inotify_read():

    // - Вызываем функцию stream_select() для файлового дескриптора $fd:
    $read = array($fd);
    $write = null;
    $except = null;
    stream_select($read, $write, $except, 0);

    // - Вызываем функцию stream_set_blocking() для файлового дескриптора $fd
    stream_set_blocking($fd, 0);
    inotify_read($fd); // Не блокирует и возвращает false, если нет ожидающих событий

    // - Вызываем функцию inotify_queue_len(), чтобы проверить, не пуста ли очередь событий
    $queue_len = inotify_queue_len($fd); // Если значение > 0, функция inotify_read() не заблокирует выполнение

    // Заканчиваем наблюдение за файлом __FILE__
    inotify_rm_watch($fd, $watch_descriptor);

    // Закрываем экземпляр inotify
    // Это закончит наблюдения
    fclose($fd);

    ?>

Вывод приведённого примера будет похож на:

    array(
      array(
        'wd' => 1,     // Соответствует дескриптору наблюдения $watch_descriptor
        'mask' => 4,   // Установлен бит IN_ATTRIB
        'cookie' => 0, // Уникальный идентификатор для подключения связанных событий (например,
                       // события IN_MOVE_FROM и IN_MOVE_TO)
        'name' => '',  // Название файла (например, если мы отслеживали изменения
                       // в каталоге)
      ),
    );

### Смотрите также

- inotify_add_watch() - Добавляет элемент наблюдения для объекта inotify
- inotify_rm_watch() - Удаляет наблюдение из экземпляра inotify
- inotify_queue_len() - Возвращает число больше нуля, если есть ожидающие события
- inotify_read() - Читает события из экземпляра inotify
- fclose() - Закрывает открытый дескриптор файла

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — Возвращает число больше нуля, если есть ожидающие события

### Описание

function inotify_queue_len(resource `$inotify_instance`): int

Функция даёт понять, будет ли функция inotify_read() блокировать выполнение или нет. Если функция возвращает число больше нуля, есть ожидающие события, а функция inotify_read() не будет блокироваться.

### Список параметров

`inotify_instance`
  Ресурс, который возвращает функция inotify_init().

### Возвращаемые значения

Возвращает число больше нуля, если есть ожидающие события.

### Смотрите также

- inotify_init() - Инициализирует экземпляр inotify
- stream_select() - Запускает эквивалент системного вызова select() на массивах потоков со временем ожидания в секундах и микросекундах
- stream_set_blocking() - Устанавливает блокирующий или неблокирующий режим для потока

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — Читает события из экземпляра inotify

### Описание

function inotify_read(resource `$inotify_instance`): array

Читает события файлового дескриптора inotify из экземпляра inotify.

### Список параметров

`inotify_instance`
  Ресурс, который возвращает функция inotify_init().

### Возвращаемые значения

Возвращает массив событий файлового дескриптора inotify или `false`, если событий в очереди нет и дескриптор `inotify_instance` не блокирующий. Каждое событие — массив со следующими ключами:

- wd — дескриптор наблюдения, который возвращает функция inotify_add_watch()
- mask — битовая маска событий
- cookie — уникальный идентификатор для объединения связанных событий (например, события `IN_MOVE_FROM` и `IN_MOVE_TO`)
- name — название файла (например, если файл изменился в каталоге, за которым велось наблюдение)

### Смотрите также

- inotify_init() - Инициализирует экземпляр inotify
- stream_select() - Запускает эквивалент системного вызова select() на массивах потоков со временем ожидания в секундах и микросекундах
- stream_set_blocking() - Устанавливает блокирующий или неблокирующий режим для потока
- inotify_queue_len() - Возвращает число больше нуля, если есть ожидающие события

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — Удаляет наблюдение из экземпляра inotify

### Описание

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

Функция inotify_rm_watch() удаляет дескриптор наблюдения `watch_descriptor` из экземпляра inotify `inotify_instance`.

### Список параметров

`inotify_instance`
  Ресурс, который возвращает функция inotify_init().
`watch_descriptor`
  Дескриптор наблюдения для удаления из дескриптора файла.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Смотрите также

- inotify_init() - Инициализирует экземпляр inotify

## Содержание

- inotify_add_watch — Добавляет элемент наблюдения для объекта inotify
- inotify_init — Инициализирует экземпляр inotify
- inotify_queue_len — Возвращает число больше нуля, если есть ожидающие события
- inotify_read — Читает события из экземпляра inotify
- inotify_rm_watch — Удаляет наблюдение из экземпляра inotify

- Установка и настройка
  - Установка и настройка
  - Типы ресурсов
- Предопределённые константы
- Функции Inotify
  - inotify_add_watch — Добавляет элемент наблюдения для объекта inotify
  - inotify_init — Инициализирует экземпляр inotify
  - inotify_queue_len — Возвращает число больше нуля, если есть ожидающие события
  - inotify_read — Читает события из экземпляра inotify
  - inotify_rm_watch — Удаляет наблюдение из экземпляра inotify

# xattr

# Введение

Модуль xattr позволяет производить манипуляции с расширенными атрибутами в файловой системе.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Для работы модуля xattr требуется установить библиотеку libattr. Библиотека доступна для скачивания по адресу » http://savannah.nongnu.org/projects/attr/.

> Замечание:

> Функции модуля работают только с файловыми системами, которые поддерживают расширенные атрибуты и включают атрибуты в момент монтирования. Вот некоторые распространённые файловые системы, которые поддерживают расширенные атрибуты: `ext2`, `ext3`, `reiserfs`, `jfs` и `xfs`.

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/xattr.

DLL для этого модуля PECL пока недоступна. Смотрите также раздел сборка на Windows.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`XATTR_ROOT` (int)
  Установить атрибут в корневом (доверенном) пространстве имён. Требует привилегий суперпользователя.
`XATTR_DONTFOLLOW` (int)
  Не разыменовывать символические ссылки, работать с самими ссылками.
`XATTR_CREATE` (int)
  Функция завершится ошибкой, если расширенный атрибут уже существует.
`XATTR_REPLACE` (int)
  Функция завершится ошибкой, если расширенный атрибут отсутствует.

# xattr Функции

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Получает расширенные атрибуты файла

### Описание

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

Функция возвращает значение расширенного атрибута файла.

Расширенные атрибуты разделяются на два пространства имён: пользовательское и корневое. Пользовательское пространство имён доступно каждому пользователю, тогда как корневое — только пользователям с root-привилегиями. Механизм xattr по умолчанию работает с пользовательским пространством имён, но поведение изменяется через параметр `flags`.

### Список параметров

`filename`

  Файл, атрибут которого требуется прочитать.

`name`

  Название атрибута.

`flags`

  Поддерживаемые xattr-флаги
  `XATTR_DONTFOLLOW` | Не разыменовывать символические ссылки, работать с самой ссылкой.
  `XATTR_ROOT` | Установить атрибут в корневом пространстве имён. Требуются права суперпользователя.

### Возвращаемые значения

Функция возвращает строку, которая содержит значение `false`, если атрибут не существует.

### Примеры

Пример #1 Проверить, подписал ли файл системный администратор

    <?php

    $file = '/usr/local/sbin/some_binary';
    $signature = xattr_get($file, 'Root signature', XATTR_ROOT);

    /* ... check if $signature is valid ... */

    ?>

### Смотрите также

- xattr_list() - Просмотр списка расширенных атрибутов файла
- xattr_set() - Установка расширенных атрибутов файла
- xattr_remove() - Удаление расширенных атрибутов файла

# xattr_list

(PECL xattr >= 0.9.0)

xattr_list — Просмотр списка расширенных атрибутов файла

### Описание

function xattr_list(string `$filename`, int `$flags` = 0): array

Эта функция возвращает список имён расширенных атрибутов файла.

Расширенные атрибуты разделяются на два пространства имён: пользовательское и корневое. Пользовательское пространство имён доступно каждому пользователю, тогда как корневое — только пользователям с root-привилегиями. Механизм xattr по умолчанию работает с пользовательским пространством имён, но поведение изменяется через параметр `flags`.

### Список параметров

`filename`

  Файл, список атрибутов которого нужно прочитать.

`flags`

  Поддерживаемые xattr-флаги
  `XATTR_DONTFOLLOW` | Не разыменовывать символические ссылки, работать с самой ссылкой.
  `XATTR_ROOT` | Установить атрибут в корневом пространстве имён. Требуются права суперпользователя.

### Возвращаемые значения

Функция возвращает массив, содержащий имена расширенных атрибутов.

### Примеры

Пример #1 Вывести имена всех расширенных атрибутов файла

    <?php
    $file = 'some_file';
    $root_attributes = xattr_list($file, XATTR_ROOT);
    $user_attributes = xattr_list($file);

    echo "Root-атрибуты: \n";
    foreach ($root_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    echo "\n Пользовательские атрибуты: \n";
    foreach ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### Смотрите также

- xattr_get() - Получает расширенные атрибуты файла

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Удаление расширенных атрибутов файла

### Описание

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

Эта функция удаляет расширенный атрибут файла.

Расширенные атрибуты разделяются на два пространства имён: пользовательское и корневое. Пользовательское пространство имён доступно каждому пользователю, тогда как корневое — только пользователям с root-привилегиями. Механизм xattr по умолчанию работает с пользовательским пространством имён, но поведение изменяется через параметр `flags`.

### Список параметров

`filename`

  Файл, атрибут которого нужно удалить.

`name`

  Имя удаляемого атрибута.

`flags`

  Поддерживаемые xattr-флаги
  `XATTR_DONTFOLLOW` | Не разыменовывать символические ссылки, работать с самой ссылкой.
  `XATTR_ROOT` | Установить атрибут в корневом пространстве имён. Требуются права суперпользователя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Удалить все расширенные атрибуты файла

    <?php
    $file = 'some_file';
    $attributes = xattr_list($file);

    foreach ($attributes as $attr_name) {
        xattr_remove($file, $attr_name);
    }
    ?>

### Смотрите также

- xattr_list() - Просмотр списка расширенных атрибутов файла
- xattr_set() - Установка расширенных атрибутов файла
- xattr_get() - Получает расширенные атрибуты файла

# xattr_set

(PECL xattr >= 0.9.0)

xattr_set — Установка расширенных атрибутов файла

### Описание

function xattr_set(
string `$filename`,
string `$name`,
string `$value`,
int `$flags` = 0
): bool

Эта функция устанавливает расширенный атрибут файла.

Расширенные атрибуты разделяются на два пространства имён: пользовательское и корневое. Пользовательское пространство имён доступно каждому пользователю, тогда как корневое — только пользователям с root-привилегиями. Механизм xattr по умолчанию работает с пользовательским пространством имён, но поведение изменяется через параметр `flags`.

### Список параметров

`filename`

  Имя файла, атрибут которого нужно установить.

`name`

  Имя расширенного атрибута. При его отсутствии атрибут создаётся, в противном случае - перезаписывается. Вы можете изменить поведение, используя флаги (`flags`).

`value`

  Значение атрибута.

`flags`

  Поддерживаемые xattr-флаги
  `XATTR_CREATE` | Функция вернёт ошибку, если атрибут существует.
  `XATTR_REPLACE` | Функция вернёт ошибку, если атрибут не существует.
  `XATTR_DONTFOLLOW` | Не разыменовывать символические ссылки, работать с самой ссылкой.
  `XATTR_ROOT` | Установить атрибут в корневом пространстве имён. Требуются права суперпользователя.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Установить расширенные атрибуты .wav файла

    <?php
    $file = 'my_favourite_song.wav';
    xattr_set($file, 'Artist', 'Someone');
    xattr_set($file, 'My ranking', 'Good');
    xattr_set($file, 'Listen count', '34');

    /* ... other code ... */

    printf("You've played this song %d times", xattr_get($file, 'Listen count'));
    ?>

### Смотрите также

- xattr_get() - Получает расширенные атрибуты файла
- xattr_remove() - Удаление расширенных атрибутов файла

# xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — Проверка поддержки расширенных атрибутов

### Описание

function xattr_supported(string `$filename`, int `$flags` = 0): bool

Эта функция проверяет поддерживает ли файловая система, содержащая файл, расширенные атрибуты. Требуется право на чтение файла.

### Список параметров

`filename`

  Путь к проверяемому файлу.

`flags`

  Поддерживаемые xattr-флаги
  `XATTR_DONTFOLLOW` | Не разыменовывать символические ссылки, работать с самой ссылкой.

### Возвращаемые значения

Функция возвращает `true`, если файловая система поддерживает расширенные атрибуты, `false`, если это не так и `null`, если невозможно определить (на пример неверный путь к файлу, или нет разрешения на чтение файла).

### Примеры

Пример #1 Пример использования функции xattr_supported()

Проверить, можно ли использовать расширенные атрибуты.

    <?php
    $file = 'some_file';

    if (xattr_supported($file)) {
        /* ... make use of some xattr_* functions ... */
    }

    ?>

### Смотрите также

- xattr_get() - Получает расширенные атрибуты файла
- xattr_list() - Просмотр списка расширенных атрибутов файла

## Содержание

- xattr_get — Получает расширенные атрибуты файла
- xattr_list — Просмотр списка расширенных атрибутов файла
- xattr_remove — Удаление расширенных атрибутов файла
- xattr_set — Установка расширенных атрибутов файла
- xattr_supported — Проверка поддержки расширенных атрибутов

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- xattr Функции
  - xattr_get — Получает расширенные атрибуты файла
  - xattr_list — Просмотр списка расширенных атрибутов файла
  - xattr_remove — Удаление расширенных атрибутов файла
  - xattr_set — Установка расширенных атрибутов файла
  - xattr_supported — Проверка поддержки расширенных атрибутов

# xdiff

# Введение

Модуль xdiff позволяет создавать и применять файлы исправлений, содержащие различия между различными версиями файлов.

Модуль поддерживает два режима работы: со строками и с файлами, также, два разных формата патчей - унифицированный и бинарный. Унифицированные патчи хороши для текстовых файлов и удобны для чтения человеком. Для бинарных файлов, таких как архивы или изображения, следует использовать бинарный формат, так как он корректно обрабатывает непечатные символы.

Начиная с версии 1.5.0 существуют два различных набора функций для создания бинарных патчей. Новые функции - xdiff_string_rabdiff() и xdiff_file_rabdiff() создают поддерживаемый старыми функциями вывод, но работают быстрее и результат занимает меньше места. Более подробно о методах создания бинарных патчей и разнице между ними читайте на сайте » libxdiff.

Модуль использует libxdiff. Более подробно читайте на сайте » http://www.xmailserver.org/xdiff-lib.html.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Для работы модуля xdiff требуется установить библиотеку libxdiff, которая доступна для скачивания на домашней странице сайта библиотеки » http://www.xmailserver.org/xdiff-lib.html.

> Замечание:

> Требуется версия библиотеки libxdiff не ниже 0.7, чтобы функции модуля знали о директиве memory_limit.

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/xdiff.

Бинарные файлы ОС Windows (DLL-файлы) для этого PECL-модуля доступны на сайте репозитория PECL.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`XDIFF_PATCH_NORMAL` (int)
  Этот флаг обозначает, что функции xdiff_string_patch() и xdiff_file_patch() должны создавать результат путём применения патча к оригинальному контенту, таким образом, создавая новую версию файла. Это является поведением по умолчанию.
`XDIFF_PATCH_REVERSE` (int)
  Этот флаг обозначает, что функции xdiff_string_patch() и xdiff_file_patch() должны создавать результат путём отката патча с полученного нового контента, таким образом, восстанавливая оригинальный контент.

# Функции xdiff

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Создать бинарный патч сравнивая два файла

### Описание

function xdiff_file_bdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Создаёт файл бинарного патча сравнивая два файла. Эта функция работает как с бинарными, так и с текстовыми файлами. В дальнейшем, полученный патч можно применить с помощью функций xdiff_file_bpatch()/xdiff_string_bpatch().

### Список параметров

`old_file`

  Путь к первому, "старому" файлу.

`new_file`

  Путь ко второму, "новому" файлу.

`dest`

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования xdiff_file_bdiff()

Следующий код создаёт бинарный патч.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Примечания

> Замечание:

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

### Смотрите также

- xdiff_file_bpatch() - Применить бинарный патч к файлу

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — Получить размер файла после применения бинарного патча

### Описание

function xdiff_file_bdiff_size(string `$file`): int

Возвращает размер файла, который будет создан после применения бинарного патча из файла `file`.

### Список параметров

`file`

  Путь к бинарному патчу, созданному функциями xdiff_string_bdiff() или xdiff_string_rabdiff().

### Возвращаемые значения

Возвращает размер файла, который будет создан.

### Примеры

Пример #1 Пример использования xdiff_file_bdiff_size()

Следующий код получает размер файла, который будет создан после применения патча.

    <?php
    $length = xdiff_string_bdiff_size('file.bdiff');
    echo "Размер результирующего файла будет $length байт";
    ?>

### Смотрите также

- xdiff_file_bdiff() - Создать бинарный патч сравнивая два файла
- xdiff_file_rabdiff() - Создать бинарный патч сравнивая два файла с помощью полиноминального алгоритма Rabin fingerprinting
- xdiff_file_bpatch() - Применить бинарный патч к файлу

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — Применить бинарный патч к файлу

### Описание

function xdiff_file_bpatch(string `$file`, string `$patch`, string `$dest`): bool

Применить к файлу `file` патч `patch` и записать результат в файл `dest`. Эта функция принимает патчи, созданные как xdiff_file_bdiff() так и xdiff_file_rabdiff() или же их копии.

### Список параметров

`file`

  Оригинальный файл.

`patch`

  Файл бинарного патча.

`dest`

  Итоговый файл.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования xdiff_file_bpatch()

В следующем коде показано применение бинарного патча к файлу.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Файл пропатчен";
    } else {
       echo "Файл не может быть пропатчен";
    }

    ?>

### Примечания

> Замечание:

> Оба файла (`file` и `patch`) будут загружены в память, так что убедитесь, что параметр memory_limit настроен корректно.

### Смотрите также

- xdiff_file_bdiff() - Создать бинарный патч сравнивая два файла
- xdiff_file_rabdiff() - Создать бинарный патч сравнивая два файла с помощью полиноминального алгоритма Rabin fingerprinting

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — Создать унифицированный патч из сравнения двух файлов

### Описание

function xdiff_file_diff(
string `$old_file`,
string `$new_file`,
string `$dest`,
int `$context` = 3,
bool `$minimal` = `false`
): bool

Создаёт унифицированный патч, содержащий различия двух файлов `old_file` и `new_file` и сохраняет его в файл `dest`. Результат человекочитаемый. Необязательный параметр `context` указывает, сколько строк контекста должно быть добавлено вокруг каждой изменённой строки. Задание параметра `minimal` равным `true` приведёт к созданию максимально короткого патча, что может занять много времени.

### Список параметров

`old_file`

  Путь к первому, "старому" файлу.

`new_file`

  Путь ко второму, "новому" файлу.

`dest`

  Путь к файлу патча.

`context`

  Указывает, сколько строк контекста необходимо включить в патч.

`minimal`

  Установите равным `true`, чтобы минимизировать размер патча. Может занять продолжительное время.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования xdiff_file_diff()

В следующем примере создаётся унифицированный патч двух скриптов php с величиной контекста 2.

    <?php
    $old_version = 'my_script.php';
    $new_version = 'my_new_script.php';

    xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
    ?>

### Примечания

> Замечание:

> С бинарными данными эта функция работает плохо. Для бинарных патчей используйте xdiff_file_bdiff()/xdiff_file_rabdiff().

### Смотрите также

- xdiff_file_patch() - Применение унифицированного патча к файлу

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — Псевдоним xdiff_file_bdiff()

### Описание

function xdiff_file_diff_binary(string `$old_file`, string `$new_file`, string `$dest`): bool

Создаёт файл бинарного патча сравнивая два файла. Эта функция работает, как с бинарными, так и с текстовыми файлами. В дальнейшем, полученный патч можно применить с помощью функций xdiff_file_bpatch().

Начиная с версии 1.5.0, эта функция является псевдонимом xdiff_file_bdiff().

### Список параметров

`old_file`

  Путь к первому, "старому" файлу.

`new_file`

  Путь ко второму, "новому" файлу.

`dest`

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции xdiff_file_diff_binary()

Следующий код создаёт бинарный патч сравнивая два архива.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
    ?>

### Примечания

> Замечание:

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

### Смотрите также

- xdiff_file_bdiff() - Создать бинарный патч сравнивая два файла
- xdiff_file_bpatch() - Применить бинарный патч к файлу

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — Объединение трёх файлов в один

### Описание

function xdiff_file_merge3(
string `$old_file`,
string `$new_file1`,
string `$new_file2`,
string `$dest`
): mixed

Объединяет три файла в один и сохраняет результат в `dest`. Файл `old_file` является оригинальным файлом, тогда как `new_file1` и `new_file2` его модифицированными версиями.

### Список параметров

`old_file`

  Путь к первому, "старому" файлу.

`new_file1`

  Путь ко второму файлу. Модифицированной версии `old_file`.

`new_file2`

  Путь к третьему файлу. Модифицированной версии `old_file`.

`dest`

  Путь к результирующему файлу, который будет содержать объединённые изменения из `new_file1` и `new_file2`.

### Возвращаемые значения

Возвращает `true`, если объединение прошло успешно, строку с отклонёнными данными, если нет, и `false` в случае внутренней ошибки.

### Примеры

Пример #1 Пример использования xdiff_file_merge3()

Следующий код объединяет три файла.

    <?php
    $old_version = 'original_script.php';
    $fix1 = 'script_with_fix1.php';
    $fix2 = 'script_with_fix2.php';

    $errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
    if (is_string($errors)) {
        echo "Отклонены:\n";
        echo $errors;
    }
    ?>

### Смотрите также

- xdiff_string_merge3() - Объединить три строки в одну

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — Применение унифицированного патча к файлу

### Описание

function xdiff_file_patch(
string `$file`,
string `$patch`,
string `$dest`,
int `$flags` = DIFF_PATCH_NORMAL
): mixed

Применяет к файлу `file` патча `patch` и сохраняет результат в файл. `patch` должен быть унифицированным патчем, созданным функциями xdiff_file_diff()/xdiff_string_diff(). Необязательный параметр `flags` задаёт режим операции.

### Список параметров

`file`

  Оригинальный файл.

`patch`

  Унифицированный патч. Его можно создать функциями xdiff_string_diff() и xdiff_file_diff(), либо другими совместимыми инструментами.

`dest`

  Путь к результирующему файлу.

`flags`

  Может быть `XDIFF_PATCH_NORMAL` (режим по умолчанию, нормальное создание патча) или `XDIFF_PATCH_REVERSE` (откат патча).

  Начиная с версии 1.5.0 вы можете использовать побитовое ИЛИ для подключения флага `XDIFF_PATCH_IGNORESPACE`.

### Возвращаемые значения

Функция возвращает `true`, если создание патча прошло успешно, строку с отклонёнными данными, если нет, и `false` в случае внутренней ошибки.

### Примеры

Пример #1 Пример использования функции xdiff_file_patch()

Следующий код применяет унифицированный патч к файлу.

    <?php
    $old_version = 'my_script-1.0.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
    if (is_string($errors)) {
       echo "Отклонены:\n";
       echo $errors;
    }

    ?>

Пример #2 Пример отката патча

Следующий код применяет откат патча к файлу.

    <?php
    $new_version = 'my_script-1.1.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
    if (is_string($errors)) {
       echo "Отклонены:\n";
       echo $errors;
    }

    ?>

### Смотрите также

- xdiff_file_diff() - Создать унифицированный патч из сравнения двух файлов

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — Псевдоним xdiff_file_bpatch()

### Описание

function xdiff_file_patch_binary(string `$file`, string `$patch`, string `$dest`): bool

Применить к файлу `file` патч `patch` и записать результат в файл `dest`. Эта функция принимает патчи созданные как xdiff_file_bdiff() так и xdiff_file_rabdiff() или же их копии.

Начиная с версии 1.5.0, эта функция является псевдонимом xdiff_file_bpatch().

### Список параметров

`file`

  Оригинальный файл.

`patch`

  Файл бинарного патча.

`dest`

  Итоговый файл.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования xdiff_file_patch_binary()

В следующем коде показано применение бинарного патча к файлу.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "Файл пропатчен";
    } else {
       echo "Файл не может быть пропатчен";
    }

    ?>

### Примечания

> Замечание:

> Оба файла (`file` и `patch`) будут загружены в память, так что убедитесь, что параметр memory_limit настроен корректно.

### Смотрите также

- xdiff_string_patch_binary() - Псевдоним xdiff_string_bpatch

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — Создать бинарный патч сравнивая два файла с помощью полиноминального алгоритма Rabin fingerprinting

### Описание

function xdiff_file_rabdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Создаёт бинарный патч сравнивая два файла и сохраняет результат в файл. Эта функция отличается от xdiff_file_bdiff() используемым алгоритмом, который работает быстрее и производит патчи меньшего размера. Эта функция работает как с текстом, так и с бинарными данными. Патч впоследствии можно применить с помощью функций xdiff_file_bpatch()/xdiff_string_bpatch().

Более подробно разница алгоритмов объяснена на сайте » libxdiff.

### Список параметров

`old_file`

  Путь к первому, "старому" файлу.

`new_file`

  Путь ко второму, "новому" файлу.

`dest`

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

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования xdiff_file_rabdiff()

Следующий код сравнивает два архива и создаёт патч.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Примечания

> Замечание:

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

### Смотрите также

- xdiff_file_bpatch() - Применить бинарный патч к файлу

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — Создать бинарный патч для двух строк

### Описание

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Производит бинарное сравнение двух строк и возвращает патч. Эта функция работает как с текстом, там и с бинарными данными. Полученный патч впоследствии можно применить с помощью функций xdiff_string_bpatch() и xdiff_file_bpatch().

### Список параметров

`old_data`

  Первая строка с бинарными данными. Это будут "старые" данные.

`new_data`

  Вторая строка с бинарными данными. Это будут "новые" данные.

### Возвращаемые значения

Возвращает строку с бинарным патчем, содержащим разницу между "старыми" и "новыми" данными, либо `false` в случае возникновения ошибки.

### Смотрите также

- xdiff_string_bpatch() - Применение бинарного патча к строке

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — Получить размер файла созданного после применения бинарного патча

### Описание

function xdiff_string_bdiff_size(string `$patch`): int

Возвращает размер файла, который будет создан после применения бинарного патча (`patch`) к оригинальному файлу.

### Список параметров

`patch`

  Бинарный патч, созданный функциями xdiff_string_bdiff() или xdiff_string_rabdiff().

### Возвращаемые значения

Возвращает рассчитанный размер файла в байтах.

### Примеры

Пример #1 Пример использования xdiff_string_bdiff_size()

В следующем коде производится подсчёт результирующего размера файла после применения бинарного патча.

    <?php
    $binary_patch = file_get_contents('file.bdiff');
    $length = xdiff_string_bdiff_size($binary_patch);
    echo "Результирующий файл будет занимать $length байт";
    ?>

### Смотрите также

- xdiff_string_bdiff() - Создать бинарный патч для двух строк
- xdiff_string_rabdiff() - Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint
- xdiff_string_bpatch() - Применение бинарного патча к строке

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — Применение бинарного патча к строке

### Описание

function xdiff_string_bpatch(string `$str`, string `$patch`): string

Применяет к строке `str` бинарный патч `patch`. Эта функция принимает патчи созданные как xdiff_string_bdiff(), так и xdiff_string_rabdiff().

### Список параметров

`str`

  Оригинальная бинарная строка.

`patch`

  Строка с бинарным патчем.

### Возвращаемые значения

Возвращает изменённую строку, либо `false` в случае возникновения ошибки.

### Смотрите также

- xdiff_string_bdiff() - Создать бинарный патч для двух строк
- xdiff_string_rabdiff() - Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — Создать обычный патч для двух строк

### Описание

function xdiff_string_diff(
string `$old_data`,
string `$new_data`,
int `$context` = 3,
bool `$minimal` = `false`
): string

Создаёт патч для строк `old_data` и `new_data`. Итоговый патч человекочитаем. Опциональный параметр `context` указывает, сколько строк контекста должно быть добавлено в патч вокруг каждого различия. Установка параметра `minimal` в значение `true` позволит получить максимально короткий патч (может занять много времени).

### Список параметров

`old_data`

  Первая строка с данными. Это будут "старые" данные.

`new_data`

  Вторая строка с данными. Это будут "новые" данные.

`context`

  Количество строк контекста вокруг каждого изменения.

`minimal`

  Если `true`, то будет создан максимально короткий патч (может занять много времени).

### Возвращаемые значения

Возвращает строку с патчем, либо `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования xdiff_string_diff()

Следующий код выведет различия двух статей.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $new_article = $_REQUEST['article']; /* Допустим кто-то отправил новую статью через html-форму */

    $diff = xdiff_string_diff($old_article, $new_article, 1);
    if (is_string($diff)) {
        echo "Различия в двух статьях:\n";
        echo $diff;
    }

    ?>

### Примечания

> Замечание:

> Эта функция не предназначена для работы с бинарными данными. Для бинарного сравнения используйте xdiff_string_bdiff() и xdiff_string_rabdiff().

### Смотрите также

- xdiff_string_patch() - Применить обычный патч к строке

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — Псевдоним xdiff_string_bdiff()

### Описание

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Производит бинарное сравнение двух строк и возвращает патч. Эта функция работает как с текстом, там и с бинарными данными. Полученный патч впоследствии можно применить с помощью функций xdiff_string_bpatch() и xdiff_file_bpatch().

Начиная с версии 1.5.0 является псевдонимом для xdiff_string_bdiff().

### Список параметров

`old_data`

  Первая строка с бинарными данными. Это будут "старые" данные.

`new_data`

  Вторая строка с бинарными данными. Это будут "новые" данные.

### Возвращаемые значения

Возвращает строку с бинарным патчем, содержащим разницу между "старыми" и "новыми" данными, либо `false` в случае возникновения ошибки.

### Смотрите также

- xdiff_string_bdiff() - Создать бинарный патч для двух строк
- xdiff_string_bpatch() - Применение бинарного патча к строке

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — Объединить три строки в одну

### Описание

function xdiff_string_merge3(
string `$old_data`,
string `$new_data1`,
string `$new_data2`,
string `&$error` = ?
): mixed

Объединяет три строки в одну и возвращает результат. В параметре `old_data` задаётся оригинальная строка, а в в `new_data1` и `new_data2` - её модифицированные версии. Опциональный параметр `error` используется для сохранения ошибок в процессе объединения.

### Список параметров

`old_data`

  Первая строка с данными. Это будут "старые" данные.

`new_data1`

  Вторая строка с данными. Модифицированная версия `old_data`.

`new_data2`

  Третья строка с данными. Модифицированная версия `old_data`.

`error`

  Если задан, то сюда будут записываться возникшие ошибки.

### Возвращаемые значения

Возвращает полученную строку, `false` в случае возникновения ошибки или `true`, если полученная строка пуста.

### Смотрите также

- xdiff_file_merge3() - Объединение трёх файлов в один

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — Применить обычный патч к строке

### Описание

function xdiff_string_patch(
string `$str`,
string `$patch`,
int `$flags` = ?,
string `&$error` = ?
): string

Применяет к строке `str` обычный патч `patch` и возвращает результат. `patch` должен быть обычным патчем, созданным с помощью функций xdiff_file_diff() или xdiff_string_diff(). Опциональный параметр `flags` задаёт режим операции. Все отвергнутые части патча будут записаны в переменную `error`.

### Список параметров

`str`

  Оригинальная строка.

`patch`

  Стандартный патч. Должен быть создан функциями xdiff_string_diff(), или xdiff_file_diff(), либо с помощью инструментов, создающих совместимые патчи.

`flags`

  `flags` может быть `XDIFF_PATCH_NORMAL` (режим по умолчанию, нормальный патч) или `XDIFF_PATCH_REVERSE` (реверсивный патч).

  Начиная с версии 1.5.0 можно использовать бинарное ИЛИ для добавления флага `XDIFF_PATCH_IGNORESPACE`.

`error`

  Если задан, то в эту переменную будут записаны все отвергнутые части патча.

### Возвращаемые значения

Возвращает строку, либо `false` в случае возникновения ошибке.

### Примеры

Пример #1 Пример использования xdiff_string_patch()

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

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $diff = $_SERVER['patch']; /* Допустим кто-то отправил патч через html-форму */

    $errors = '';

    $new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
    if (is_string($new_article)) {
        echo "Новая статья:\n";
        echo $new_article;
    }

    if (strlen($errors)) {
        echo "Отклонены: \n";
        echo $errors;
    }

    ?>

### Смотрите также

- xdiff_string_diff() - Создать обычный патч для двух строк

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — Псевдоним xdiff_string_bpatch()

### Описание

function xdiff_string_patch_binary(string `$str`, string `$patch`): string

Применяет к строке `str` бинарный патч `patch`. Эта функция принимает патчи созданные как xdiff_string_bdiff(), так и xdiff_string_rabdiff().

Начиная с версии 1.5.0 является псевдонимом для xdiff_string_bpatch().

### Список параметров

`str`

  Оригинальная бинарная строка.

`patch`

  Строка с бинарным патчем.

### Возвращаемые значения

Возвращает изменённую строку, либо `false` в случае возникновения ошибки.

### Смотрите также

- xdiff_string_bpatch() - Применение бинарного патча к строке
- xdiff_string_bdiff() - Создать бинарный патч для двух строк
- xdiff_string_rabdiff() - Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint

### Описание

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

Создаёт бинарный патч для двух строк с помощью алгоритма цифровых отпечатков полиномов Рабина, реализованного в » libxdiff. По сравнению с функций xdiff_string_bdiff(), этот алгоритм обычно даёт меньшие различия и работает быстрее, оставаясь полностью совместимым с функциями xdiff_string_bpatch() и xdiff_file_bpatch() для применения патчей.

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

Более подробно о различиях в алгоритмах читайте » документацию libxdiff.

### Список параметров

`old_data`

  Первая строка, содержащая «старые» бинарные данные.

`new_data`

  Вторая строка, содержащая «новые» бинарные данные.

### Возвращаемые значения

Функция возвращает строку с бинарным патчем, содержащую различия между старыми и новыми данными или `false`, если возникла ошибка.

### Примеры

Пример #1 Создание двоичного сравнения между двумя строками

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### Смотрите также

- xdiff_string_bdiff() - Создать бинарный патч для двух строк
- xdiff_string_bpatch() - Применение бинарного патча к строке
- xdiff_file_bpatch() - Применить бинарный патч к файлу

## Содержание

- xdiff_file_bdiff — Создать бинарный патч сравнивая два файла
- xdiff_file_bdiff_size — Получить размер файла после применения бинарного патча
- xdiff_file_bpatch — Применить бинарный патч к файлу
- xdiff_file_diff — Создать унифицированный патч из сравнения двух файлов
- xdiff_file_diff_binary — Псевдоним xdiff_file_bdiff
- xdiff_file_merge3 — Объединение трёх файлов в один
- xdiff_file_patch — Применение унифицированного патча к файлу
- xdiff_file_patch_binary — Псевдоним xdiff_file_bpatch
- xdiff_file_rabdiff — Создать бинарный патч сравнивая два файла с помощью полиноминального алгоритма Rabin fingerprinting
- xdiff_string_bdiff — Создать бинарный патч для двух строк
- xdiff_string_bdiff_size — Получить размер файла созданного после применения бинарного патча
- xdiff_string_bpatch — Применение бинарного патча к строке
- xdiff_string_diff — Создать обычный патч для двух строк
- xdiff_string_diff_binary — Псевдоним xdiff_string_bdiff
- xdiff_string_merge3 — Объединить три строки в одну
- xdiff_string_patch — Применить обычный патч к строке
- xdiff_string_patch_binary — Псевдоним xdiff_string_bpatch
- xdiff_string_rabdiff — Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Функции xdiff
  - xdiff_file_bdiff — Создать бинарный патч сравнивая два файла
  - xdiff_file_bdiff_size — Получить размер файла после применения бинарного патча
  - xdiff_file_bpatch — Применить бинарный патч к файлу
  - xdiff_file_diff — Создать унифицированный патч из сравнения двух файлов
  - xdiff_file_diff_binary — Псевдоним xdiff_file_bdiff
  - xdiff_file_merge3 — Объединение трёх файлов в один
  - xdiff_file_patch — Применение унифицированного патча к файлу
  - xdiff_file_patch_binary — Псевдоним xdiff_file_bpatch
  - xdiff_file_rabdiff — Создать бинарный патч сравнивая два файла с помощью полиноминального алгоритма Rabin fingerprinting
  - xdiff_string_bdiff — Создать бинарный патч для двух строк
  - xdiff_string_bdiff_size — Получить размер файла созданного после применения бинарного патча
  - xdiff_string_bpatch — Применение бинарного патча к строке
  - xdiff_string_diff — Создать обычный патч для двух строк
  - xdiff_string_diff_binary — Псевдоним xdiff_string_bdiff
  - xdiff_string_merge3 — Объединить три строки в одну
  - xdiff_string_patch — Применить обычный патч к строке
  - xdiff_string_patch_binary — Псевдоним xdiff_string_bpatch
  - xdiff_string_rabdiff — Сравнить две строки и создать бинарный патч используя полиноминальный алгоритм Rabin fingerprint

- Прямой ввод/вывод (Direct IO)
  - Установка и настройка
  - Предопределённые константы
  - Функции прямого ввода/вывода
- Каталоги
  - Предопределённые константы
  - Directory — Класс Directory
  - Функции для работы с каталогами
- FileInfo — Информация о файле
  - Установка и настройка
  - Предопределённые константы
  - Функции модуля Fileinfo
  - finfo — Класс finfo
- Файловая система
  - Установка и настройка
  - Предопределённые константы
  - Функции файловой системы
- Inotify
  - Установка и настройка
  - Предопределённые константы
  - Функции Inotify
- xattr
  - Установка и настройка
  - Предопределённые константы
  - xattr Функции
- xdiff
  - Установка и настройка
  - Предопределённые константы
  - Функции xdiff

# Поддержка языков и кодировок

# Библиотека проверки правописания Enchant

# Введение

Модуль Enchant является представлением в » библиотеке Enchant. Enchant позволяет обеспечить единообразие и согласованность всех библиотек орфографии и реализовать определённые функции, которые могут отсутствовать в какой-либо отдельной библиотеке. Все и везде должно "просто работать", при любом определении "просто работающего".

Enchant поддерживает следующие бэкенды:

- `Aspell/Pspell (со временем заменят Ispell)`
- `Ispell (древний, как помёт мамонта, но, по факту, является стандартом)`
- `MySpell/Hunspell (проект OpenOffice.org, также используется Mozilla)`
- `Uspell (В основном, идиш, иврит и восточноевропейские языки - размещается в CVS AbiWord в модуле "uspell")`
- `Hspell (Иврит)`
- `AppleSpell (Mac OSX)`

# Установка и настройка

## Содержание

- Требования
- Установка
- Типы ресурсов

## Требования

Эта версия использует функции » библиотеки Enchant library, которую написал Dom Lachowicz. Требуется Enchant версии 1.2.4 или выше. Библиотека Enchant 2.0.0 или новее поддерживается только с PHP 8.0.0.

Требуется также библиотека » Glib 2.6 или выше. Скомпилированные библиотеки для Windows доступны по ссылке: » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.

## Установка

Если установлены необходимые библиотеки, то модуль можно установить с помощью опции --with-enchant[=dir] при компиляции PHP.

Пользователи Windows должны включить php_enchant.dll, чтобы использовать модуль.

> Замечание: Дополнительная настройка в Windows
> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: libenchant.dll, glib-2.dll, gmodule-2.dll. Кроме того, необходимо скопировать хотя бы одного поставщика из lib\enchant в \usr\local\lib\enchant-2 (это абсолютный путь от корня текущего диска). До версии PHP 8.0.0, т.е. при использовании Enchant v1, поставщики должны были быть скопированы в C:\enchant_plugins, где этот путь может быть настроен путём создания значения реестра `HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir`, указав в нём желаемый путь.

## Типы ресурсов

До PHP 8.0.0 в модуле было два типа ресурсов. Первый — брокер (менеджер бэкендов), а второй — для словаря.

# Предопределённые константы

`LIBENCHANT_VERSION` (string)
  Версия libenchant. Доступно с PHP 8.0.0.
`ENCHANT_MYSPELL` (int)
  Тип словаря MySpell. Используется с enchant_broker_get_dict_path() и enchant_broker_set_dict_path(). Объявлено устаревшим в PHP 8.0.0.
`ENCHANT_ISPELL` (int)
  Тип словаря Ispell. Используется с enchant_broker_get_dict_path() и enchant_broker_set_dict_path(). Объявлено устаревшим в PHP 8.0.0.

# Примеры

Пример #1 Пример использования Enchant

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Доступны следующие бэкенды:\n";
    print_r($bprovides);

    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        $dprovides = enchant_dict_describe($d);
        echo "словарь $tag:\n";
        $wordcorrect = enchant_dict_check($d, "soong");
        print_r($dprovides);
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Предложения для 'soong':";
            print_r($suggs);
        }
        enchant_broker_free_dict($d);
    } else {
    }
    enchant_broker_free($r);
    ?>

# Функции Enchant

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Перечисляет провайдеров Enchant

### Описание

function enchant_broker_describe(EnchantBroker `$broker`): array

Перечисляет провайдеров Enchant и возвращает минимальную информацию о них. Та же информация может быть получена через phpinfo().

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().

### Возвращаемые значения

Возвращает массив (array) доступных провайдеров Enchant с их данными.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).
8.0.0 | До этой версии функция возвращала `false` в случае возникновения ошибки.

### Примеры

Пример #1 Список бэкендов предоставляемых конкретным брокером

    <?php
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Брокер предоставляет следующие бэкенды:\n";
    print_r($bprovides);

    ?>

Вывод приведённого примера будет похож на:

    Брокер предоставляет следующие бэкенды:
    Array
    (
        [0] => Array
            (
                [name] => aspell
                [desc] => Aspell Provider
                [file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [name] => hspell
                [desc] => Hspell Provider
                [file] => /usr/lib/enchant/libenchant_hspell.so
            )

        [2] => Array
            (
                [name] => ispell
                [desc] => Ispell Provider
                [file] => /usr/lib/enchant/libenchant_ispell.so
            )

        [3] => Array
            (
                [name] => myspell
                [desc] => Myspell Provider
                [file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

# enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — Проверяет, присутствует ли словарь или нет

### Описание

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Проверяет, присутствует ли словарь или нет используя не пустой тег

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`tag`
  Не пустой тег в формате LOCALE, т.е.: us_US, ch_DE и т.д.

### Возвращаемые значения

Возвращает `true` или `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования enchant_broker_dict_exists()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        echo $tag . " словарь найден.\n";
    }
    ?>

### Смотрите также

- enchant_broker_describe() - Перечисляет провайдеров Enchant

# enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — Освобождает ресурс брокера и его словари

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

Функция освобождает брокера со всеми его словарями. Начиная с PHP 8.0.0 вместо вызова функции рекомендуют уничтожить объект.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу удаления объекта.
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

### Смотрите также

- enchant_broker_init() - Создать новый объект брокера

# enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — Освобождает ресурс словаря

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function enchant_broker_free_dict(EnchantDictionary `$dictionary`): bool

Освобождает словарь. Начиная с PHP 8.0.0 вместо вызова функции рекомендуют уничтожить объект.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела в пользу удаления объекта.
8.0.0 | Параметр `dictionary` теперь ожидает экземпляр класса EnchantDictionary; раньше ожидался ресурс (resource).

### Смотрите также

- enchant_broker_request_dict() - Создаёт новый словарь на основе тега
- enchant_broker_request_pwl_dict() - Создать словарь используя файл PWL

# enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — Возвращает путь словаря для заданного бэкенда

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Функция возвращает путь словаря для заданного бэкенда.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`type`
  Тип словарей — `ENCHANT_MYSPELL` или `ENCHANT_ISPELL`.

### Возвращаемые значения

Функция возвращает путь к директории словаря, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела.
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

### Примечания

> Замечание: Функция доступна, только если модуль скомпилировали с библиотекой Enchant v1.

### Смотрите также

- enchant_broker_set_dict_path() - Устанавливает путь для бэкенда

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — Возвращает последнюю ошибку брокера

### Описание

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Возвращает последнюю ошибку, возникшую на брокере.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().

### Возвращаемые значения

Возвращает строку с ошибкой, если таковая была, или `false`

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — Создать новый объект брокера

### Описание

function enchant_broker_init(): EnchantBroker|false

### Список параметров

### Возвращаемые значения

Возвращает ресурс брокера или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция возвращает экземпляр EnchantBroker; Ранее возвращался ресурс (resource).

### Смотрите также

- enchant_broker_free() - Освобождает ресурс брокера и его словари

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — Возвращает список доступных словарей

### Описание

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Возвращает список доступных словарей.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().

### Возвращаемые значения

Возвращает массив (array) доступных словарей с их данными.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).
8.0.0 | До этой версии функция возвращала `false` в случае возникновения ошибки.

### Примеры

Пример #1 Список всех доступных на брокере словарей

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => Array
            (
                [lang_tag] => de
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [lang_tag] => de_DE
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [3] => Array
            (
                [lang_tag] => en
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [4] => Array
            (
                [lang_tag] => en_GB
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [5] => Array
            (
                [lang_tag] => en_US
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [6] => Array
            (
                [lang_tag] => hi_IN
                [provider_name] => myspell
                [provider_desc] => Myspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

### Смотрите также

- enchant_broker_describe() - Перечисляет провайдеров Enchant

# enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — Создаёт новый словарь на основе тега

### Описание

function enchant_broker_request_dict(EnchantBroker `$broker`, string `$tag`): EnchantDictionary|false

Функция создаёт новый словарь по непустому языковому тегу наподобие "en_US" или "ru_RU".

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`tag`
  Тег описания локали в формате en_US, ru_RU.

### Возвращаемые значения

Функция возвращает ресурс словаря, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).
8.0.0 | При успешном выполнении функция теперь возвращает экземпляр класса EnchantDictionary; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания нового словаря функцией enchant_broker_request_dict()

Проверяем доступность словаря функцией enchant_broker_dict_exists() и запрашиваем его.

    <?php

    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        var_dump($dict);
    }

    ?>

### Смотрите также

- enchant_dict_describe() - Возвращает информацию о словаре
- enchant_broker_dict_exists() - Проверяет, присутствует ли словарь или нет
- enchant_broker_free_dict() - Освобождает ресурс словаря

# enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — Создать словарь используя файл PWL

### Описание

function enchant_broker_request_pwl_dict(EnchantBroker `$broker`, string `$filename`): EnchantDictionary|false

Создаёт словарь используя файл PWL. Файл PWL - это пользовательский файл со словами, по одному слову на строку.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`filename`
  Путь к файлу PWL. Если файл отсутствует, то будет создан новый с таким именем, если возможно.

### Возвращаемые значения

Возвращает ресурс словаря в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).
8.0.0 | В случае успешного выполнения функция возвращает экземпляр EnchantDictionary; Ранее возвращался ресурс (resource).

### Смотрите также

- enchant_dict_describe() - Возвращает информацию о словаре
- enchant_broker_dict_exists() - Проверяет, присутствует ли словарь или нет
- enchant_broker_free_dict() - Освобождает ресурс словаря

# enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — Устанавливает путь для бэкенда

Внимание

Начиная с PHP 8.0.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Функция устанавливает путь для заданного бэкенда.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`type`
  Тип словарей — `ENCHANT_MYSPELL` или `ENCHANT_ISPELL`.
`path`
  Путь к директории со словарями.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция устарела.
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

### Примечания

> Замечание: Функция доступна, только если модуль скомпилировали с библиотекой Enchant v1.

### Смотрите также

- enchant_broker_get_dict_path() - Возвращает путь словаря для заданного бэкенда

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — Задать предпочтения по выбору словарей для языка

### Описание

function enchant_broker_set_ordering(EnchantBroker `$broker`, string `$tag`, string `$ordering`): bool

Задаёт предпочтения по выбору словарей для языка, описанный с помощью тега 'tag'. Порядок задаётся с помощью списка имён провайдеров, разделённых запятыми. В особых случаях можно использовать тег "*" для определения порядка для всех языков, для которых этот порядок не задаётся явно.

### Список параметров

`broker`
  Провайдер Enchant, который возвращает функция enchant_broker_init().
`tag`
  Языковой тег. В особых случаях можно использовать тег "*" для определения порядка для всех языков, для которых этот порядок не задаётся явно.
`ordering`
  Список имён провайдеров, разделённых запятыми

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `broker` ожидает экземпляр класса EnchantBroker; Раньше параметр ждал ресурс (resource).

# enchant_dict_add

(PHP 8)

enchant_dict_add — Добавляет слово в личный словарь

### Описание

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Функция добавляет слово в личный словарь.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для добавления.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример добавления слова в персональный список слов (англ. PWL, Personal Word List)

    <?php

    $filename = './my_word_list.pwl';
    $word = 'Supercalifragilisticexpialidocious';

    $broker = enchant_broker_init();
    $dict = enchant_broker_request_pwl_dict($broker, $filename);

    enchant_dict_add($dict, $word);

    ?>

### Смотрите также

- enchant_broker_request_pwl_dict() - Создать словарь используя файл PWL
- enchant_broker_request_dict() - Создаёт новый словарь на основе тега

# enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — Псевдоним enchant_dict_add()

Внимание

Начиная с PHP 8.0.0 псевдоним УСТАРЕЛ.

### Описание

Псевдоним функции enchant_dict_add().

# enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — Добавить слово в текущую сессию проверки

### Описание

function enchant_dict_add_to_session(EnchantDictionary `$dictionary`, string `$word`): void

Добавляет слово в заданный словарь. Слово будет присутствовать только в текущей сессии проверки.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для добавления

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

### Смотрите также

- enchant_broker_request_dict() - Создаёт новый словарь на основе тега

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — Проверяет, корректно ли задано слово

### Описание

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

Возвращает `true`, если слово написано без ошибок или `false`, если с ошибками.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для проверки

### Возвращаемые значения

Возвращает `true`, если слово написано без ошибок или `false`, если с ошибками.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Возвращает информацию о словаре

### Описание

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Функция возвращает информацию о словаре.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).
8.0.0 | До этой версии функция возвращала `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения информации о словаре функцией enchant_dict_describe()

Проверим доступность словаря функцией enchant_broker_dict_exists() и получим информацию о нём.

    <?php

    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        $dict_details = enchant_dict_describe($dict);
        print_r($dict_details);
    }

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [lang] => en_US
        [name] => aspell
        [desc] => Aspell Provider
        [file] => /usr/lib/enchant/libenchant_aspell.so
    )

# enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — Возвращает последнюю ошибку текущей сессии проверки

### Описание

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Возвращает последнюю ошибку текущей сессии проверки.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().

### Возвращаемые значения

Возвращает строку с ошибкой или `false`, если таковой нет.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Определяет, существует ли слово в этой орфографической сессии

### Описание

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Определяет, существует ли уже слово в текущей сессии.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для поиска

### Возвращаемые значения

Возвращает `true`, если слово уже существует, в противном случае возвращает `false`

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

### Смотрите также

- enchant_dict_add_to_session() - Добавить слово в текущую сессию проверки

# enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — Псевдоним enchant_dict_is_added()

Внимание

Начиная с PHP 8.0.0 псевдоним УСТАРЕЛ.

### Описание

Псевдоним функции enchant_dict_is_added().

# enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — Проверить, правильно ли написано слово и предложить варианты замены

### Описание

function enchant_dict_quick_check(EnchantDictionary `$dictionary`, string `$word`, array `&$suggestions` = `null`): bool

Если слово корректно, то вернёт `true`, в ином случае вернёт `false`. Если задан параметр suggestions, то он будет заполнен вариантами замены.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для проверки
`suggestions`
  Если проверка провалилась, то эта переменная будет содержать массив с вариантами замены

### Возвращаемые значения

Возвращает `true`, если слово написано правильно или `false`, если нет

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования enchant_dict_quick_check()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();

    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        enchant_dict_quick_check($d, 'soong', $suggs);
        print_r($suggs);
    }
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => song
        [1] => snog
        [2] => soon
        [3] => Sang
        [4] => Sung
        [5] => sang
        [6] => sung
        [7] => sponge
        [8] => spongy
        [9] => snag
        [10] => snug
        [11] => sonic
        [12] => sing
        [13] => songs
        [14] => Son
        [15] => Sonja
        [16] => Synge
        [17] => son
        [18] => Sejong
        [19] => sarong
        [20] => sooner
        [21] => Sony
        [22] => sown
        [23] => scone
        [24] => song's
    )

### Смотрите также

- enchant_dict_check() - Проверяет, корректно ли задано слово
- enchant_dict_suggest() - Возвращает список возможных вариантов исправления для слова с ошибкой

# enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — Добавить исправление для слова

### Описание

function enchant_dict_store_replacement(EnchantDictionary `$dictionary`, string `$misspelled`, string `$correct`): void

Добавить исправление 'cor' для 'mis'. Обратите внимание, что если вы замените @mis на @cor, то в будущем вхождения @mis будут заменяться на @cor. Соответственно это может поднять @cor вверх в списке возможных замен.

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`misspelled`
  Слово для исправления
`correct`
  Корректное слово

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Возвращает список возможных вариантов исправления для слова с ошибкой

### Описание

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### Список параметров

`dictionary`
  Словарь Enchant, который возвращает функция enchant_broker_request_dict() или enchant_broker_request_pwl_dict().
`word`
  Слово для проверки.

### Возвращаемые значения

Функция возвращает массив подсказок с исправлениями для слова с ошибкой.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dictionary` ожидает экземпляр класса EnchantDictionary; Раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример получения подсказок с исправлениями функцией enchant_dict_suggest()

    <?php

    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r, $tag)) {
        $d = enchant_broker_request_dict($r, $tag);

        $wordcorrect = enchant_dict_check($d, "soong");
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Подсказки для 'soong':";
            print_r($suggs);
        }
    }

    ?>

### Смотрите также

- enchant_dict_check() - Проверяет, корректно ли задано слово
- enchant_dict_quick_check() - Проверить, правильно ли написано слово и предложить варианты замены

## Содержание

- enchant_broker_describe — Перечисляет провайдеров Enchant
- enchant_broker_dict_exists — Проверяет, присутствует ли словарь или нет
- enchant_broker_free — Освобождает ресурс брокера и его словари
- enchant_broker_free_dict — Освобождает ресурс словаря
- enchant_broker_get_dict_path — Возвращает путь словаря для заданного бэкенда
- enchant_broker_get_error — Возвращает последнюю ошибку брокера
- enchant_broker_init — Создать новый объект брокера
- enchant_broker_list_dicts — Возвращает список доступных словарей
- enchant_broker_request_dict — Создаёт новый словарь на основе тега
- enchant_broker_request_pwl_dict — Создать словарь используя файл PWL
- enchant_broker_set_dict_path — Устанавливает путь для бэкенда
- enchant_broker_set_ordering — Задать предпочтения по выбору словарей для языка
- enchant_dict_add — Добавляет слово в личный словарь
- enchant_dict_add_to_personal — Псевдоним enchant_dict_add
- enchant_dict_add_to_session — Добавить слово в текущую сессию проверки
- enchant_dict_check — Проверяет, корректно ли задано слово
- enchant_dict_describe — Возвращает информацию о словаре
- enchant_dict_get_error — Возвращает последнюю ошибку текущей сессии проверки
- enchant_dict_is_added — Определяет, существует ли слово в этой орфографической сессии
- enchant_dict_is_in_session — Псевдоним enchant_dict_is_added
- enchant_dict_quick_check — Проверить, правильно ли написано слово и предложить варианты замены
- enchant_dict_store_replacement — Добавить исправление для слова
- enchant_dict_suggest — Возвращает список возможных вариантов исправления для слова с ошибкой

# Класс EnchantBroker

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `enchant_broker` в PHP 8.0.0.

## Обзор класса

final class EnchantBroker {
}

# Класс EnchantDictionary

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `enchant_dict` в PHP 8.0.0.

## Обзор класса

final class EnchantDictionary {
}

- Установка и настройка
  - Требования
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Примеры
- Функции Enchant
  - enchant_broker_describe — Перечисляет провайдеров Enchant
  - enchant_broker_dict_exists — Проверяет, присутствует ли словарь или нет
  - enchant_broker_free — Освобождает ресурс брокера и его словари
  - enchant_broker_free_dict — Освобождает ресурс словаря
  - enchant_broker_get_dict_path — Возвращает путь словаря для заданного бэкенда
  - enchant_broker_get_error — Возвращает последнюю ошибку брокера
  - enchant_broker_init — Создать новый объект брокера
  - enchant_broker_list_dicts — Возвращает список доступных словарей
  - enchant_broker_request_dict — Создаёт новый словарь на основе тега
  - enchant_broker_request_pwl_dict — Создать словарь используя файл PWL
  - enchant_broker_set_dict_path — Устанавливает путь для бэкенда
  - enchant_broker_set_ordering — Задать предпочтения по выбору словарей для языка
  - enchant_dict_add — Добавляет слово в личный словарь
  - enchant_dict_add_to_personal — Псевдоним enchant_dict_add
  - enchant_dict_add_to_session — Добавить слово в текущую сессию проверки
  - enchant_dict_check — Проверяет, корректно ли задано слово
  - enchant_dict_describe — Возвращает информацию о словаре
  - enchant_dict_get_error — Возвращает последнюю ошибку текущей сессии проверки
  - enchant_dict_is_added — Определяет, существует ли слово в этой орфографической сессии
  - enchant_dict_is_in_session — Псевдоним enchant_dict_is_added
  - enchant_dict_quick_check — Проверить, правильно ли написано слово и предложить варианты замены
  - enchant_dict_store_replacement — Добавить исправление для слова
  - enchant_dict_suggest — Возвращает список возможных вариантов исправления для слова с ошибкой
- EnchantBroker — Класс EnchantBroker
- EnchantDictionary — Класс EnchantDictionary

# Определение пола по имени

# Введение

Модуль PHP Gender - это порт программы gender.c, написанной Михаэлем Йоргом. Главное назначение этой программы - определение пола человека по его имени. Текущая база данных содержит более 40000 имён из 54 стран.

# Установка и настройка

## Содержание

- Установка

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/gender.

# Примеры

## Содержание

- Пример использования

## Пример использования

Пример использования класса Gender.

Пример #1 Пример использования.

    <?php

    namespace Gender;

    $gender = new Gender;

    $name = "Milene";
    $country = Gender::FRANCE;

    $result = $gender->get($name, $country);

    $data = $gender->country($country);

    switch($result) {
        case Gender::IS_FEMALE:
            printf("%s - это женское имя в стране %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("%s  - это скорее всего женское имя в стране %s\n", $name, $data['country']);
        break;

        case Gender::IS_MALE:
            printf("%s - это мужское имя в стране %s\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("%s  - это скорее всего женское имя в стране %s\n", $name, $data['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("Имя %s годится и для женщин, и для мужчин в стране %s\n", $name, $data['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("Имя %s может быть и женским, и мужским в стране %s\n", $name, $data['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("Имя %s не найдено для страны %s\n", $name, $data['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "В заданном имени ошибка!\n";
        break;

        default:
            echo "Произошла ошибка!\n";
        break;

    }

# Класс Gender\Gender

(PECL gender >= 0.6.0)

## Введение

## Обзор класса

class Gender\Gender {
/* Константы */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* Методы */
public function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function similarNames(string `$name`, int `$country` = ?): array
}

## Предопределённые константы

`Gender\Gender::IS_FEMALE`
`Gender\Gender::IS_MOSTLY_FEMALE`
`Gender\Gender::IS_MALE`
`Gender\Gender::IS_MOSTLY_MALE`
`Gender\Gender::IS_UNISEX_NAME`
`Gender\Gender::IS_A_COUPLE`
`Gender\Gender::NAME_NOT_FOUND`
`Gender\Gender::ERROR_IN_NAME`
`Gender\Gender::ANY_COUNTRY`
`Gender\Gender::BRITAIN`
`Gender\Gender::IRELAND`
`Gender\Gender::USA`
`Gender\Gender::SPAIN`
`Gender\Gender::PORTUGAL`
`Gender\Gender::ITALY`
`Gender\Gender::MALTA`
`Gender\Gender::FRANCE`
`Gender\Gender::BELGIUM`
`Gender\Gender::LUXEMBOURG`
`Gender\Gender::NETHERLANDS`
`Gender\Gender::GERMANY`
`Gender\Gender::EAST_FRISIA`
`Gender\Gender::AUSTRIA`
`Gender\Gender::SWISS`
`Gender\Gender::ICELAND`
`Gender\Gender::DENMARK`
`Gender\Gender::NORWAY`
`Gender\Gender::SWEDEN`
`Gender\Gender::FINLAND`
`Gender\Gender::ESTONIA`
`Gender\Gender::LATVIA`
`Gender\Gender::LITHUANIA`
`Gender\Gender::POLAND`
`Gender\Gender::CZECH_REP`
`Gender\Gender::SLOVAKIA`
`Gender\Gender::HUNGARY`
`Gender\Gender::ROMANIA`
`Gender\Gender::BULGARIA`
`Gender\Gender::BOSNIA`
`Gender\Gender::CROATIA`
`Gender\Gender::KOSOVO`
`Gender\Gender::MACEDONIA`
`Gender\Gender::MONTENEGRO`
`Gender\Gender::SERBIA`
`Gender\Gender::SLOVENIA`
`Gender\Gender::ALBANIA`
`Gender\Gender::GREECE`
`Gender\Gender::RUSSIA`
`Gender\Gender::BELARUS`
`Gender\Gender::MOLDOVA`
`Gender\Gender::UKRAINE`
`Gender\Gender::ARMENIA`
`Gender\Gender::AZERBAIJAN`
`Gender\Gender::GEORGIA`
`Gender\Gender::KAZAKH_UZBEK`
`Gender\Gender::TURKEY`
`Gender\Gender::ARABIA`
`Gender\Gender::ISRAEL`
`Gender\Gender::CHINA`
`Gender\Gender::INDIA`
`Gender\Gender::JAPAN`
`Gender\Gender::KOREA`

# Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — Соединение с внешней базой имён

### Описание

public function Gender\Gender::connect(string `$dsn`): bool

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

### Список параметров

`dsn`
  DSN для открытия.

### Возвращаемые значения

`true` либо `false` в зависимости от успешности.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Конструктор объекта класса Gender

### Описание

public function Gender\Gender::__construct(string `$dsn` = ?)

Создаёт объект класса Gender, который необязательно может быть подключён к внешнему словарю имён. Если внешняя база данных не задана, то будут использоваться внутренние скомпилированные данные.

### Список параметров

`dsn`
  DSN для открытия.

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Получить текстовое представление страны

### Описание

public function Gender\Gender::country(int `$country`): array|false

Возвращает текстовое представление страны из констант класса Gender.

### Список параметров

`country`
  Идентификатор страны, заданный константой класса Gender\Gender.

### Возвращаемые значения

Возвращает массив с коротким и полным имени страны в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

Результат выполнения приведённого примера:

    array(2) {
      'country_short' =>
      string(2) "UK"
      'country' =>
      string(13) "Great Britain"
    }

# Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — Получить пол по имени

### Описание

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Получить пол по имени в заданной стране.

### Список параметров

`name`
  Имя для проверки.
`country`
  Идентификатор страны, заданный константой класса Gender.

### Возвращаемые значения

Возвращает пол по имени.

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — Проверяет, является ли name0 псевдонимом для name1

### Описание

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Проверяет, является ли name0 псевдонимом для name1.

### Список параметров

`name0`
  Имя для проверки.
`name1`
  Имя для проверки.
`country`
  Идентификатор страны, определяемой константой класса Gender. Если опущен, то используется ANY_COUNTRY.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Получить похожие имена

### Описание

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Получить похожие имена для заданных имени и страны.

### Список параметров

`name`
  Имя для проверки.
`country`
  Идентификатор страны заданный константой класса. Если опущен, то используется ANY_COUNTRY.

### Возвращаемые значения

Возвращает массив с найденными похожими именами.

## Содержание

- Gender\Gender::connect — Соединение с внешней базой имён
- Gender\Gender::__construct — Конструктор объекта класса Gender
- Gender\Gender::country — Получить текстовое представление страны
- Gender\Gender::get — Получить пол по имени
- Gender\Gender::isNick — Проверяет, является ли name0 псевдонимом для name1
- Gender\Gender::similarNames — Получить похожие имена

- Установка и настройка
  - Установка
- Примеры
  - Пример использования
- Gender\Gender — Класс Gender\Gender
  - Gender\Gender::connect — Соединение с внешней базой имён
  - Gender\Gender::__construct — Конструктор объекта класса Gender
  - Gender\Gender::country — Получить текстовое представление страны
  - Gender\Gender::get — Получить пол по имени
  - Gender\Gender::isNick — Проверяет, является ли name0 псевдонимом для name1
  - Gender\Gender::similarNames — Получить похожие имена

# Gettext

# Введение

Функции модуля gettext реализуют API-интерфейс поддержки родного языка NLS (Native Language Support), через который интернационализируют PHP-приложения. Подробное описание функций и документация gettext для текущей системы доступны по адресу » http://www.gnu.org/software/gettext/manual/gettext.html.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Функции модуля будут работать, только если установить пакет GNU gettext, который доступен для скачивания по ссылке: » http://www.gnu.org/software/gettext/gettext.html.

## Установка

Чтобы включить поддержку GNU gettext в вашу сборку PHP, добавьте в конфигурацию ключ --with-gettext[=DIR], где DIR - папка установки gettext, обычно это /usr/local.

# Функции gettext

# _

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

_ — Псевдоним функции gettext()

### Описание

Псевдоним функции gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Устанавливает или получает кодировку, в которой будут возвращаться сообщения из каталога сообщений домена

### Описание

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

Функция bind_textdomain_codeset() устанавливает или получает кодировку, в которой функции наподобие gettext() будут возвращать сообщения из домена `domain`.

### Список параметров

`domain`

  Домен.

`codeset`

  Кодировка. Функция вернёт текущую установленную кодировку, если для параметра установили значение `null`.

### Возвращаемые значения

Функция возвращает строку, если выполнилась успешно.

### Ошибки

Функция выбрасывает ошибку ValueError, если в аргументе `domain` передали пустую строку (string).

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `domain` является пустой строкой (string).
8.4.0 | Параметр `codeset` стал необязательным. Раньше параметр требовалось указывать при каждом вызове.
8.0.3 | Параметр `codeset` теперь принимает значение `null`. Раньше было невозможно получить текущую установленную кодировку.

### Примечания

> Замечание:

> Информация, которую устанавливает функция bind_textdomain_codeset(), сохраняется для каждого процесса, а не для потока.

# bindtextdomain

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

bindtextdomain — Устанавливает или получает путь к домену

### Описание

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

Функция bindtextdomain() устанавливает или получает путь к домену.

### Список параметров

`domain`

  Домен.

`directory`

  Путь к каталогу. Пустая строка обозначает текущий каталог. Функция возвращает текущий установленный каталог, если для параметра установили значение `null`.

### Возвращаемые значения

Функция возвращает полный путь к домену, который установили в параметре `domain` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `directory` стал необязательным. Раньше параметр требовалось указывать при каждом вызове.
8.0.3 | Параметр `directory` теперь принимает значение `null`. Раньше было невозможно получить текущий установленный каталог.

### Примеры

Пример #1 Пример установки пути к домену функцией bindtextdomain()

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

Результат выполнения приведённого примера:

    /usr/share/myapp/locale

### Примечания

> Замечание:

> Информация которую устанавливает функция bindtextdomain(), сохраняется для каждого процесса, а не для потока.

# dcgettext

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

dcgettext — Переопределяет одно сообщение в домене

### Описание

function dcgettext(string `$domain`, string `$message`, int `$category`): string

Данная функция позволяет переопределить текущий домен для одного сообщения.

### Список параметров

`domain`

  Домен

`message`

  Сообщение

`category`

  Категория

### Возвращаемые значения

В случае успешного выполнения возвращает значение типа string.

### Смотрите также

- gettext() - Ищет сообщение в текущем домене

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Версия dcgettext для множественного числа

### Описание

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

Данная функция позволяет переопределить одно сообщение с использованием множественного числа в текущем домене.

### Список параметров

`domain`

  Домен.

`singular`

`plural`

`count`

`category`

### Возвращаемые значения

В случае успешного выполнения возвращает строку (string).

### Смотрите также

- ngettext() - Версия функции gettext для сообщений во множественном числе

# dgettext

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

dgettext — Переопределяет текущий домен для одного сообщения

### Описание

function dgettext(string `$domain`, string `$message`): string

Функция dgettext() позволяет переопределить текущий домен `domain` для одного сообщения.

### Список параметров

`domain`

  Домен.

`message`

  Сообщение.

### Возвращаемые значения

В случае успешного выполнения возвращает значение типа string.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `domain` является пустой строкой (string).

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `domain` является пустой строкой (string).

### Смотрите также

- gettext() - Ищет сообщение в текущем домене

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Версия dgettext для множественного числа

### Описание

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

Функция dngettext() позволяет переопределить текущий домен `domain` для одного сообщения во множественном числе.

### Список параметров

`domain`

  Домен.

`singular`

`plural`

`count`

### Возвращаемые значения

В случае успешного выполнения возвращает строку (string).

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `domain` является пустой строкой (string).

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `domain` является пустой строкой (string).

### Смотрите также

- ngettext() - Версия функции gettext для сообщений во множественном числе

# gettext

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

gettext — Ищет сообщение в текущем домене

### Описание

function gettext(string `$message`): string

Функция ищет сообщение в текущем домене.

### Список параметров

`message`

  Переводимое сообщение.

### Возвращаемые значения

Функция возвращает строку (string) перевода, если строка содержится в таблице перевода, иначе функция возвращает исходное сообщение.

### Примеры

Пример #1 Пример проверки перевода функцией gettext()

    <?php

    // Устанавливаем русский язык
    putenv('LC_ALL=ru_RU');
    setlocale(LC_ALL, 'ru_RU');

    // Указываем путь к таблицам переводов
    bindtextdomain("myPHPApp", "./locale");

    // Выбираем домен
    textdomain("myPHPApp");

    // Теперь функция будет искать перевод в файле ./locale/ru_RU/LC_MESSAGES/myPHPApp.mo

    // Выводим тестовое сообщение
    echo gettext("Welcome to My PHP Application");

    // Или вызываем псевдоним функции gettext() — функцию _()
    echo _("Have a nice day");

    ?>

### Примечания

> Замечание:

> Символ подчёркивания «_» работает как псевдоним функции.

> Замечание:

> В отдельных системах установки языка недостаточно, и для установки текущей локали вызывают функцию putenv().

### Смотрите также

- _() - Псевдоним функции gettext
- setlocale() - Устанавливает региональные настройки

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Версия функции gettext для сообщений во множественном числе

### Описание

function ngettext(string `$singular`, string `$plural`, int `$count`): string

Функция — версия функции gettext() для сообщений во множественном числе. Отдельные языки содержат больше одной формы сообщений во множественном числе, в зависимости от количества.

### Список параметров

`singular`

  Идентификатор сообщения в единственном числе.

`plural`

  Идентификатор сообщения во множественном числе.

`count`

  Число (например, количество элементов), на основе которого функция определит грамматическую форму перевода.

### Возвращаемые значения

Функция возвращает правильную форму сообщения во множественном числе, которую идентифицирует по параметрам `singular` и `plural` для количества `count`.

### Примеры

Пример #1 Пример использования функции ngettext()

    <?php

    setlocale(LC_ALL, 'ru_RU');

    printf(ngettext("%d окно\n", "%d окон\n", 1), 1); // 1 окно
    printf(ngettext("%d окно\n", "%d окна\n", 2), 2); // 2 окна
    printf(ngettext("%d окно\n", "%d окон\n", 5), 5); // 5 окон

    ?>

# textdomain

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

textdomain — Устанавливает домен по умолчанию

### Описание

function textdomain(?string `$domain` = `null`): string

Функция устанавливает домен, название которого часто совпадает с названием приложения, в котором будет искать сообщение функция gettext().

### Список параметров

`domain`

  Новый домен сообщений или `null`, чтобы получить текущее значение без изменения.

### Возвращаемые значения

Функция возвращает текущий домен сообщений после возможного изменения, если не возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если в аргументе `domain` передали пустую строку (string).

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Параметр `domain` стал необязательным. Раньше параметр требовалось указывать при каждом вызове.
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если в аргументе `domain` передали пустую строку (string).

### Примечания

> Замечание:

> Информацию о домене, которую устанавливает или возвращает функция textdomain(), сохраняется для каждого процесса, а не для потока.

## Содержание

- _ — Псевдоним функции gettext
- bind_textdomain_codeset — Устанавливает или получает кодировку, в которой будут возвращаться сообщения из каталога сообщений домена
- bindtextdomain — Устанавливает или получает путь к домену
- dcgettext — Переопределяет одно сообщение в домене
- dcngettext — Версия dcgettext для множественного числа
- dgettext — Переопределяет текущий домен для одного сообщения
- dngettext — Версия dgettext для множественного числа
- gettext — Ищет сообщение в текущем домене
- ngettext — Версия функции gettext для сообщений во множественном числе
- textdomain — Устанавливает домен по умолчанию

- Установка и настройка
  - Требования
  - Установка
- Функции gettext
  - _ — Псевдоним функции gettext
  - bind_textdomain_codeset — Устанавливает или получает кодировку, в которой будут возвращаться сообщения из каталога сообщений домена
  - bindtextdomain — Устанавливает или получает путь к домену
  - dcgettext — Переопределяет одно сообщение в домене
  - dcngettext — Версия dcgettext для множественного числа
  - dgettext — Переопределяет текущий домен для одного сообщения
  - dngettext — Версия dgettext для множественного числа
  - gettext — Ищет сообщение в текущем домене
  - ngettext — Версия функции gettext для сообщений во множественном числе
  - textdomain — Устанавливает домен по умолчанию

# iconv

# Введение

Этот модуль содержит интерфейс преобразования кодировок функцией iconv. С этим модулем можно изменять кодировку строки на другую, которая может быть набором символов Юникод. Набор поддерживаемых кодировок зависит от реализации iconv в системе. Заметьте, бывают системы, в которых функция iconv работает не так, как ожидалось. Тогда хорошей идеей будет — установить библиотеку » GNU libiconv. Скорее всего, это приведёт к более непротиворечивым результатам.

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

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Операционные системы, отвечающие стандартам POSIX, поставляются с C-библиотеками, предоставляющими функциональность iconv. Если ваша система в этот список не входит, вам нужно установить библиотеку » libiconv.

## Установка

Этот модуль включён по умолчанию, чтобы его отключить, используйте опцию --without-iconv.

Также может быть задана необязательная директива --with-iconv[=DIR] для указания альтернативного расположения iconv в системе, в которой компилируется PHP, иначе будет использовано расположение по умолчанию.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Iconv
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | Устарело с PHP 5.6.0.
iconv.output_encoding | "" | `INI_ALL` | Устарело с PHP 5.6.0.
iconv.internal_encoding | "" | `INI_ALL` | Устарело с PHP 5.6.0.

Краткое разъяснение конфигурационных директив.

Внимание

Некоторые системы (например IBM AIX) используют "ISO8859-1" вместо "ISO-8859-1", поэтому это значение должно быть указано в настройках и параметрах функции.

`iconv.input_encoding` string
  Внимание

  Начиная с PHP 5.6.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

  В PHP 5.6 и новее нужно оставлять эту опцию пустой и использовать вместо неё input_encoding.

`iconv.output_encoding` string
  Внимание

  Начиная с PHP 5.6.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

  В PHP 5.6 и новее нужно оставлять эту опцию пустой и использовать вместо неё output_encoding.

`iconv.internal_encoding` string
  Внимание

  Начиная с PHP 5.6.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

  В PHP 5.6 и новее нужно оставлять эту опцию пустой и использовать вместо неё `default_charset`.

# Предопределённые константы

Возможно узнать во время выполнения, какая реализация `iconv` используется модулем.

Константы реализации `iconv`
Имя | Тип | Описание
--- | --- | ---
`ICONV_IMPL` (string) | string | Реализация
`ICONV_VERSION` (string) | string | Версия реализации

> Замечание:

> Используйте эти константы для написания сценариев, независимых от реализации.

Доступны также следующие константы:

Другие константы `iconv`
Имя | Тип | Описание
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` (int) | int | Битовая маска, используемая в iconv_mime_decode()
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` (int) | int | Битовая маска, используемая в iconv_mime_decode()

# Функции iconv

# Смотрите также

Смотрите также Функции GNU Recode.

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — Преобразовывает строку из одной кодировки символов в другую

### Описание

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

Преобразовывает строку `string` из кодировки `from_encoding` в кодировку `to_encoding`.

### Список параметров

`from_encoding`

  Текущая кодировка, используемая для интерпретации параметра `string`.

`to_encoding`

  Требуемая на выходе кодировка.

  Если к параметру `to_encoding` добавлена строка `//TRANSLIT`, включается режим транслитерации. Это значит, что в случае, если символ не может быть представлен в требуемой кодировке, он может быть заменён одним или несколькими похожими символами. Если добавлена строка `//IGNORE`, то символы, которые не могут быть представлены в требуемой кодировке, будут удалены. В случае отсутствия вышеуказанных параметров будет сгенерирована ошибка уровня `E_NOTICE`, а функция вернёт `false`.

  Предостережение

  Как будет работать `//TRANSLIT` и будет ли вообще, зависит от системной реализации iconv() (`ICONV_IMPL`). Известны некоторые реализации, которые просто игнорируют `//TRANSLIT`, так что конвертация для символов некорректных для `to_encoding` скорее всего закончится ошибкой.

`string`

  Строка (string) для преобразования.

### Возвращаемые значения

Возвращает преобразованную строку или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования iconv()

    <?php
    $text = "Это символ евро - '€'.";

    echo 'Исходная строка        : ', $text, PHP_EOL;
    echo 'С добавлением TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'С добавлением IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Обычное преобразование : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

    ?>

Вывод приведённого примера будет похож на:

    Исходная строка        : Это символ евро - '€'.
    С добавлением TRANSLIT : Это символ евро - 'EUR'.
    С добавлением IGNORE   :Это символ евро - ''.
    Обычное преобразование :
    Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

### Примечания

> Замечание:

> Доступные кодировки и опции зависят от установленной реализации iconv. Если параметр `from_encoding` или `from_encoding` не поддерживается в текущей системе, будет возвращено значение `false`.

### Смотрите также

- mb_convert_encoding() - Преобразовывает строку из одной кодировки символов в другую
- UConverter::transcode() - Преобразовывает строку из одной кодировки символов в другую

# iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — Получает текущее значение настроек преобразования кодировок

### Описание

function iconv_get_encoding(string `$type` = "all"): array|string|false

Возвращает внутренние параметры конфигурации модуля iconv.

### Список параметров

`type`

  Возможные значения необязательного параметра `type`:

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### Возвращаемые значения

Возвращает текущее значение указанной переменной и `false` в случае возникновения ошибки.

Если `type` не указан или равен "all", iconv_get_encoding() вернёт массив со значениями всех переменных.

### Примеры

Пример #1 Пример использования iconv_get_encoding()

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

Результат выполнения приведённого примера:

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### Смотрите также

- iconv_set_encoding() - Устанавливает текущей настройки для преобразования символов кодировки
- ob_iconv_handler() - Преобразовывает символы из текущей кодировки в кодировку выходного буфера

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — Декодирует поле `MIME`-заголовка

### Описание

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

Декодирует поле `MIME`-заголовка.

### Список параметров

`string`

  Закодированный заголовок в виде строки.

`mode`

  `mode` задаёт режим поведения функции в случае, когда iconv_mime_decode() определит, что `MIME`-заголовок имеет недопустимую структуру. Режим задаётся комбинацией следующих битовых масок.

  Битовые маски, применяемые в iconv_mime_decode()
  Значение | Константа | Описание
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Если задано, заголовок декодируется в полном соответствии со стандартом » RFC2047. Эта опция отключена по умолчанию, так как существует множество почтовых программ, которые не следуют спецификации и формируют некорректные с точки зрения стандарта `MIME`-заголовки.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Если задано, iconv_mime_decode_headers() будет пытаться пропускать грамматические ошибки и продолжать обработку заголовка.

`encoding`

  Необязательный аргумент `encoding` задаёт набор символов, в котором будет представлен результат. Если аргумент опущен, будет использоваться iconv.internal_encoding.

### Возвращаемые значения

Возвращает декодированный `MIME`-заголовок в случае успешного выполнения или `false` в случае возникновения ошибки.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `encoding` теперь допускает значение null.

### Примеры

Пример #1 Пример использования iconv_mime_decode()

    <?php
    // Выдаст в результате "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### Смотрите также

- iconv_mime_decode_headers() - Декодирует несколько полей заголовка MIME
- mb_decode_mimeheader() - Декодирует строку в MIME-заголовке
- imap_mime_header_decode() - Декодирует элементы заголовка
- imap_base64() - Декодирует закодированный BASE64 текст
- imap_qprint() - Преобразовывает строку из формата quoted-printable в 8-битную строку

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — Декодирует несколько полей заголовка `MIME`

### Описание

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

Декодирует несколько полей заголовка `MIME` за один раз.

### Список параметров

`headers`

  Закодированные заголовки в виде строки.

`mode`

  Параметр `mode` определяет поведение, если iconv_mime_decode_headers() обнаружит неправильное поле заголовка `MIME`. Можно указать любую комбинацию следующих битовых масок.

  Битовые маски iconv_mime_decode_headers()
  Значение | Константа | Описание
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | Строго следовать стандартам, определённым в » RFC2047. Эта опция по умолчанию отключена, так как много проприетарных программ электронной почты не следуют стандартам и создают некорректные заголовки `MIME`.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | Если установлена, iconv_mime_decode_headers() будет пытаться игнорировать любые ошибки и продолжать обработку текущего заголовка.

`encoding`

  Необязательный параметр `encoding` указывает кодировку, в которой будет представлен результат. Если опущен, будет использовано значение директивы iconv.internal_encoding.

### Возвращаемые значения

В случае успешного выполнения возвращает ассоциативный массив с полями `MIME`-заголовков, указанных параметром `headers`, или `false` в случае возникновения ошибки.

Каждый ключ элемента возвращаемого массива представляет собой отдельное имя поля, а сам элемент - его значение. Если в заголовке существует несколько полей с одинаковым именем, iconv_mime_decode_headers() автоматически помещает их в подмассив с числовыми индексами в порядке их обработки. Обратите внимание, что имена заголовков не нечувствительны к регистру.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `encoding` теперь допускает значение null.

### Примеры

Пример #1 Пример использования iconv_mime_decode_headers()

    <?php
    $headers_string = <<<EOF
    Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
    To: example@example.com
    Date: Thu, 1 Jan 1970 00:00:00 +0000
    Message-Id: <example@example.com>
    Received: from localhost (localhost [127.0.0.1]) by localhost
        with SMTP id example for <example@example.com>;
        Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
        (envelope-from example-return-0000-example=example.com@example.com)
    Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

    EOF;

    $headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
    print_r($headers);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [Subject] => Prüfung Prüfung
        [To] => example@example.com
        [Date] => Thu, 1 Jan 1970 00:00:00 +0000
        [Message-Id] => <example@example.com>
        [Received] => Array
            (
                [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
                [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
            )

    )

### Смотрите также

- iconv_mime_decode() - Декодирует поле MIME-заголовка
- mb_decode_mimeheader() - Декодирует строку в MIME-заголовке
- imap_mime_header_decode() - Декодирует элементы заголовка
- imap_base64() - Декодирует закодированный BASE64 текст
- imap_qprint() - Преобразовывает строку из формата quoted-printable в 8-битную строку

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Создаёт поле `MIME`-заголовка

### Описание

function iconv_mime_encode(string `$field_name`, string `$field_value`, array `$options` = []): string|false

Создаёт и возвращает корректное поле `MIME`-заголовка в виде строки вида:

    Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

В примере выше "Subject" является именем поля, а часть строки, начиная с "=?ISO-8859-1?..." - его значение.

### Список параметров

`field_name`

  Имя поля.

`field_value`

  Значение поля.

`options`

  Есть возможность контролировать поведение функции iconv_mime_encode() посредством передачи массива с настройками в качестве третьего аргумента `options`. Возможные значения этого массива, поддерживаемые функцией iconv_mime_encode(), перечислены ниже. Обратите внимание, что имена элементов чувствительны к регистру символов.

  Настройки, поддерживаемые в iconv_mime_encode()
  Элемент | Тип | Описание | Значение по умолчанию | Пример
  --- | --- | --- | --- | ---
  scheme | string | Задаёт, каким образом закодировать значение поля. Значением этого элемента может быть либо "B", либо "Q". "B" означает схему кодирования `base64`, а "Q" - `quoted-printable`. | B | B
  input-charset | string | Задаёт, в какой кодировке представлены аргументы `field_name` и `field_value`. Если не задан, iconv_mime_encode() предполагает, что набор символов указан в ini-настройке iconv.internal_encoding. | iconv.internal_encoding | ISO-8859-1
  output-charset | string | Задаёт набор символов, в котором будет представлен результирующий `MIME`-заголовок. | iconv.internal_encoding | UTF-8
  line-length | int | Устанавливает максимальную длину строк заголовка. Если результирующий заголовок окажется длиннее этой величины, функция его разрежет на несколько строк в соответствии с » Форматом интернет сообщений - RFC2822. Если не задан, эта длина будет установлена 76 символов. | 76 | 996
  line-break-chars | string | Задаёт последовательность символов, которые будут использоваться для завершения "разрезанных" строк заголовка, если заголовок окажется длиннее одной строки. Если не задан, будут использоваться символы "\r\n" (`CR` `LF`). Обратите внимание, что этот аргумент всегда обрабатывается как строка ASCII вне зависимости от значения `input-charset`. | \r\n | \n

### Возвращаемые значения

Возвращает закодированное `MIME`-поле в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования iconv_mime_encode()

    <?php
    $preferences = array(
        "input-charset" => "ISO-8859-1",
        "output-charset" => "UTF-8",
        "line-length" => 76,
        "line-break-chars" => "\n"
    );
    $preferences["scheme"] = "Q";
    // Результат "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // Результат "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### Смотрите также

- imap_binary() - Конвертирует 8-битную строку в строку base64
- mb_encode_mimeheader() - Кодирует строку для заголовка MIME
- imap_8bit() - Конвертирует 8-битную строку в строку в формате quoted-printable
- quoted_printable_encode() - Преобразовывает 8-битную строку методом quoted-printable

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — Устанавливает текущей настройки для преобразования символов кодировки

### Описание

function iconv_set_encoding(string `$type`, string `$encoding`): bool

Изменяет значение указанной параметром `type` внутренней переменной конфигурации на `encoding`.

### Список параметров

`type`

  Значение `type` может быть одним из приведённых ниже:

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  Набор символов.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования iconv_set_encoding()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### Смотрите также

- iconv_get_encoding() - Получает текущее значение настроек преобразования кодировок
- ob_iconv_handler() - Преобразовывает символы из текущей кодировки в кодировку выходного буфера

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — Возвращает количество символов в строке

### Описание

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

В отличие от функции strlen(), функция iconv_strlen() учитывает кодировку строки. Длина строки `string` иногда не соответствует количеству байтов в ней, поскольку в кодировках символы кодируются переменным количеством байтов, например, в Юникоде символы кодируются и двумя, и четырьмя байтами.

### Список параметров

`string`

  Строка.

`encoding`

  Функция предполагает, что кодировка строки `string` эквивалентна значению директивы iconv.internal_encoding, если параметр `encoding` опустили.

### Возвращаемые значения

Функция возвращает количество символов в аргументе `string` в виде целого числа или `false`, если при кодировании возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- grapheme_strlen() - Получает количество графемных кластеров в строке
- mb_strlen() - Получает длину строки
- strlen() - Получает длину строки

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Возвращает позицию первого вхождения подстроки

### Описание

function iconv_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Возвращает позицию первого вхождения подстроки `needle` в строке `haystack`.

В отличие от strpos(), iconv_strpos() возвращает смещение перед искомой строкой в символах, а не в байтах. Количество символов трактуется в зависимости от указанной параметром `encoding` кодировки.

### Список параметров

`haystack`

  Строка, в которой производится поиск.

`needle`

  Искомая подстрока.

`offset`

  Необязательный параметр `offset` позволяет указать, с какого по счёту символа строки начинать поиск. Если указано отрицательное значение, то смещение будет отсчитываться с конца строки.

`encoding`

  Если параметр `encoding` не указан, то подразумевается, что `string` имеет кодировку iconv.internal_encoding.

Если `haystack` или `needle` не являются строками, они будут преобразованы в строку и применены как код символа.

### Возвращаемые значения

Возвращает номер позиции первого вхождения строки `needle` в `haystack`.

Если строка `needle` не найдена, iconv_strpos() возвращает `false`.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `encoding` теперь допускает значение null.
7.1.0 | Поддержка отрицательных значений `offset`.

### Смотрите также

- strpos() - Ищет позицию первого вхождения подстроки
- iconv_strrpos() - Возвращает позицию последнего вхождения подстроки
- mb_strpos() - Ищет в строке позицию первого вхождения подстроки

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Возвращает позицию последнего вхождения подстроки

### Описание

function iconv_strrpos(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int|false

Находит последнюю позицию подстроки `needle` в строке `haystack`.

В отличие от strrpos(), iconv_strrpos() возвращает смещение перед искомой строкой в символах, а не в байтах. Количество символов трактуется в зависимости от указанной параметром `encoding` кодировки.

### Список параметров

`haystack`

  Строка, в которой производится поиск.

`needle`

  Искомая подстрока.

`encoding`

  Если параметр `encoding` не указан, то подразумевается, что `string` имеет кодировку iconv.internal_encoding.

Если `haystack` или `needle` не являются строками, они будут преобразованы в строку и применены как код символа.

### Возвращаемые значения

Возвращает номер позиции последнего вхождения строки `needle` в `haystack`.

Если строка `needle` не найдена, iconv_strrpos() возвращает `false`.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `encoding` теперь допускает значение null.

### Смотрите также

- strrpos() - Возвращает позицию последнего вхождения подстроки в строку
- iconv_strpos() - Возвращает позицию первого вхождения подстроки
- mb_strrpos() - Ищет в строке позицию последнего вхождения подстроки

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — Получение части строки

### Описание

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

Получает часть строки `string`, определённую параметрами `offset` и `length`.

### Список параметров

`string`

  Изначальная строка.

`offset`

  Если `offset` неотрицателен, iconv_substr() получает часть строки `string` начиная с символа с порядковым номером `offset` (нумерация начинается с нуля).

  Если `offset` отрицателен, iconv_substr() получает часть строки начиная с позиции, отстоящую от конца строки `string` на `offset` символов.

`length`

  Если `length` задан и положителен, возвращаемое значение содержит не более `length` символов, начиная с `offset` (зависит от длины строки `string`).

  Если указан отрицательный `length`, iconv_substr() получает часть строки `string`, начиная с `offset` символа и до символа, отстоящего от конца строки на `length` символов. В случае, если `offset` также отрицателен, стартовая позиция вычисляется заранее в соответствии с вышеописанным правилом.

`encoding`

  Если параметр `encoding` не указан, предполагается, что строка `string` имеет кодировку iconv.internal_encoding.

  Обратите внимание, что и `offset`, и `length` основываются на размере символа, рассчитанного исходя из кодировки текста (`encoding`), в то время как схожая функция substr() всегда рассматривает их побайтовое смещение.

### Возвращаемые значения

Возвращает часть строки `string`, определённую параметрами `offset` и `length`.

Если строка `string` имеет меньшую длину, чем параметр `offset`, будет возвращено `false`. Если `string` имеет длину равную `offset`, будет возвращена пустая строка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `length` и `encoding` теперь допускают значение null.
7.0.11 | Если `string` имеет длину равную `offset`, будет возвращена пустая строка. Ранее в подобных случаях возвращалось `false`.

### Смотрите также

- substr() - Возвращает подстроку
- mb_substr() - Возвращает часть строки
- mb_strcut() - Получает часть строки

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — Преобразовывает символы из текущей кодировки в кодировку выходного буфера

### Описание

function ob_iconv_handler(string `$contents`, int `$status`): string

Преобразовывает закодированную в `internal_encoding` строку, в строку, закодированную в `output_encoding`.

Значения `internal_encoding` и `output_encoding` должны быть определены в файле php.ini или функцией iconv_set_encoding().

### Список параметров

Информацию об аргументах этого обработчика можно посмотреть в описании к функции ob_start().

### Возвращаемые значения

Информацию о возвращаемых значениях этого обработчика можно посмотреть в описании к функции ob_start().

### Примеры

Пример #1 Пример использования ob_iconv_handler()

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // запуск буферизации вывода
    ?>

### Смотрите также

- iconv_get_encoding() - Получает текущее значение настроек преобразования кодировок
- iconv_set_encoding() - Устанавливает текущей настройки для преобразования символов кодировки
- Функции контроля вывода

## Содержание

- iconv — Преобразовывает строку из одной кодировки символов в другую
- iconv_get_encoding — Получает текущее значение настроек преобразования кодировок
- iconv_mime_decode — Декодирует поле MIME-заголовка
- iconv_mime_decode_headers — Декодирует несколько полей заголовка MIME
- iconv_mime_encode — Создаёт поле MIME-заголовка
- iconv_set_encoding — Устанавливает текущей настройки для преобразования символов кодировки
- iconv_strlen — Возвращает количество символов в строке
- iconv_strpos — Возвращает позицию первого вхождения подстроки
- iconv_strrpos — Возвращает позицию последнего вхождения подстроки
- iconv_substr — Получение части строки
- ob_iconv_handler — Преобразовывает символы из текущей кодировки в кодировку выходного буфера

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Функции iconv
  - iconv — Преобразовывает строку из одной кодировки символов в другую
  - iconv_get_encoding — Получает текущее значение настроек преобразования кодировок
  - iconv_mime_decode — Декодирует поле MIME-заголовка
  - iconv_mime_decode_headers — Декодирует несколько полей заголовка MIME
  - iconv_mime_encode — Создаёт поле MIME-заголовка
  - iconv_set_encoding — Устанавливает текущей настройки для преобразования символов кодировки
  - iconv_strlen — Возвращает количество символов в строке
  - iconv_strpos — Возвращает позицию первого вхождения подстроки
  - iconv_strrpos — Возвращает позицию последнего вхождения подстроки
  - iconv_substr — Получение части строки
  - ob_iconv_handler — Преобразовывает символы из текущей кодировки в кодировку выходного буфера

# Функции интернационализации

# Введение

Модуль интернационализации (далее Intl) - это обёртка для библиотеки » ICU, позволяющая программистам на PHP производить различные операции, которые зависят от локали, например, форматирование, транслитерация, преобразование кодировок, операции с календарём, совместимое с » UCA сравнение, определение границ текста и работать с идентификаторами локалей, часовыми поясами и графемами.

Программный интерфейс модуля разрабатывается так, чтобы как можно точнее повторять API ICU, чтобы люди, работавшие с ICE в C/C++ или Java, могли легко использовать API PHP. Также благодаря этому документация ICE может быть полезной чтобы понять различие функции ICU.

Intl состоит из нескольких модулей, каждый из которых предоставляет соответствующий API ICU:

- Модуль сравнения: предоставляет инструменты для сравнения строк с поддержкой соответствующего локали порядка сортировки.
- Модуль форматирования чисел: позволяет отображать числа в соответствии с правилами локали, или заданным шаблоном или с набором правил. Также позволяет правильно разбирать строки в числа.
- Модуль форматирования сообщений: позволяет создавать сообщения, включающие данные (такие как числа и даты), отформатированные в соответствии с заданными шаблоном и локальными правилами, и, также, разбирать сообщения, извлекая из них данные.
- Модуль нормализации: предоставляет функции для преобразования текста в одну из нормализованных форм Unicode. Также предоставляет возможность проверить, является ли предоставленный текст уже нормализованным.
- Модуль локали: предоставляет взаимодействие с идентификаторами локали как к функциями, позволяя получить вложенные теги локали; разбор, композиция, сравнение (поиск и фильтрация) идентификаторов локали.
- Модуль календаря: предоставляет класс, полезный для проведения зависимых от локали операций с календарём, получения различной информации, такой как часовые пояса для выбранной локали, первый день недели или режим текущего зимнего/летнего времени.
- Модуль часового пояса: предоставляет обёртку над » базой данных часовых поясов, в которой содержится исчерпывающая информация о всех мировых часовых поясах.
- Модуль форматирования даты: позволяет отображать дату в соответствии с принятым для данной локали форматом либо заданным шаблоном или набором правил. Также нужен для разбора строк, содержащих описание даты и времени.
- Модуль транслитерации: позволяет получить представление строки на различных языках в латинице.

## Ссылки

- » Различная документация ICU

- » Руководство пользователя ICU

- » Алгоритм сопоставления Unicode

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Для установки данного модуля необходимо предварительно установить библиотеку » ICU версии 4.0.0 или выше. Начиная с PHP 7.4.0 требуется ICU 50.1 или новее.

## Установка

Используйте --enable-intl, чтобы включить модуль при компиляции PHP.

Если ICU установлен в нестандартную директорию, то её необходимо указать в переменной окружения `LD_LIBRARY_PATH`, чтобы динамический линковщик смог его найти:

$ export LD_LIBRARY_PATH=/opt/icu/lib

В противном случае, если ICU установлен в стандартную директорию, то никаких дополнительных параметров для configure не требуется.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки Intl
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Доступно с PECL 3.0.0a1

Краткое разъяснение конфигурационных директив.

`intl.default_locale` string

  Локаль по умолчанию для использования в функциях в случаях если соответствующие параметры будут опущены, либо заданы как `NULL`. Это локаль ICU, а не системная. Встроенные локали ICU и их данные можно посмотреть по ссылке » https://unicode-org.github.io/icu/userguide/locale/.

  По умолчанию значение пусто, что ведёт к принудительному использованию локали ICU по умолчанию. Единожды задав это значение его уже нельзя будет сбросить на начальное. Не рекомендуется использовать локаль ICU по умолчанию, поскольку она зависит от локали окружения сервера.

`intl.error_level` int

  Тип сообщений об ошибках, генерируемых при их возникновении в функциях ICU. Задаётся как уровень ошибок PHP, таких как `E_WARNING`. Можно установить равным `0`, если вообще не хотите видеть сообщения об ошибках. Данная настройка не влияет на возвращаемые значения функций в случае ошибок и результат выполнения intl_get_error_code() и специфичных для классов методов, возвращающих информацию об ошибках.

  По умолчанию равно `0`.

`intl.use_exceptions` int

  Если установлено как `true`, то вместо ошибок будут выбрасываться исключения класса IntlException. Можно использовать в дополнение к intl.error_level.

  по умолчанию равно `false`.

# Предопределённые константы

`INTL_ICU_DATA_VERSION` (string)
  Версия данных в библиотеке ICU4C.
`INTL_ICU_VERSION` (string)
  Текущая версия библиотеки ICU в виде чисел с точечными разделителями.
`INTL_MAX_LOCALE_LEN` (int)
  Задаёт длину имени локали. Для PHP установлено равным 80. Имена локалей больше этого значения не принимаются.
`IDNA_DEFAULT` (int)
  Запретить передачу неопределённых кодов символов в функции IDN и не проверять ввод на соответствие правилам доменных имён ASCII.
`IDNA_ALLOW_UNASSIGNED` (int)
  Разрешить передачу неопределённых кодов символов в функции IDN
`IDNA_USE_STD3_RULES` (int)
  Проверять ввод для функций IDN на соответствие правилам доменных имён ASCII.
`IDNA_CHECK_BIDI` (int)
  Проверять, соответствует ли ввод правилам BiDi. Игнорируется в реализации IDNA2003, которая всегда производит эту проверку.
`IDNA_CHECK_CONTEXTJ` (int)
  Проверять, соответствует ли ввод правилам CONTEXTJ. Игнорируется в реализации IDNA2003, так как эта проверка введена в IDNA2008.
`IDNA_NONTRANSITIONAL_TO_ASCII` (int)
  Опция для несквозной обработки в idn_to_ascii(). Сквозная обработка активирована по умолчанию. Игнорируется в реализации IDNA2003.
`IDNA_NONTRANSITIONAL_TO_UNICODE` (int)
  Опция для несквозной обработки в idn_to_utf8(). Сквозная обработка активирована по умолчанию. Игнорируется в реализации IDNA2003.
`INTL_IDNA_VARIANT_2003` (int)
  Использовать алгоритм IDNA 2003 в idn_to_utf8() и idn_to_ascii(). Задано по умолчанию. Эта константа и то, что она используется по умолчанию, объявлено устаревшим в PHP 7.2.0.
`INTL_IDNA_VARIANT_UTS46` (int)
  Использовать алгоритм UTS #46 в функциях idn_to_utf8() и idn_to_ascii(). Доступно с ICU 4.6.
`GRAPHEME_EXTR_COUNT` (int)
  Количество кластеров графем по умолчанию для извлечения.
`GRAPHEME_EXTR_MAXBYTES` (int)
  Максимальное количество возвращаемых байтов.
`GRAPHEME_EXTR_MAXCHARS` (int)
  Максимальное количество возвращаемых UTF-8-символов.

Следующие ошибки — часть битовой маски, которую возвращает алгоритм UTS #46 в функциях idn_to_utf8() и idn_to_ascii().

`IDNA_ERROR_EMPTY_LABEL` (int)
`IDNA_ERROR_LABEL_TOO_LONG` (int)
`IDNA_ERROR_DOMAIN_NAME_TOO_LONG` (int)
`IDNA_ERROR_LEADING_HYPHEN` (int)
`IDNA_ERROR_TRAILING_HYPHEN` (int)
`IDNA_ERROR_HYPHEN_3_4` (int)
`IDNA_ERROR_LEADING_COMBINING_MARK` (int)
`IDNA_ERROR_DISALLOWED` (int)
`IDNA_ERROR_PUNYCODE` (int)
`IDNA_ERROR_LABEL_HAS_DOT` (int)
`IDNA_ERROR_INVALID_ACE_LABEL` (int)
`IDNA_ERROR_BIDI` (int)
`IDNA_ERROR_CONTEXTJ` (int)
`ULOC_ACTUAL_LOCALE` (int)
  Локаль, из которой фактически поступают данные.
`ULOC_VALID_LOCALE` (int)
  Наиболее конкретная локаль, которую поддерживает библиотека ICU.
`U_AMBIGUOUS_ALIAS_WARNING` (int)
  Этот псевдоним конвертера могут использовать другие реализации конвертера.
`U_BAD_VARIABLE_DEFINITION` (int)
  Отсутствует символ `$` или повторяется имя переменной.
`U_BRK_ASSIGN_ERROR` (int)
  Синтаксическая ошибка в инструкции назначения правил RBBI-итератора прерывания.
`U_BRK_ERROR_LIMIT` (int)
  Это всегда должно быть последнее значение, которое указывает предел сбоев итератора прерывания.
`U_BRK_ERROR_START` (int)
  Начало кодов, которые указывают на сбои итератора прерывания.
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  Шестнадцатеричные цифры, которые ожидаются как часть экранированного символа в правиле.
`U_BRK_INIT_ERROR` (int)
  Ошибка инициализации. Вероятно, отсутствуют ICU-данные.
`U_BRK_INTERNAL_ERROR` (int)
  Модуль обнаружил внутреннюю ошибку (баг).
`U_BRK_MALFORMED_RULE_TAG` (int)
  У тега `{nnn}` в правиле неправильная форма.
`U_BRK_MISMATCHED_PAREN` (int)
  Неправильные круглые скобки в RBBI-правиле.
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  В RBBI-правиле отсутствует закрывающая кавычка.
`U_BRK_RULE_EMPTY_SET` (int)
  Правило содержит пустой набор Юникода.
`U_BRK_RULE_SYNTAX` (int)
  Синтаксическая ошибка в RBBI-правиле.
`U_BRK_SEMICOLON_EXPECTED` (int)
  Отсутствует символ `;` в конце RBBI-правила.
`U_BRK_UNCLOSED_SET` (int)
  UnicodeSet записывает RBBI-правило без закрывающего символа `]`.
`U_BRK_UNDEFINED_VARIABLE` (int)
  Использование неопределенного значения переменной `$Variable` в RBBI-правиле.
`U_BRK_UNRECOGNIZED_OPTION` (int)
  Модуль не распознал опцию в RBBI-правилах.
`U_BRK_VARIABLE_REDFINITION` (int)
  Переопределена переменная RBBI-правила.
`U_BUFFER_OVERFLOW_ERROR` (int)
  Результат не поместился в предоставленный буфер.
`U_CE_NOT_FOUND_ERROR` (int)
  Пока константа используется только при настройке ICU-параметра по умолчанию [variable top], но может использоваться в целом.
`U_COLLATOR_VERSION_MISMATCH` (int)
  Версия класса Collator несовместима с базовой версией.
`U_DIFFERENT_UCA_VERSION` (int)
  Функция ucol_open обнаружила несоответствие между версией алгоритма сопоставления Юникода (UCA) и версией изображения колатора, поэтому колатор был построен на основе правил. Константа не влияет на дальнейшее функционирование.
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  Экземпляр объекта перечисления `UEnumeration` не синхронизирован с базовой коллекцией.
`U_ERROR_LIMIT` (int)
  Псевдоним константы `U_PLUGIN_ERROR_LIMIT`.
`U_ERROR_WARNING_LIMIT` (int)
  Это всегда должно быть последнее значение предупреждения, которое указывает ограничение для предупреждений экземпляра UErrorCode (код последнего предупреждения + 1).
`U_ERROR_WARNING_START` (int)
  Начало информационных результатов (семантически успешное).
`U_FILE_ACCESS_ERROR` (int)
  Запрошенный файл не найден.
`U_FMT_PARSE_ERROR_LIMIT` (int)
  Ограничение ошибок библиотеки форматов.
`U_FMT_PARSE_ERROR_START` (int)
  Запуск ошибок библиотеки форматов.
`U_IDNA_ACE_PREFIX_ERROR` (int)
`U_IDNA_CHECK_BIDI_ERROR` (int)
`U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR` (int)
`U_IDNA_ERROR_LIMIT` (int)
`U_IDNA_ERROR_START` (int)
`U_IDNA_LABEL_TOO_LONG_ERROR` (int)
`U_IDNA_PROHIBITED_ERROR` (int)
`U_IDNA_STD3_ASCII_RULES_ERROR` (int)
`U_IDNA_UNASSIGNED_ERROR` (int)
`U_IDNA_VERIFICATION_ERROR` (int)
`U_IDNA_ZERO_LENGTH_LABEL_ERROR` (int)
`U_ILLEGAL_ARGUMENT_ERROR` (int)
  Указывает неверное значение аргумента.
`U_ILLEGAL_CHAR_FOUND` (int)
  Преобразование символов: недопустимая последовательность ввода.
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  Не используется с ICU 2.4.
`U_ILLEGAL_CHARACTER` (int)
  Служебный символ находится вне разрешенного контекста.
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  Недопустимая экранирующая последовательность ISO-2022.
`U_ILLEGAL_PAD_POSITION` (int)
  Дополнительный символ неправильно расположен в цифровом шаблоне.
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  Попытка получить доступ к индексу, который находится за пределами допустимого.
`U_INTERNAL_PROGRAM_ERROR` (int)
  Указывает на ошибку в коде библиотеки.
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  Внутренняя системная ошибка транслитератора.
`U_INVALID_CHAR_FOUND` (int)
  При преобразовании символов: несопоставимая входная последовательность. В других API: недопустимый символ.
`U_INVALID_FORMAT_ERROR` (int)
  Формат данных не соответствует ожидаемому.
`U_INVALID_FUNCTION` (int)
  Правило `&fn()` указывает неизвестный транслитератор.
`U_INVALID_ID` (int)
  Правило `::id` указывает неизвестный транслитератор.
`U_INVALID_PROPERTY_PATTERN` (int)
  Не используется с ICU 2.4.
`U_INVALID_RBT_SYNTAX` (int)
  Правило `::id` передали в анализатор RuleBasedTransliterator.
`U_INVALID_STATE_ERROR` (int)
  Запрошенная операция не может быть завершена в ICU в её текущем состоянии.
`U_INVALID_TABLE_FILE` (int)
  Файл таблицы преобразования не найден.
`U_INVALID_TABLE_FORMAT` (int)
  Файл таблицы преобразования найден, но поврежден.
`U_INVARIANT_CONVERSION_ERROR` (int)
  Невозможно преобразовать строку `UChar*` в `char*` с инвариантным преобразователем.
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  Символ группировки в шаблоне экспоненты.
`U_MALFORMED_PRAGMA` (int)
  Прагма `'use'` недопустима.
`U_MALFORMED_RULE` (int)
  Элементы правила расположены не на своем месте.
`U_MALFORMED_SET` (int)
  Недопустимый шаблон `UnicodeSet`.
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  Не используется с ICU 2.4.
`U_MALFORMED_UNICODE_ESCAPE` (int)
  Недопустимый шаблон экранирования Юникода.
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  Недопустимое определение переменной.
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  Ссылка на переменную недействительна.
`U_MEMORY_ALLOCATION_ERROR` (int)
  Ошибка выделения памяти.
`U_MESSAGE_PARSE_ERROR` (int)
  Невозможно проанализировать сообщение (формат сообщения).
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  Не используется с ICU 2.4.
`U_MISPLACED_ANCHOR_START` (int)
  Стартовый якорь появляется в недопустимой позиции.
`U_MISPLACED_COMPOUND_FILTER` (int)
  Составной фильтр находится в неправильном месте.
`U_MISPLACED_CURSOR_OFFSET` (int)
  Смещение курсора происходит в недопустимой позиции.
`U_MISPLACED_QUANTIFIER` (int)
  Квантификатор появляется после разделителя закрытия сегмента.
`U_MISSING_OPERATOR` (int)
  Правило не содержит оператора.
`U_MISSING_RESOURCE_ERROR` (int)
  Запрошенный ресурс не найден.
`U_MISSING_SEGMENT_CLOSE` (int)
  Не используется с ICU 2.4.
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  Больше одного предварительного контекста.
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  Больше одного составного фильтра.
`U_MULTIPLE_CURSORS` (int)
  Больше одного курсора.
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  В числовом шаблоне больше одного десятичного разделителя.
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  Псевдоним константы `U_MULTIPLE_DECIMAL_SEPARATORS`.
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  Больше одного символа экспоненты в числовом шаблоне.
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  Больше одного символа панели в цифровом шаблоне.
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  Больше одного символа процента в числовом шаблоне.
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  Больше одного символа промилле в числовом шаблоне.
`U_MULTIPLE_POST_CONTEXTS` (int)
  Больше одного контекста публикации.
`U_NO_SPACE_AVAILABLE` (int)
  Нет места для расширения в буфере для арабского оформления.
`U_NO_WRITE_PERMISSION` (int)
  Попытка изменить данные, которые доступны только для чтения, или постоянные данные.
`U_PARSE_ERROR` (int)
  Эквивалент исключения `ParseException` в языке Java.
`U_PARSE_ERROR_LIMIT` (int)
  Предел ошибок экземпляра Transliterator.
`U_PARSE_ERROR_START` (int)
  Начало ошибок экземпляра Transliterator.
`U_PATTERN_SYNTAX_ERROR` (int)
  Синтаксическая ошибка в шаблоне формата.
`U_PRIMARY_TOO_LONG_ERROR` (int)
  Пользователь попытался установить ICU-параметр по умолчанию [variable top] как первичный, длина которого превышает два байта.
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  Нераспознанная экранирующая последовательность обратной слеша в шаблоне.
`U_REGEX_BAD_INTERVAL` (int)
  Ошибка в интервале `{min,max}`.
`U_REGEX_ERROR_LIMIT` (int)
  Это всегда должно быть последнее значение, которое указывает предел ошибок регулярного выражения.
`U_REGEX_ERROR_START` (int)
  Начало кодов, которые указывают на ошибки регулярного выражения.
`U_REGEX_INTERNAL_ERROR` (int)
  Обнаружена внутренняя ошибка (баг).
`U_REGEX_INVALID_BACK_REF` (int)
  Обратная ссылка на несуществующую группу захвата.
`U_REGEX_INVALID_FLAG` (int)
  Недопустимое значение для флагов режима сопоставления.
`U_REGEX_INVALID_STATE` (int)
  Экземпляр `RegexMatcher` находится в недопустимом состоянии для запрошенной операции.
`U_REGEX_LOOK_BEHIND_LIMIT` (int)
  Соответствия ретроспективного шаблона должны иметь ограниченную максимальную длину.
`U_REGEX_MAX_LT_MIN` (int)
  В интервале `{min,max}`, значение max меньше значения min.
`U_REGEX_MISMATCHED_PAREN` (int)
  Неправильно вложенные круглые скобки в шаблоне регулярного выражения.
`U_REGEX_NUMBER_TOO_BIG` (int)
  Десятичное число слишком большое.
`U_REGEX_PROPERTY_SYNTAX` (int)
  Неверное свойство Юникода.
`U_REGEX_RULE_SYNTAX` (int)
  Синтаксическая ошибка в шаблоне регулярного выражения.
`U_REGEX_SET_CONTAINS_STRING` (int)
  Регулярные выражения не могут содержать `UnicodeSet`, которые содержат строки.
`U_REGEX_UNIMPLEMENTED` (int)
  Использование возможностей регулярного выражения, которые ещё не реализовали.
`U_RESOURCE_TYPE_MISMATCH` (int)
  Запрашивается операция над ресурсом, который её не поддерживает.
`U_RULE_MASK_ERROR` (int)
  Правило скрыто более ранним более общим правилом.
`U_SAFECLONE_ALLOCATED_WARNING` (int)
  Операция `SafeClone` требовала выделения памяти (только в информационных целях).
`U_SORT_KEY_TOO_SHORT_WARNING` (int)
  Количество уровней, запрошенных в `getBound`, больше, чем количество уровней в ключе сортировки.
`U_STANDARD_ERROR_LIMIT` (int)
  Это всегда должно быть последнее значение, которое обозначает предел стандартных ошибок.
`U_STATE_OLD_WARNING` (int)
  ICU должен использовать уровень совместимости, чтобы создать службу. Ожидайте снижения производительности или памяти.
`U_STATE_TOO_OLD_ERROR` (int)
  ICU не может создать службу из этого состояния, поскольку она больше не поддерживается.
`U_STRING_NOT_TERMINATED_WARNING` (int)
  Выходная строка не может завершиться NUL-байтом, поскольку выходные данные `length==destCapacity`.
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  Псевдоним константы `U_IDNA_CHECK_BIDI_ERROR`.
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  Псевдоним константы `U_IDNA_PROHIBITED_ERROR`.
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  Псевдоним константы `U_IDNA_UNASSIGNED_ERROR`.
`U_TOO_MANY_ALIASES_ERROR` (int)
  В пути к запрошенному ресурсу слишком много псевдонимов. Вполне возможно, что произошло циклическое определение псевдонима.
`U_TRAILING_BACKSLASH` (int)
  Висячий обратный слеш.
`U_TRUNCATED_CHAR_FOUND` (int)
  При преобразовании символов: неполная последовательность ввода.
`U_UNCLOSED_SEGMENT` (int)
  Закрывающий символ `)` отсутствует.
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  Ссылка на сегмент не соответствует определённому сегменту.
`U_UNDEFINED_VARIABLE` (int)
  Ссылка на переменную не соответствует определённой переменной.
`U_UNEXPECTED_TOKEN` (int)
  Синтаксическая ошибка в шаблоне формата.
`U_UNMATCHED_BRACES` (int)
  Фигурные скобки не соответствуют шаблону сообщения.
`U_UNQUOTED_SPECIAL` (int)
  Служебный символ не заключили в кавычки или не заэкранировали.
`U_UNSUPPORTED_ATTRIBUTE` (int)
  Не используется с ICU 2.4.
`U_UNSUPPORTED_ERROR` (int)
  Запрошенная операция не поддерживается в текущем контексте.
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  Неподдерживаемая экранирующая последовательность ISO-2022.
`U_UNSUPPORTED_PROPERTY` (int)
  Не используется с ICU 2.4.
`U_UNTERMINATED_QUOTE` (int)
  Заключительная одинарная кавычка отсутствует.
`U_USELESS_COLLATOR_ERROR` (int)
  У колатора — это только параметры, базу не указали.
`U_USING_DEFAULT_WARNING` (int)
  Поиск пакета ресурсов вернул результат из корневой локали (не ошибку).
`U_USING_FALLBACK_WARNING` (int)
  Поиск пакета ресурсов вернул резервный результат (не ошибку).
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  Для этого диапазона переменных создали слишком много дублёров.
`U_VARIABLE_RANGE_OVERLAP` (int)
  Диапазон переменных перекрывает символы, которые используются в правилах.
`U_ZERO_ERROR` (int)
  Ни ошибки, ни предупреждения.

# Примеры

## Содержание

- Основы использования модуля

## Основы использования модуля

Каждый модуль предоставляет два типа API: процедурный и объектно-ориентированный. Они идентичны и описываются в соответствующих разделах руководства.

> Замечание:

> Все входные данные должны быть в кодировке UTF-8. Все выходные данные также.

Пример #1 Пример использования процедурного API

    <?php
    $coll  = collator_create('en_US');
    $result = collator_compare($coll, "string#1", "string#2");
    ?>

Пример #2 Пример использования объектно-ориентированного API

    <?php
    $coll = new Collator('en_US');
    $al   = $coll->getLocale(Locale::ACTUAL_LOCALE);
    echo "Текущая локаль: $al\n";

    $formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    echo $formatter->format(1234567);
    ?>

# Класс Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

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

## Обзор класса

class Collator {
/* Константы */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Методы */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Предопределённые константы

`Collator::FRENCH_COLLATION` int

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

  - `Collator::ON`
  - `Collator::OFF`(по умолчанию)
  - `Collator::DEFAULT_VALUE`

  Пример #1 Правила FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  Атрибут "Alternate" используется для контроля обработки так называемых "переменных символов" в UCA: пробелы, знаки пунктуации и символы. Если "Alternate" установлен как NonIgnorable (N), то различия в этих символах будут считаться такими же значимыми, как и различия между буквами. Если "Alternate" установлен как Shifted (S), то эти символы будут иметь низкую значимость. Значение Shifted зачастую используется в комбинации с Strength, установленным в "Quaternary". В таких случаях подобные символы будут учитываться при сортировке, но только если все остальные аспекты строк (буквы, акценты, регистр) идентичны. Если "Alternate" не установлен как "Shifted", то разницы между уровнями "Strength" 3 и 4 не будет. Более подробно и с примерами читайте в разделе "Variable_Weighting" на сайте » UCA. Причина, по которой значения для "Alternate" — это не просто On и Off, заключается в том, что в будущем могут быть добавлены дополнительные варианты. Опция UCA "Blanked" выражается с помощью "Strength", установленного в 3, и "Alternate", установленного в "Shifted". Для большинства локалей этот параметр по умолчанию равен "NonIgnorable". Если задано "Shifted", то обработка может быть медленнее в случае, если у вас много строк, отличающихся только пунктуацией. Длина ключа сортировки не затрагивается, только если также не увеличивался уровень "Strength".

  Возможные значения:

  - `Collator::NON_IGNORABLE`(по умолчанию)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Пример #2 ALTERNATE_HANDLING rules

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  Атрибут "Case_First" используется для определения порядка сортировки в зависимости от регистра символов при отсутствии других различий в строках. Возможные значения: Uppercase_First(U), Lowercase_First (L), Default и Off. Между "Off" и "Lowercase_First" практически нет разницы, так что пользователи обычно не используют "Lowercase_First", а только Off или Uppercase_First. (Те, кому действительно интересна разница между X и L могут обратиться к `Настройке Collation`). Задание L или U не сказывается на скорости сравнения, но влияет на длину ключа сортировки.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Пример #3 Правила CASE_FIRST

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  Атрибут "Case_Level" используется, когда акценты не важны, а регистр важен. В таких случаях установите "Strength" в значение Primary, и "Case_Level" в On. В большинстве локалей по умолчанию задано значение "Off". Оказывает незначительное влияние на скорость сравнения и длину ключа сортировки, если установлено как On.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Пример #4 CASE_LEVEL rules

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  Настройка "Normalization" определяет, будет ли текст тщательно нормализован в сравнении или нет. Даже если данная настройка отключена (по умолчанию для многих локалей), текст в общем случае будет сравниваться корректно (подробности в UTN #5). Проблемы могут быть только с отметками акцентов, расположенными в неканоничном порядке. Если установлено как On, то будет гарантирован наилучший результат для всех возможных вариантов текста. Однако, если установлено значение On, это скажется на скорости сравнения в зависимости от количества последовательностей, которые необходимо нормализовать. Какого-либо заметного влияния на длину ключа сортировки оказано не будет. Если заранее известно, что текст уже нормализован как NFD или NFKD, необходимости в использовании этой настройки нет.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  ICU Collation Service поддерживает множество уровней сравнения (они называются "Levels", но также известны как "Strengths"). Использование этих настроек позволяет ICU сортировать строки точно в соответствии с правилами локали. Однако, разрешая выборочное использование этих уровней, поиск строки в тексте можно производить с использованием различных условий. Больше информации описано в главе, посвящённой collator_set_strength().

  Возможные значения:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(по умолчанию)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  Совместимость с JIS x 4061 требует введения дополнительного уровня для выделения символов Hiragana и Katakana. Если требуется совместимость со стандартом, то этот атрибут потребуется задать как On, а "Strength" как "Quaternary". Это скажется на длине ключа сортировки и скорости сравнения.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Если включён, этот атрибут генерирует ключ сравнения для числового значения подстроки, состоящей из цифр. Это позволяет при сортировке помещать '100' после '2'.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — Сортирует массив с сохранением ассоциации индекса

### Описание

Объектно-ориентированный стиль

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Процедурный стиль

function collator_asort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

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

Эквивалентно стандартной функции PHP asort().

### Список параметров

`object`

  Объект Collator.

`array`

  Массив строк для сортировки.

`flags`

  Необязательный тип сортировки, один из следующих:

  - `Collator::SORT_REGULAR` - сравнивает элементы как обычно (не изменяя тип)

  - `Collator::SORT_NUMERIC` - сравнивает элементы, как числа

  - `Collator::SORT_STRING` - сравнивает элементы, как строки

  Значение `flags` по умолчанию - `Collator::SORT_REGULAR`. Также используется, если указано недопустимое значение `flags`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_asort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr = array(
         'a' => '100',
         'b' => '50',
         'c' => '7'
    );
    collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
    var_export( $arr );

    collator_asort( $coll, $arr, Collator::SORT_STRING );
    var_export( $arr );
    ?>

Результат выполнения приведённого примера:

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### Смотрите также

- Константы Collator
- collator_sort() - Сортирует массив с использованием указанного средства сортировки
- collator_sort_with_sort_keys() - Сортирует массив с использованием указанного Collator и ключей сортировки

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — Сравнивает две строки Unicode

### Описание

Объектно-ориентированный стиль

public function Collator::compare(string `$string1`, string `$string2`): int|false

Процедурный стиль

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Сравнивает две строки Unicode в соответствии с правилами сопоставления.

### Список параметров

`object`

  Объект Collator.

`string1`

  Первая строка для сравнения.

`string2`

  Вторая строка для сравнения.

### Возвращаемые значения

Возвращает результат сравнения:

- 1, если `string1` больше `string2`;

- 0, если `string1` равна `string2`;

- -1, если `string1` меньше `string2`.

В случае возникновения ошибки возвращает `false`.
Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Примеры

Пример #1 Пример использования collator_compare()

    <?php
    $s1 = 'Hello';
    $s2 = 'hello';

    $coll = collator_create( 'en_US' );
    $res  = collator_compare( $coll, $s1, $s2 );

    if ($res === false) {
        echo collator_get_error_message( $coll );
    } else if( $res > 0 ) {
        echo "s1 больше s2\n";
    } else if( $res < 0 ) {
        echo "s1 меньше s2\n";
    } else {
        echo "s1 и s2 равны\n";
    }
    ?>

Результат выполнения приведённого примера:

s1 больше s2

Пример #2 Сравнение строк без диакритических знаков и без учёта регистра

    <?php
    $c = new Collator( 'en' );
    $c->setStrength( Collator::PRIMARY );

    if ( $c->compare( 'Séan', 'Sean' ) == 0 )
    {
        echo "Значения равны\n";
    }

Результат выполнения приведённого примера:

Значения равны

В этом примере Collator сравнивает, принимая во внимание только базовые символы. Документация для Collator->setStrength() объясняет различные сильные стороны.

### Смотрите также

- collator_sort() - Сортирует массив с использованием указанного средства сортировки

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — Создаёт новый экземпляр Collator

### Описание

public function Collator::__construct(string `$locale`)

Создаёт новый экземпляр Collator.

### Список параметров

`locale`

  Локаль, правила сопоставления которой следует использовать. Могут быть переданы специальные значения для языковых стандартов - если для языкового стандарта передана пустая строка (string), будут использоваться правила сопоставления языкового стандарта по умолчанию. Если передано значение `"root"`, будут использоваться правила » UCA.

  Атрибут `locale` обычно является наиболее важным атрибутом для правильной сортировки и сопоставления в соответствии с ожиданиями пользователей в разных странах и регионах. По умолчанию порядок сортировки » UCA будет правильно отсортировать только несколько языков, таких как голландский и португальский ("правильно" означает в соответствии с обычными ожиданиями пользователей этих языков). В противном случае вам необходимо указать локаль в UCA, чтобы правильно сопоставить текст для данного языка. Таким образом, необходимо указать языковой стандарт, чтобы выбрать Collator, который правильно адаптирован для этого языкового стандарта. Выбор языкового стандарта автоматически устанавливает значения для всех атрибутов на то, что подходит для этого языкового стандарта. Таким образом, в большинстве случаев другие атрибуты не нужно явно указывать. В некоторых случаях выбор локали будет иметь значение для производительности сравнения строк и/или длины ключа сортировки.

### Ошибки

Возвращает "пустой" объект в случае возникновения ошибки. Используйте intl_get_error_code() и/или intl_get_error_message(), чтобы узнать что произошло.

### Примеры

Пример #1 Пример использования Collator::__construct()

    <?php
    $coll = new Collator('en_CA');
    ?>

### Смотрите также

- Collator::create() - Создаёт новый экземпляр Collator
- collator_create() - Создаёт новый экземпляр Collator

# Collator::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — Создаёт новый экземпляр Collator

### Описание

Объектно-ориентированный стиль

public static function Collator::create(string `$locale`): ?Collator

Процедурный стиль

function collator_create(string `$locale`): ?Collator

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

### Список параметров

`locale`

  Локаль, содержащая необходимые правила сопоставления. Могут быть переданы специальные значения для языковых стандартов, если для языкового стандарта передана пустая строка (string), будут использоваться правила сопоставления языковых стандартов по умолчанию. Если передаётся значение `"root"`, будут использоваться правила » UCA.

### Возвращаемые значения

Возвращает новый экземпляр Collator или `null` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования collator_create()

    <?php
    $coll = collator_create( 'en_US' );

    if( !isset( $coll ) ) {
        printf( "Не удалось создать Collator: %s\n", intl_get_error_message() );
        exit( 1 );
    }
    ?>

### Смотрите также

- Collator::__construct() - Создаёт новый экземпляр Collator

# Collator::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — Получает значение атрибута сопоставления

### Описание

Объектно-ориентированный стиль

public function Collator::getAttribute(int `$attribute`): int|false

Процедурный стиль

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Получает значение целочисленного атрибута сопоставителя.

### Список параметров

`object`

  Объект Collator.

`attribute`

  Атрибут, для которого требуется получить значение.

### Возвращаемые значения

Значение атрибута или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_get_attribute()

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Обработка ошибки
    }
    ?>

### Смотрите также

- Константы Collator
- collator_set_attribute() - Устанавливает атрибут сопоставления
- collator_get_strength() - Получает текущую силу сопоставления

# Collator::getErrorCode

# collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — Получает последний код ошибки Collator

### Описание

Объектно-ориентированный стиль

public function Collator::getErrorCode(): int|false

Процедурный стиль

function collator_get_error_code(Collator `$object`): int|false

### Список параметров

`object`

  Объект Collator.

### Возвращаемые значения

Код ошибки, возвращённый последним вызовом функции API Collator или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_get_error_code()

    <?php
    $coll = collator_create( 'en_US' );
    if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
            handle_error( collator_get_error_code() );
    ?>

### Смотрите также

- collator_get_error_message() - Получает текст для кода последней ошибки Collator

# Collator::getErrorMessage

# collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — Получает текст для кода последней ошибки Collator

### Описание

Объектно-ориентированный стиль

public function Collator::getErrorMessage(): string|false

Процедурный стиль

function collator_get_error_message(Collator `$object`): string|false

Получает сообщение о последней ошибке.

### Список параметров

`object`

  Объект Collator.

### Возвращаемые значения

Описание ошибки, возвращённой последним вызовом функции API Collator или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_get_error_message()

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### Смотрите также

- collator_get_error_code() - Получает последний код ошибки Collator

# Collator::getLocale

# collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — Получает название локали для Collator

### Описание

Объектно-ориентированный стиль

public function Collator::getLocale(int `$type`): string|false

Процедурный стиль

function collator_get_locale(Collator `$object`, int `$type`): string|false

Получает название локали для Collator.

### Список параметров

`object`

  Объект Collator.

`type`

  Вы можете выбирать между корректным и фактическим языковым стандартом ( `Locale::VALID_LOCALE` и `Locale::ACTUAL_LOCALE`, соответственно).

### Возвращаемые значения

Функция возвращает настоящее имя локали, из которого берутся данные сопоставления. Если Collator был создан из правил или произошла ошибка, возвращает `false`.

### Примеры

Пример #1 Пример использования функции collator_get_locale()

    <?php
    $coll    = collator_create( 'en_US_California' );
    $res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
    $res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
    printf( "Название корректной локали: %s\nНазвание фактической локали: %s\n",
             $res_val, $res_act );
    ?>

Результат выполнения приведённого примера:

    Запрошенное название локали: en_US_California
    Название корректной локали: en_US
    Название фактической локали: en

### Смотрите также

- collator_create() - Создаёт новый экземпляр Collator

# Collator::getSortKey

# collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — Получает ключ сортировки строки

### Описание

Объектно-ориентированный стиль

public function Collator::getSortKey(string `$string`): string|false

Процедурный стиль

function collator_get_sort_key(Collator `$object`, string `$string`): string|false

Функция возвращает ключ сопоставления для строки. Ключи сопоставления возможно сравнивать напрямую, а не строки, хотя они зависят от реализации и могут меняться в зависимости от версии библиотеки ICU. Ключи сортировки обычно полезны только в базах данных или в других случаях, когда вызовы функций чрезвычайно дороги.

### Список параметров

`object`

  Объект Collator.

`string`

  Строка, из которой создаётся ключ.

### Возвращаемые значения

Функция возвращает ключ сопоставления для строки или `false`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Примеры

Пример #1 Пример получения ключа сортировки строки функцией collator_get_sort_key()

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);

    ?>

Вывод приведённого примера будет похож на:

3832404046010901dc08

Пример #2 Пример работы метода Collator::getSortKey() с функцией usort()

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Создаём объект Collator */
    $col = new Collator('en');

    /* Определяем порядок сортировки: заглавные варианты символов идут перед строчными. */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Сортируем данные пользовательской функцией, которая также удаляет эмодзи */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Указываем идентификатор 'S', который удалит символы Юникод-класса Symbols, и удаляем пробельные символы
             * в начале и конце строки функцией trim */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

            /* Создаём ключи сортировки */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

            /* Сравниваем ключи, чтобы определить порядок элементов. */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);

    ?>

Вывод приведённого примера будет похож на:

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### Смотрите также

- collator_sort() - Сортирует массив с использованием указанного средства сортировки
- collator_sort_with_sort_keys() - Сортирует массив с использованием указанного Collator и ключей сортировки

# Collator::getStrength

# collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — Получает текущую силу сопоставления

### Описание

Объектно-ориентированный стиль

public function Collator::getStrength(): int

Процедурный стиль

function collator_get_strength(Collator `$object`): int

### Список параметров

`object`

  Объект Collator.

### Возвращаемые значения

Возвращает текущую силу сопоставления или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_get_strength()

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### Смотрите также

- Константы Collator
- collator_set_strength() - Устанавливает силу сопоставления
- collator_get_attribute() - Получает значение атрибута сопоставления

# Collator::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — Устанавливает атрибут сопоставления

### Описание

Объектно-ориентированный стиль

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

Процедурный стиль

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

### Список параметров

`object`

  Объект Collator.

`attribute`

  Атрибут.

`value`

  Значение атрибута.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример установки атрибута функцией collator_set_attribute()

    <?php

    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);

### Смотрите также

- Константы класса Collator
- collator_get_attribute() - Получает значение атрибута сопоставления
- collator_set_strength() - Устанавливает силу сопоставления

# Collator::setStrength

# collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — Устанавливает силу сопоставления

### Описание

Объектно-ориентированный стиль

public function Collator::setStrength(int `$strength`): true

Процедурный стиль

function collator_set_strength(Collator `$object`, int `$strength`): true

Служба сопоставления в наборе библиотек » ICU поддерживает ряд уровней сравнения строк. Эти уровни называются «Уровнями», но их также называют «Силой сравнения». По этим категориям ICU сортирует строки точно в соответствии с местными соглашениями. Однако за счёт выборочной установки уровней искать строки в тексте можно с разными условиями сопоставления.

1. Первичный уровень: Обычно обозначает различия между базовыми символами, например: "a" < "b". Это самый сильный уровень различия. Например, словари разбивают на разделы по базовым символам. Этот уровень ещё называется силой `level 1`.

2. Вторичный уровень: Акценты в символах считают вторичными различиями, например: "as" < "às" < "at". Другие отличия между буквами тоже считают вторичными в зависимости от языка. Вторичное различие игнорируется, если строка содержит первичные различия. Этот уровень ещё называется силой `level 2`.

   > Замечание:

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

3. Третичный уровень: Различия в верхнем и нижнем регистре символов относятся к третичному уровню, например: "ao" < "Ao" < "aò". Кроме того, вариант буквы отличается от базовой формы на третичном уровне, например: "a" и "𝒶". Другой пример — разница между большой и маленькой Кана. Третичное различие игнорируется, если строки содержат первичное или вторичное различие. Этот уровень ещё называется силой `level 3`.

4. Четвертичный уровень: Когда пунктуация игнорируется (смотрите раздел Ignoring Punctuation («Игнорирование знаков препинания») в документации ICU) на уровнях 1-3, различия устанавливаются на дополнительном уровне, чтобы различить слова с пунктуацией и без неё, например: "ab" < "a-b" < "aB". Эта разница игнорируется, если строки содержат первичное, вторичное или третичное различие. Этот уровень ещё называется силой `level 4`. Строки сравнивают на четвертичном уровне, только если требуется игнорирование знаков препинания или при обработке японского текста (смотрите раздел Hiragana Processing («Обработка хираганы») в документации ICU).

5. Идентичный уровень: Решающий уровень сравнения строк, которые равны на остальных уровнях. Значения кодовых точек Unicode формы NFD (англ. Normalization Form D — форма нормализации D) каждой строки сравниваются на этом уровне, только если нет разницы на уровнях 1-4. Например, кантиляционные знаки иврита различаются только на этом уровне. На этом уровне строки сравнивают с осторожностью, поскольку разница только в значениях кодовых точек между двумя строками — предельно редкое явление. Сравнение строк на этом уровне заметно снижает производительность как для инкрементного сравнения, так и для генерации ключа сортировки, и увеличивает длину ключа сортировки. Этот уровень ещё называется силой `level 5`.

Приведём пример. Иногда при поиске текста пользователи игнорируют акценты или акценты и регистр. Бо́льшая часть символов различается по первым трём уровням, поэтому в большей части языков значение по умолчанию — третичный уровень сравнения. Однако, если для параметра «Альтернативный» задали значение «Shifted», то разницу на четвертичном уровне устанавливают, чтобы найти различия между пробелами, пунктуацией и символами, которые иначе функция проигнорировала бы. Символы сравнивают на Идентичном уровне, когда требуется обнаружить тонкие различия между символами наподобие математической полужирной строчной буквой A и математической курсивной строчной буквой A. Однако сравнение на уровнях выше третичного значительно увеличивает длину ключей сортировки и снижает производительность сравнения равных строк.

### Список параметров

`object`

  Объект Collator.

`strength`

  Strength to set.

  Допустимые значения:

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Примеры

Пример #1 Пример установки силы сопоставления функцией collator_set_strength()

    <?php

    $arr  = array('aò', 'Ao', 'ao');
    $coll = collator_create('en_US');

    // Сортировка массива с силой по умолчанию
    collator_sort($coll, $arr);
    var_export($arr);

    // Сортировка массива с первичной силой
    collator_set_strength($coll, Collator::PRIMARY);
    collator_sort($coll, $arr);
    var_export($arr);

    ?>

Результат выполнения приведённого примера:

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### Смотрите также

- Константы класса Collator
- collator_get_strength() - Получает текущую силу сопоставления

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — Сортирует массив с использованием указанного средства сортировки

### Описание

Объектно-ориентированный стиль

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Процедурный стиль

function collator_sort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Функция сортирует массив в соответствии с текущими правилами локали.

Эквивалентна стандартной функции PHP sort() .

### Список параметров

`object`

  Объект Collator.

`array`

  Array of strings to sort.

`flags`

  Необязательный тип сортировки, один из следующих:

  - `Collator::SORT_REGULAR` - сравнивает элементы как обычно (не изменяя тип)

  - `Collator::SORT_NUMERIC` - сравнивает элементы, как числа

  - `Collator::SORT_STRING` - сравнивает элементы, как строки

  Тип сортировки по умолчанию - `Collator::SORT_REGULAR`. Он также используется, если указано недопустимое значение `flags`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_sort()

    <?php
    $coll = collator_create( 'en_US' );
    $arr  = array( 'at', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

Результат выполнения приведённого примера:

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### Смотрите также

- Константы Collator
- collator_asort() - Сортирует массив с сохранением ассоциации индекса
- collator_sort_with_sort_keys() - Сортирует массив с использованием указанного Collator и ключей сортировки

# Collator::sortWithSortKeys

# collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Сортирует массив с использованием указанного Collator и ключей сортировки

### Описание

Объектно-ориентированный стиль

public function Collator::sortWithSortKeys(array `&$array`): bool

Процедурный стиль

function collator_sort_with_sort_keys(Collator `$object`, array `&$array`): bool

То же, что и collator_sort(), но использует ключи сортировки ICU, созданные ucol_getSortKey() для увеличения скорости работы с большими массивами.

### Список параметров

`object`

  Объект Collator.

`array`

  Массив строк для сортировки

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования collator_sort_with_sort_keys()

    <?php
    $arr  = array( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

Результат выполнения приведённого примера:

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### Смотрите также

- Константы Collator
- collator_sort() - Сортирует массив с использованием указанного средства сортировки
- collator_asort() - Сортирует массив с сохранением ассоциации индекса

## Содержание

- Collator::asort — Сортирует массив с сохранением ассоциации индекса
- Collator::compare — Сравнивает две строки Unicode
- Collator::__construct — Создаёт новый экземпляр Collator
- Collator::create — Создаёт новый экземпляр Collator
- Collator::getAttribute — Получает значение атрибута сопоставления
- Collator::getErrorCode — Получает последний код ошибки Collator
- Collator::getErrorMessage — Получает текст для кода последней ошибки Collator
- Collator::getLocale — Получает название локали для Collator
- Collator::getSortKey — Получает ключ сортировки строки
- Collator::getStrength — Получает текущую силу сопоставления
- Collator::setAttribute — Устанавливает атрибут сопоставления
- Collator::setStrength — Устанавливает силу сопоставления
- Collator::sort — Сортирует массив с использованием указанного средства сортировки
- Collator::sortWithSortKeys — Сортирует массив с использованием указанного Collator и ключей сортировки

# The NumberFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

Программы хранят и оперируют числами в двоичном представлении, которое не зависит от текущих региональных настроек. При выводе на экран или печати числа программы преобразовывают числа в строку по правилам, которые соответствуют региональным параметрам. Число 12345.67 в локали US программа выведет как «12,345.67», во французской локали — как «12 345,67» и как «12.345,67» в немецкой.

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

Для валют можно использовать тип формата денежной единицы, который возвращает строку с отформатированным числом и символом валюты. Естественно, класс NumberFormatter не знает об обменных курсах, так что выводимое число будет одинаковым независимо от установленной валюты. То есть одинаковые числа имеют разную денежную стоимость, которая зависит от настроек региональной валюты. Для числа 9988776.65 результат будет таким:

- 9 988 776,65 € для Франции
- 9.988.776,65 € для Германии
- $9,988,776.65 для США

Чтобы отформатировать процентную величину, создают средство форматирования с типом процентного формата, который соответствует текущим региональным настройкам. Такое средство форматирования отобразит десятичную дробь числа 0.75 как 75 %.

Для более сложного форматирования, например записи чисел в виде текста, работают правила средства форматирования по преобразованию чисел в текст.

## Обзор класса

class NumberFormatter {
/* Константы */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Методы */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Предопределённые константы

## Типы форматирования

Следующие стили определяют режим форматирования значений функцией numfmt_create().

`NumberFormatter::PATTERN_DECIMAL` int
  Формат десятичных чисел по шаблону.
`NumberFormatter::DECIMAL` int
  Формат десятичных чисел.
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Формат десятичных чисел в краткой форме компактной нотации: "23K", "45B". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Формат десятичных чисел в длинной форме компактной нотации: "23 thousand", "45 billion". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::CURRENCY` int
  Формат валюты.
`NumberFormatter::CURRENCY_ISO` int
  Формат валюты по стандарту ISO: "USD1.00". Режим доступен с PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Формат денежной суммы со склонением названия валюты в единственном или множественном числе: "1.00 US dollar" и "3.00 US dollars". Режим доступен с PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Символ валюты для наличных, без дробной части: "NT$3" вместо "NT$3.23". Режим доступен с PHP 8.5.0 и ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Формат денежной суммы с символом валюты: "$1.00". Отрицательные суммы выводятся не в скобках, как в бухгалтерском формате, а со знаком минуса: "-$1.00". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::PERCENT` int
  Процентный формат.
`NumberFormatter::SCIENTIFIC` int
  Научный формат.
`NumberFormatter::SPELLOUT` int
  Формат по правилам представления чисел прописью: "одна тысяча девятьсот девяносто пять" для числа 1995.
`NumberFormatter::ORDINAL` int
  Формат по правилам записи порядковых числительных: "8th".
`NumberFormatter::DURATION` int
  Формат интервала времени по заданным правилам: "7:40" для числа 460 или "5 sec." для числа 5.
`NumberFormatter::PATTERN_RULEBASED` int
  Формат по шаблону на основе правил.
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Бухгалтерский формат денежных сумм. Отрицательные суммы выводятся в скобках, а не со знаком минуса: `($3.00)` вместо `-$3.00`. Режим доступен с PHP 7.4.1 и ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Формат по умолчанию для текущих региональных настроек.
`NumberFormatter::IGNORE` int
  Псевдоним режима PATTERN_DECIMAL.

## Спецификаторы числового формата

Константы определяют способ разбора чисел функцией numfmt_parse() или форматирования чисел функцией numfmt_format().

`NumberFormatter::TYPE_DEFAULT` int
  Автоопределение типа значения.
`NumberFormatter::TYPE_INT32` int
  Форматирование или разбор значения как 32-битного целого числа.
`NumberFormatter::TYPE_INT64` int
  Форматирование или разбор значения как 64-битного целого числа.
`NumberFormatter::TYPE_DOUBLE` int
  Форматирование или разбор значения как числа с плавающей точкой.
`NumberFormatter::TYPE_CURRENCY` int
  Форматирование или разбор значения как денежной суммы. Спецификатор устарел с PHP 8.3.0.

## Атрибуты форматирования чисел

Атрибуты определяют формат чисел при обработке значений функциями numfmt_get_attribute() и numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Разбирать только целые числа.
`NumberFormatter::GROUPING_USED` int
  Разделять группы разрядов.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Выводить десятичную точку даже в числах без дробной части.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Максимум разрядов в целой части числа.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Минимум разрядов в целой части числа.
`NumberFormatter::INTEGER_DIGITS` int
  Количество разрядов в целой части числа.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Максимум разрядов в дробной части числа.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Минимум разрядов в дробной части числа.
`NumberFormatter::FRACTION_DIGITS` int
  Количество разрядов в дробной части числа.
`NumberFormatter::MULTIPLIER` int
  Множитель.
`NumberFormatter::GROUPING_SIZE` int
  Размер группы разрядов.
`NumberFormatter::ROUNDING_MODE` int
  Режим округления.
`NumberFormatter::ROUNDING_INCREMENT` int
  Шаг округления.
`NumberFormatter::FORMAT_WIDTH` int
  Ширина, до которой вывод метода format() дополняется пробелами.
`NumberFormatter::PADDING_POSITION` int
  Позиция, с которой начинается дополнение. Смотрите описание констант дополнения.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Размер второй группы разрядов.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Выводить только значащие цифры.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Минимум значащих цифр.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Максимум значащих цифр.
`NumberFormatter::LENIENT_PARSE` int
  Мягкий режим разбора при форматировании чисел по шаблону на основе правил.

## Атрибуты текстового формата чисел

Атрибуты определяют текстовый формат чисел при обработке значений функциями numfmt_get_text_attribute() и numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Префикс для положительных чисел и нуля.
`NumberFormatter::POSITIVE_SUFFIX` int
  Суффикс для положительных чисел и нуля.
`NumberFormatter::NEGATIVE_PREFIX` int
  Префикс для отрицательных чисел.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Суффикс для отрицательных чисел.
`NumberFormatter::PADDING_CHARACTER` int
  Символ для дополнения до заданной ширины.
`NumberFormatter::CURRENCY_CODE` int
  Код валюты по стандарту ISO.
`NumberFormatter::DEFAULT_RULESET` int
  Набор правил по умолчанию. Атрибут доступен только для форматирования на основе правил.
`NumberFormatter::PUBLIC_RULESETS` int
  Публичный набор правил. Атрибут доступен только для форматирования на основе правил. Атрибут доступен только для чтения. Публичный набор правил возвращается в виде одной строки, в которой название каждого набора правил отделяется символом ';' — точка с запятой.

## Спецификаторы формата символов

Символы форматирования чисел для numfmt_get_symbol() и numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  Десятичный разделитель.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  Разделитель групп.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  Разделитель шаблонов.
`NumberFormatter::PERCENT_SYMBOL` int
  Знак процента.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Ноль.
`NumberFormatter::DIGIT_SYMBOL` int
  Символ представления цифры в шаблоне.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  Знак минус.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  Знак плюс.
`NumberFormatter::CURRENCY_SYMBOL` int
  Символ валюты.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  Международный символ валюты.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  Десятичный разделитель в денежных форматах.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  Символ экспоненты в научной нотации.
`NumberFormatter::PERMILL_SYMBOL` int
  Символ промилле.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Символ экранирования заполнителя.
`NumberFormatter::INFINITY_SYMBOL` int
  Знак бесконечности.
`NumberFormatter::NAN_SYMBOL` int
  Символ нечисла (англ. Not-a-number, сокр. NaN).
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Символ значащей цифры.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  Разделитель групп для денежного формата.

## Режимы округления

Режимы округления при вызове функций numfmt_get_attribute() и numfmt_set_attribute() с атрибутом `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Псевдоним константы `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING` int
  Округление в сторону положительной бесконечности.
`NumberFormatter::ROUND_DOWN` int
  Округление к меньшему по модулю числу.
`NumberFormatter::ROUND_FLOOR` int
  Округление в сторону отрицательной бесконечности.
`NumberFormatter::ROUND_HALFDOWN` int
  Округление к ближайшему числу; при равном удалении — к меньшему по модулю.
`NumberFormatter::ROUND_HALFEVEN` int
  Округление к ближайшему числу; при равном удалении — к ближайшему чётному.
`NumberFormatter::ROUND_HALFODD`
  Округление к ближайшему нечётному числу.
`NumberFormatter::ROUND_HALFUP` int
  Округление к ближайшему числу; при равном удалении — к большему по модулю.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Псевдоним константы `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Округление к большему по модулю числу.

## Спецификаторы дополнения

Значения позиции дополнения при вызове функций numfmt_get_attribute() и numfmt_set_attribute() с атрибутом `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Символы дополнения вставляются после префикса.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Символы дополнения вставляются после суффикса.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Символы дополнения вставляются перед префиксом.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Символы дополнения вставляются перед суффиксом.

## Смотрите также

- » Документация проекта ICU по форматированию
- » ICU. Форматирование чисел
- » ICU. Форматирование десятичных дробей
- » ICU. Форматирование чисел на основе правил

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавлены константы `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | Константы класса стали типизированными.

# NumberFormatter::create

# numfmt_create

# NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Создаёт средство форматирования чисел

### Описание

Объектно-ориентированный стиль (метод)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Процедурный стиль

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Объектно-ориентированный стиль (конструктор):

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Создаёт средство форматирования чисел.

### Список параметров

`locale`

  Локаль, в которой будет отформатировано число (название локали, например en_CA).

`style`

  Стиль форматирования, одна из констант стиля форматирования. Если передана `NumberFormatter::PATTERN_DECIMAL` или `NumberFormatter::PATTERN_RULEBASED`, то формат числа открывается с использованием данного шаблона, который должен соответствовать синтаксису, описанному в » документации ICU DecimalFormat или » документации ICU RuleBasedNumberFormat, соответственно.

`pattern`

  Строка шаблона, если для выбранного стиля требуется шаблон.

### Возвращаемые значения

Возвращает объект NumberFormatter или `null` в случае возникновения ошибки.

### Ошибки

Выбрасывается ошибка ValueError, если значение параметра `locale` недопустимо.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь выбрасывается ошибка ValueError, если значение параметра `locale` недопустимо.
8.0.0 | `pattern` теперь допускает значение null.

### Примеры

Пример #1 Пример использования numfmt_create()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    $fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
    echo numfmt_format($fmt, 1142)."\n";
    ?>

Пример #2 Пример использования NumberFormatter::create()

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
    echo $fmt->format(1142)."\n";
    ?>

Результат выполнения приведённого примера:

    1.234.567,891
    millicentoquarantadue

### Смотрите также

- numfmt_format() - Форматирует число
- numfmt_parse() - Разбирает число

# NumberFormatter::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — Форматирует число

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Процедурный стиль

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Функция форматирует числовое значение по правилами средства форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`num`

  Значение для форматирования. Параметр принимает значения int, float и другие типы, которые преобразовываются в числовое значение.

`type`

  Тип форматирования. Параметр не поддерживает константу `NumberFormatter::TYPE_CURRENCY`; вместо вызова с этим флагом значение валюты форматируют методом NumberFormatter::formatCurrency().

### Возвращаемые значения

Функция возвращает строку, которая содержит отформатированное значение, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример форматирования числа функцией numfmt_format()

    <?php

    $fmt = numfmt_create('de_DE', NumberFormatter::DECIMAL);
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);

    ?>

Пример #2 Пример форматирования числа в объектно-ориентированном стиле

    <?php

    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);

    ?>

Результат выполнения приведённого примера:

    string(13) "1.234.567,891"

### Примечания

> Замечание:

> Этот метод форматирования поддерживает функции базовой библиотеки ICU не на 100 % и, например, не разрешает выбирать формат обозначения валюты: р. или ₽.

> Полную поддержку функций библиотеки даёт функция msgfmt_format_message().

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_format_currency() - Форматирует значение валюты
- numfmt_parse() - Разбирает число
- msgfmt_format_message() - Быстро форматирует сообщение

# NumberFormatter::formatCurrency

# numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — Форматирует значение валюты

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

Процедурный стиль

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Форматирует значение валюты в соответствии с правилами форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`amount`

  Числовое значение валюты.

`currency`

  Трёхбуквенный код валюты ISO 4217, обозначающий используемую валюту.

### Возвращаемые значения

Строка, представляющая форматированное значение валюты или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования numfmt_format_currency()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    $fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    $fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    ?>

Результат выполнения приведённого примера:

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### Примечания

> Замечание:

> Форматы, достижимые этим способом форматирования, не могут полностью использовать возможности базовой библиотеки ICU, например, форматировать валюту с узким символом валюты.

> Для полной поддержки, используйте функцию msgfmt_format_message().

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_format() - Форматирует число
- numfmt_parse_currency() - Разбирает номер валюты
- msgfmt_format_message() - Быстро форматирует сообщение

# NumberFormatter::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — Получает атрибут

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

Процедурный стиль

function numfmt_get_attribute(NumberFormatter `$formatter`, int `$attribute`): int|float|false

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

### Список параметров

`formatter`

  Объект NumberFormatter.

`attribute`

  Спецификатор атрибута - одна из констант числового атрибута.

### Возвращаемые значения

Возвращает значение атрибута в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_get_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Цифр: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Цифр: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Цифр: 3
    1.234.567,891
    Цифр: 2
    1.234.567,89

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_get_text_attribute() - Получает текстовый атрибут
- numfmt_set_attribute() - Устанавливает значение для атрибута форматирования чисел

# NumberFormatter::getErrorCode

# numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — Получает последний код ошибки средства форматирования

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getErrorCode(): int

Процедурный стиль

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Функция получает код результата последней операции средства форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

### Возвращаемые значения

Функция возвращает код ошибки последнего вызова средства форматирования.

### Примеры

Пример #1 Пример получения последнего кода ошибки функцией numfmt_get_error_code()

    <?php

    $fmt  = numfmt_create('de_DE', NumberFormatter::DECIMAL);
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if (intl_is_failure(numfmt_get_error_code($fmt))) {
        echo 'Formatter error';
    }

    ?>

Пример #2 Пример получения кода ошибки последнего вызова в объектно-ориентированном стиле

    <?php

    $fmt = new NumberFormatter('de_DE', NumberFormatter::DECIMAL);
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Formatter error';
    }

    ?>

### Смотрите также

- numfmt_get_error_message() - Получает последнее сообщение об ошибке средства форматирования
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# NumberFormatter::getErrorMessage

# numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — Получает последнее сообщение об ошибке средства форматирования

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getErrorMessage(): string

Процедурный стиль

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Получает сообщение об ошибке от последней функции, выполненной средством форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

### Возвращаемые значения

Возвращает сообщение об ошибке из последнего вызова средства форматирования.

### Примеры

Пример #1 Пример использования numfmt_get_error_message()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# NumberFormatter::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — Получает локаль средства форматирования

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Процедурный стиль

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Получает название локали средства форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`type`

  Вы можете выбрать действительную или фактическую локаль ( `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, соответственно). По умолчанию используется фактическая локаль.

### Возвращаемые значения

Имя локали, используемое для создания средства форматирования или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_get_locale()

    <?php
    $req     = 'fr_FR_PARIS';
    $fmt     = numfmt_create( $req,  NumberFormatter::DECIMAL);
    $res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
    $res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
    printf( "Запрошенная локаль: %s\nДействительная локаль: %s\nФактическая локаль: %s\n",
             $req, $res_val, $res_act );
    ?>

Результат выполнения приведённого примера:

    Запрошенная локаль: fr_FR_PARIS
    Действительная локаль: fr_FR
    Фактическая локаль: fr

### Смотрите также

- numfmt_create() - Создаёт средство форматирования чисел
- numfmt_get_error_code() - Получает последний код ошибки средства форматирования

# NumberFormatter::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — Получает шаблон средства форматирования

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getPattern(): string|false

Процедурный стиль

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Извлекает шаблон, используемый средством форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

### Возвращаемые значения

Строка (string) шаблона, используемого средством форматирования или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_get_pattern()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Шаблон: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Шаблон: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Шаблон: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Шаблон: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Шаблон: #,##0.###
    1.234.567,891
    Шаблон: #0.# kg
    1234567,9 kg

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_set_pattern() - Устанавливает шаблон средства форматирования
- numfmt_create() - Создаёт средство форматирования чисел

# NumberFormatter::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — Получает значение символа

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getSymbol(int `$symbol`): string|false

Процедурный стиль

function numfmt_get_symbol(NumberFormatter `$formatter`, int `$symbol`): string|false

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

### Список параметров

`formatter`

  Объект NumberFormatter.

`symbol`

  Спецификатор символа, одна из констант символов форматирования.

### Возвращаемые значения

Строка символа или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_get_symbol()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Разделитель: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Разделитель: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Разделитель: .
    1.234.567,891
    Разделитель: *
    1*234*567,891

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_set_symbol() - Устанавливает значение символа

# NumberFormatter::getTextAttribute

# numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Получает текстовый атрибут

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

Процедурный стиль

function numfmt_get_text_attribute(NumberFormatter `$formatter`, int `$attribute`): string|false

Получает текстовый атрибут, связанный со средством форматирования. Примером текстового атрибута является суффикс для положительных чисел. Если средство форматирования не понимает атрибут, выдаётся ошибка `U_UNSUPPORTED_ERROR`. Средства форматирования на основе правил понимают только `NumberFormatter::DEFAULT_RULESET` и `NumberFormatter::PUBLIC_RULESETS`.

### Список параметров

`formatter`

  Объект NumberFormatter.

`attribute`

  Спецификатор атрибута - одна из констант текстового атрибута.

### Возвращаемые значения

Возвращает значение атрибута в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_get_text_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Префикс: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Префикс: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Префикс: -
    -1.234.567,891
    Префикс: MINUS
    MINUS1.234.567,891

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_get_attribute() - Получает атрибут
- numfmt_set_text_attribute() - Устанавливает текстовый атрибут

# NumberFormatter::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — Разбирает число

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

Процедурный стиль

function numfmt_parse(
NumberFormatter `$formatter`,
string `$string`,
int `$type` = `NumberFormatter::TYPE_DOUBLE`,
int `&$offset` = `null`
): int|float|false

Преобразовывает строку в число по правилам средства форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`string`

  Строка для разбора числа.

`type`

  Используемый тип форматирования. По умолчанию используется `NumberFormatter::TYPE_DOUBLE`. Обратите внимание, что константа `NumberFormatter::TYPE_CURRENCY` не поддерживается; воспользуйтесь вместо неё методом NumberFormatter::parseCurrency().

`offset`

  Смещение в строке, с которой начинается синтаксический анализ. При возврате это значение будет содержать смещение, на котором закончился синтаксический анализ.

### Возвращаемые значения

Возвращает значение анализируемого числа или логическое значение `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_parse()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo numfmt_parse($fmt, $num)."\n";
    echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo $fmt->parse($num)."\n";
    echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Результат выполнения приведённого примера:

    1234567.891
    1234567

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_format() - Форматирует число
- numfmt_parse_currency() - Разбирает номер валюты

# NumberFormatter::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — Разбирает номер валюты

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

Процедурный стиль

function numfmt_parse_currency(
NumberFormatter `$formatter`,
string `$string`,
string `&$currency`,
int `&$offset` = `null`
): float|false

Разбирает строку на число с плавающей точкой и валюту с помощью средства форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`currency`

  Параметр для получения названия валюты (трёхбуквенный код валюты ISO 4217).

`offset`

  Смещение в строке, с которой начинается синтаксический анализ. При возврате это значение будет содержать смещение, на котором закончился синтаксический анализ.

### Возвращаемые значения

Разобранное числовое значение или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования numfmt_parse_currency()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "У нас ".numfmt_parse_currency($fmt, $num, $curr)." в $curr\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "У нас ".$fmt->parseCurrency($num, $curr)." в $curr\n";
    ?>

Результат выполнения приведённого примера:

    У нас 1234567.89 в USD

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_parse() - Разбирает число
- numfmt_format_currency() - Форматирует значение валюты

# NumberFormatter::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — Устанавливает значение для атрибута форматирования чисел

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

Процедурный стиль

function numfmt_set_attribute(NumberFormatter `$formatter`, int `$attribute`, int|float `$value`): bool

Функция устанавливает значение для атрибута форматирования чисел. Пример атрибута числового формата — количество разрядов в целой части числа, которое выведет средство форматирования.

### Список параметров

`formatter`

  Объект NumberFormatter.

`attribute`

  Спецификатор атрибута — константа атрибута форматирования чисел.

`value`

  Значение для атрибута.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример форматирования чисел функцией numfmt_set_attribute()

    <?php

    $fmt = numfmt_create('de_DE', NumberFormatter::DECIMAL);
    echo "Количество разрядов в дробной части числа: " . numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS) . "\n";
    echo numfmt_format($fmt, 1234567.891234567890000) . "\n";

    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Количество разрядов в дробной части числа: " . numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS) . "\n";
    echo numfmt_format($fmt, 1234567.891234567890000) . "\n";

Пример #2 Пример форматирования чисел в объектно-ориентированном стиле

    <?php

    $fmt = new NumberFormatter('de_DE', NumberFormatter::DECIMAL);
    echo "Количество разрядов в дробной части числа: " . $fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS) . "\n";
    echo $fmt->format(1234567.891234567890000) . "\n";

    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Количество разрядов в дробной части числа: " . $fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS) . "\n";
    echo $fmt->format(1234567.891234567890000) . "\n";

Результат выполнения приведённого примера:

    Количество разрядов в дробной части числа: 3
    1.234.567,891
    Количество разрядов в дробной части числа: 2
    1.234.567,89

Пример #3 Пример усечения значений атрибутом `NumberFormatter::ROUNDING_MODE`

По умолчанию объект NumberFormatter округляет значения. В режиме `NumberFormatter::ROUND_DOWN` для атрибута `NumberFormatter::ROUNDING_MODE` функция усекает значение до заданного количества дробных разрядов без округления.

    <?php

    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Округление в режиме по умолчанию:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 — результат округления вверх
    echo $fmt->format(3.781), "\n"; // 3.78 — результат округления вниз

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\nУсечение в режиме ROUND_DOWN:\n";
    echo $fmt->format(3.789), "\n"; // 3.78 — результат усечения
    echo $fmt->format(3.781), "\n"; // 3.78 — результат усечения

Результат выполнения приведённого примера:

    Округление в режиме по умолчанию:
    3.79
    3.78

    Усечение в режиме ROUND_DOWN:
    3.78
    3.78

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_get_attribute() - Получает атрибут
- numfmt_set_text_attribute() - Устанавливает текстовый атрибут

# NumberFormatter::setPattern

# numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — Устанавливает шаблон средства форматирования

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::setPattern(string `$pattern`): bool

Процедурный стиль

function numfmt_set_pattern(NumberFormatter `$formatter`, string `$pattern`): bool

Устанавливает шаблон, используемый средством форматирования. Не может использоваться в средстве форматирования на основе правил.

### Список параметров

`formatter`

  Объект NumberFormatter.

`pattern`

  Шаблон в синтаксисе, описанном в » документации ICU DecimalFormat.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования numfmt_set_pattern()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Шаблон: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Шаблон: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Шаблон: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Шаблон: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Шаблон: #,##0.###
    1.234.567,891
    Шаблон: #0.# kg
    1234567,9 kg

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_create() - Создаёт средство форматирования чисел
- numfmt_get_pattern() - Получает шаблон средства форматирования

# NumberFormatter::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — Устанавливает значение символа

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

Процедурный стиль

function numfmt_set_symbol(NumberFormatter `$formatter`, int `$symbol`, string `$value`): bool

Устанавливает символ, связанный со средством форматирования. Средство форматирования использует символы для представления специальных символов, зависящих от языка, в числах, например, знак процента. Этот API не поддерживается для средств форматирования на основе правил.

### Список параметров

`formatter`

  Объект NumberFormatter.

`symbol`

  Спецификатор символа, одна из констант символа форматирования.

`value`

  Текст для символа.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования numfmt_set_symbol()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Разделитель: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Разделитель: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Разделитель: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Разделитель: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Разделитель: .
    1.234.567,891
    Разделитель: *
    1*234*567,891

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_get_symbol() - Получает значение символа

# NumberFormatter::setTextAttribute

# numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Устанавливает текстовый атрибут

### Описание

Объектно-ориентированный стиль

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

Процедурный стиль

function numfmt_set_text_attribute(NumberFormatter `$formatter`, int `$attribute`, string `$value`): bool

Устанавливает текстовый атрибут, связанный со средством форматирования. Примером текстового атрибута является суффикс для положительных чисел. Если средство форматирования не понимает атрибут, выдаётся ошибка `U_UNSUPPORTED_ERROR`. Средства форматирования на основе правил понимают только `NumberFormatter::DEFAULT_RULESET` и `NumberFormatter::PUBLIC_RULESETS`.

### Список параметров

`formatter`

  Объект NumberFormatter.

`attribute`

  Спецификатор атрибута - одна из констант текстового атрибута.

`value`

  Текст для значения атрибута.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования numfmt_set_text_attribute()

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Префикс: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Префикс: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Префикс: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Префикс: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

Результат выполнения приведённого примера:

    Префикс: -
    -1.234.567,891
    Префикс: MINUS
    MINUS1.234.567,891

### Смотрите также

- numfmt_get_error_code() - Получает последний код ошибки средства форматирования
- numfmt_get_text_attribute() - Получает текстовый атрибут
- numfmt_set_attribute() - Устанавливает значение для атрибута форматирования чисел

## Содержание

- NumberFormatter::create — Создаёт средство форматирования чисел
- NumberFormatter::format — Форматирует число
- NumberFormatter::formatCurrency — Форматирует значение валюты
- NumberFormatter::getAttribute — Получает атрибут
- NumberFormatter::getErrorCode — Получает последний код ошибки средства форматирования
- NumberFormatter::getErrorMessage — Получает последнее сообщение об ошибке средства форматирования
- NumberFormatter::getLocale — Получает локаль средства форматирования
- NumberFormatter::getPattern — Получает шаблон средства форматирования
- NumberFormatter::getSymbol — Получает значение символа
- NumberFormatter::getTextAttribute — Получает текстовый атрибут
- NumberFormatter::parse — Разбирает число
- NumberFormatter::parseCurrency — Разбирает номер валюты
- NumberFormatter::setAttribute — Устанавливает значение для атрибута форматирования чисел
- NumberFormatter::setPattern — Устанавливает шаблон средства форматирования
- NumberFormatter::setSymbol — Устанавливает значение символа
- NumberFormatter::setTextAttribute — Устанавливает текстовый атрибут

# Класс Locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

Locale — идентификатор, через который из API получают информацию о языке, культуре или региональном поведении. Локали PHP организованы и обозначены так же, как и локали проекта CLDR, которыми пользуется проект ICU и многие производители систем Unix, Linux и Mac, Java и т. д. Локали обозначаются согласно языковым меткам стандарта RFC 4646 (который использует тире, а не подчёркивание) в дополнение к традиционным обозначением с символом подчёркивания. Функции класса понимают оба написания, если явно не указали иное.

Примеры идентификаторов:

- en-US (Английский, США)
- zh-Hant-TW (Китайский, Традиционное начертание, Тайвань)
- fr-CA, fr-FR (Французский для Канады и Франции)

Класс Locale (и соответствующие процедурные функции) используется для взаимодействия с идентификаторами локалей, для проверки правильного составления идентификатора, его корректности и т. д. Модули используются CLDR в UAX #35 (и наследуется ICU), являются корректными и используются везде они были бы в ICU.

Данный класс нельзя инстанциировать как объект. Все методы/функции объявлены статическими.

`null` или пустая строка будут считаться за «базовую» локаль. «Базовая» локаль — «en_US_POSIX» в проекте CLDR. Языковые метки (и идентификаторы локали) регистронезависимы. В классе присутствует метод, который преобразует их к каноничному виду.

## Обзор класса

class Locale {
/* Константы */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* Методы */
public static function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## Предопределённые константы

`Locale::DEFAULT_LOCALE` null
  Используется в качестве параметра, задающего локаль в функциях где это необходимо, таких как NumberFormatter. Эта константа вынуждает использовать локаль по умолчанию.

Эти константы описывают выбор локали для метода getLocale различных классов.

`Locale::ACTUAL_LOCALE` int
  Описывает текущую локаль.
`Locale::VALID_LOCALE` int
  Это самая специфичная локаль, поддерживаемая ICU.

## Подтеги локали

Эти константы определяют, как анализируются или составляются локали. Их следует задавать как ключи массива аргументов для функции locale_compose() и возвращать как ключи возвращаемого ассоциативного массива (array) функции locale_parse().

`Locale::LANG_TAG` int
  Подтег языка
`Locale::EXTLANG_TAG` int
  Расширенный подтег языка
`Locale::SCRIPT_TAG` int
  Подтег начертания
`Locale::REGION_TAG` int
  Подтег региона
`Locale::VARIANT_TAG` int
  Подтег варианта
`Locale::GRANDFATHERED_LANG_TAG` int
  Подтег языка в старом синтаксисе (grandfathered)
`Locale::PRIVATE_TAG` int
  Частный подтег

## Смотрите также

- » RFC 4646 — метки для идентификаторов языков
- » RFC 4647 — проверка языковых меток
- » Проект Unicode CLDR:Стандартный репозиторий данных локалей
- » Регистр языковых меток IANA
- » Руководство пользователя ICU — Локаль
- » ICU API локали

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# Locale::acceptFromHttp

# locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — Попытаться определить наилучшую локаль основываясь на заголовке HTTP "Accept-Language"

### Описание

Объектно-ориентированный стиль

public static function Locale::acceptFromHttp(string `$header`): string|false

Процедурный стиль

function locale_accept_from_http(string `$header`): string|false

Пытается определить локаль, удовлетворяющую списку языков, запрошенному в HTTP-заголовке "Accept-Language".

### Список параметров

`header`

  Строка, содержащая заголовок "Accept-Language" в соответствии с форматом RFC 2616.

### Возвращаемые значения

Соответствующий идентификатор локали.

Возвращает `false`, если длина `header` превышает `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_accept_from_http()

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Результат выполнения приведённого примера:

    en_US

### Смотрите также

- locale_lookup() - Поиск языковых меток наиболее подходящих заданной локали

# Locale::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — Канонизировать строку локали

### Описание

public static function Locale::canonicalize(string `$locale`): ?string

Канонизирует переданную строку локали в формат ICU.

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

Поведение метода зависит от версии ICU, используемой PHP (`INTL_ICU_VERSION`).

### Список параметров

`locale`
  Оригинальная строка локализации.

### Возвращаемые значения

Канонизированная строка локали.

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования функции locale_canonicalize()

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

Вывод приведённого примера будет похож на:

    en_US
    totally_NOT_VALID

# Locale::composeLocale

# locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — Возвращает правильно упорядоченный и разделенный идентификатор локали

### Описание

Объектно-ориентированный стиль

public static function Locale::composeLocale(array `$subtags`): string|false

Процедурный стиль

function locale_compose(array `$subtags`): string|false

Функция возвращает правильно упорядоченный и разделенный идентификатор локали. Ключи идентифицируют конкретные подтеги идентификатора локали, а значения — связанные значения подтегов.

### Список параметров

`subtags`

  Массив (array), который содержит список пар ключ-значение, где ключи — имена подтегов идентификатора локали, а значения, соответственно, значения этих подтегов.

  > Замечание:

  > Разрешается не более 15 подтегов `'variant'` и `'private'`, подтегов `'extlang'` не более 3 и т. д. Варианты допустимы с суффиксами от 0 до 14. Ключи для этого подтега должны называться так: `variant0`, `variant1`, …,`variant14`. В возвращаемом идентификаторе локали вложенный тег упорядочен по суффиксу, в результате чего следует `variant0`, за которым следует `variant1`, за которым следует `variant2` и так далее.

  > В качестве альтернативы, множественные подтеги `'variant'`, `'private'` и `'extlang'` можно задать в виде массива под соответствующим ключом (например `'variant'`). Тогда ограничения на количество распознанных вложенных тегов не применяются.

### Возвращаемые значения

Функция возвращает соответствующий идентификатор локали или `false`, если параметр `subtags` не задали.

### Примеры

Пример #1 Пример использования функции locale_compose()

    <?php

    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );

    echo locale_compose($arr);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php

    $arr = array(
        'language'=>'en' ,
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );

    echo Locale::composeLocale($arr);

    ?>

Результат выполнения приведённого примера:

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

Пример #3 Пределы подтегов

Если параметр `subtags` задали как отдельные ключи с числовым суффиксом, неподдерживаемые ключи игнорируются (в этом случае `'extlang3'`) и упорядочиваются в результате по числовому суффиксу. Ограничений нет, если подтеги задали в виде массива (array); порядок такой, как задали.

    <?php

    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang3' => 'd',
        'extlang2' => 'c',
        'extlang1' => 'b',
        'extlang0' => 'a',
    );

    echo locale_compose($arr), PHP_EOL;

    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang'  => ['a', 'b', 'c', 'd'],
    );

    echo locale_compose($arr), PHP_EOL;

    ?>

Результат выполнения приведённого примера:

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### Смотрите также

- locale_parse() - Получить ассоциативный массив всех подтегов локали

# Locale::filterMatches

# locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — Проверить, соответствует ли тег фильтра языка локали

### Описание

Объектно-ориентированный стиль

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Процедурный стиль

function locale_filter_matches(string `$langtag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Проверить, соответствует ли фильтр `languageTag` локали `locale` руководствуясь базовыми фильтрующими алгоритмами RFC 4647

### Список параметров

`languageTag`

  Языковой тег

`locale`

  Локаль

`canonicalize`

  Если `true`, аргумент будет преобразован к каноничной форме перед проверкой.

### Возвращаемые значения

`true` если `locale` подходит для `languageTag`, или `false`, если нет.

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_filter_matches()

    <?php
    echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Подходит" : "Не подходит";
    echo '; ';
    echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Подходит" : "Не подходит";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Подходит" : "Не подходит";
    echo '; ';
    echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Подходит" : "Не подходит";
    ?>

Результат выполнения приведённого примера:

    Не подходит; Подходит

### Смотрите также

- locale_lookup() - Поиск языковых меток наиболее подходящих заданной локали

# Locale::getAllVariants

# locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — Получение вариантов из переданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getAllVariants(string `$locale`): ?array

Процедурный стиль

function locale_get_all_variants(string `$locale`): ?array

Получение вариантов из переданной локали

### Список параметров

`locale`

  Локаль из которой будут извлечены варианты

### Возвращаемые значения

Массив, содержащий список вариантов заданной локали, или `null`, если таковых нет

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_get_all_variants()

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
     $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
     var_export( $arr );
    ?>

Результат выполнения приведённого примера:

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### Смотрите также

- locale_get_primary_language() - Получить первичный язык для локали
- locale_get_script() - Получить алфавит для локали
- locale_get_region() - Получить регион для локали

# Locale::getDefault

# locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — Получение значения локали INTL по умолчанию из опции 'default_locale'

### Описание

Объектно-ориентированный стиль

public static function Locale::getDefault(): string

Процедурный стиль

function locale_get_default(): string

Получение значения локали по умолчанию. при инициализации PHP, это значение устанавливается в значение 'intl.default_locale' из php.ini, если оно там есть, или в значение функции ICU uloc_getDefault().

### Список параметров

### Возвращаемые значения

Текущая локаль времени исполнения

### Примеры

Пример #1 Пример использования locale_get_default()

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo locale_get_default();
    echo '; ';
    locale_set_default('fr');
    echo locale_get_default();
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

Результат выполнения приведённого примера:

    de-DE; fr

### Смотрите также

- locale_set_default() - Устанавливает локаль по умолчанию во время исполнения

# Locale::getDisplayLanguage

# locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — Возвращает соответствующим образом локализованное имя языка для заданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

Процедурный стиль

function locale_get_display_language(string `$locale`, ?string `$displayLocale` = `null`): string|false

Возвращает соответствующим образом локализованное имя языка для заданной локали. Если `null`, то будет использована локаль по умолчанию.

### Список параметров

`locale`

  Локаль, для которой будет возвращено название языка

`displayLocale`

  Необязательный параметр, задающий локаль, в которой надо будет отобразить название

### Возвращаемые значения

Название языка для локали `locale` в формате, соответствующем локали `displayLocale` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `displayLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_get_display_language()

    <?php
    echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
    ?>

Результат выполнения приведённого примера:

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### Смотрите также

- locale_get_display_name() - Возвращает соответствующим образом локализованное имя локали
- locale_get_display_script() - Возвращает соответствующим образом локализованное название алфавита для заданной локали
- locale_get_display_region() - Возвращает соответствующим образом локализованное название региона для заданной локали
- locale_get_display_variant() - Возвращает соответствующим образом локализованное название варианта для заданной локали

# Locale::getDisplayName

# locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — Возвращает соответствующим образом локализованное имя локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

Процедурный стиль

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

Возвращает соответствующим образом локализованное имя локали. Если `locale` равно `null`, то будет использована локаль по умолчанию.

### Список параметров

`locale`

  Локаль.

`displayLocale`

  Необязательная локаль для форматирования

### Возвращаемые значения

Имя локали в формате локали `displayLocale` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `displayLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_get_display_name()

    <?php
    echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
    ?>

Результат выполнения приведённого примера:

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone;
    Slowenisch (Lateinisch, Italien, NEDIS)

### Смотрите также

- locale_get_display_language() - Возвращает соответствующим образом локализованное имя языка для заданной локали
- locale_get_display_script() - Возвращает соответствующим образом локализованное название алфавита для заданной локали
- locale_get_display_region() - Возвращает соответствующим образом локализованное название региона для заданной локали
- locale_get_display_variant() - Возвращает соответствующим образом локализованное название варианта для заданной локали

# Locale::getDisplayRegion

# locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — Возвращает соответствующим образом локализованное название региона для заданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

Процедурный стиль

function locale_get_display_region(string `$locale`, ?string `$displayLocale` = `null`): string|false

Возвращает соответствующим образом локализованное название региона для заданной локали. Если `null`, то будет использована локаль по умолчанию.

### Список параметров

`locale`

  Локаль.

`displayLocale`

  Необязательная локаль для форматирования

### Возвращаемые значения

Название региона для `locale` в формате локали `displayLocale` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `displayLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_get_display_region()

    <?php
    echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
    ?>

Результат выполнения приведённого примера:

    Italy;
    Italie;
    Italien

### Смотрите также

- locale_get_display_name() - Возвращает соответствующим образом локализованное имя локали
- locale_get_display_language() - Возвращает соответствующим образом локализованное имя языка для заданной локали
- locale_get_display_script() - Возвращает соответствующим образом локализованное название алфавита для заданной локали
- locale_get_display_variant() - Возвращает соответствующим образом локализованное название варианта для заданной локали

# Locale::getDisplayScript

# locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — Возвращает соответствующим образом локализованное название алфавита для заданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

Процедурный стиль

function locale_get_display_script(string `$locale`, ?string `$displayLocale` = `null`): string|false

Возвращает соответствующим образом локализованное название алфавита для заданной локали. Если `null`, то будет использована локаль по умолчанию.

### Список параметров

`locale`

  Локаль.

`displayLocale`

  Необязательная локаль для форматирования

### Возвращаемые значения

Название алфавита для `locale` в формате локали `displayLocale` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `displayLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_get_display_script()

    <?php
    echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
    ?>

Результат выполнения приведённого примера:

    Latin;
    latin;
    Lateinisch

### Смотрите также

- locale_get_display_name() - Возвращает соответствующим образом локализованное имя локали
- locale_get_display_language() - Возвращает соответствующим образом локализованное имя языка для заданной локали
- locale_get_display_region() - Возвращает соответствующим образом локализованное название региона для заданной локали
- locale_get_display_variant() - Возвращает соответствующим образом локализованное название варианта для заданной локали

# Locale::getDisplayVariant

# locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — Возвращает соответствующим образом локализованное название варианта для заданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Процедурный стиль

function locale_get_display_variant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Возвращает соответствующим образом локализованное название варианта для заданной локали. Если `null`, то будет использована локаль по умолчанию.

### Список параметров

`locale`

  Локаль.

`displayLocale`

  Необязательная локаль для форматирования

### Возвращаемые значения

Название варианта для `locale` в формате локали `displayLocale` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `displayLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_get_display_variant()

    <?php
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
    ?>

Результат выполнения приведённого примера:

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### Смотрите также

- locale_get_display_name() - Возвращает соответствующим образом локализованное имя локали
- locale_get_display_language() - Возвращает соответствующим образом локализованное имя языка для заданной локали
- locale_get_display_script() - Возвращает соответствующим образом локализованное название алфавита для заданной локали
- locale_get_display_region() - Возвращает соответствующим образом локализованное название региона для заданной локали

# Locale::getKeywords

# locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — Получить ключевые слова для локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getKeywords(string `$locale`): array|false|null

Процедурный стиль

function locale_get_keywords(string `$locale`): array|false|null

Получает ключевые слова для локали.

### Список параметров

`locale`

  Локаль для извлечения ключевых слов

### Возвращаемые значения

Ассоциативный массив (array) с парами ключ-значение для заданной локали

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_get_keywords()

    <?php
    $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Результат выполнения приведённого примера:

    collation = PHONEBOOK
    currency = EUR

### Смотрите также

- locale_get_all_variants() - Получение вариантов из переданной локали

# Locale::getPrimaryLanguage

# locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — Получить первичный язык для локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

Процедурный стиль

function locale_get_primary_language(string `$locale`): ?string

Получает первичный язык для локали.

### Список параметров

`locale`

  Локаль для извлечения первичного языка

### Возвращаемые значения

Код языка, связанный с локалью.

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_get_primary_language()

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

Результат выполнения приведённого примера:

    zh

### Смотрите также

- locale_get_script() - Получить алфавит для локали
- locale_get_region() - Получить регион для локали
- locale_get_all_variants() - Получение вариантов из переданной локали

# Locale::getRegion

# locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — Получить регион для локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getRegion(string `$locale`): ?string

Процедурный стиль

function locale_get_region(string `$locale`): ?string

Получает регион для локали.

### Список параметров

`locale`

  Локаль для извлечения кода региона

### Возвращаемые значения

Код региона, связанный с локалью или `null`, если отсутствует.

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_get_region()

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

Результат выполнения приведённого примера:

    CH

### Смотрите также

- locale_get_primary_language() - Получить первичный язык для локали
- locale_get_script() - Получить алфавит для локали
- locale_get_all_variants() - Получение вариантов из переданной локали

# Locale::getScript

# locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — Получить алфавит для локали

### Описание

Объектно-ориентированный стиль

public static function Locale::getScript(string `$locale`): ?string

Процедурный стиль

function locale_get_script(string `$locale`): ?string

Получает алфавит для локали.

### Список параметров

`locale`

  Локаль для извлечения алфавита

### Возвращаемые значения

Алфавит, связанный с локалью или `null`, если отсутствует.

### Примеры

Пример #1 Пример использования locale_get_script()

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

Результат выполнения приведённого примера:

    Cyrl

### Смотрите также

- locale_get_primary_language() - Получить первичный язык для локали
- locale_get_region() - Получить регион для локали
- locale_get_all_variants() - Получение вариантов из переданной локали

# Locale::isRightToLeft

(No version information available, might only be in Git)

Locale::isRightToLeft — Проверяет, характерно ли для языка направление письма справа налево

### Описание

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

Метод определяет, характерна ли для языка система письма справа налево.

Метод работает на основе библиотеки ICU и проверяет направление по доминирующей системе письменности языка.

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

### Список параметров

`locale`
  Идентификатор набора региональных настроек. При передаче пустой строки проверяется язык региональных настроек по умолчанию.

### Возвращаемые значения

Метод возвращает `true`, если для языка характерна система письма справа налево, иначе возвращается `false`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили метод Locale::isRightToLeft().

### Примеры

Пример #1 Пример проверки направления письма

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

Результат выполнения приведённого примера:

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — Поиск языковых меток наиболее подходящих заданной локали

### Описание

Объектно-ориентированный стиль

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Процедурный стиль

function locale_lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Ищет элементы `languageTag`, наилучшим образом подходящие для диапазона языков, указанного в `locale`, в соответствии с алгоритмом поиска RFC 4647.

### Список параметров

`languageTag`

  Массив (array), содержащий список меток языков для сравнения с `locale`. Не более 100 элементов.

`locale`

  Локаль.

`canonicalize`

  Если `true`, то аргументы сперва будут приведены к каноническому виду.

`defaultLocale`

  Локаль по умолчанию, если совпадений не будет найдено.

### Возвращаемые значения

Наиболее подходящая данной локали метка языка.

Метод возвращает `null`, если длина параметра `locale` превышает значение константы `INTL_MAX_LOCALE_LEN`.

### Список изменений

Версия | Описание
--- | ---
7.4.0 | `defaultLocale` теперь допускает значение null.

### Примеры

Пример #1 Пример использования locale_lookup()

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Результат выполнения приведённого примера:

    de_de_1996

### Смотрите также

- locale_filter_matches() - Проверить, соответствует ли тег фильтра языка локали

# Locale::parseLocale

# locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — Получить ассоциативный массив всех подтегов локали

### Описание

Объектно-ориентированный стиль

public static function Locale::parseLocale(string `$locale`): ?array

Процедурный стиль

function locale_parse(string `$locale`): ?array

Возвращает ассоциативный массив, содержащий все подтеги заданной локали.

### Список параметров

`locale`

  Локаль из которой будут извлекаться подтеги. Обратите внимание: подтегов 'variant' и 'private' может быть не более 15, а подтегов 'extlang' не более 3.

### Возвращаемые значения

Возвращает ассоциативный массив, в котором ключами выступают имена подтегов, а значениями, соответственно, их значения. Подтеги будут отсортированы как подтеги идентификатора локали, т.е. если идентификатор содержит несколько вариантов '-varX-varY-varZ', то в массиве они будут располагаться так: variant0=>varX, variant1=>varY, variant2=>varZ

Возвращает `null` если длина параметра `locale` превышает `INTL_MAX_LOCALE_LEN`.

### Примеры

Пример #1 Пример использования locale_parse()

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Результат выполнения приведённого примера:

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### Смотрите также

- locale_compose() - Возвращает правильно упорядоченный и разделенный идентификатор локали

# Locale::setDefault

# locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — Устанавливает локаль по умолчанию во время исполнения

### Описание

Объектно-ориентированный стиль

public static function Locale::setDefault(string `$locale`): true

Процедурный стиль

function locale_set_default(string `$locale`): true

Функция устанавливает региональные настройки по умолчанию во время исполнения согласно аргументу `locale`. Функция изменяет значение глобальной опции 'default_locale'. Допускаются расширения UAX #35.

### Список параметров

`locale`

  Метка языка в виде стандартизированного кода BCP 47.

### Возвращаемые значения

Возвращает `true`.

### Примеры

Пример #1 Пример установки локали по умолчанию функцией locale_set_default()

    <?php

    locale_set_default('de-DE');
    echo locale_get_default();

    ?>

Пример #2 Пример установки локали по умолчанию в объектно-ориентированном стиле

    <?php

    Locale::setDefault('de-DE');
    echo Locale::getDefault();

    ?>

Результат выполнения приведённого примера:

    de-DE

### Смотрите также

- locale_get_default() - Получение значения локали INTL по умолчанию из опции 'default_locale'

## Содержание

- Locale::acceptFromHttp — Попытаться определить наилучшую локаль основываясь на заголовке HTTP "Accept-Language"
- Locale::canonicalize — Канонизировать строку локали
- Locale::composeLocale — Возвращает правильно упорядоченный и разделенный идентификатор локали
- Locale::filterMatches — Проверить, соответствует ли тег фильтра языка локали
- Locale::getAllVariants — Получение вариантов из переданной локали
- Locale::getDefault — Получение значения локали INTL по умолчанию из опции 'default_locale'
- Locale::getDisplayLanguage — Возвращает соответствующим образом локализованное имя языка для заданной локали
- Locale::getDisplayName — Возвращает соответствующим образом локализованное имя локали
- Locale::getDisplayRegion — Возвращает соответствующим образом локализованное название региона для заданной локали
- Locale::getDisplayScript — Возвращает соответствующим образом локализованное название алфавита для заданной локали
- Locale::getDisplayVariant — Возвращает соответствующим образом локализованное название варианта для заданной локали
- Locale::getKeywords — Получить ключевые слова для локали
- Locale::getPrimaryLanguage — Получить первичный язык для локали
- Locale::getRegion — Получить регион для локали
- Locale::getScript — Получить алфавит для локали
- Locale::isRightToLeft — Проверяет, характерно ли для языка направление письма справа налево
- Locale::lookup — Поиск языковых меток наиболее подходящих заданной локали
- Locale::parseLocale — Получить ассоциативный массив всех подтегов локали
- Locale::setDefault — Устанавливает локаль по умолчанию во время исполнения

# Класс Normalizer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

Нормализация — процесс преобразования символов и их последовательностей в формальное представление более низкого уровня. Этот процесс крайне важен при сравнении строк при сортировке или при поиске, но также используется при сохранении текста, чтобы быть уверенным в том, что он сохранился корректно.

Консорциум Unicode определил несколько форм нормализации, отражающих разные потребности приложений:

- Normalization Form D (NFD) — Каноническое разложение
- Normalization Form C (NFC) — Каноническое разложение с последующей канонической сборкой
- Normalization Form KD (NFKD) — Совместимое разложение
- Normalization Form KC (NFKC) — Совместимое разложение с последующей канонической сборкой

Различные формы задаются в требованиях наборов преобразований текста. Преобразования вычисляются с алгоритма и набора файлов данных.

## Обзор класса

class Normalizer {
/* Константы */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* Методы */
public static function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## Предопределённые константы

Константы устанавливают форму нормализации, которую использует нормализатор:

`Normalizer::FORM_C` int
  Форма нормализации C (NFC) — Каноническое разложение, после которого каноническая сборка
`Normalizer::FORM_D` int
  Форма нормализации D (NFD) — Каноническое разложение
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  Форма нормализации KC (NFKC) — Совместимое разложение, после которого каноническая сборка
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  Форма нормализации KD (NFKD) — Совместимое разложение
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## Смотрите также

- » Нормализация Unicode
- » Нормализация Unicode. FAQ
- » ICU Руководство пользователя — нормализация
- » ICU Описание API — нормализация

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.
8.0.0 | Константу `Normalizer::NONE` удалили.

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Извлекает свойство Decomposition_Mapping для заданного символа UTF-8

### Описание

Объектно-ориентированный стиль

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Процедурный стиль

function normalizer_get_raw_decomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Извлекает свойство Decomposition_Mapping, как определено в Unicode Character Database (UCD), для заданного символа UTF-8.

### Список параметров

`string`

  Строка, которая должна представлять из себя единичный символ в кодировке UTF-8.

### Возвращаемые значения

Возвращает строку (string), содержащую свойство Decomposition_Mapping, если оно присутствует в UCD.

Возвращает `null` если для символа отсутствует свойство Decomposition_Mapping.

### Примеры

Пример #1 Пример использования Normalizer::getRawDecomposition()

    <?php

    $result = "";
    $strings = [
        "a",
        "\u{FFDA}",
        "\u{FDFA}",
        "",
        "aa",
        "\xF5",
    ];

    foreach ($strings as $string) {
        $decomposition = Normalizer::getRawDecomposition($string);
        // $decomposition = normalizer_get_raw_decomposition($string); Процедурный стиль

        $error_code = intl_get_error_code();
        $error_message = intl_get_error_message();

        $string_hex = bin2hex($string);
        $result .= "---------------------\n";

        if ($decomposition === null) {
            $result .= "'$string_hex' не имеет соответствия декомпозиции\n" ;
        } else {
            $result .= "'$string_hex' имеет соответствие декомпозиции '" . bin2hex($decomposition) . "'\n" ;
        }

        $result .= "error info: '$error_message' ($error_code)\n";
    }

    echo $result;
    ?>

Результат выполнения приведённого примера:

    ---------------------
    '61' не имеет соответствия декомпозиции
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efbf9a' имеет соответствие декомпозиции 'e385a1'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efb7ba' имеет соответствие декомпозиции 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    '' не имеет соответствия декомпозиции
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    '6161' не имеет соответствия декомпозиции
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    'f5' не имеет соответствия декомпозиции
    error info: 'Code point out of range: U_ILLEGAL_ARGUMENT_ERROR' (1)

### Смотрите также

- Normalizer::normalize() - Нормализация строки
- Normalizer::isNormalized() - Проверить, соответствует ли переданная строка заданной форме нормализации

# Normalizer::isNormalized

# normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — Проверить, соответствует ли переданная строка заданной форме нормализации

### Описание

Объектно-ориентированный стиль

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Процедурный стиль

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Проверить, соответствует ли переданная строка заданной форме нормализации.

### Список параметров

`string`

  Проверяемая строка

`form`

  Одна из форм нормализации.

### Возвращаемые значения

`true` если нормализована и `false`, если нет или если произошла ошибка

### Примеры

Пример #1 Пример использования normalizer_is_normalized()

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Результат выполнения приведённого примера:

    not normalized; normalized

### Смотрите также

- normalizer_normalize() - Нормализация строки

# Normalizer::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — Нормализация строки

### Описание

Объектно-ориентированный стиль

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Процедурный стиль

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Нормализует переданную строку

### Список параметров

`string`

  Строка для нормализации

`form`

  Одна из форм нормализации

### Возвращаемые значения

Нормализованная строка или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования normalizer_normalize()

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Результат выполнения приведённого примера:

    %C3%85 %C3%85

### Смотрите также

- normalizer_is_normalized() - Проверить, соответствует ли переданная строка заданной форме нормализации

## Содержание

- Normalizer::getRawDecomposition — Извлекает свойство Decomposition_Mapping для заданного символа UTF-8
- Normalizer::isNormalized — Проверить, соответствует ли переданная строка заданной форме нормализации
- Normalizer::normalize — Нормализация строки

# Класс MessageFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

MessageFormatter - это класс, позволяющий создавать склеиваемые, независимые от языка сообщения. Методы этого класса используются для создания всех сообщений, показываемых пользователю.

Класс MessageFormatter собирает сообщение из разных фрагментов (таких как текст, числа и даты), поставляемых программой. Данный класс позволяет программе не задумываться о том, в каком порядке эти фрагменты надо склеивать. Класс использует спецификации форматирования для сборки этих фрагментов в сообщение, хранящееся в виде одной строки в хранилище ресурсов. К примеру, MessageFormatter позволит напечатать фразу "Finished printing x out of y files..." таким образом, чтобы обеспечить гибкость перевода.

Ранее сообщение для конечного пользователя создавалось как законченная фраза и обрабатывалась как строка. Такая процедура приводила к проблемам локализации, поскольку структура фразы, порядок слов, формат чисел и прочее сильно отличались в разных языках. Нейтральная к языку процедура создания сообщений держит каждую часть сообщения отдельно и предоставляет ключи к данным. Используя эти ключи, класс MessageFormatter может склеивать части сообщения, преобразовывать их в соответствии с локалью и отображать в виде грамотного сообщения конечному пользователю.

MessageFormatter берет набор объектов, форматирует их и вставляет в шаблон в нужных местах. Совместно с MessageFormatter полезно использовать средства форматирования выбора (choice formatter) для обработки множественного/единственного числа, сравнения чисел и выбора из массива элементов. Обычно формат сообщения берётся из ресурсов, а аргументы передаются во время выполнения.

## Обзор класса

class MessageFormatter {
/* Методы */
public function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## Смотрите также

- » ICU. Документация по форматированию.
- » ICU. Описание форматирования сообщений.
- » ICU. Средства форматирования сообщений
- » ICU. Средства форматирования выбора

# MessageFormatter::create

# MessageFormatter::__construct

# msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Создаёт средство форматирования сообщений

### Описание

Объектно-ориентированный стиль (метод)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

Объектно-ориентированный стиль (конструктор):

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

Процедурный стиль

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Создаёт средство форматирования сообщений.

### Список параметров

`locale`

  Локаль, используемая при форматировании аргументов

`pattern`

  Строка (string) шаблона для вставки аргументов. В шаблоне используется "дружественный к апострофам" синтаксис; подробнее смотрите в разделе » Quoting/Escaping.

### Возвращаемые значения

Объект MessageFormatter или `null` в случае возникновения ошибки.

### Ошибки

При вызове в качестве конструктора в случае возникновения ошибки выбрасывается исключение IntlException.

### Примеры

Пример #1 Пример использования msgfmt_create()

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

Результат выполнения приведённого примера:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Смотрите также

- msgfmt_format() - Форматирует сообщение
- msgfmt_parse() - Разбирает строку согласно шаблону
- msgfmt_get_error_code() - Возвращает код ошибки последней операции
- msgfmt_get_error_message() - Возвращает текст ошибки последней операции

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — Форматирует сообщение

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::format(array `$values`): string|false

Процедурный стиль

function msgfmt_format(MessageFormatter `$formatter`, array `$values`): string|false

Форматирует сообщение, подставляя данные в строку формата в соответствии с правилами локали.

### Список параметров

`formatter`

  Объект MessageFormatter

`values`

  Аргументы для вставки в строку формата

### Возвращаемые значения

Отформатированная строка или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования msgfmt_format()

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

Результат выполнения приведённого примера:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_parse() - Разбирает строку согласно шаблону
- msgfmt_format_message() - Быстро форматирует сообщение
- msgfmt_get_error_code() - Возвращает код ошибки последней операции
- msgfmt_get_error_message() - Возвращает текст ошибки последней операции

# MessageFormatter::formatMessage

# msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — Быстро форматирует сообщение

### Описание

Объектно-ориентированный стиль

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

Процедурный стиль

function msgfmt_format_message(string `$locale`, string `$pattern`, array `$values`): string|false

Функция быстрого форматирования, которая форматирует строку без необходимости явно создавать объект форматирования. Используйте эту функцию, когда операция форматирования выполняется только один раз и не требует сохранения параметров или состояния, а также когда необходимо настроить вывод, предоставив дополнительный контекст непосредственно для ICU.

### Список параметров

`locale`

  Локаль, используемая для форматирования частей, зависящих от локали

`pattern`

  Строка (string) шаблона для вставки аргументов. В шаблоне используется "дружественный к апострофам" синтаксис; подробнее смотрите в разделе » Quoting/Escaping.

`values`

  Массив значений (array) для вставки в строку формата (string).

### Возвращаемые значения

Строка отформатированного шаблона или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования msgfmt_format_message()

    <?php
    echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo msgfmt_format_message("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo MessageFormatter::formatMessage("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";
    ?>

Результат выполнения приведённого примера:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
    You finished 3rd!
    There are no apples

Пример #3 Пример использования ICU для форматирования валюты с общим и с узким символом валюты

Requires ICU ≥ 67.

    <?php
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

Результат выполнения приведённого примера:

    123,45 CA$
    123,45 $

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_parse() - Разбирает строку согласно шаблону
- msgfmt_get_error_code() - Возвращает код ошибки последней операции
- msgfmt_get_error_message() - Возвращает текст ошибки последней операции

# MessageFormatter::getErrorCode

# msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — Возвращает код ошибки последней операции

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::getErrorCode(): int

Процедурный стиль

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Возвращает код ошибки последней операции.

### Список параметров

`formatter`

  Объект MessageFormatter

### Возвращаемые значения

Код ошибки, одно из значений UErrorCode. Начальное значение - U_ZERO_ERROR.

### Смотрите также

- msgfmt_get_error_message() - Возвращает текст ошибки последней операции
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# MessageFormatter::getErrorMessage

# msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Возвращает текст ошибки последней операции

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::getErrorMessage(): string

Процедурный стиль

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Возвращает текст ошибки последней операции.

### Список параметров

`formatter`

  Объект MessageFormatter

### Возвращаемые значения

Описание последней ошибки.

### Примеры

Пример #1 Пример использования msgfmt_get_error_message()

    <?php
    $fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
    $str = msgfmt_format($fmt, array());
    if(!$str) {
        echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
    }
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
    $str = $fmt->format(array());
    if(!$str) {
        echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
    }
    ?>

Результат выполнения приведённого примера:

    ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### Смотрите также

- msgfmt_get_error_code() - Возвращает код ошибки последней операции
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# MessageFormatter::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — Возвращает локаль, для которой было создано средство форматирования

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::getLocale(): string

Процедурный стиль

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Возвращает локаль, для которой было создано средство форматирования.

### Список параметров

`formatter`

  Объект MessageFormatter

### Возвращаемые значения

Имя локали.

### Примеры

Пример #1 Пример использования msgfmt_get_locale()

    <?php
    $fmt = msgfmt_create('en_US', "Number {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter('en_US', "Number {0,number}");
    echo $fmt->getLocale();
    ?>

Результат выполнения приведённого примера:

    en_US

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений

# MessageFormatter::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — Возвращает шаблон, используемый средством форматирования

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::getPattern(): string|false

Процедурный стиль

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Возвращает шаблон, используемый средством форматирования.

### Список параметров

`formatter`

  Объект MessageFormatter

### Возвращаемые значения

Строка (string) шаблона для данного средства форматирования сообщения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования msgfmt_get_pattern()

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
    ?>

Результат выполнения приведённого примера:

    Default pattern: '{0,number} monkeys on {1,number} trees'
    Formatting result: 123 monkeys on 456 trees
    New pattern: '{0,number} trees hosting {1,number} monkeys'
    Formatted number: 123 trees hosting 456 monkeys

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_set_pattern() - Устанавливает шаблон, используемый средством форматирования

# MessageFormatter::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — Разбирает строку согласно шаблону

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::parse(string `$string`): array|false

Процедурный стиль

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Разбирает входную строку (string) и возвращает все извлечённые элементы в виде массива (array).

### Список параметров

`formatter`

  Объект MessageFormatter.

`string`

  Строка (string) для разбора.

### Возвращаемые значения

Массив (array), содержащий извлечённые элементы или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования msgfmt_parse()

    <?php
    $fmt = msgfmt_create('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = msgfmt_parse($fmt, "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = msgfmt_create('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = $fmt->parse("4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = new MessageFormatter('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

Результат выполнения приведённого примера:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_format() - Форматирует сообщение
- msgfmt_parse_message() - Быстро разбирает входную строку

# MessageFormatter::parseMessage

# msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — Быстро разбирает входную строку

### Описание

Объектно-ориентированный стиль

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

Процедурный стиль

function msgfmt_parse_message(string `$locale`, string `$pattern`, string `$message`): array|false

Разбирает входную строку без явного создания объекта форматирования. Используйте эту функцию, когда операция форматирования выполняется только один раз и не требует сохранения параметров или состояния.

### Список параметров

`locale`

  Локаль, используемая для разбора частей, зависящих от локали

`pattern`

  Шаблон, использующийся для разбора `message`.

`message`

  Строка (string) для разбора, соответствующая `pattern`.

### Возвращаемые значения

Массив (array), содержащий извлечённые элементы или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования msgfmt_parse_message()

    <?php
    $fmt = msgfmt_parse_message('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = msgfmt_parse_message('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Результат выполнения приведённого примера:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_format_message() - Быстро форматирует сообщение
- msgfmt_parse() - Разбирает строку согласно шаблону

# MessageFormatter::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — Устанавливает шаблон, используемый средством форматирования

### Описание

Объектно-ориентированный стиль

public function MessageFormatter::setPattern(string `$pattern`): bool

Процедурный стиль

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Устанавливает шаблон, используемый средством форматирования.

### Список параметров

`formatter`

  Объект MessageFormatter

`pattern`

  Строка (string) шаблона для использования в этом средстве форматирования сообщения. В шаблоне используется "дружественный к апострофам" синтаксис; подробнее смотрите в разделе » Quoting/Escaping.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования msgfmt_set_pattern()

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
    ?>

Результат выполнения приведённого примера:

    Default pattern: '{0,number} monkeys on {1,number} trees'
    Formatting result: 123 monkeys on 456 trees
    New pattern: '{0,number} trees hosting {1,number} monkeys'
    Formatted number: 123 trees hosting 456 monkeys

### Смотрите также

- msgfmt_create() - Создаёт средство форматирования сообщений
- msgfmt_get_pattern() - Возвращает шаблон, используемый средством форматирования

## Содержание

- MessageFormatter::create — Создаёт средство форматирования сообщений
- MessageFormatter::format — Форматирует сообщение
- MessageFormatter::formatMessage — Быстро форматирует сообщение
- MessageFormatter::getErrorCode — Возвращает код ошибки последней операции
- MessageFormatter::getErrorMessage — Возвращает текст ошибки последней операции
- MessageFormatter::getLocale — Возвращает локаль, для которой было создано средство форматирования
- MessageFormatter::getPattern — Возвращает шаблон, используемый средством форматирования
- MessageFormatter::parse — Разбирает строку согласно шаблону
- MessageFormatter::parseMessage — Быстро разбирает входную строку
- MessageFormatter::setPattern — Устанавливает шаблон, используемый средством форматирования

# Класс IntlCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Введение

## Обзор класса

class IntlCalendar {
/* Константы */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* Методы */
private function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## Предопределённые константы

`IntlCalendar::FIELD_ERA` int

  Поле календаря численно представляет эпоху, например `1` для «от рождества Христова» и `0` для «до рождества Христова» в Григорианском и Юлианском календарях и `235` для периода Хэйсэй (平成) в Японском календаре. Не все календари имеют больше одной эпохи.

`IntlCalendar::FIELD_YEAR` int

  Поле календаря для года. Не уникально в контексте нескольких эпох. Обычно минимальное значение этого поля равно `1`, если календарь содержит больше одной эры.

`IntlCalendar::FIELD_MONTH` int

  Поле календаря для месяца. Последовательность месяцев начинается с нуля, следовательно Janurary (январь) (здесь используется для обозначения первого месяца года, но по фактически иногда бывает совсем другое имя, например Muharram для Исламского календаря) будет представлен числом `0`, February (Февраль) числом `1`, …, December (декабрь) числом `11` и, для отдельных календарей, 13-й или високосный месяц, значение будет равно `12`.

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  Поле календаря для номера недели в году. Зависит от того, с какого дня начинается неделя и минимального количества дней в неделе.

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  Поле календаря для номера недели в месяце. Зависит от того, с какого дня начинается неделя и минимального количества дней в неделе.

`IntlCalendar::FIELD_DATE` int

  Поле календаря для номера дня в месяце. То же, что и константа `IntlCalendar::FIELD_DAY_OF_MONTH`.

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  Поле календаря для номера дня в году. Для Грегорианского календаря начинается с `1` и заканчивается на `365` или `366`.

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  Поле календаря для номера дня в неделе. Начинается с `1` (воскресенье, смотрите описание константы `IntlCalendar::DOW_SUNDAY` и связанные константы) и заканчивается 7 (суббота).

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  Номер дня недели (воскресенье, понедельник, …) в месяце. Допустим это значение равно `1`, а значение дня недели равно `2` (понедельник), следовательно, это первый понедельник месяца. Максимальное значение равно `5`.

  Также допустимы значения `0` и ниже (отрицательные). Значение `0` охватывает 7 дней непосредственно перед началом месяца (первый подходящий день в месяце имеет значение `1`). Отрицательные значения отсчитываются от конца месяца. Так, значение `-1` указывает на последний подходящий день месяца, `-2` на второй с конца и т. д.

  В отличие от констант `IntlCalendar::FIELD_WEEK_OF_MONTH` и `IntlCalendar::FIELD_WEEK_OF_YEAR`, это значение не зависит от методов IntlCalendar::getFirstDayOfWeek() и IntlCalendar::getMinimalDaysInFirstWeek(). Первая среда — это первая среда, даже если неделя началась в предыдущем месяце.

`IntlCalendar::FIELD_AM_PM` int

  Поле календаря, которое определяет время до или после полудня. Соответственно `0` — до полудня, (`1`) — после. Полночь считается как «до полудня», полдень как «после полудня».

`IntlCalendar::FIELD_HOUR` int

  Поле календаря для часов, без указания до или после полудня. Допускаются значения в интервале от `0` до `11`.

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  Поле календаря для полных (24-часовой формат) часов. Допускаются значения от `0` до `23`.

`IntlCalendar::FIELD_MINUTE` int

  Поле календаря для минут.

`IntlCalendar::FIELD_SECOND` int

  Поле календаря для секунд.

`IntlCalendar::FIELD_MILLISECOND` int

  Поле календаря для миллисекунд.

`IntlCalendar::FIELD_ZONE_OFFSET` int

  Поле календаря для «сырого» смещения часового пояса, в миллисекундах. «Сырое» смещение не учитывает переходы на летнее и зимнее время.

`IntlCalendar::FIELD_DST_OFFSET` int

  Поле календаря для смещения часового пояса в миллисекундах в зависимости от летнего или зимнего времени, если применимо к данному часовому поясу.

`IntlCalendar::FIELD_YEAR_WOY` int

  Поле календаря, которое представляет год для недели года.

`IntlCalendar::FIELD_DOW_LOCAL` int

  Поле календаря для локализованного дня недели. Принимает значения в диапазоне от `1` до `7`. Значение `1` используется для дня недели, который соответствует значению, которое возвращает метод IntlCalendar::getFirstDayOfWeek().

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  Поле календаря для представления номера года в контексте обеспечения непрерывности между эпохами. Например, для Грегорианского календаря это значение для эпохи «после рождества Христова» будет соответствовать константе `IntlCalendar::FIELD_YEAR`, а для эпохи «до рождества Христова» год `y` будет представлен как `-y + 1`.

`IntlCalendar::FIELD_JULIAN_DAY` int

  Поле календаря для модифицированных номеров дней Юлианского календаря. В отличие от стандартного Юлианского календаря, в нём переход происходит в полночь по локальному времени, а не в полдень по времени UTC. Он однозначно идентифицирует дату.

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  Поле календаря, которое охватывает `IntlCalendar::FIELD_HOUR_OF_DAY`, `IntlCalendar::FIELD_MINUTE`, `IntlCalendar::FIELD_SECOND` и `IntlCalendar::FIELD_MILLISECOND`. Находится в диапазоне от `0` до `24 * 3600 * 1000 - 1`. Это не количество миллисекунд, которое прошло с полуночи, поскольку в моменты перехода на летнее или зимнее время будет иметь разрывы.

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  Поле календаря, которое принимает значение `1` для високосного месяца и `0` для обычного.

`IntlCalendar::FIELD_FIELD_COUNT` int

  Общее количество полей.

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  Псевдоним константы `IntlCalendar::FIELD_DATE`.

`IntlCalendar::DOW_SUNDAY` int

  Воскресенье.

`IntlCalendar::DOW_MONDAY` int

  Понедельник.

`IntlCalendar::DOW_TUESDAY` int

  Вторник.

`IntlCalendar::DOW_WEDNESDAY` int

  Среда.

`IntlCalendar::DOW_THURSDAY` int

  Четверг.

`IntlCalendar::DOW_FRIDAY` int

  Пятница.

`IntlCalendar::DOW_SATURDAY` int

  Суббота.

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  Вывод метода IntlCalendar::getDayOfWeekType() означает, что день — будний.

`IntlCalendar::DOW_TYPE_WEEKEND` int

  Вывод метода IntlCalendar::getDayOfWeekType() означает, что день — выходной.

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  Вывод IntlCalendar::getDayOfWeekType() означает, что выходные начинаются в этот день.

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  Вывод метода IntlCalendar::getDayOfWeekType() означает, что выходные заканчиваются в этот день.

`IntlCalendar::WALLTIME_FIRST` int

  Вывод метода IntlCalendar::getSkippedWallTimeOption() означает, что время в пропущенном диапазоне должно ссылаться на момент времени меньший на один час, а вывод метода IntlCalendar::getRepeatedWallTimeOption() означает, что время в повторяемом диапазоне должно относиться к моменту первого появления такого времени.

`IntlCalendar::WALLTIME_LAST` int

  Вывод метода IntlCalendar::getSkippedWallTimeOption() означает, что время в пропущенном диапазоне должно ссылаться на момент времени больший на один час, а вывод метода IntlCalendar::getRepeatedWallTimeOption() означает, что время в повторяемом диапазоне должно относиться к моменту второго появления такого времени.

`IntlCalendar::WALLTIME_NEXT_VALID` int

  Вывод метода IntlCalendar::getSkippedWallTimeOption() означает, что время в пропущенном диапазоне относится к моменту, когда случился переход на зимнее или летнее время.

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — Добавляет количество (со знаком) времени в поле

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::add(int `$field`, int `$value`): bool

Процедурный стиль

function intlcal_add(IntlCalendar `$calendar`, int `$field`, int `$value`): bool

Добавляет количество со знаком в поле. Добавление положительной суммы позволяет продвигаться во времени, даже если числовое значение поля уменьшается (например, при работе с годами до нашей эры).

Другие поля могут нуждаться в корректировке, например, добавление месяца к 31 января приведёт к 28 (или 29) февраля. В отличие от IntlCalendar::roll(), когда значение оборачивается, более важные поля могут измениться. Например, добавление 1 дня к 31 января приведёт к 1 февраля, а не к 1 января.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

`value`

  Количество со знаком, добавляемое к текущему полю. Если сумма положительная, момент времени будет перемещён вперёд; если он отрицательный, момент времени будет перемещён в прошлое. Единица неявно связана с типом поля. Например, часы для `IntlCalendar::FIELD_HOUR_OF_DAY`.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::add()

    <?php
    ini_set('intl.default_locale', 'fr_FR');
    ini_set('date.timezone', 'UTC');

    $cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

Результат выполнения приведённого примера:

    31 janv. 2012 00:00:00
    29 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — Определяет, время этого объекта позже времени переданного объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::after(IntlCalendar `$other`): bool

Процедурный стиль

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Возвращает, соответствует ли время этого объекта времени аргумента.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`other`

  Календарь, время которого будет сравниваться со временем основного объекта.

### Возвращаемые значения

Возвращает `true`, если текущее время этого объекта позже времени аргумента `calendar`. В противном случае возвращает `false`.

Если возникла ошибка, также возвращается `false`. Для обнаружения условий ошибки вызывают функцию intl_get_error_code() или настраивают выбрасывание исключений в Intl.

### Примеры

Пример #1 Пример использования IntlCalendar::after()

    <?php
    $cal1 = IntlCalendar::createInstance();
    $cal2 = clone $cal1;

    var_dump($cal1->after($cal2), //false
            $cal2->after($cal1)); //false

    $cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

    var_dump($cal1->after($cal2), //true
            $cal2->after($cal1)); //false

# IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — Определяет, время этого объекта раньше времени переданного объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::before(IntlCalendar `$other`): bool

Процедурный стиль

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Возвращает, предшествует ли время этого объекта времени аргумента.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`other`

  Календарь, время которого будет сравниваться со временем основного объекта.

### Возвращаемые значения

Возвращает `true`, если текущее время этого объекта раньше времени аргумента `calendar`. В противном случае возвращает `false`.

Если возникла ошибка, также возвращается `false`. Для обнаружения условий ошибки вызывают функцию intl_get_error_code() или настраивают выбрасывание исключений в Intl.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Очищает поле или все поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::clear(?int `$field` = `null`): true

Процедурный стиль

function intlcal_clear(IntlCalendar `$calendar`, ?int `$field` = `null`): true

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

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Пример #1 Пример использования IntlCalendar::clear()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'UTC');

    $fields = array(
        'FIELD_ERA'                  => 0,
        'FIELD_YEAR'                 => 1,
        'FIELD_MONTH'                => 2,
        'FIELD_WEEK_OF_YEAR'         => 3,
        'FIELD_WEEK_OF_MONTH'        => 4,
        'FIELD_DATE'                 => 5,
        'FIELD_DAY_OF_YEAR'          => 6,
        'FIELD_DAY_OF_WEEK'          => 7,
        'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
        'FIELD_AM_PM'                => 9,
        'FIELD_HOUR'                 => 10,
        'FIELD_HOUR_OF_DAY'          => 11,
        'FIELD_MINUTE'               => 12,
        'FIELD_SECOND'               => 13,
        'FIELD_MILLISECOND'          => 14,
        'FIELD_ZONE_OFFSET'          => 15,
        'FIELD_DST_OFFSET'           => 16,
        'FIELD_YEAR_WOY'             => 17,
        'FIELD_DOW_LOCAL'            => 18,
        'FIELD_EXTENDED_YEAR'        => 19,
        'FIELD_JULIAN_DAY'           => 20,
        'FIELD_MILLISECONDS_IN_DAY'  => 21,
        'FIELD_IS_LEAP_MONTH'        => 22,
        'FIELD_FIELD_COUNT'          => 23,
    );
    function getSetFields(IntlCalendar $cal) {
        global $fields;
        $ret = array();
        foreach ($fields as $name => $value) {
            if ($cal->isSet($value)) {
                $ret[] = $name;
            }
        }
        return $ret;
    }

    $cal = new IntlGregorianCalendar(2013, 2 /* Март */, 15);
    echo "После создания григорианского календаря\n";
    print_r(getSetFields($cal));
    echo "\n";

    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "После того, как средство форматирования запросило поле EXTENDED_YEAR\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear(IntlCalendar::FIELD_YEAR);
    echo "После того, как год будет очищен, дата останется прежней\n";
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "Потому что FIELD_EXTENDED_YEAR все ещё установлен\n";
    print_r(getSetFields($cal));
    echo "\n";

    var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
    echo "После того, как поле EXTENDED_YEAR было очищено\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "\n";

    echo "После пересчёта полей,\n"
            . " снова установлено поле EXTENDED_YEAR (до 1970 г.)\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear();
    echo "После вызова варианта без аргументов\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";

Результат выполнения приведённого примера:

    После создания григорианского календаря
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
    )

    15/03/2013 00:00:00
    После того, как средство форматирования запросило поле EXTENDED_YEAR
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
        [4] => FIELD_EXTENDED_YEAR
    )

    После того, как год будет очищен, дата останется прежней
    15/03/2013 00:00:00
    Потому что FIELD_EXTENDED_YEAR все ещё установлен
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    bool(true)
    После того, как поле EXTENDED_YEAR было очищено
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
    )
    15/03/1970 00:00:00

    После пересчёта полей,
     снова установлено поле EXTENDED_YEAR (до 1970 г.)
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    После вызова варианта без аргументов
    Array
    (
    )
    01/01/1970 00:00:00

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — Закрытый конструктор для запрета создания экземпляров

### Описание

private function IntlCalendar::__construct()

Закрытый конструктор для запрета создания экземпляров с помощью оператора new.

Вместо этого используйте метод IntlCalendar::createInstance().

### Список параметров

Сигнатура функции не содержит параметров.

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Создаёт новый объект IntlCalendar

### Описание

Объектно-ориентированный стиль

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Процедурный стиль

function intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Учитывая часовой пояс и языковой стандарт, метод создаёт объект IntlCalendar. Этот фабричный метод может возвращать дочерний класс IntlCalendar.

Созданный календарь будет представлять момент времени, в который он был создан, на основе системного времени. Все поля можно очистить, вызвав IntCalendar::clear() без аргументов. Смотрите также IntlGregorianCalendar::__construct().

### Список параметров

`timezone`

  Часовой пояс для использования.

  - Если `null`, то будет использован часовой пояс по умолчанию, заданная в ini-настройки date.timezone либо с помощью функции date_default_timezone_set() и возвращённая функцией date_default_timezone_get().

  - Объект класса IntlTimeZone.

  - Объект класса DateTimeZone. Его идентификатор будет извлечён и на его основе будет создан объект часового пояса ICU; часовой пояс будет сохранён в базе данных ICU, а не PHP.

  - Строка, являющаяся корректным идентификатором часового пояса ICU. Смотрите IntlTimeZone::createTimeZoneIDEnumeration(). "Сырые" смещения, типа `"GMT+08:30"`, также поддерживаются.

`locale`

  Используемый языковой стандарт или значение `null` для использования языкового стандарта по умолчанию.

### Возвращаемые значения

Созданный экземпляр IntlCalendar или `null` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::createInstance()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'Europe/Madrid');

    $cal = IntlCalendar::createInstance();
    echo "Без аргументов\n";
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Явное указание часового пояса\n";
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Явное указание языкового стандарта (с календарём)\n";
    $cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

Результат выполнения приведённого примера:

    Без аргументов
    string(21) "IntlGregorianCalendar"
    string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

    Явное указание часового пояса
    string(21) "IntlGregorianCalendar"
    string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

    Явное указание языкового стандарта (с календарём)
    string(12) "IntlCalendar"
    string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

### Смотрите также

- IntlGregorianCalendar::__construct() - Конструктор класса григорианского календаря

# IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — Сравнивает время двух объектов IntlCalendar на предмет равенства

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::equals(IntlCalendar `$other`): bool

Процедурный стиль

function intlcal_equals(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Возвращает true, если у обоих календарей одно и то же время. Настройки, типы календаря и состояния полей не обязательно должны совпадать.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`other`

  Календарь для сравнения с основным объектом.

### Возвращаемые значения

Возвращает `true`, если текущее время этого и переданного в IntlCalendar объекта одинаковое или `false` в противном случае.

Если возникла ошибка, также возвращается `false`. Для обнаружения условий ошибки вызывают функцию intl_get_error_code() или настраивают выбрасывание исключений в Intl.

### Примеры

Пример #1 Пример использования IntlCalendar::equals()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    $cal2 = clone $cal1;

    var_dump($cal1->equals($cal2)); //TRUE

    // Языковой стандарт не включён в сравнение
    $cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    // И состояние установленных полей также не включено
    $cal2->clear(IntlCalendar::FIELD_YEAR);
    var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
            $cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
    var_dump($cal1->equals($cal2)); //TRUE

    // И тип календаря
    $cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    // Только время
    $cal2 = clone $cal1;
    $cal2->setTime($cal1->getTime() + 1.);
    var_dump($cal1->equals($cal2)); //FALSE

# IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Вычисляет разницу между заданным временем и временем объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

Процедурный стиль

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

Возвращает разницу между заданным временем и временем, установленным для объекта, относительно количества, указанного в параметре `field`.

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

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`timestamp`

  Время, с которым сравнивается количество, представленное `field`. Чтобы результат был положительным, время, указанное в этом параметре, должно опережать время объекта, для которого вызывается метод.

`field`

  Поле, представляющее сравниваемое количество.

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Возвращает разность времени (со знаком) в единицах измерения, связанных с указанным полем или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::fieldDifference()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
    $cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
    $time = $cal2->getTime();

    echo "Время до: ", IntlDateFormatter::formatObject($cal1), "\n";

    printf(
        "Разница во времени: %d год(лет), %d месяц(ев), "
      . "%d день(дней), %d час(ов) и %d минуту(минут)\n",
        $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
    );

    // теперь оно было продвинуто к целевому времени, за исключением секунд,
    // для которых мы не измеряли разницу
    echo "Время после: ", IntlDateFormatter::formatObject($cal1), "\n";

Результат выполнения приведённого примера:

    Время до: 29 févr. 2012 09:00:11
    Разница во времени: 1 год(лет), 0 месяц(ев), 1 день(дней), 0 час(ов) and 19 минуту(минут)
    Время после: 1 mars 2013 09:19:11

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Создаёт объект IntlCalendar из объекта DateTime или строки

### Описание

Объектно-ориентированный стиль

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Процедурный стиль

function intlcal_from_date_time(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Метод создаёт объект IntlCalendar либо из объекта DateTime, либо из строки, из которой возможно создать объект DateTime.

Новый календарь представит тот же момент времени, который представляет объект DateTime, с возможной потерей точности для дат, для которых недостаточно исторических данных, или дат за пределами диапазона точного представления времени, и тот же часовой пояс с возможным расхождением в системах с разными базами данных часовых поясов.

### Список параметров

`datetime`

  Объект DateTime или строка (string, которую возможно передать в метод DateTime::__construct().

### Возвращаемые значения

Функция возвращает объект IntlCalendar или значение `null`, если возникла ошибка. При передаче в первый параметр значения string каждое исключение, которое возникнет внутри конструктора класса DateTime, всплывает по стеку вызовов.

### Примеры

Пример #1 Пример создания календаря из даты и времени методом IntlCalendar::fromDateTime()

    <?php

    ini_set('date.timezone', 'Europe/Lisbon');

    // Присваивание аналогично вызову IntlCalendar::fromDateTime(new DateTime(...))
    $cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');

    // Обратите внимание, что для календаря указали часовой пояс Europe/Berlin,
    // а не Europe/Lisbon, который установили как пояс по умолчанию
    echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

    ?>

Результат выполнения приведённого примера:

    2013 Februar 28 00:01:02 Deutschland Zeit

# IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — Получает значение поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::get(int `$field`): int|false

Процедурный стиль

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Получает значение определённого поля.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число со значением поля времени.

### Примеры

Пример #1 Пример использования IntlCalendar::get()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $class = new ReflectionClass('IntlCalendar');
    $fields = array();
    foreach ($class->getConstants() as $name => $val) {
        if (strpos($name, 'FIELD_') !== 0 || $val > 22)
            continue;
        $fields[$val] = $name;
    }

    $cal = IntlCalendar::createInstance(); // current time
    var_dump(IntlDateFormatter::formatObject($cal));
    foreach ($fields as $val => $name) {
        echo "$val ($name)", "\n    ", $cal->get($val), "\n";
    }

Результат выполнения приведённого примера:

    string(23) "Jul 1, 2013, 4:44:44 AM"
    0 (FIELD_ERA)
        1
    1 (FIELD_YEAR)
        2013
    2 (FIELD_MONTH)
        6
    3 (FIELD_WEEK_OF_YEAR)
        27
    4 (FIELD_WEEK_OF_MONTH)
        1
    5 (FIELD_DAY_OF_MONTH)
        1
    6 (FIELD_DAY_OF_YEAR)
        182
    7 (FIELD_DAY_OF_WEEK)
        2
    8 (FIELD_DAY_OF_WEEK_IN_MONTH)
        1
    9 (FIELD_AM_PM)
        0
    10 (FIELD_HOUR)
        4
    11 (FIELD_HOUR_OF_DAY)
        4
    12 (FIELD_MINUTE)
        44
    13 (FIELD_SECOND)
        44
    14 (FIELD_MILLISECOND)
        551
    15 (FIELD_ZONE_OFFSET)
        0
    16 (FIELD_DST_OFFSET)
        3600000
    17 (FIELD_YEAR_WOY)
        2013
    18 (FIELD_DOW_LOCAL)
        2
    19 (FIELD_EXTENDED_YEAR)
        2013
    20 (FIELD_JULIAN_DAY)
        2456475
    21 (FIELD_MILLISECONDS_IN_DAY)
        17084551
    22 (FIELD_IS_LEAP_MONTH)
        0

# IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — Максимальное значение для поля с учётом текущего времени объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getActualMaximum(int `$field`): int|false

Процедурный стиль

function intlcal_get_actual_maximum(IntlCalendar `$calendar`, int `$field`): int|false

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

Например, в григорианском календаре фактическое максимальное значение для дня месяца будет варьироваться от `28` до `31`, в зависимости от месяца и года текущего времени.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число (int), представляющее максимальное значение в единицах измерения, связанное с данным `field` или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getActualMaximum()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = IntlCalendar::fromDateTime('2013-02-15');
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

    $cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

Результат выполнения приведённого примера:

    int(28)
    int(29)

### Смотрите также

- IntlCalendar::getMaximum() - Получает глобальное максимальное значение поля
- IntlCalendar::getLeastMaximum() - Получает наименьший локальный максимум поля
- IntlCalendar::getActualMinimum() - Минимальное значение для поля с учётом текущего времени объекта

# IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — Минимальное значение для поля с учётом текущего времени объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getActualMinimum(int `$field`): int|false

Процедурный стиль

function intlcal_get_actual_minimum(IntlCalendar `$calendar`, int `$field`): int|false

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

Для григорианского календаря это всегда то же самое, что и IntlCalendar::getMinimum().

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число (int), представляющее значение поля или `false`, если возникла ошибка.

### Смотрите также

- IntlCalendar::getMinimum() - Получает глобальное минимальное значение поля
- IntlCalendar::getGreatestMinimum() - Получает наибольшее локальное минимальное значение поля
- IntlCalendar::getActualMaximum() - Максимальное значение для поля с учётом текущего времени объекта

# IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Получает массив языковых стандартов, для которых есть данные

### Описание

Объектно-ориентированный стиль

public static function IntlCalendar::getAvailableLocales(): array

Процедурный стиль

function intlcal_get_available_locales(): array

Предоставляет список языковых стандартов, для которых установлены календари. Начиная с ICU 51, это список всех установленных языковых стандартов ICU.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив (array) строк (string), каждая из которых соответствует языковому стандарту.

### Примеры

Пример #1 Пример использования IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

Результат выполнения приведённого примера:

    Array
    (
        [0] => af
        [1] => af_NA
        [2] => af_ZA
        [3] => agq
        [4] => agq_CM
        [5] => ak
        [6] => ak_GH
        [7] => am
        [8] => am_ET
        [9] => ar
        [10] => ar_001
        [11] => ar_AE
        [12] => ar_BH
        [13] => ar_DJ
        … output abbreviated …
        [595] => zh_Hant_HK
        [596] => zh_Hant_MO
        [597] => zh_Hant_TW
        [598] => zu
        [599] => zu_ZA
    )

# IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Сообщает, является ли день будним, выходным или днём с переходом между ними

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

Процедурный стиль

function intlcal_get_day_of_week_type(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Возвращает, является ли указанный день рабочим днём (`IntlCalendar::DOW_TYPE_WEEKDAY`), выходным днём (`IntlCalendar::DOW_TYPE_WEEKEND`), днём, в течение которого происходит переход в выходные (`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`) или день, в течение которого прекращаются выходные (`IntlCalendar::DOW_TYPE_WEEKEND_CEASE`).

Если возврат либо `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`, либо `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`, затем можно вызвать IntlCalendar::getWeekendTransition() для получения времени перехода.

Для этой функции требуется ICU 4.4 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`dayOfWeek`

  Одна из констант: `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, ..., `IntlCalendar::DOW_SATURDAY`.

### Возвращаемые значения

Возвращает одну из констант: `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` или `IntlCalendar::DOW_TYPE_WEEKEND_CEASE` или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getDayOfWeekType()

    <?php
    foreach (array('en_US', 'ar_SA') as $locale) {
        echo "Языковой стандарт: ", Locale::getDisplayName($locale, "en_US"), "\n";

        $cal = IntlCalendar::createInstance('UTC', $locale);

        for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
            $type = $cal->getDayOfWeekType($i);
            $transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
                ? $cal->getWeekendTransition($i)
                : '';
            echo $i, " ", $type, " ", $transition, "\n";
        }
        echo "\n";
    }
    ?>

Результат выполнения приведённого примера:

    Языковой стандарт: English (United States)
    1 1 86400000
    2 0
    3 0
    4 0
    5 0
    6 0
    7 1 0

    Языковой стандарт: Arabic (Saudi Arabia)
    1 0
    2 0
    3 0
    4 0
    5 0
    6 1 0
    7 1 86400000

# IntlCalendar::getErrorCode

# intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Получает последний код ошибки объекта

### Описание

Объектно-ориентированный стиль (метод):

public function IntlCalendar::getErrorCode(): int|false

Процедурный стиль:

function intlcal_get_error_code(IntlCalendar `$calendar`): int|false

Возвращает числовой код ошибки ICU для последнего вызова этого объекта (включая клонирование) или IntlCalendar, указанный для параметра `calendar` (в версии с процедурным стилем). Это может означать только предупреждение (отрицательный код ошибки) или полное отсутствие ошибки (`U_ZERO_ERROR`). Фактическое наличие ошибки можно проверить с помощью intl_is_failure().

Недействительные аргументы, обнаруженные на стороне PHP (до вызова функций библиотеки ICU), не записываются для этой функции.

Последнюю ошибку, которая произошла при любом вызове функции модуля intl, включая ошибки ранних аргументов, можно получить с помощью функции intl_get_error_code(). Эта функция сбрасывает глобальный код ошибки, а не код ошибки объекта.

### Список параметров

`calendar`

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

### Возвращаемые значения

Код ошибки ICU, указывающий на успешное выполнение, сбой или предупреждение. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::getErrorCode() и IntlCalendar::getErrorMessage()

    <?php
    ini_set("intl.error_level", E_WARNING);
    ini_set("intl.default_locale", "nl");

    $intlcal = new IntlGregorianCalendar(2012, 1, 29);
    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );
    $intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );

Результат выполнения приведённого примера:

    int(0)
    string(12) "U_ZERO_ERROR"

    Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
    int(1)
    string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

### Смотрите также

- IntlCalendar::getErrorMessage() - Получает последнее сообщение об ошибке для объекта
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя
- intl_error_name() - Получить имя ошибки по её коду
- intl_get_error_code() - Получить код последней ошибки
- intl_get_error_message() - Получить описание ошибки

# IntlCalendar::getErrorMessage

# intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Получает последнее сообщение об ошибке для объекта

### Описание

Объектно-ориентированный стиль (метод):

public function IntlCalendar::getErrorMessage(): string|false

Процедурный стиль:

function intlcal_get_error_message(IntlCalendar `$calendar`): string|false

Возвращает сообщение об ошибке (если есть), связанное с ошибкой, о которой сообщает IntlCalendar::getErrorCode() or intlcal_get_error_code(). Если связанного сообщения об ошибке нет, будет возвращено только строковое представление имени константы ошибки. В противном случае сообщение об ошибке также включает сообщение, установленное на стороне привязки PHP.

### Список параметров

`calendar`

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

### Возвращаемые значения

Сообщение об ошибке, связанное с последней ошибкой, возникшей при вызове функции для этого объекта или строка, указывающая на отсутствие ошибки. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

Результат выполнения приведённого примера:

    string(12) "U_ZERO_ERROR"
    string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"

# IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Получает первый день недели для языкового стандарта календаря

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getFirstDayOfWeek(): int|false

Процедурный стиль

function intlcal_get_first_day_of_week(IntlCalendar `$calendar`): int|false

День недели, который считается началом недели: либо значение по умолчанию для этого языкового стандарта, либо значение, установленное с помощью IntlCalendar::setFirstDayOfWeek().

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Одна из констант: `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY` или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    var_dump($cal1->getFirstDayOfWeek()); // Понедельник
    $cal1->set(2013, 1 /* Февраль */, 3); // Воскресенье
    var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

    $cal2 = IntlCalendar::createInstance(NULL, 'en_US');
    var_dump($cal2->getFirstDayOfWeek()); // Воскресенье
    $cal2->set(2013, 1 /* Февраль */, 3); // Воскресенье
    var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

Результат выполнения приведённого примера:

    int(2)
    int(5)
    int(1)
    int(6)

### Смотрите также

- IntlCalendar::setFirstDayOfWeek() - Устанавливает день, который является началом недели

# IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Получает наибольшее локальное минимальное значение поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

Процедурный стиль

function intlcal_get_greatest_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Возвращает наибольшее локальное минимальное значение поля. Это должно быть значение, большее или равное значению, возвращаемому IntlCalendar::getActualMinimum(), которое, в свою очередь, больше или равно значению, возвращаемому IntlCalendar::getMinimum(). Все эти три функции возвращают одно и то же значение для григорианского календаря.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число (int), представляющее значение поля или `false`, если возникла ошибка.

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Получает набор значений ключевых слов языкового стандарта

### Описание

Объектно-ориентированный стиль

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Процедурный стиль

function intlcal_get_keyword_values_for_locale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Для заданного ключа языкового стандарта получает набор значений для этого ключа, которые приведут к другому поведению. На данный момент поддерживается только ключевое слово `'calendar'`.

Для работы функции требуется ICU 4.2 или новее.

### Список параметров

`keyword`

  Ключевое слово языкового стандарта, для которого нужно запросить релевантные значения. Поддерживается только `'calendar'`.

`locale`

  Языковой стандарт, к которому должна быть добавлена пара "ключевое слово/значение".

`onlyCommon`

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

### Возвращаемые значения

Итератор, который выдаёт строки со значениями ключевых слов языкового стандарта или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getKeywordValuesForLocale()

    <?php
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', true)));
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', false)));

Результат выполнения приведённого примера:

    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
    )
    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
        [4] => japanese
        [5] => buddhist
        [6] => roc
        [7] => hebrew
        [8] => chinese
        [9] => indian
        [10] => coptic
        [11] => ethiopic
        [12] => ethiopic-amete-alem
    )

# IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Получает наименьший локальный максимум поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

Процедурный стиль

function intlcal_get_least_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Метод возвращает наименьший локальный максимум поля. Значение возврата меньше или равно значению, которое возвращается методом IntlCalendar::getActualMaximum(), которое при этом меньше или равно значению, которое возвращается методом IntlCalendar::getMaximum().

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Метод возвращает целое число (int), которое представляет значение поля в единицах измерения этого поля, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения наименьшего локального максимума

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'it_IT');

    $cal = new IntlGregorianCalendar(2013, 3 /* April */, 6);
    var_dump(
        $cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH),  // 28
        $cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
        $cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)        // 31
    );

Результат выполнения приведённого примера:

    int(28)
    int(30)
    int(31)

### Смотрите также

- IntlCalendar::getActualMaximum() - Максимальное значение для поля с учётом текущего времени объекта
- IntlCalendar::getMaximum() - Получает глобальное максимальное значение поля
- IntlCalendar::getGreatestMinimum() - Получает наибольшее локальное минимальное значение поля

# IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Получает языковой стандарт, связанный с объектом

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getLocale(int `$type`): string|false

Процедурный стиль

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Возвращает языковой стандарт, связанный с объектом.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`type`

  Следует ли получать фактический языковой стандарт (языковой стандарт, из которого происходят данные календаря, с помощью `Locale::ACTUAL_LOCALE`) или действительный языковой стандарт, т.к. наиболее конкретный языковой стандарт, поддерживаемый ICU относительно запрошенного языкового стандарта - смотрите `Locale::VALID_LOCALE`. От наиболее общих к наиболее частным, языковые стандарты отсортированы следующим образом: фактический языковой стандарт, допустимый языковой стандарт, запрошенный языковой стандарт.

### Возвращаемые значения

Языковой стандарт в виде строки или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

Результат выполнения приведённого примера:

    string(2) "en"
    string(5) "en_US"

# IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Получает глобальное максимальное значение поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getMaximum(int `$field`): int|false

Процедурный стиль

function intlcal_get_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Получает глобальное максимальное значение поля в этом конкретном календаре. Это значение больше или равно значению, возвращаемому IntlCalendar::getActualMaximum(), которое, в свою очередь, больше или равно значению, возвращаемому IntlCalendar::getLeastMaximum().

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число (int), представляющее значение для данного поля или `false`, если возникла ошибка.

### Смотрите также

- IntlCalendar::getActualMaximum() - Максимальное значение для поля с учётом текущего времени объекта
- IntlCalendar::getLeastMaximum() - Получает наименьший локальный максимум поля
- IntlCalendar::getMinimum() - Получает глобальное минимальное значение поля

# IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Получает минимальное количество дней, которое может быть в первой неделе в году или месяце

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

Процедурный стиль

function intlcal_get_minimal_days_in_first_week(IntlCalendar `$calendar`): int|false

Возвращает наименьшее количество дней, которые должны пройти в первую неделю года или месяца в новом году или месяце. Например, в григорианском календаре, если это значение равно 1, то первая неделя года обязательно будет включать 1 января, а если это значение равно 7, то неделя с 1 января будет первой неделей года, только если день недели 1 января совпадает с днём недели, возвращаемым IntlCalendar::getFirstDayOfWeek(); в противном случае это будет последняя неделя прошлого года.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Целое число (int, представляющее количество дней или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getMinimalDaysInFirstWeek()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 0 /* Январь */, 2);
    var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // Среда

    var_dump($cal->getMinimalDaysInFirstWeek(), // 1
    $cal->getFirstDayofWeek()); // 1 (Воскресенье)

    // Первая неделя 2013 года
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(4);
    // Всё ещё первая неделя 2013 года (в 1-й неделе 5 дней в новом году)
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(6);
    // 53 неделя 2012 года
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

Результат выполнения приведённого примера:

    string(9) "Wednesday"
    int(1)
    int(1)
    string(14) "Week 1 of 2013"
    string(14) "Week 1 of 2013"
    string(15) "Week 53 of 2012"

# IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Получает глобальное минимальное значение поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getMinimum(int `$field`): int|false

Процедурный стиль

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Получает глобальное минимальное значение поля в этом конкретном календаре. Это значение меньше или равно значению, возвращаемому IntlCalendar::getActualMinimum(), которое, в свою очередь, меньше или равно значению, возвращаемому IntlCalendar::getGreatestMinimum(). Для григорианского календаря эти три функции всегда возвращают одно и то же значение (для каждого поля).

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

Целое число (int), представляющее значение для данного поля или `false`, если возникла ошибка.

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Получает число, представляющее текущее время

### Описание

Объектно-ориентированный стиль

public static function IntlCalendar::getNow(): float

Процедурный стиль

function intlcal_get_now(): float

Количество миллисекунд, прошедших с начала эпохи Unix. Число определяется системным временем.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Число с плавающей точкой (float), представляющее количество миллисекунд с начала эпохи Unix, не считая дополнительных секунд.

### Примеры

Пример #1 Пример использования IntlCalendar::getNow()

    <?php
    $formatter = IntlDateFormatter::create('es_ES',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'Europe/Madrid');

    $val = IntlCalendar::getNow();

    var_dump($val);
    echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

Результат выполнения приведённого примера:

    float(1371425814666)
    lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central

# IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Получает поведение для обработки повторяющегося времени процессора

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getRepeatedWallTimeOption(): int

Процедурный стиль

function intlcal_get_repeated_wall_time_option(IntlCalendar `$calendar`): int

Получает текущую стратегию работы со временем процессора, которая повторяется всякий раз, когда часы переводятся назад во время переходов на летнее время. Значение по умолчанию - `IntlCalendar::WALLTIME_LAST`.

Для этой функции требуется ICU 4.9 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Одна из констант: `IntlCalendar::WALLTIME_FIRST` или `IntlCalendar::WALLTIME_LAST`.

### Примеры

Пример #1 Пример использования IntlCalendar::getRepeatedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    // 27 октября в 02:00 часы переводятся на 1 час назад с GMT+01 на GMT+00.
    $cal = new IntlGregorianCalendar(2013, 9 /* Октябрь */, 27, 1, 30);

    var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000.));

    $cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000.));

Результат выполнения приведённого примера:

    int(0)
    string(42) "Sunday, October 27, 2013 at 1:30:00 AM GMT"
    int(1)
    string(43) "Sunday, October 27, 2013 at 12:30:00 AM GMT"

### Смотрите также

- IntlCalendar::getSkippedWallTimeOption() - Получает поведение для обработки пропущенного времени процессора
- IntlCalendar::setSkippedWallTimeOption() - Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса
- IntlCalendar::setRepeatedWallTimeOption() - Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса

# IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Получает поведение для обработки пропущенного времени процессора

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getSkippedWallTimeOption(): int

Процедурный стиль

function intlcal_get_skipped_wall_time_option(IntlCalendar `$calendar`): int

Получает текущую стратегию для работы со временем процессора, которое пропускается всякий раз, когда часы переводятся во время переходов времени на летнее время. Значение по умолчанию - `IntlCalendar::WALLTIME_LAST`.

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

Для этой функции требуется ICU 4.9 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Одна из констант: `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` или `IntlCalendar::WALLTIME_NEXT_VALID`.

### Примеры

Пример #1 Пример использования IntlCalendar::getSkippedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    // 31 марта в 01:00 часы переводятся на 1 час вперёд и с GMT+00 на GMT+01.
    $cal = new IntlGregorianCalendar(2013, 2 /* March */, 31, 1, 30);

    var_dump(
        $cal->isLenient(),               // true
        $cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
    );

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
    var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

Результат выполнения приведённого примера:

    bool(true)
    int(0)
    string(40) "Sunday, March 31, 2013 at 1:30:00 AM GMT"
    int(1)
    string(41) "Sunday, March 31, 2013 at 12:30:00 AM GMT"
    int(2)
    string(40) "Sunday, March 31, 2013 at 1:00:00 AM GMT"

### Смотрите также

- IntlCalendar::getRepeatedWallTimeOption() - Получает поведение для обработки повторяющегося времени процессора
- IntlCalendar::setSkippedWallTimeOption() - Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса
- IntlCalendar::setRepeatedWallTimeOption() - Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса

# IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — Получает время, представленное в данный момент объектом

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getTime(): float|false

Процедурный стиль

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Возвращает время, связанное с этим объектом, выраженное в миллисекундах с начала эпохи Unix.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Число с плавающей точкой (float), представляющее количество миллисекунд, прошедших с начала эпохи Unix (1 января 1970 00:00:00 UTC) или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlCalendar::getTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 4 /* Май */, 1, 0, 0, 0);
    $time = $cal->getTime();
    var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

Результат выполнения приведённого примера:

    float(1367362800000)
    bool(true)

### Смотрите также

- IntlCalendar::getNow() - Получает число, представляющее текущее время

# IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Получает часовой пояс объекта

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

Процедурный стиль

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Возвращает объект IntlTimeZone, связанный с календарём.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Объект IntlTimeZone, соответствующий тому, который используется внутри объекта. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::getTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance();
    print_r($cal->getTimeZone());

    $cal->setTimeZone('UTC');
    print_r($cal->getTimeZone());

    $cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
    print_r($cal->getTimeZone());

Результат выполнения приведённого примера:

    IntlTimeZone Object
    (
        [valid] => 1
        [id] => Europe/Lisbon
        [rawOffset] => 0
        [currentOffset] => 3600000
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => UTC
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+03:33
        [rawOffset] => 12780000
        [currentOffset] => 12780000
    )

### Смотрите также

- IntlCalendar::setTimeZone() - Устанавливает часовой пояс, используемый календарём
- IntlCalendar::createInstance() - Создаёт новый объект IntlCalendar
- IntlGregorianCalendar::__construct() - Конструктор класса григорианского календаря

# IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — Получает тип календаря

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getType(): string

Процедурный стиль

function intlcal_get_type(IntlCalendar `$calendar`): string

Строка, описывающая тип календаря. Одно из допустимых значений для значения ключевого слова календаря `'calendar'`.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Строка (string), представляющая тип календаря, например, `'gregorian'`, `'islamic'` и т.д.

### Примеры

Пример #1 Пример использования IntlCalendar::getType()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
    var_dump($cal->getType());

    $cal = new IntlGregorianCalendar();
    var_dump($cal->getType());

Результат выполнения приведённого примера:

    string(19) "ethiopic-amete-alem"
    string(9) "gregorian"

# IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Получает время дня, когда выходные начинаются или заканчиваются

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

Процедурный стиль

function intlcal_get_weekend_transition(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

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

Применимо только для дней недели, для которых IntlCalendar::getDayOfWeekType() возвращает либо `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`, либо `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`. Вызов этой функции для других дней недели является ошибкой.

Для этой функции требуется ICU 4.4 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`dayOfWeek`

  Одна из констант: `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Возвращаемые значения

Количество миллисекунд после полуночи, когда выходные начинаются или заканчиваются или `false`, если возникла ошибка.

### Примеры

Примеры смотрите в описании функции IntlCalendar::getDayOfWeekType().

# IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Определяет, переходит ли время объекта на летнее время

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::inDaylightTime(): bool

Процедурный стиль

function intlcal_in_daylight_time(IntlCalendar `$calendar`): bool

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

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Возвращает `true`, если дата указана в летнее время, в противном случае возвращает `false`.

Если возникла ошибка, также возвращается `false`. Для обнаружения условий ошибки вызывают функцию intl_get_error_code() или настраивают выбрасывание исключений в Intl.

### Примеры

Пример #1 Пример использования IntlCalendar::inDaylightTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 6 /* Июль */, 1, 4, 56, 31);
    var_dump($cal->inDaylightTime()); // true
    $cal->set(IntlCalendar::FIELD_MONTH, 11 /* Декабрь */);
    var_dump($cal->inDaylightTime()); // false

    //DST end transition on 2013-10-27 at 0200 (время процессора назад на 1 час)
    $cal = new IntlGregorianCalendar(2013, 9 /* Октябрь */, 27, 1, 30, 0);

    var_dump($cal->inDaylightTime()); // false (по умолчанию WALLTIME_LAST)

    $cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // принудительный перерасчёт времени
    var_dump($cal->inDaylightTime()); // true

# IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Определяет, равен ли другой календарь, но для другого времени

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

Процедурный стиль

function intlcal_is_equivalent_to(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Возвращает, равны ли этот и данный объект для всех целей, кроме установленного времени. Языковые стандарты могут не совпадать, если из-за такого несоответствия не происходит никаких изменений в поведении. Сюда входит часовой пояс, установлен ли мягкий режим, повторяющиеся и пропущенные настройки времени процессора, дни недели, когда выходные начинаются и заканчиваются и время, когда происходят такие переходы. Также может содержать другие настройки, специфичные для календаря, например, момент перехода между григорианским и юлианским календарём.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`other`

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

### Возвращаемые значения

При отсутствии ошибок аргумента возвращает `true`, если календари равны, за исключением, возможно, установленного времени.

### Примеры

Пример #1 Пример использования IntlCalendar::isEquivalentTo()

    <?php
    $cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_PT');
    $cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
    $cal2->clear();

    var_dump($cal1->isEquivalentTo($cal2)); // true

    $cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
    var_dump($cal1->isEquivalentTo($cal3)); // false
    var_dump($cal1->getFirstDayOfWeek(),    // 2 (Понедельник)
    $cal3->getFirstDayOfWeek());            // 1 (Воскресенье)

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    int(2)
    int(1)

### Смотрите также

- IntlCalendar::equals() - Сравнивает время двух объектов IntlCalendar на предмет равенства

# IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Определяет, является ли интерпретация даты/времени мягкой

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::isLenient(): bool

Процедурный стиль

function intlcal_is_lenient(IntlCalendar `$calendar`): bool

Возвращает, является ли текущая интерпретация даты и времени мягкой (по умолчанию). В этом случае некоторые значения полей вне допустимого диапазона будут приняты вместо того, чтобы вызывать ошибку.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Логическое значение (bool), указывающее, установлен ли в календаре мягкий режим.

### Примеры

Пример #1 Пример использования IntlCalendar::isLenient()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');
    ini_set('intl.use_exceptions', '1');

    $cal = new IntlGregorianCalendar(2013, 6 /* Июль */, 1);
    var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
    $cal->isLenient()); // true

    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

    $cal->setLenient(false);
    var_dump($cal->isLenient()); // false
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // ошибка

Результат выполнения приведённого примера:

    string(20) "01/07/2013, 00:00:00"
    bool(true)
    string(20) "02/08/2013, 00:00:00"
    bool(false)

    Fatal error: Uncaught exception 'IntlException' with message 'datefmt_format_object: error obtaining instant from IntlCalendar' in /home/foobar/example.php:16
    Stack trace:
    #0 /home/foobar/example.php(16): IntlDateFormatter::formatObject(Object(IntlGregorianCalendar))
    #1 {main}
      thrown in /home/foobar/example.php on line 16

# IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — Определяет, установлено ли поле

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::isSet(int `$field`): bool

Процедурный стиль

function intlcal_is_set(IntlCalendar `$calendar`, int `$field`): bool

Возвращает, установлено ли поле (в отличие от clear). Установленные поля приоритетнее неустановленных полей и их значений по умолчанию при вычислении даты и времени. Поля, установленные позже приоритетнее полей, установленных ранее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

### Возвращаемые значения

В случае отсутствия ошибок аргумента возвращает `true`, если поле установлено.

### Примеры

Смотрите пример в описании метода IntlCalendar::clear().

### Смотрите также

- IntlCalendar::clear() - Очищает поле или все поля
- IntlCalendar::set() - Устанавливает поле времени или сразу несколько общих полей

# IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Определяет, приходятся ли определённые дата/время на выходные

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

Процедурный стиль

function intlcal_is_weekend(IntlCalendar `$calendar`, ?float `$timestamp` = `null`): bool

Возвращает, является ли текущее время объекта или заданная временная метка выходными в календарной системе этого объекта.

Для этой функции требуется ICU 4.4 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`timestamp`

  Необязательная метка времени, представляющая количество миллисекунд с начала эпохи Unix, исключая дополнительные секунды. Если `null`, вместо этого используется текущее время объекта.

### Возвращаемые значения

Логическое значение (bool), указывающее, является ли время объекта выходными.

Если возникла ошибка, также возвращается `false`. Для обнаружения условий ошибки вызывают функцию intl_get_error_code() или настраивают выбрасывание исключений в Intl.

### Примеры

Пример #1 Пример использования IntlCalendar::isWeekend()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = new IntlGregorianCalendar(NULL, 'en_US');
    $cal->set(2013, 6 /* Июль */, 7); // Воскресенье

    var_dump($cal->isWeekend()); // true
    var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, Понедельник

    $cal = new IntlGregorianCalendar(NULL, 'ar_SA');
    $cal->set(2013, 6 /* Июль */, 7); // Воскресенье
    var_dump($cal->isWeekend()); // false, воскресенье не является выходным днём в этом календаре

### Смотрите также

- IntlCalendar::getDayOfWeekType() - Сообщает, является ли день будним, выходным или днём с переходом между ними
- IntlCalendar::getWeekendTransition() - Получает время дня, когда выходные начинаются или заканчиваются

# IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — Добавляет значение в поле без переноса в более важные поля

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

Процедурный стиль

function intlcal_roll(IntlCalendar `$calendar`, int `$field`, int|bool `$value`): bool

Добавляет количество (со знаком) в поле. Отличие от IntlCalendar::add() состоит в том, что когда значение поля переполняется, оно не переносится в более важные поля.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

`value`

  Количество (со знаком), добавляемое к полю, `true` для сворачивания (добавление `1`) или `false` для скатывания вниз (вычитание `1`).

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::roll()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 5 /* Июнь */, 30);

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

    $cal->set(2013, 5 /* Июнь */, 30);
    $cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // свернуть так же, как скатиться +1
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

Результат выполнения приведённого примера:

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### Смотрите также

- IntlCalendar::add() - Добавляет количество (со знаком) времени в поле
- IntlCalendar::set() - Устанавливает поле времени или сразу несколько общих полей

# IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — Устанавливает поле времени или сразу несколько общих полей

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

Процедурный стиль

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function intlcal_set(
IntlCalendar `$cal`,
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): bool

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

Для полей, которые конфликтуют, поля, которые устанавливаются позже, приоритетнее.

Метод нельзя вызвать ровно с четырьмя аргументами.

### Список параметров

`cal`
  Экземпляр класса IntlCalendar.
`field`

  Одна из представленных в классе IntlCalendar констант полей типа дата/время. Целое число от `0` до `IntlCalendar::FIELD_COUNT`.

`value`

  Новое значение заданного поля.

`year`

  Новое значение поля `IntlCalendar::FIELD_YEAR`.

`month`

  Новое значение поля `IntlCalendar::FIELD_MONTH`. Последовательность месяцев начинается с нуля: январь представляется 0, февраль — 1, ..., декабрь — 11, а тринадцатый месяц, если содержится в календаре, — 12.

`dayOfMonth`

  Новое значение поля `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  Новое значение поля `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  Новое значение поля `IntlCalendar::FIELD_MINUTE`.

`second`

  Новое значение поля `IntlCalendar::FIELD_SECOND`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.
8.4.0 | Метод устарел в пользу методов IntlCalendar::setDate() и IntlCalendar::setDateTime().

### Примеры

Пример #1 Пример установки поля времени или нескольких общих полей методом IntlCalendar::set()

    <?php

    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    // Вызовы, которые сделали позже, приоритетнее
    $cal = new IntlGregorianCalendar(2013, 6 /* Июль */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    var_dump(IntlDateFormatter::formatObject($cal));

    $cal = new IntlGregorianCalendar(2013, 6 /* Июль */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    // Время еще не пересчиталось. Метод использует год, который установили прежде,
    // если очистить EXTENDED_YEAR
    $cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
    var_dump(IntlDateFormatter::formatObject($cal));

    ?>

Результат выполнения приведённого примера:

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### Смотрите также

- IntlCalendar::get() - Получает значение поля
- IntlCalendar::add() - Добавляет количество (со знаком) времени в поле
- IntlCalendar::roll() - Добавляет значение в поле без переноса в более важные поля

# IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — Устанавливает поля даты

### Описание

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Устанавливает в поля даты заданное значение.

### Список параметров

`year`

  Новое значение для `IntlCalendar::FIELD_YEAR`.

`month`

  Новое значение для `IntlCalendar::FIELD_MONTH`. Последовательность месяцев начинается с нуля, т. е. январь обозначается как 0, февраль – 1, …, декабрь - 11, а недекабрь (если он есть в календаре) – 12.

`dayOfMonth`

  Новое значение для `IntlCalendar::FIELD_DAY_OF_MONTH`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования метода IntlCalendar::setDate()

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDate(2012, 1, 29);
    ?>

# IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — Устанавливает поля даты и времени

### Описание

public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void

Метод устанавливает поля даты и времени в заданное значение.

### Список параметров

`year`

  Новое значение для константы `IntlCalendar::FIELD_YEAR`.

`month`

  Новое значение для константы `IntlCalendar::FIELD_MONTH`. Последовательность месяцев начинается с нуля, т. е. январь обозначается как 0, февраль – 1, …, декабрь — 11, а недекабрь (если он есть в календаре) — 12.

`dayOfMonth`

  Новое значение для константы `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  Новое значение для константы `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  Новое значение для константы `IntlCalendar::FIELD_MINUTE`.

`second`

  Новое значение для константы `IntlCalendar::FIELD_SECOND`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример использования метода IntlCalendar::setDateTime()

    <?php

    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDateTime(2012, 1, 29, 23, 58);

    ?>

# IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Устанавливает день, который является началом недели

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

Процедурный стиль

function intlcal_set_first_day_of_week(IntlCalendar `$calendar`, int `$dayOfWeek`): true

Определяет день недели, который считается началом недели. Это влияет на поведение полей, которые зависят от концепции начала и конца недели, например: `IntlCalendar::FIELD_WEEK_OF_YEAR` и `IntlCalendar::FIELD_YEAR_WOY`.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`dayOfWeek`

  Одна из констант `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Пример #1 Пример использования IntlCalendar::setFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = IntlCalendar::createInstance();
    $cal->set(2013, 5 /* Июнь */, 30); // Воскресенье

    var_dump($cal->getFirstDayOfWeek()); // 2 (Понедельник)

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'местный день недели: 'cc'
    неделя месяца    : 'W'
    неделя года     : 'ww
    EOD
    ), "\n";

    $cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'местный день недели: 'cc'
    неделя месяца    : 'W'
    неделя года     : 'ww
    EOD
    ), "\n";

Результат выполнения приведённого примера:

    int(2)
    местный день недели: 7
    неделя месяца    : 4
    неделя года     : 26
    местный день недели: 1
    неделя месяца    : 5
    неделя года     : 27

# IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Устанавливает, должна ли интерпретация даты/времени быть мягкой

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setLenient(bool `$lenient`): true

Процедурный стиль

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

Определяет, является ли календарь "мягким" режимом. В таком режиме принимаются некоторые из значений, выходящих за границы для некоторых полей, поведение аналогично поведению IntlCalendar::add() (т.е. значение переносится каждый раз в более важные поля). Если мягкий режим выключен, такие значения будут вызывать ошибку.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`lenient`

  Используйте `true` для активации мягкого режима; `false` для выключения.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Смотрите пример в описании метода IntlCalendar::isLenient().

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — Устанавливает минимальное количество дней, которое может быть в первой неделе в году или месяце

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

Процедурный стиль

function intlcal_set_minimal_days_in_first_week(IntlCalendar `$calendar`, int `$days`): true

Устанавливает наименьшее количество дней, которые должны пройти в первую неделю года или месяца в новом году или месяце. Например, в григорианском календаре, если это значение равно 1, то первая неделя года обязательно будет включать 1 января, а если это значение равно 7, то неделя с 1 января будет первой неделей года, только если день недели 1 января совпадает с днём недели, возвращаемым IntlCalendar::getFirstDayOfWeek(); в противном случае это будет последняя неделя прошлого года.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`days`

  Количество минимальных дней, которые нужно установить.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Ошибки

Метод выбрасывает ошибку ValueError, если параметр `days` находится вне диапазона (меньше `1` или больше `7`).

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае некорректного ввода данных теперь выдаётся ошибка ValueError; ранее возвращалось значение `false`.

# IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

Процедурный стиль

function intlcal_set_repeated_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Устанавливает текущую стратегию работы со временем процессора, которая повторяется всякий раз, когда часы переводятся назад во время перехода на летнее время. Значение по умолчанию - `IntlCalendar::WALLTIME_LAST` (момент после перехода на летнее время). Другое возможное значение - `IntlCalendar::WALLTIME_FIRST` (момент, который наступает во время перехода на летнее время).

Для этой функции требуется ICU 4.9 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`option`

  Одна из констант: `IntlCalendar::WALLTIME_FIRST` или `IntlCalendar::WALLTIME_LAST`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Смотрите примеры в описании функции IntlCalendar::getRepeatedWallTimeOption().

### Смотрите также

- intlCalendar::getRepeatedWallTimeOption() - Получает поведение для обработки повторяющегося времени процессора
- intlCalendar::setSkippedWallTimeOption() - Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса
- intlCalendar::getSkippedWallTimeOption() - Получает поведение для обработки пропущенного времени процессора

# IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

Процедурный стиль

function intlcal_set_skipped_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Устанавливает текущую стратегию для работы со временем процессора, которое пропускается всякий раз, когда часы переводятся на летнее время. Значение по умолчанию - `IntlCalendar::WALLTIME_LAST` (момент, когда время процессора на один час больше). Альтернативные значения: `IntlCalendar::WALLTIME_FIRST` (момент, когда время процессора на один час меньше) и `IntlCalendar::WALLTIME_NEXT_VALID` (момент, когда начинается летнее время).

Влияет только на момент, представленный календарём (как сообщает IntlCalendar::getTime()), значения поля не будут переписаны соответствующим образом.

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

Для этой функции требуется ICU 4.9 или новее.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`option`

  Одна из констант: `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` или `IntlCalendar::WALLTIME_NEXT_VALID`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Вместо общего логического типа bool теперь возвращается конкретный тип `true`.

### Примеры

Смотрите примеры в описании функции IntlCalendar::getSkippedWallTimeOption().

### Смотрите также

- intlCalendar::getSkippedWallTimeOption() - Получает поведение для обработки пропущенного времени процессора
- intlCalendar::setRepeatedWallTimeOption() - Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса
- intlCalendar::getRepeatedWallTimeOption() - Получает поведение для обработки повторяющегося времени процессора

# IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — Устанавливает календарное время в миллисекундах с начала эпохи Unix

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setTime(float `$timestamp`): bool

Процедурный стиль

function intlcal_set_time(IntlCalendar `$calendar`, float `$timestamp`): bool

Устанавливает момент, представленный объектом. Момент представлен числом с плавающей точкой (float), значение которого должно быть целым числом миллисекунд, прошедших с начала эпохи Unix (1 января 1970 00:00:00.000 UTC), без учёта дополнительных секунд. Все значения полей будут соответственно пересчитаны.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`timestamp`

  Момент, представленный количеством миллисекунд между этим моментом и эпохой Unix, без учёта дополнительных секунд.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::setTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    /* В Europe/Lisbon 27 октября 2013 года в 02:00 часы переводятся на один час назад,
       а часовой пояс - с UTC+01 на UTC+00 */

    $cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    $cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

Результат выполнения приведённого примера:

    samedi 1 juin 2013 12:00:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure normale d’Europe de l’Ouest

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Устанавливает часовой пояс, используемый календарём

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Процедурный стиль

function intlcal_set_time_zone(IntlCalendar `$calendar`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Определяет новый часовой пояс для календаря. Время, представленное объектом, сохраняется в ущерб значениям поля.

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.
`timezone`

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

  - Если `null`, то будет использован часовой пояс по умолчанию, заданная в ini-настройки date.timezone либо с помощью функции date_default_timezone_set() и возвращённая функцией date_default_timezone_get().

  - Объект класса IntlTimeZone.

  - Объект класса DateTimeZone. Его идентификатор будет извлечён и на его основе будет создан объект часового пояса ICU; часовой пояс будет сохранён в базе данных ICU, а не PHP.

  - Строка, являющаяся корректным идентификатором часового пояса ICU. Смотрите IntlTimeZone::createTimeZoneIDEnumeration(). "Сырые" смещения, типа `"GMT+08:30"`, также поддерживаются.

### Возвращаемые значения

Возвращает `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone(IntlTimeZone::getGMT());
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone('GMT+03:33');
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

Результат выполнения приведённого примера:

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Преобразовывает объект IntlCalendar в объект DateTime

### Описание

Объектно-ориентированный стиль

public function IntlCalendar::toDateTime(): DateTime|false

Процедурный стиль

function intlcal_to_date_time(IntlCalendar `$calendar`): DateTime|false

Создаёт объект DateTime, который представляет тот же момент (с точностью до секунды, с ошибкой округления менее 1 секунды) с аналогичным часовым поясом (разница в том, что часовой пояс DateTime поддерживается часовым поясом PHP, в то время как часовой пояс IntlCalendar поддерживается ICU).

### Список параметров

`calendar`
  Экземпляр класса IntlCalendar.

### Возвращаемые значения

Объект DateTime с тем же часовым поясом, что и заданный объект (хотя с использованием базы данных PHP вместо ICU) и с тем же временем, за исключением меньшей точности (вторая точность вместо миллисекунд). Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования IntlCalendar::toDateTime()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = IntlCalendar::createInstance('Europe/Lisbon'); //current time

    $dt = $cal->toDateTime();
    print_r($dt);

Результат выполнения приведённого примера:

    DateTime Object
    (
        [date] => 2013-07-02 00:29:13
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### Смотрите также

- IntlCalendar::fromDateTime() - Создаёт объект IntlCalendar из объекта DateTime или строки
- IntlCalendar::getTime() - Получает время, представленное в данный момент объектом
- IntlCalendar::createInstance() - Создаёт новый объект IntlCalendar
- DateTime::__construct() - Конструктор класса DateTime

## Содержание

- IntlCalendar::add — Добавляет количество (со знаком) времени в поле
- IntlCalendar::after — Определяет, время этого объекта позже времени переданного объекта
- IntlCalendar::before — Определяет, время этого объекта раньше времени переданного объекта
- IntlCalendar::clear — Очищает поле или все поля
- IntlCalendar::__construct — Закрытый конструктор для запрета создания экземпляров
- IntlCalendar::createInstance — Создаёт новый объект IntlCalendar
- IntlCalendar::equals — Сравнивает время двух объектов IntlCalendar на предмет равенства
- IntlCalendar::fieldDifference — Вычисляет разницу между заданным временем и временем объекта
- IntlCalendar::fromDateTime — Создаёт объект IntlCalendar из объекта DateTime или строки
- IntlCalendar::get — Получает значение поля
- IntlCalendar::getActualMaximum — Максимальное значение для поля с учётом текущего времени объекта
- IntlCalendar::getActualMinimum — Минимальное значение для поля с учётом текущего времени объекта
- IntlCalendar::getAvailableLocales — Получает массив языковых стандартов, для которых есть данные
- IntlCalendar::getDayOfWeekType — Сообщает, является ли день будним, выходным или днём с переходом между ними
- IntlCalendar::getErrorCode — Получает последний код ошибки объекта
- IntlCalendar::getErrorMessage — Получает последнее сообщение об ошибке для объекта
- IntlCalendar::getFirstDayOfWeek — Получает первый день недели для языкового стандарта календаря
- IntlCalendar::getGreatestMinimum — Получает наибольшее локальное минимальное значение поля
- IntlCalendar::getKeywordValuesForLocale — Получает набор значений ключевых слов языкового стандарта
- IntlCalendar::getLeastMaximum — Получает наименьший локальный максимум поля
- IntlCalendar::getLocale — Получает языковой стандарт, связанный с объектом
- IntlCalendar::getMaximum — Получает глобальное максимальное значение поля
- IntlCalendar::getMinimalDaysInFirstWeek — Получает минимальное количество дней, которое может быть в первой неделе в году или месяце
- IntlCalendar::getMinimum — Получает глобальное минимальное значение поля
- IntlCalendar::getNow — Получает число, представляющее текущее время
- IntlCalendar::getRepeatedWallTimeOption — Получает поведение для обработки повторяющегося времени процессора
- IntlCalendar::getSkippedWallTimeOption — Получает поведение для обработки пропущенного времени процессора
- IntlCalendar::getTime — Получает время, представленное в данный момент объектом
- IntlCalendar::getTimeZone — Получает часовой пояс объекта
- IntlCalendar::getType — Получает тип календаря
- IntlCalendar::getWeekendTransition — Получает время дня, когда выходные начинаются или заканчиваются
- IntlCalendar::inDaylightTime — Определяет, переходит ли время объекта на летнее время
- IntlCalendar::isEquivalentTo — Определяет, равен ли другой календарь, но для другого времени
- IntlCalendar::isLenient — Определяет, является ли интерпретация даты/времени мягкой
- IntlCalendar::isSet — Определяет, установлено ли поле
- IntlCalendar::isWeekend — Определяет, приходятся ли определённые дата/время на выходные
- IntlCalendar::roll — Добавляет значение в поле без переноса в более важные поля
- IntlCalendar::set — Устанавливает поле времени или сразу несколько общих полей
- IntlCalendar::setDate — Устанавливает поля даты
- IntlCalendar::setDateTime — Устанавливает поля даты и времени
- IntlCalendar::setFirstDayOfWeek — Устанавливает день, который является началом недели
- IntlCalendar::setLenient — Устанавливает, должна ли интерпретация даты/времени быть мягкой
- IntlCalendar::setMinimalDaysInFirstWeek — Устанавливает минимальное количество дней, которое может быть в первой неделе в году или месяце
- IntlCalendar::setRepeatedWallTimeOption — Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса
- IntlCalendar::setSkippedWallTimeOption — Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса
- IntlCalendar::setTime — Устанавливает календарное время в миллисекундах с начала эпохи Unix
- IntlCalendar::setTimeZone — Устанавливает часовой пояс, используемый календарём
- IntlCalendar::toDateTime — Преобразовывает объект IntlCalendar в объект DateTime

# Класс IntlGregorianCalendar

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

## Обзор класса

class IntlGregorianCalendar extends IntlCalendar {
/* Наследуемые константы */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* Методы */
public function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* Наследуемые методы */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — Конструктор класса григорианского календаря

### Описание

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Метод объявлен устаревшим, следует использовать методы IntlGregorianCalendar::createFromDate() и IntlGregorianCalendar::createFromDateTime().

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — Создаёт новый экземпляр класса IntlGregorianCalendar из даты

### Описание

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Создаёт новый экземпляр класса IntlGregorianCalendar из даты.

### Список параметров

`year`

  Новое значение для константы `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  Новое значение для константы `IntlGregorianCalendar::FIELD_MONTH`. Последовательность месяцев начинается с нуля, т. е. январь обозначается как 0, февраль – 1, …, декабрь — 11, а недекабрь (если он есть в календаре) — 12.

`dayOfMonth`

  Новое значение для константы `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

### Возвращаемые значения

Метод возвращает новый экземпляр класса IntlGregorianCalendar.

### Примеры

Пример #1 Пример использования метода IntlGregorianCalendar::createFromDate()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);

    ?>

Вывод приведённого примера будет похож на:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(0)
        ["is leap month"]=>
        int(0)
      }
    }

### Смотрите также

- IntlGregorianCalendar::createFromDateTime() - Создаёт новый экземпляр класса IntlGregorianCalendar из даты и времени

# IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — Создаёт новый экземпляр класса IntlGregorianCalendar из даты и времени

### Описание

public static function IntlGregorianCalendar::createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static

Создаёт новый экземпляр класса IntlGregorianCalendar из даты и времени.

### Список параметров

`year`

  Новое значение для константы `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  Новое значение для `IntlGregorianCalendar::FIELD_MONTH`. Последовательность месяцев начинается с нуля, т. е. январь обозначается как 0, февраль – 1, …, декабрь — 11, а недекабрь (если он есть в календаре) — 12.

`dayOfMonth`

  Новое значение для константы `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  Новое значение для константы `IntlGregorianCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  Новое значение для константы `IntlGregorianCalendar::FIELD_MINUTE`.

`second`

  Новое значение для константы `IntlGregorianCalendar::FIELD_SECOND`.

### Возвращаемые значения

Метод возвращает новый экземпляр класса IntlGregorianCalendar.

### Примеры

Пример #1 Пример использования метода IntlGregorianCalendar::createFromDateTime()

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);

    ?>

Вывод приведённого примера будет похож на:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(1)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(12)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(43200000)
        ["is leap month"]=>
        int(0)
      }
    }

### Смотрите также

- IntlGregorianCalendar::createFromDate() - Создаёт новый экземпляр класса IntlGregorianCalendar из даты

# IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — Получает дату изменения григорианского календаря

### Описание

public function IntlGregorianCalendar::getGregorianChange(): float

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дату изменения.

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — Определяет, является ли данный год високосным

### Описание

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`year`

### Возвращаемые значения

Возвращает `true` в случае, если год является високосным, `false`, если не является или в случае возникновения ошибки.

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — Устанавливает дату изменения в григорианском календаре

### Описание

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timestamp`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

## Содержание

- IntlGregorianCalendar::__construct — Конструктор класса григорианского календаря
- IntlGregorianCalendar::createFromDate — Создаёт новый экземпляр класса IntlGregorianCalendar из даты
- IntlGregorianCalendar::createFromDateTime — Создаёт новый экземпляр класса IntlGregorianCalendar из даты и времени
- IntlGregorianCalendar::getGregorianChange — Получает дату изменения григорианского календаря
- IntlGregorianCalendar::isLeapYear — Определяет, является ли данный год високосным
- IntlGregorianCalendar::setGregorianChange — Устанавливает дату изменения в григорианском календаре

# Класс IntlTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Введение

## Обзор класса

class IntlTimeZone {
/* Константы */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* Методы */
private function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## Предопределённые константы

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — Конструктор класса, запрещающий прямое создание экземпляра

### Описание

private function IntlTimeZone::__construct()

### Список параметров

Сигнатура функции не содержит параметров.

# IntlTimeZone::countEquivalentIDs

# intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — Получить количество идентификаторов в группе похожих часовых поясов, включая данный идентификатор

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

Процедурный стиль:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

### Возвращаемые значения

# IntlTimeZone::createDefault

# intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — Создать новую копию часового пояса по умолчанию для текущего хоста

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::createDefault(): IntlTimeZone

Процедурный стиль:

function intltz_create_default(): IntlTimeZone

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::createEnumeration

# intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — Получить перечисление из идентификаторов часовых поясов по указанной стране или смещению

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Процедурный стиль:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`countryOrRawOffset`

### Возвращаемые значения

# IntlTimeZone::createTimeZone

# intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — Создать объект часового пояса по заданному идентификатору

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

Процедурный стиль:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

### Возвращаемые значения

# IntlTimeZone::createTimeZoneIDEnumeration

# intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Получить перечисление из идентификаторов системных часовых поясов по заданным условиям фильтрации

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Процедурный стиль:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`type`

`region`

`rawOffset`

### Возвращаемые значения

Возвращает IntlIterator или `false`, если возникла ошибка.

# IntlTimeZone::fromDateTimeZone

# intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — Создать объект часового пояса из DateTimeZone

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

Процедурный стиль:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezone`

### Возвращаемые значения

# IntlTimeZone::getCanonicalID

# intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — Получает канонический системный идентификатор часового пояса или нормализованный пользовательский идентификатор часового пояса по идентификатору часового пояса

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Процедурный стиль:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

`isSystemId`

### Возвращаемые значения

# IntlTimeZone::getDisplayName

# intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — Получить имя часового пояса для отображения пользователю

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

Процедурный стиль:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`dst`

`style`

`locale`

### Возвращаемые значения

# IntlTimeZone::getDSTSavings

# intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — Получить количество миллисекунд, которое нужно добавить к местному поясному времени, чтобы получить летнее время

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getDSTSavings(): int

Процедурный стиль:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getEquivalentID

# intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — Получить идентификатор в группе похожих часовых поясов, включая заданный идентификатор

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

Процедурный стиль:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

`offset`

### Возвращаемые значения

# IntlTimeZone::getErrorCode

# intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — Получить последний код об ошибке в объекте

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getErrorCode(): int|false

Процедурный стиль:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getErrorMessage

# intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — Получить последнее сообщение об ошибке в объекте

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getErrorMessage(): string|false

Процедурный стиль:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getGMT

# intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — Создать часовой пояс по GMT (UTC)

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getGMT(): IntlTimeZone

Процедурный стиль:

function intltz_get_gmt(): IntlTimeZone

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Возвращает эквивалент идентификатора часового пояса из базы часовых поясов IANA

### Описание

Объектно-ориентированный стиль (method):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

Процедурный стиль:

function intltz_get_iana_id(string `$timezoneId`): string|false

Функция переводит идентификатор часового пояса в эквивалент, который получила из базы часовых поясов IANA: для `"GMT"` возвращается `"Etc/GMT"`, а для `"US/Eastern"` — `"America/New_York"`.

> Замечание: Для работы функции требуется библиотека ICU 74 или новее.

### Список параметров

`timezoneId`
  Идентификатор часового пояса для перевода.

### Возвращаемые значения

Функция возвращает IANA-идентификатор часового пояса в виде строки string, или `false`, если возникла ошибка.

### Смотрите также

- intltz_get_id_for_windows_id() - Преобразовать часовой пояс для Windows в системный часовой пояс
- intltz_get_windows_id() - Преобразовать системный часовой пояс в часовой пояс для Windows
- intltz_create_time_zone() - Создать объект часового пояса по заданному идентификатору

# IntlTimeZone::getID

# intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — Получает идентификатор часового пояса

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getID(): string|false

Процедурный стиль:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getIDForWindowsID

# intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Преобразовать часовой пояс для Windows в системный часовой пояс

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

Процедурный стиль:

function intltz_get_id_for_windows_id(string `$timezoneId`, ?string `$region` = `null`): string|false

Переводит часовой пояс для Windows (например, «Pacific Standard Time») в системный часовой пояс (например, «America/Los_Angeles»).

> Замечание: Для работы этой функции требуется ICU версии ≥ 52.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

`region`

### Возвращаемые значения

Возвращает системный часовой пояс или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `region` теперь допускает значение `null`.

### Смотрите также

- IntlTimeZone::getWindowsID() - Преобразовать системный часовой пояс в часовой пояс для Windows

# IntlTimeZone::getOffset

# intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — Получить необработанное значение часового пояса и смещение по Гринвичу (GMT) по заданному моменту времени

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Процедурный стиль:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timestamp`

`local`

`rawOffset`

`dstOffset`

### Возвращаемые значения

# IntlTimeZone::getRawOffset

# intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — Получить необработанное значение смещения по Гринвичу (GMT) без учёта летнего времени

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::getRawOffset(): int

Процедурный стиль:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — Получить код региона, соответствующего заданному идентификатору системного часового пояса

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

Процедурный стиль:

function intltz_get_region(string `$timezoneId`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

### Возвращаемые значения

Возвращает регион или `false`, если возникла ошибка.

# IntlTimeZone::getTZDataVersion

# intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — Получить версию данных о часовом поясе, который в данный момент используется в ICU

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getTZDataVersion(): string|false

Процедурный стиль:

function intltz_get_tz_data_version(): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Получить неизвестный часовой пояс («unknown»)

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

Процедурный стиль:

function intltz_get_unknown(): IntlTimeZone

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает IntlTimeZone или `null` в случае возникновения ошибки.

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Преобразовать системный часовой пояс в часовой пояс для Windows

### Описание

Объектно-ориентированный стиль (метод):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

Процедурный стиль:

function intltz_get_windows_id(string `$timezoneId`): string|false

Переводит системный часовой пояс (например, «America/Los_Angeles») в часовой пояс для Windows (например, «Pacific Standard Time»).

> Замечание: Для работы этой функции требуется ICU версии ≥ 52.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`timezoneId`

### Возвращаемые значения

Возвращает часовой пояс для Windows или `false`, если возникла ошибка.

### Смотрите также

- IntlTimeZone::getIDForWindowsID() - Преобразовать часовой пояс для Windows в системный часовой пояс

# IntlTimeZone::hasSameRules

# intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — Проверить, что в другом часовом поясе используются те же самые правила и смещения, что и в первом заданном

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

Процедурный стиль:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`other`

### Возвращаемые значения

# IntlTimeZone::toDateTimeZone

# intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — Преобразовать в объект DateTimeZone

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

Процедурный стиль:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlTimeZone::useDaylightTime

# intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — Проверить, что в данном часовом поясе используется летнее время

### Описание

Объектно-ориентированный стиль (метод):

public function IntlTimeZone::useDaylightTime(): bool

Процедурный стиль:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- IntlTimeZone::__construct — Конструктор класса, запрещающий прямое создание экземпляра
- IntlTimeZone::countEquivalentIDs — Получить количество идентификаторов в группе похожих часовых поясов, включая данный идентификатор
- IntlTimeZone::createDefault — Создать новую копию часового пояса по умолчанию для текущего хоста
- IntlTimeZone::createEnumeration — Получить перечисление из идентификаторов часовых поясов по указанной стране или смещению
- IntlTimeZone::createTimeZone — Создать объект часового пояса по заданному идентификатору
- IntlTimeZone::createTimeZoneIDEnumeration — Получить перечисление из идентификаторов системных часовых поясов по заданным условиям фильтрации
- IntlTimeZone::fromDateTimeZone — Создать объект часового пояса из DateTimeZone
- IntlTimeZone::getCanonicalID — Получает канонический системный идентификатор часового пояса или нормализованный пользовательский идентификатор часового пояса по идентификатору часового пояса
- IntlTimeZone::getDisplayName — Получить имя часового пояса для отображения пользователю
- IntlTimeZone::getDSTSavings — Получить количество миллисекунд, которое нужно добавить к местному поясному времени, чтобы получить летнее время
- IntlTimeZone::getEquivalentID — Получить идентификатор в группе похожих часовых поясов, включая заданный идентификатор
- IntlTimeZone::getErrorCode — Получить последний код об ошибке в объекте
- IntlTimeZone::getErrorMessage — Получить последнее сообщение об ошибке в объекте
- IntlTimeZone::getGMT — Создать часовой пояс по GMT (UTC)
- IntlTimeZone::getIanaID — Возвращает эквивалент идентификатора часового пояса из базы часовых поясов IANA
- IntlTimeZone::getID — Получает идентификатор часового пояса
- IntlTimeZone::getIDForWindowsID — Преобразовать часовой пояс для Windows в системный часовой пояс
- IntlTimeZone::getOffset — Получить необработанное значение часового пояса и смещение по Гринвичу (GMT) по заданному моменту времени
- IntlTimeZone::getRawOffset — Получить необработанное значение смещения по Гринвичу (GMT) без учёта летнего времени
- IntlTimeZone::getRegion — Получить код региона, соответствующего заданному идентификатору системного часового пояса
- IntlTimeZone::getTZDataVersion — Получить версию данных о часовом поясе, который в данный момент используется в ICU
- IntlTimeZone::getUnknown — Получить неизвестный часовой пояс («unknown»)
- IntlTimeZone::getWindowsID — Преобразовать системный часовой пояс в часовой пояс для Windows
- IntlTimeZone::hasSameRules — Проверить, что в другом часовом поясе используются те же самые правила и смещения, что и в первом заданном
- IntlTimeZone::toDateTimeZone — Преобразовать в объект DateTimeZone
- IntlTimeZone::useDaylightTime — Проверить, что в данном часовом поясе используется летнее время

# Класс IntlDateFormatter

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

Средство форматирования дат — класс, который форматирует или разбирает даты через строковые и (или) библиотечные шаблоны с учётом языковых настроек.

Класс поддерживает функциональность форматирования дат по стандарту ICU и помогает пользователям отображать даты в формате, который учитывает настройки локали, или разбирать строки в значения PHP-дат через строковые и (или) готовые шаблоны.

## Синопсис класса

class IntlDateFormatter {
/* Константы */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* Методы */
public function __construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)
public static function create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter
public function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавили константу `IntlDateFormatter::PATTERN`.

## Смотрите также

- » Средство форматирования дат по стандарту ICU

- » Синтаксис формата дат по стандарту ICU

## Предопределённые константы

Константы устанавливают формат в конструкторах DateType и TimeType.

`IntlDateFormatter::NONE` int
  Не включать этот элемент
`IntlDateFormatter::FULL` int
  Полный формат (Tuesday, April 12, 1952 AD or 3:30:42pm PST)
`IntlDateFormatter::LONG` int
  Длинный формат (January 12, 1952 or 3:30:32pm)
`IntlDateFormatter::MEDIUM` int
  Средний формат (Jan 12, 1952)
`IntlDateFormatter::SHORT` int
  Наиболее сокращённый формат, только самые необходимые данные (12/13/52 или 3:30pm)
`IntlDateFormatter::RELATIVE_FULL` int
  То же, что и константа `IntlDateFormatter::FULL`, но «вчера», «сегодня» и «завтра» выводятся как `yesterday`, `today` и `tomorrow`. Константа доступна с PHP 8.0.0 только для параметра `dateType`.
`IntlDateFormatter::RELATIVE_LONG` int
  То же, что и константа `IntlDateFormatter::LONG`, но «вчера», «сегодня» и «завтра» выводятся как `yesterday`, `today` и `tomorrow`. Константа доступна с PHP 8.0.0 только для параметра `dateType`.
`IntlDateFormatter::RELATIVE_MEDIUM` int
  То же, что и константа `IntlDateFormatter::MEDIUM`, но «вчера», «сегодня» и «завтра» выводятся как `yesterday`, `today` и `tomorrow`. Константа доступна с PHP 8.0.0 только для параметра `dateType`.
`IntlDateFormatter::RELATIVE_SHORT` int
  То же, что и константа `IntlDateFormatter::SHORT`, но но «вчера», «сегодня» и «завтра» выводятся как `yesterday`, `today` и `tomorrow`. Константа доступна с PHP 8.0.0 только для параметра `dateType`.

Следующие константы устанавливают тип календаря. Эти календари прямо завязаны на Григорианский календарь. Не Григорианский календарь устанавливается в локали. Например, locale="hi@calendar=BUDDHIST".

`IntlDateFormatter::TRADITIONAL` int
  Не Григорианский календарь
`IntlDateFormatter::GREGORIAN` int
  Григорианский календарь
`IntlDateFormatter::PATTERN` int
  Использует шаблон, указанный в параметре `pattern`. Доступно начиная с PHP 8.4.0.

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# IntlDateFormatter::create

# datefmt_create

# IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Создаёт средство форматирования даты

### Описание

Объектно-ориентированный стиль

public static function IntlDateFormatter::create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Объектно-ориентированный стиль (конструктор)

public function IntlDateFormatter::__construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)

Процедурный стиль

function datefmt_create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
string `$pattern` = ""
): ?IntlDateFormatter

Создаёт средство форматирования даты.

### Список параметров

`locale`

  Языковой стандарт, который будет использован для форматирования или синтаксического анализа, или `null` для выбора значения, заданного в ini-настройке intl.default_locale.

`dateType`

  Формат даты, который был определён одной из констант IntlDateFormatter. Значение по умолчанию `IntlDateFormatter::FULL`.

`timeType`

  Формат времени, который был определён одной из констант IntlDateFormatter. Значение по умолчанию `IntlDateFormatter::FULL`.

`timezone`

  Идентификатор часового пояса. По умолчанию (и тот, который используется, если указан `null`) — это тот, который возвращается date_default_timezone_get() или, если применимо, объект IntlCalendar, указанный в параметре `calendar`. Этот идентификатор должен быть корректным идентификатором в базе данных ICU или идентификатором, представляющим явное смещение, например, `GMT-05:30`.

  Также может быть объект IntlTimeZone или DateTimeZone.

`calendar`

  Календарь для форматирования или анализа. Значение по умолчанию — `null`, что соответствует `IntlDateFormatter::GREGORIAN`. Может быть одна из констант IntlDateFormatter или объект IntlCalendar. Любой переданный объект IntlCalendar будет клонирован; он не будет изменён IntlDateFormatter. Это определит используемый тип календаря (григорианский, исламский, персидский и т.д.) и, если в параметре `timezone` указано значение `null`, также определит используемый часовой пояс.

`pattern`

  Необязательный шаблон для использования при форматировании или анализе. Возможные шаблоны задокументированы по адресу » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Возвращаемые значения

Метод возвращает созданный объект IntlDateFormatter или `null` в случае возникновения ошибки.

### Ошибки

Если значение параметра `locale` некорректно, выбрасывается ошибка ValueError.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь если значение параметра `locale` некорректно, выбрасывается ошибка ValueError.
8.1.0 | Теперь параметры `dateType` и `timeType` необязательны.

### Примеры

Пример #1 Пример использования функции datefmt_create()

    <?php
    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles', IntlDateFormatter::GREGORIAN  );
    echo "First Formatted output is ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Second Formatted output is ".datefmt_format( $fmt , 0);

    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "First Formatted output with pattern is ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Second Formatted output with pattern is ".datefmt_format( $fmt , 0);
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Первый форматированный вывод: ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Второй форматированный вывод: ".$fmt->format(0);

    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Первый форматированный вывод с шаблоном: ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
          'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
    echo "Второй форматированный вывод с шаблоном: ".$fmt->format(0);
    ?>

Пример #3 Пример обработки неверного значения языкового стандарта

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

Результат выполнения приведённого примера:

    Первый форматированный вывод: Wednesday, December 31, 1969 4:00:00 PM PT
    Второй форматированный вывод: Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    Первый форматированный вывод с шаблоном: 12/31/1969
    Второй форматированный вывод с шаблоном: 12/31/1969

### Смотрите также

- datefmt_format() - Форматирует значение даты и времени как строку
- datefmt_parse() - Преобразовывает строку в значение отметки времени
- datefmt_get_error_code() - Получает код ошибки последней операции
- datefmt_get_error_message() - Получает текст ошибки последней операции

# IntlDateFormatter::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — Форматирует значение даты и времени как строку

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Процедурный стиль

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Метод форматирует значение даты и времени в виде строки.

### Список параметров

`formatter`

  Источник средства форматирования даты.

`datetime`

  Значение, которое требуется отформатировать. Параметр принимает объекты интерфейса DateTimeInterface, объект IntlCalendar, значения с типом numeric, который представляет (возможно, дробное) количество секунд с начала эпохи Unix, или массив (array) в формате, который возвращает функция localtime().

  Метод не учитывает часовой пояс объектов DateTime и IntlCalendar. Метод отформатирует объект с часовым поясом, который настроили в средстве форматирования. На средстве форматирования вначале вызывают метод IntlDateFormatter::setTimeZone() с часовым поясом объекта форматирования, когда требуется отформатировать объект с часовым поясом, который установили для объекта форматирования. Как альтернативу этому вызывают статический метод IntlDateFormatter::formatObject().

### Возвращаемые значения

Метод возвращает строку, которую сформировал при форматировании, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.1.5 | Теперь параметр `datetime` поддерживает общие объекты DateTimeInterface. Раньше поддерживались только объекты DateTime.
PECL-модуль intl 3.0.0 | Теперь параметр `datetime` поддерживает объекты IntlCalendar.

### Примеры

Пример #1 Пример форматирования значения даты и времени в виде строки функцией datefmt_format()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Первый форматированный вывод: ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Второй форматированный вывод: ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Первый форматированный вывод с шаблоном: ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo "Второй форматированный вывод с шаблоном: " . datefmt_format($fmt, 0);

    ?>

Пример #2 Пример форматирования в объектно-ориентированном стиле

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Первый форматированный вывод: ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Второй форматированный вывод: ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Первый форматированный вывод с шаблоном: ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Второй форматированный вывод с шаблоном: ' . $fmt->format(0);

    ?>

Результат выполнения приведённого примера:

    Первый форматированный вывод: Wednesday, December 31, 1969 4:00:00 PM PT
    Второй форматированный вывод: Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    Первый форматированный вывод с шаблоном: 12/31/1969
    Второй форматированный вывод с шаблоном: 12/31/1969

Пример #3 Пример форматирования с объектом IntlCalendar

    <?php

    $tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));

    $formatter = IntlDateFormatter::create(
        'fr_FR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        $tz,
        IntlDateFormatter::GREGORIAN
    );

    $cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
    $cal->set(IntlCalendar::FIELD_MONTH, 8); // 9-й месяц, Рамадан
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); // Первый день
    $cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
    $cal->clear(IntlCalendar::FIELD_MINUTE);
    $cal->clear(IntlCalendar::FIELD_SECOND);
    $cal->clear(IntlCalendar::FIELD_MILLISECOND);

    echo "В этом исламском году Рамадан начался или начнётся:\n\t",
    $formatter->format($cal), "\n";

    // Это часовой пояс средства форматирования:
    $formatter->setTimeZone('Asia/Tokyo');
    echo "После изменения часового пояса:\n\t",
        $formatter->format($cal), "\n"
    ;

    ?>

Результат выполнения приведённого примера:

    В этом исламском году Рамадан начался/начнётся:
        mardi 9 juillet 2013 19:00:00 heure avancée d’Europe centrale
    После изменения часового пояса:
        mercredi 10 juillet 2013 02:00:00 heure normale du Japon

### Смотрите также

- datefmt_create() - Создаёт средство форматирования даты
- datefmt_parse() - Преобразовывает строку в значение отметки времени
- datefmt_get_error_code() - Получает код ошибки последней операции
- datefmt_get_error_message() - Получает текст ошибки последней операции
- datefmt_format_object() - Форматирует объект

# IntlDateFormatter::formatObject

# datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — Форматирует объект

### Описание

Объектно-ориентированный стиль

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Процедурный стиль

function datefmt_format_object(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Функция позволяет форматировать объект IntlCalendar или DateTime без предварительного явного создания объекта IntlDateFormatter.

Временный IntlDateFormatter, который будет создан, принимает часовой пояс из переданного объекта. База данных часовых поясов, связанная с PHP, не будет использоваться - вместо неё будет использоваться ICU. Следовательно, идентификатор часового пояса, используемый в объектах DateTime, также должен существовать в базе данных ICU.

### Список параметров

`datetime`

  Объект типа IntlCalendar или DateTime. Будет использоваться информация о часовом поясе в объекте.

`format`

  Как отформатировать дату/время. Может быть либо массив (array) с двумя элементами (сначала стиль даты, затем стиль времени, может быть одна из констант: `IntlDateFormatter::NONE`, `IntlDateFormatter::SHORT`, `IntlDateFormatter::MEDIUM`, `IntlDateFormatter::LONG`, `IntlDateFormatter::FULL`), целое число (int) со значением одной из этих констант (в этом случае оно будет использоваться как для времени, так и для даты) или строка (string) в формате, описанном в » документации ICU. Если указано значение `null`, будет использоваться стиль по умолчанию.

`locale`

  Используемый языковой стандарт или `null` для использования значения по умолчанию.

### Возвращаемые значения

Строка с результатом или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlDateFormatter::formatObject()

    <?php
    /* часовой пояс по умолчанию не имеет значения; часовой пояс взят из объекта */
    ini_set('date.timezone', 'UTC');
    /* языковой стандарт по умолчанию берётся из этой настройки ini */
    ini_set('intl.default_locale', 'fr_FR');

    $cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
    echo "По умолчанию:\n\t",
            IntlDateFormatter::formatObject($cal),
            "\n";

    echo "Полная запись: \$format (full):\n\t",
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
            "\n";

    echo "Массив: \$format (none, full):\n\t",
            IntlDateFormatter::formatObject($cal, array(
                    IntlDateFormatter::NONE,
                    IntlDateFormatter::FULL)),
            "\n";

    echo "Строка: \$format (d 'of' MMMM y):\n\t",
            IntlDateFormatter::formatObject($cal, "d 'of' MMMM y", 'en_US'),
            "\n";

    echo "Объект DateTime:\n\t",
            IntlDateFormatter::formatObject(
                    new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                    IntlDateFormatter::FULL,
                    'es_ES'),
            "\n";

Результат выполнения приведённого примера:

    По умолчанию:
        6 juin 2013 17:05:06
    Полная запись: $format (full):
        jeudi 6 juin 2013 17:05:06 heure d’été irlandaise
    Массив: $format (none, full):
        17:05:06 heure d’été irlandaise
    Строка: $format (d 'of' MMMM y):
        6 of June 2013
    Объект DateTime:
        lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

# IntlDateFormatter::getCalendar

# datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — Получает тип календаря для объекта IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getCalendar(): int|false

Процедурный стиль

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Возвращает тип календаря для сервиса форматирования. Либо `IntlDateFormatter::TRADITIONAL`, либо `IntlDateFormatter::GREGORIAN`. Возвращает `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования функции datefmt_get_calendar()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип календаря средства форматирования : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Теперь тип календаря средства форматирования : ' . datefmt_get_calendar($fmt);
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип календаря средства форматирования : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Теперь тип календаря средства форматирования : ' . $fmt->getCalendar();

    ?>

Пример #3 Пример обработки неверного значения языкового стандарта

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
        $cal = $fmt->getCalendar();
    } catch (\Error $e) {
        // ...
    }
    ?>

Пример #4 Пример обработки недопустимого языкового стандарта

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
        $cal = $fmt->getCalendar();
    } catch (\Error $e) {
        // ...
    }
    ?>

Результат выполнения приведённого примера:

    Тип календаря средства форматирования : 1
    Теперь тип календаря средства форматирования : 0

### Смотрите также

- datefmt_get_calendar_object() - Получает копию объекта календаря средства форматирования
- datefmt_set_calendar() - Устанавливает тип календаря для средства форматирования
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getDateType

# datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — Получает тип даты, используемый IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getDateType(): int|false

Процедурный стиль

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Получает тип даты, используемый средством форматирования.

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Значение текущего типа даты средства форматирования или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_get_datetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип даты средства форматирования : ' . datefmt_get_datetype($fmt);
    echo 'Первый отформатированный вывод с типом даты ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Теперь тип даты средства форматирования : ' . datefmt_get_datetype($fmt);
    echo 'Второй отформатированный вывод с типом даты ' . datefmt_format($fmt, 0);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип даты средства форматирования : ' . $fmt->getDateType();
    echo 'Первый отформатированный вывод с типом даты ' . $fmt->format(0);
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Теперь тип даты средства форматирования : ' . $fmt->getDateType();
    echo 'Второй отформатированный вывод с типом даты ' . $fmt->format(0);

    ?>

Результат выполнения приведённого примера:

    Тип даты средства форматирования : 0
    Первый отформатированный вывод с типом даты Wednesday, December 31, 1969 4:00:00 PM PT
    Теперь тип даты средства форматирования : 2
    Второй отформатированный вывод с типом даты 12/31/69 4:00:00 PM PT

### Смотрите также

- datefmt_get_timetype() - Получает тип времени, используемый IntlDateFormatter
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getErrorCode

# datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — Получает код ошибки последней операции

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getErrorCode(): int

Процедурный стиль

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Возвращает код ошибки последней операции форматирования.

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Код ошибки, одно из значений UErrorCode. Начальное значение - U_ZERO_ERROR.

### Примеры

Пример #1 Пример использования функции datefmt_get_error_code()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt, 0);

    printf(
        "ОШИБКА: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ОШИБКА: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

Результат выполнения приведённого примера:

    ОШИБКА: U_ZERO_ERROR (0)

### Смотрите также

- datefmt_get_error_message() - Получает текст ошибки последней операции
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# IntlDateFormatter::getErrorMessage

# datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — Получает текст ошибки последней операции

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getErrorMessage(): string

Процедурный стиль

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Получает текст ошибки последней операции.

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Описание последней ошибки.

### Примеры

Пример #1 Пример использования datefmt_get_error_message()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt, 0);

    printf(
        "ОШИБКА: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ОШИБКА: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

Результат выполнения приведённого примера:

    ОШИБКА: U_ZERO_ERROR (0)

### Смотрите также

- datefmt_get_error_code() - Получает код ошибки последней операции
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# IntlDateFormatter::getLocale

# datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Получает языковой стандарт, используемый средством форматирования

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Процедурный стиль

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Получает языковой стандарт, используемый средством форматирования.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`type`

  Вы можете выбирать между корректным и текущим языковым стандартом (`Locale::VALID_LOCALE` и `Locale::ACTUAL_LOCALE`, соответственно). По умолчанию используется текущий языковой стандарт.

### Возвращаемые значения

Языковой стандарт средства форматирования или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_get_locale()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Языковой стандарт средства форматирования : ' . datefmt_get_locale($fmt);
    echo 'Первый отформатированный вывод ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Языковой стандарт средства форматирования : ' . datefmt_get_locale($fmt);
    echo 'Второй отформатированный вывод ' . datefmt_format($fmt, 0);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Языковой стандарт средства форматирования : ' . $fmt->getLocale();
    echo 'Первый отформатированный вывод ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Языковой стандарт средства форматирования : ' . $fmt->getLocale();
    echo 'Второй отформатированный вывод ' . $fmt->format(0);

    ?>

Результат выполнения приведённого примера:

    Языковой стандарт средства форматирования : en
    Первый отформатированный вывод Wednesday, December 31, 1969 4:00:00 PM PT
    Языковой стандарт средства форматирования : de
    Второй отформатированный вывод Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

### Смотрите также

- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getPattern

# datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — Получает шаблон, используемый IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getPattern(): string|false

Процедурный стиль

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

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

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Строка шаблона, используемая для форматирования/разбора или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_get_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Шаблон средства форматирования : ' . datefmt_get_pattern($fmt);
    echo 'Первый отформатированный вывод с шаблоном ' . datefmt_format($fmt, 0);
    datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
    echo 'Теперь шаблон средства форматирования : ' . datefmt_get_pattern($fmt);
    echo 'Второй отформатированный вывод с шаблоном ' . datefmt_format($fmt, 0);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Шаблон средства форматирования : ' . $fmt->getPattern();
    echo 'Первый отформатированный вывод с шаблоном ' . $fmt->format(0);
    $fmt->setPattern('yyyymmdd hh:mm:ss z');
    echo 'Теперь шаблон средства форматирования : ' . $fmt->getPattern();
    echo 'Второй отформатированный вывод с шаблоном ' . $fmt->format(0);
    ?>

Результат выполнения приведённого примера:

    Шаблон средства форматирования : MM/dd/yyyy
    Первый отформатированный вывод с шаблоном 12/31/1969
    Теперь шаблон средства форматирования : yyyymmdd hh:mm:ss z
    Второй отформатированный вывод с шаблоном 19690031 04:00:00 PST

### Смотрите также

- datefmt_set_pattern() - Устанавливает шаблон, используемый IntlDateFormatter
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getTimeType

# datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — Получает тип времени, используемый IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getTimeType(): int|false

Процедурный стиль

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Возвращает тип времени, используемый средством форматирования.

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Значение текущего типа даты средства форматирования или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_get_timetype()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип времени средства форматирования : ' . datefmt_get_timetype($fmt);
    echo 'Первый отформатированный вывод ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Теперь тип времени средства форматирования : ' . datefmt_get_timetype($fmt);
    echo 'Второй отформатированный вывод ' . datefmt_format($fmt, 0);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Тип времени средства форматирования : ' . $fmt->getTimeType();
    echo 'Первый отформатированный вывод ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Теперь тип времени средства форматирования : ' . $fmt->getTimeType();
    echo 'Второй отформатированный вывод ' . $fmt->format(0);

    ?>

Результат выполнения приведённого примера:

    Тип времени средства форматирования : 0
    Первый отформатированный вывод Wednesday, December 31, 1969 4:00:00 PM PT
    Теперь тип времени средства форматирования : 3
    Второй отформатированный вывод Wednesday, December 31, 1969 4:00 PM

### Смотрите также

- datefmt_get_datetype() - Получает тип даты, используемый IntlDateFormatter
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getTimeZoneId

# datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — Получает идентификатор часового пояса, используемый IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getTimeZoneId(): string|false

Процедурный стиль

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

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

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Строка идентификатора часового пояса, используемого этим средством форматирования или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_get_timezone_id()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id средства форматирования: ' . datefmt_get_timezone_id($fmt) . "\n";
    datefmt_set_timezone($fmt, 'Europe/Madrid');
    echo 'Теперь timezone_id средства форматирования: ' . datefmt_get_timezone_id($fmt);

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id средства форматирования: ' . $fmt->getTimezoneId() . "\n";
    $fmt->setTimezone('Europe/Madrid');
    echo 'Теперь timezone_id средства форматирования: ' . $fmt->getTimezoneId();

    ?>

Результат выполнения приведённого примера:

    timezone_id средства форматирования: America/Los_Angeles
    Теперь timezone_id средства форматирования: Europe/Madrid

### Смотрите также

- datefmt_set_timezone() - Устанавливает часовой пояс средства форматирования
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::getCalendarObject

# datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — Получает копию объекта календаря средства форматирования

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

Процедурный стиль

function datefmt_get_calendar_object(IntlDateFormatter `$formatter`): IntlCalendar|false|null

Получает копию объекта календаря, используемого для внутренних целей средством форматирования. Календарь будет иметь тип (например, грегорианский, японский, буддийский, рок, персидский, исламский и т.д.) и часовой пояс, которые соответствуют типу и часовому поясу, используемыми средством форматирования. Дата и время объекта не указаны.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Копия внутреннего объекта календаря, используемого средством форматирования или `null`, если ничего не было установлено или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlDateFormatter::getCalendarObject()

    <?php
    $formatter = IntlDateFormatter::create(
        "fr_FR@calendar=islamic",
        NULL,
        NULL,
        "GMT-01:00",
        IntlDateFormatter::TRADITIONAL
    );

    $cal = $formatter->getCalendarObject();

    var_dump(
        $cal->getType(),
        $cal->getTimeZone(),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

Результат выполнения приведённого примера:

    string(7) "islamic"
    object(IntlTimeZone)#3 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(9) "GMT-01:00"
      ["rawOffset"]=>
      int(-3600000)
      ["currentOffset"]=>
      int(-3600000)
    }
    string(5) "fr_FR"

### Смотрите также

- IntlDateFormatter::getCalendar() - Получает тип календаря для объекта IntlDateFormatter
- IntlDateFormatter::setCalendar() - Устанавливает тип календаря для средства форматирования
- IntlCalendar

# IntlDateFormatter::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — Получает часовой пояс средства форматирования

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

Процедурный стиль

function datefmt_get_timezone(IntlDateFormatter `$formatter`): IntlTimeZone|false

Возвращает объект IntlTimeZone, представляющий часовой пояс, который будет использоваться этим объектом для форматирования даты и времени. При форматировании объектов IntlCalendar и DateTime с помощью этого IntlDateFormatter, используемый часовой пояс будет тот, который возвращается этим методом, а не тот, который связан с форматируемыми объектами.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Связанный объект IntlTimeZone или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlDateFormatter::getTimeZone()

    <?php

    $madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
    $lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

    var_dump($madrid->getTimezone());
    echo $madrid->getTimezone()->getDisplayName(
            false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
    echo $lisbon->getTimeZone()->getId(), "\n";
    //Идентификатор также можно получить с помощью ->getTimezoneId()
    echo $lisbon->getTimeZoneId(), "\n";

Результат выполнения приведённого примера:

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### Смотрите также

- IntlDateFormatter::getTimeZoneId() - Получает идентификатор часового пояса, используемый IntlDateFormatter
- IntlDateFormatter::setTimeZone() - Устанавливает часовой пояс средства форматирования
- IntlTimeZone

# IntlDateFormatter::isLenient

# datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — Получает снисходительность, используемую для IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::isLenient(): bool

Процедурный стиль

function datefmt_is_lenient(IntlDateFormatter `$formatter`): bool

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

### Список параметров

`formatter`

  Ресурс средства форматирования.

### Возвращаемые значения

Возвращает `true`, если парсер снисходителен или `false`, если парсер строгий. По умолчанию парсер снисходителен.

### Примеры

Пример #1 Пример использования datefmt_is_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/mm/yyyy'
    );
    echo 'Снисходительность средства форматирования: ';
    if ($fmt->isLenient()) {
        echo 'Да';
    } else {
        echo 'Нет';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Попытка выполнить синтаксический анализ '35/13/1971'.\nРезультат: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nОшибка: " . intl_get_error_message();
        echo "\nКод ошибки: " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo 'Теперь снисходительность средства форматирования: ';
    if ($fmt->isLenient()) {
        echo 'Да';
    } else {
        echo 'Нет';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Попытка выполнить синтаксический анализ '35/13/1971'.\nРезультат: " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nОшибка: " . intl_get_error_message();
        echo "\nКод ошибки: " . intl_get_error_code();
    }

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/mm/yyyy"
    );
    echo "Снисходительность средства форматирования: ";
    if ($fmt->isLenient()) {
        echo 'Да';
    } else {
        echo 'Нет';
    }
    $fmt->parse('35/13/1971');
    echo "\n Попытка выполнить синтаксический анализ '35/13/1971'.\nРезультат: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nОшибка: " . intl_get_error_message();
        echo "\nКод ошибки: " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo 'Теперь снисходительность средства форматирования: ';
    if ($fmt->isLenient()) {
        echo 'Да';
    } else {
        echo 'Нет';
    }
    $fmt->parse('35/13/1971');
    echo "\n Попытка выполнить синтаксический анализ '35/13/1971'.\nРезультат: " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nОшибка: " . intl_get_error_message();
        echo "\nКод ошибки: " . intl_get_error_code();
    }

    ?>

Результат выполнения приведённого примера:

    Снисходительность средства форматирования: Да
    Попытка выполнить синтаксический анализ '35/13/1971'.
    Результат: -2147483
    Теперь снисходительность средства форматирования: Нет
    Попытка выполнить синтаксический анализ '35/13/1971'.
    Результат:
    Ошибка: Date parsing failed: U_PARSE_ERROR
    Код ошибки: 9

### Смотрите также

- datefmt_set_lenient() - Устанавливает мягкий режим анализатора
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — Разбирает строку на отдельные составляющие времени, которые возвращает в ассоциативном массиве

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

Процедурный стиль

function datefmt_localtime(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): array|false

Функция преобразовывает строку $value в массив полей, каждое из которых представляет отдельный компонент времени. Функция начинает с позиции, которую определили в параметре $parse_pos, с захватом как можно большей части входного значения.

### Список параметров

`formatter`

  Средство форматирования.

`string`

  Строка, которую требуется преобразовать в массив отдельных составляющих времени.

`offset`

  Позиция, с которой функция начнёт разбор значения $value, в котором индексация символов начинается с нуля. Функция присвоит параметру $parse_pos значение -1, если до конца разбора строки $value не возникло ошибок, иначе присвоит позицию, на которой закончился синтаксический анализ. Разбор немедленно завершается ошибкой, если выполняется условие выражения $parse_pos > `strlen($value)`.

### Возвращаемые значения

Функция возвращает массив целочисленных значений. Структура массива совместима с форматом представления местного времени функцией localtime: содержит 24-часовое значение в поле tm_hour или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример преобразования строки в значение времени на основе поля функцией datefmt_localtime()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );

    $arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);

    echo 'Результат разбора: ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value, ";
        }
    }

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );

    $arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);

    echo 'Результат разбора: ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key: $value, ";
        }
    }

    ?>

Результат выполнения приведённого примера:

    Результат разбора: tm_sec: 0, tm_min: 0, tm_hour: 16, tm_year: 69, tm_mday: 31, tm_wday: 3, tm_yday: 365, tm_mon: 11, tm_isdst: 0,

### Смотрите также

- datefmt_create() - Создаёт средство форматирования даты
- datefmt_format() - Форматирует значение даты и времени как строку
- datefmt_parse() - Преобразовывает строку в значение отметки времени
- datefmt_get_error_code() - Получает код ошибки последней операции
- datefmt_get_error_message() - Получает текст ошибки последней операции

# IntlDateFormatter::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — Преобразовывает строку в значение отметки времени

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

Процедурный стиль

function datefmt_parse(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): int|float|false

Преобразовывает строку `string` в инкрементное значение времени, начиная со значения параметра `offset` и используя как можно большую часть входного значения.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`string`

  Строка для преобразования во время.

`offset`

  Позиция, с которой следует начать синтаксический анализ в `string` (начиная с нуля). Если до использования `string` ошибки не возникает, `offset` будет содержать -1, в противном случае он будет содержать позицию, в которой закончился синтаксический анализ (и произошла ошибка). Эта переменная будет содержать конечную позицию, если при синтаксическом анализе возникла ошибка. Если `offset` > `strlen($string)`, разбор немедленно завершается ошибкой.

### Возвращаемые значения

Возвращает отметку времени преобразованного значения или `false`, если значение не может быть преобразовано.

### Примеры

Пример #1 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Первый преобразованный вывод: ' . $fmt->parse('Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    ?>

Пример #2 Пример использования datefmt_parse()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Первый преобразованный вывод: ' . datefmt_parse($fmt, 'Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Второй преобразованный вывод: ' . datefmt_parse($fmt, 'Mittwoch, 20. Dezember 1989 16:00 Uhr GMT-08:00');
    ?

Результат выполнения приведённого примера:

    Первый преобразованный вывод: 630201600
    Второй преобразованный вывод: 630201600

### Смотрите также

- datefmt_create() - Создаёт средство форматирования даты
- datefmt_format() - Форматирует значение даты и времени как строку
- datefmt_localtime() - Разбирает строку на отдельные составляющие времени, которые возвращает в ассоциативном массиве
- datefmt_get_error_code() - Получает код ошибки последней операции
- datefmt_get_error_message() - Получает текст ошибки последней операции

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — Разбирает строку в метку времени, которой обновляет открытый календарь

### Описание

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

Метод преобразует строку `string` в метку времени — количество секунд, которое прошло с начала эпохи Юникс. Преобразование начинается с позиции `offset` и захватывает максимально возможную часть входного значения.

Метод работает аналогично методу IntlDateFormatter::parse(), за исключением обновления часового пояса форматировщика с учётом информации о часовом поясе, которая содержится в разобранной строке `string`.

### Список параметров

`string`
  Строковое представление даты и времени для преобразования в метку времени.
`offset`
  Позиция, с которой начинается разбор строки `string` при отсчёте с нуля. Параметру `offset` присвоится значение, которое соответствует количеству символов от начала входной строки до позиции окончания разбора, если до завершения разбора строки `string` не возникнет ошибка. При ошибке параметру присваивается позиция окончания разбора. При `offset` > `strlen($string)` разбор немедленно завершается.

### Возвращаемые значения

Метод возвращает метку времени разобранного значения или `false`, если значение невозможно разобрать.

### Примеры

Пример #1 Пример преобразования строки с датой в метку времени методом IntlDateFormatter::parseToCalendar()

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );

    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');

Результат выполнения приведённого примера:

    630201600

### Смотрите также

- IntlDateFormatter::parse() - Преобразовывает строку в значение отметки времени
- IntlDateFormatter::format() - Форматирует значение даты и времени как строку
- IntlDateFormatter::getErrorCode() - Получает код ошибки последней операции
- IntlDateFormatter::getErrorMessage() - Получает текст ошибки последней операции

# IntlDateFormatter::setCalendar

# datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Устанавливает тип календаря для средства форматирования

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

Процедурный стиль

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Метод устанавливает тип календаря с которым будет работать средство форматирования.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`calendar`

  Параметр принимает константы типа календаря или объект IntlCalendar. Метод использует календарь по умолчанию — `IntlDateFormatter::GREGORIAN`, если указали значение `null`.

  Метод клонирует объект IntlCalendar, который получит в аргументе; сам объект аргумента не изменится.

  Часовой пояс средства форматирования сохранится, только если объект IntlCalendar не передали, иначе новый часовой пояс будет таким же, как у объекта, который передали.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль intl 3.0.0 | Теперь метод принимает объект IntlCalendar.

### Примеры

Пример #1 Пример установки типа календаря функцией datefmt_set_calendar()

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );

    echo 'Тип календаря средства форматирования: ' . datefmt_get_calendar($fmt);

    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Теперь тип календаря: ' . datefmt_get_calendar($fmt);

    ?>

Пример #2 Пример установки типа календаря в объектно-ориентированном стиле

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );

    echo 'Тип календаря средства форматирования: ' . $fmt->getCalendar();

    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Теперь тип календаря: ' . $fmt->getCalendar();

    ?>

Результат выполнения приведённого примера:

    Тип календаря средства форматирования: 1
    Теперь тип календаря: 0

Пример #3 Пример установки типа календаря через объект IntlCalendar в аргументе

    <?php

    $time = strtotime("2013-03-03 00:00:00 UTC");
    $formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

    echo "До: ", $formatter->format($time), "\n";

    /* Обратите внимание: метод не учитывает языковой стандарт календаря! */
    $formatter->setCalendar(
        IntlCalendar::createInstance(
            "America/New_York",
            "pt_PT@calendar=islamic"
        )
    );

    echo "После: ", $formatter->format($time), "\n";

    ?>

Результат выполнения приведённого примера:

    До: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
    После: Saturday, Rabiʻ II 20, 1434 at 7:00:00 PM Eastern Standard Time

### Смотрите также

- datefmt_get_calendar() - Получает тип календаря для объекта IntlDateFormatter
- datefmt_get_calendar_object() - Получает копию объекта календаря средства форматирования
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — Устанавливает мягкий режим анализатора

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::setLenient(bool `$lenient`): void

Процедурный стиль

function datefmt_set_lenient(IntlDateFormatter `$formatter`, bool `$lenient`): void

Определяет, является ли режим анализатора строгим или мягким при интерпретации входных данных, которые в точности не соответствуют шаблону. Включение мягкого синтаксического анализа позволяет синтаксическому анализатору принимать ошибочные шаблоны даты или времени, анализируя как можно больше для получения значения. Лишний пробел, нераспознанные токены или недопустимые значения ("February 30th") не принимаются.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`lenient`

  Устанавливает, является ли анализатор мягким или нет, по умолчанию `true` (мягкий).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования datefmt_set_lenient()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Мягкий режим средства форматирования : ';
    if ($fmt->isLenient()) {
        echo 'ДА';
    } else {
        echo 'НЕТ';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nПопытка разобрать '35/13/1971'.\nРезультат : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nСообщение об ошибке : " . intl_get_error_message();
        echo "\nКод ошибки : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt, false);
    echo "\nТеперь мягкий режим средства форматирования : ";
    if ($fmt->isLenient()) {
        echo 'ДА';
    } else {
        echo 'НЕТ';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nПопытка разобрать '35/13/1971'.\nРезультат : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nСообщение об ошибке : ".intl_get_error_message();
        echo "\nКод ошибки : ".intl_get_error_code();
    }

    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'Мягкий режим средства форматирования : ';
    if ($fmt->isLenient()) {
        echo 'ДА';
    } else {
        echo 'НЕТ';
    }
    $fmt->parse('35/13/1971');
    echo "\nПопытка разобрать '35/13/1971'.\nРезультат : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nСообщение об ошибке : " . intl_get_error_message();
        echo "\nКод ошибки : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nТеперь мягкий режим средства форматирования : ";
    if ($fmt->isLenient()) {
        echo 'ДА';
    } else {
        echo 'НЕТ';
    }
    $fmt->parse('35/13/1971');
    echo "\nПопытка разобрать '35/13/1971'.\nРезультат : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nСообщение об ошибке : " . intl_get_error_message();
        echo "\nКод ошибки : " . intl_get_error_code();
    }

    ?>

Результат выполнения приведённого примера:

    Мягкий режим средства форматирования : ДА
    Попытка разобрать '35/13/1971'.
    Результат : 66038400
    Теперь мягкий режим средства форматирования : НЕТ
    Попытка разобрать '35/13/1971'.
    Результат :
    Сообщение об ошибке : Date parsing failed: U_PARSE_ERROR
    Код ошибки : 9

### Смотрите также

- datefmt_is_lenient() - Получает снисходительность, используемую для IntlDateFormatter
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::setPattern

# datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — Устанавливает шаблон, используемый IntlDateFormatter

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::setPattern(string `$pattern`): bool

Процедурный стиль

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Устанавливает шаблон, используемый IntlDateFormatter.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`pattern`

  Новая строка шаблона для использования. Возможные шаблоны можно посмотреть на » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. Обычно причиной ошибки являются плохо отформатированные строки.

### Примеры

Пример #1 Пример использования datefmt_set_pattern()

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Шаблон средства форматирования : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Первый отформатированный вывод : ', datefmt_format($fmt, 0), PHP_EOL;
    datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
    echo 'Теперь шаблон средства форматирования : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Второй отформатированный вывод : ', datefmt_format($fmt, 0), PHP_EOL;
    ?>

Пример #2 Пример использования в объектно-ориентированном стиле

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Шаблон средства форматирования : ', $fmt->getPattern(), PHP_EOL;
    echo 'Первый отформатированный вывод : ', $fmt->format(0), PHP_EOL;
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Теперь шаблон средства форматирования : ', $fmt->getPattern(), PHP_EOL;
    echo 'Второй отформатированный вывод : ', $fmt->format(0), PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    Шаблон средства форматирования : MM/dd/yyyy
    Первый отформатированный вывод : 12/31/1969
    Теперь шаблон средства форматирования : yyyyMMdd hh:mm:ss z
    Второй отформатированный вывод : 19691231 04:00:00 PST

### Смотрите также

- datefmt_get_pattern() - Получает шаблон, используемый IntlDateFormatter
- datefmt_create() - Создаёт средство форматирования даты

# IntlDateFormatter::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — Устанавливает часовой пояс средства форматирования

### Описание

Объектно-ориентированный стиль

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Процедурный стиль

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Устанавливает часовой пояс, используемый объектом IntlDateFormatter.

### Список параметров

`formatter`

  Ресурс средства форматирования.

`timezone`

  Часовой пояс для средства форматирования. Можно указать в следующих форматах:

  - Если `null`, то будет использован часовой пояс по умолчанию, заданная в ini-настройки date.timezone либо с помощью функции date_default_timezone_set() и возвращённая функцией date_default_timezone_get().

  - Объект класса IntlTimeZone.

  - Объект класса DateTimeZone. Его идентификатор будет извлечён и на его основе будет создан объект часового пояса ICU; часовой пояс будет сохранён в базе данных ICU, а не PHP.

  - Строка, являющаяся корректным идентификатором часового пояса ICU. Смотрите IntlTimeZone::createTimeZoneIDEnumeration(). "Сырые" смещения, типа `"GMT+08:30"`, также поддерживаются.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Функция теперь возвращает `true` в случае успешного выполнения; ранее она возвращала `null`.

### Примеры

Пример #1 Пример использования IntlDateFormatter::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Amsterdam');

    $formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

    $formatter->setTimeZone(NULL);
    echo "NULL\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
    echo "IntlTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
    echo "DateTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('Europe/Rome');
    echo "String\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('GMT+00:30');
    print_r($formatter->getTimeZone());

Результат выполнения приведённого примера:

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### Смотрите также

- IntlDateFormatter::getTimeZone() - Получает часовой пояс средства форматирования

## Содержание

- IntlDateFormatter::create — Создаёт средство форматирования даты
- IntlDateFormatter::format — Форматирует значение даты и времени как строку
- IntlDateFormatter::formatObject — Форматирует объект
- IntlDateFormatter::getCalendar — Получает тип календаря для объекта IntlDateFormatter
- IntlDateFormatter::getDateType — Получает тип даты, используемый IntlDateFormatter
- IntlDateFormatter::getErrorCode — Получает код ошибки последней операции
- IntlDateFormatter::getErrorMessage — Получает текст ошибки последней операции
- IntlDateFormatter::getLocale — Получает языковой стандарт, используемый средством форматирования
- IntlDateFormatter::getPattern — Получает шаблон, используемый IntlDateFormatter
- IntlDateFormatter::getTimeType — Получает тип времени, используемый IntlDateFormatter
- IntlDateFormatter::getTimeZoneId — Получает идентификатор часового пояса, используемый IntlDateFormatter
- IntlDateFormatter::getCalendarObject — Получает копию объекта календаря средства форматирования
- IntlDateFormatter::getTimeZone — Получает часовой пояс средства форматирования
- IntlDateFormatter::isLenient — Получает снисходительность, используемую для IntlDateFormatter
- IntlDateFormatter::localtime — Разбирает строку на отдельные составляющие времени, которые возвращает в ассоциативном массиве
- IntlDateFormatter::parse — Преобразовывает строку в значение отметки времени
- IntlDateFormatter::parseToCalendar — Разбирает строку в метку времени, которой обновляет открытый календарь
- IntlDateFormatter::setCalendar — Устанавливает тип календаря для средства форматирования
- IntlDateFormatter::setLenient — Устанавливает мягкий режим анализатора
- IntlDateFormatter::setPattern — Устанавливает шаблон, используемый IntlDateFormatter
- IntlDateFormatter::setTimeZone — Устанавливает часовой пояс средства форматирования

# Класс ResourceBundle

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Введение

Локализованные программные продукты часто нуждаются в наборах данных подготовленных в зависимости от текущей локали, например: сообщения, метки, шаблоны форматирования. Механизм ресурсов ICU позволяет задать наборы ресурсов, которые приложение может загрузить в зависимости от текущей локали и использовать унифицированным, не зависящим от локали, образом.

Этот класс реализует доступ к файлам ресурсов ICU. Эти файлы являются бинарными массивами данных, которые ICU использует для хранения локализованных данных.

Пакет ресурсов ICU может содержать простые и сложные ресурсы. Сложные ресурсы - это контейнеры, которые могут быть индексированы как числами так и строками (аналогично массивам PHP). Простые ресурсы могут быть следующих типов: строки, целые, бинарные поля данных и целочисленные массивы.

ResourceBundleподдерживает прямой доступ к данным через синтаксис доступа к массивам и итерироваться через foreach, так же как и доступ через методы. В результате будет получено значение PHP для простых ресурсов и объекты ResourceBundle для сложных. Все ресурсы доступны только для чтения.

## Обзор класса

class ResourceBundle implements IteratorAggregate, Countable {
/* Методы */
public function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## Список изменений

Версия | Описание
--- | ---
8.0.0 | Класс ResourceBundle теперь реализует интерфейс IteratorAggregate. Ранее был реализован интерфейс Traversable.
7.4.0 | Класс ResourceBundle теперь реализует интерфейс Countable.

## Смотрите также

- » Менеджер ресурсов ICU
- » Данные ICU

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — Получить количество элементов в пакете

### Описание

Объектно-ориентированный стиль

public function ResourceBundle::count(): int

Процедурный стиль

function resourcebundle_count(ResourceBundle `$bundle`): int

Получает количество элементов в пакете.

### Список параметров

`bundle`

  Объект ResourceBundle.

### Возвращаемые значения

Возвращает количество элементов в пакете.

### Примеры

Пример #1 Пример использования resourcebundle_count()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_count($r);
    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->count();
    ?>

Результат выполнения приведённого примера:

    42

### Смотрите также

- resourcebundle_get() - Получает данные из пакета

# ResourceBundle::create

# resourcebundle_create

# ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — Создать пакет ресурсов

### Описание

Объектно-ориентированный стиль (метод)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Процедурный стиль

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Объектно-ориентированный стиль (конструктор):

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Создаёт пакет ресурсов.

### Список параметров

`locale`

  Локаль для которой необходимо загружать ресурсы (имя локали, например, ru_RU).

`bundle`

  Директория, в которой лежат данные, либо имя .dat файла.

`fallback`

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

### Возвращаемые значения

Возвращает объект ResourceBundle или `null` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования resourcebundle_create()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Пример #2 Пример использования ResourceBundle::create()

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Результат выполнения приведённого примера:

    ¡Hola, mundo!

### Смотрите также

- resourcebundle_get() - Получает данные из пакета

# ResourceBundle::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — Получает данные из пакета

### Описание

Объектно-ориентированный стиль

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Процедурный стиль

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Метод получает данные из пакета по индексу или строковому ключу.

### Список параметров

`bundle`

  Объект класса ResourceBundle.

`index`

  Индекс данных в виде строки или целого числа.

`fallback`

  Требуется ли точное совпадение локали или откатиться к родительской локали.

### Возвращаемые значения

Метод возвращает данные из пакета по индексу или строковому ключу, или `null`, если возникла ошибка. Строки, целые числа и строки двоичных данных возвращаются как PHP-типы, которые соответствуют структуре данных, массивы целых чисел возвращаются как PHP-массивы. Сложные типы возвращаются как объекты класса ResourceBundle.

### Ошибки

При недопустимом типе смещеиня метод выбросит ошибку TypeError.

Метод выбросит ошибку ValueError, если в аргументе `index` передали значение с типом string и строка оказалсь пустой, или передали значение с типом int, которое не вписывается в 32-битный целочисленный тип.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | При недопустимом типе смещеиня метод выбросит ошибку TypeError. Метод выбросит ошибку ValueError, если в аргументе `index` передали значение с типом string и строка оказалсь пустой, или передали значение с типом int, которое не вписывается в 32-битный целочисленный тип.

### Примеры

Пример #1 Пример получения данных из пакета функцией resourcebundle_get()

    <?php

    $r = resourcebundle_create('es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');

    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php

    $r = new ResourceBundle('es', "/usr/share/data/myapp");
    echo $r->get('somestring');

    ?>

Результат выполнения приведённого примера:

    ?Hola, mundo!

### Смотрите также

- resourcebundle_count() - Получить количество элементов в пакете

# ResourceBundle::getErrorCode

# resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — Получить последний код ошибки пакета

### Описание

Объектно-ориентированный стиль

public function ResourceBundle::getErrorCode(): int

Процедурный стиль

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Возвращает код последней ошибки возникшей при вызове функций пакета.

### Список параметров

`bundle`

  Объект ResourceBundle.

### Возвращаемые значения

Возвращает код последней ошибки возникшей при вызове функций пакета.

### Примеры

Пример #1 Пример использования resourcebundle_get_error_code()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Ошибка пакета");
    }
    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Ошибка пакета");
    }
    ?>

### Смотрите также

- resourcebundle_get_error_message() - Получить последнее сообщение об ошибке пакета
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# ResourceBundle::getErrorMessage

# resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — Получить последнее сообщение об ошибке пакета

### Описание

Объектно-ориентированный стиль

public function ResourceBundle::getErrorMessage(): string

Процедурный стиль

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Возвращает последнее сообщение об ошибке при вызове функций пакета.

### Список параметров

`bundle`

  Объект ResourceBundle.

### Возвращаемые значения

Возвращает последнее сообщение об ошибке при вызове функций пакета.

### Примеры

Пример #1 Пример использования resourcebundle_get_error_message()

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Ошибка пакета: ".resourcebundle_get_error_message($r));
    }
    ?>

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Ошибка пакета: ".ResourceBundle::getErrorMessage($r));
    }
    ?>

### Смотрите также

- resourcebundle_get_error_code() - Получить последний код ошибки пакета
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя

# ResourceBundle::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — Получить поддерживаемые локали

### Описание

Объектно-ориентированный стиль

public static function ResourceBundle::getLocales(string `$bundle`): array|false

Процедурный стиль

function resourcebundle_locales(string `$bundle`): array|false

Возвращает доступные в ResourceBundle локали.

### Список параметров

`bundle`

  Путь к ResourceBundle или пустая строка, для получения списка по умолчанию или `false` в случае возникновения ошибки.

### Возвращаемые значения

Возвращает доступные в ResourceBundle локали.

### Примеры

Пример #1 Пример использования resourcebundle_locales()

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

Вывод приведённого примера будет похож на:

    es
    root

Пример #2 Пример в объектно-ориентированном стиле

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

Вывод приведённого примера будет похож на:

    es
    root

### Смотрите также

- resourcebundle_get() - Получает данные из пакета

## Содержание

- ResourceBundle::count — Получить количество элементов в пакете
- ResourceBundle::create — Создать пакет ресурсов
- ResourceBundle::get — Получает данные из пакета
- ResourceBundle::getErrorCode — Получить последний код ошибки пакета
- ResourceBundle::getErrorMessage — Получить последнее сообщение об ошибке пакета
- ResourceBundle::getLocales — Получить поддерживаемые локали

# Класс Spoofchecker

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Введение

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

Методы, которые предоставляет класс, умеют проверять строку на предмет попыток обмануть пользователя (`spoof detection`), например, вставить в слово "pаypаl" кириллический символ 'а'.

## Обзор класса

class Spoofchecker {
/* Константы */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
public const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* Методы */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## Предопределённые константы

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  Включает сопоставление без учёта регистра
`Spoofchecker::ADD_CASE_MAPPINGS` int

  Добавляет все сопоставления регистра для каждого элемента в наборе

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  Включает сопоставление без учёта регистра

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлены константы `Spoofchecker::IGNORE_SPACE`, `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.
8.4.0 | Константы класса стали типизированными.
7.3.0 | Добавили для метода Spoofchecker::setRestrictionLevel() следующие константы класса: `Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`.

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Проверить, являются ли строки подозрительными

### Описание

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Проверяет, на сколько легко перепутать две строки.

### Список параметров

`string1`

  Первая строка.

`string2`

  Вторая строка.

`errorCode`

  Этот параметр передаётся по ссылке и заполняется целым числом (int), содержащим ошибку, если таковая есть.

### Возвращаемые значения

Возвращает `true`, если две строки легко перепутать и `false`, если нет.

### Примеры

Пример #1 Пример использования Spoofchecker::areConfusable()

    <?php
    $checker = new Spoofchecker();

    $checker->areConfusable('google.com', 'goog1e.com'); // true
    // Английскую строчную "l" легко перепутать с цифрой 1

    $checker->areConfusable('google.com', 'g00g1e.com'); // false
    // Ноль (0) сложно перепутать со строчной "o"

# Spoofchecker::__construct

(No version information available, might only be in Git)

Spoofchecker::__construct — Конструктор класса

### Описание

public function Spoofchecker::__construct()

Создаёт экземпляр класса Spoofchecker.

### Список параметров

Сигнатура функции не содержит параметров.

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Проверяет, содержит ли текст подозрительные символы

### Описание

public function Spoofchecker::isSuspicious(string `$string`, int `&$errorCode` = `null`): bool

Метод проверяет, содержит ли текст подозрительные символы наподобие визуально неразличимых букв, которые при этом относятся к другому набору символов Юникода.

### Список параметров

`string`

  Строка для проверки.

`errorCode`

  Параметр передаётся по ссылке и заполняется целочисленным (int) кодом ошибки.

### Возвращаемые значения

Метод возвращает `true`, если текст содержит подозрительные символы, иначе возвращается `false`.

### Примеры

Пример #1 Пример проверки текста на подозрительные символы методом Spoofchecker::isSuspicious()

    <?php

    $checker = new Spoofchecker();

    $checker->isSuspicious('google.com'); // false: строка содержит только символы ASCII

    $checker->isSuspicious('Рaypal.com'); // true
    // Первая буква — не латинская "P", а кириллическое «эр»

# Spoofchecker::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — Задаёт набор символов, допустимых при выполнении проверок

### Описание

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

Ограничивает символы, которые последующие проверки считают допустимыми, набором, описанным в параметре `pattern`. Любой символ вне этого набора приводит к тому, что метод Spoofchecker::isSuspicious() сообщает о результате.

### Список параметров

`pattern`
  Набор символов, описанный как шаблон `UnicodeSet`, то есть класс символов в стиле регулярного выражения. Он должен начинаться с `[` и заканчиваться `]`, например `[a-z0-9]`.
`patternOptions`
  Битовая маска, управляющая тем, как интерпретируется параметр `pattern`. Должна быть `0` или `Spoofchecker::IGNORE_SPACE` по отдельности либо в сочетании ровно с одной из констант `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS` или `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.

### Возвращаемые значения

Метод не возвращает значения.

### Ошибки

Выбрасывает исключение ValueError, если параметр `pattern` не является допустимым шаблоном набора символов или если параметр `patternOptions` не является допустимой комбинацией настроек.

### Примеры

Пример #1 Пример использования метода Spoofchecker::setAllowedChars()

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)

### Смотрите также

- Spoofchecker::setAllowedLocales() - Локаль для использования в проверках
- Spoofchecker::isSuspicious() - Проверяет, содержит ли текст подозрительные символы

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — Локаль для использования в проверках

### Описание

public function Spoofchecker::setAllowedLocales(string `$locales`): void

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locales`

### Возвращаемые значения

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Установить набор проверок

### Описание

public function Spoofchecker::setChecks(int `$checks`): void

Устанавливает проверки, которые будут выполняться методом SpoofChecker::isSuspicious().

### Список параметров

`checks`

  Проверки, которые будут выполняться методом SpoofChecker::isSuspicious(). Битовая маска, состоящая из констант `Spoofchecker::SINGLE_SCRIPT_CONFUSABLE`, `Spoofchecker::MIXED_SCRIPT_CONFUSABLE`, `Spoofchecker::WHOLE_SCRIPT_CONFUSABLE`, `Spoofchecker::ANY_CASE`, `Spoofchecker::SINGLE_SCRIPT`, `Spoofchecker::INVISIBLE` или `Spoofchecker::CHAR_LIMIT`. По умолчанию все проверки, начиная с ICU 58; до этой версии константа `Spoofchecker::SINGLE_SCRIPT` была исключена.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Устанавливает уровень ограничения

### Описание

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Устанавливает уровень ограничения метода SpoofChecker::isSuspicious().

### Список параметров

`level`

  Устанавливает уровень ограничения метода SpoofChecker::isSuspicious(). Одна из констант: `Spoofchecker::ASCII`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE` или `Spoofchecker::UNRESTRICTIVE`. Значение по умолчанию `Spoofchecker::HIGHLY_RESTRICTIVE`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

## Содержание

- Spoofchecker::areConfusable — Проверить, являются ли строки подозрительными
- Spoofchecker::__construct — Конструктор класса
- Spoofchecker::isSuspicious — Проверяет, содержит ли текст подозрительные символы
- Spoofchecker::setAllowedChars — Задаёт набор символов, допустимых при выполнении проверок
- Spoofchecker::setAllowedLocales — Локаль для использования в проверках
- Spoofchecker::setChecks — Установить набор проверок
- Spoofchecker::setRestrictionLevel — Устанавливает уровень ограничения

# Класс Transliterator

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Введение

Класс предоставляет функциональность транслитерации строк.

## Обзор класса

class Transliterator {
/* Константы */
public const int FORWARD;
public const int REVERSE;
/* Свойства */
public readonly string $id;
/* Методы */
final private function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## Свойства

id

## Предопределённые константы

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.
8.2.0 | Свойство id теперь доступно только для чтения.

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — Приватный конструктор

### Описание

final private function Transliterator::__construct()

Этот метод не может быть вызван. Он существует только для закрытия возможности создания объекта с помощью оператора new.

Вместо него используйте фабричные методы Transliterator::create() или Transliterator::createFromRules().

### Список параметров

Сигнатура функции не содержит параметров.

### Смотрите также

- Transliterator::create() - Создать транслитератор
- Transliterator::createFromRules() - Создать транслитератор на основе правил

# Transliterator::create

# transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Создать транслитератор

### Описание

Объектно-ориентированный стиль

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Процедурный стиль

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Открывает объект Transliterator по идентификатору.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`id`

  Идентификатор. Список всех зарегистрированных идентификаторов транслитератора можно получить с помощью Transliterator::listIDs().

`direction`

  Направление транслитерации. По умолчанию >Transliterator::FORWARD. Можно использовать Transliterator::REVERSE.

### Возвращаемые значения

Возвращает объект Transliterator или `null` в случае возникновения ошибки.

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::__construct() - Приватный конструктор

# Transliterator::createFromRules

# transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — Создать транслитератор на основе правил

### Описание

Объектно-ориентированный стиль

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Процедурный стиль

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Создать транслитератор на основе правил.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`rules`

  Правила, которые описаны в разделе Transform Rules Syntax отчёта UTS #35: Unicode LDML.

`direction`

  Направление транслитерации. По умолчанию Transliterator::FORWARD. Можно использовать Transliterator::REVERSE.

### Возвращаемые значения

Возвращает объект Transliterator или `null` в случае возникновения ошибки.

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::create() - Создать транслитератор

# Transliterator::createInverse

# transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — Создать инвертированный транслитератор

### Описание

Объектно-ориентированный стиль

public function Transliterator::createInverse(): ?Transliterator

Процедурный стиль

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Открывает инвертированный транслитератор.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект Transliterator или `null` в случае возникновения ошибки.

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::create() - Создать транслитератор

# Transliterator::getErrorCode

# transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — Получить код последней ошибки

### Описание

Объектно-ориентированный стиль

public function Transliterator::getErrorCode(): int

Процедурный стиль

function transliterator_get_error_code(Transliterator `$transliterator`): int

Возвращает код последней ошибки.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`transliterator`

### Возвращаемые значения

Код ошибки или `false`, если ошибок не было или если получить его не удалось.

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::listIDs() - Получить идентификаторы транслитератора

# Transliterator::getErrorMessage

# transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — Получить последнее сообщение об ошибке

### Описание

Объектно-ориентированный стиль

public function Transliterator::getErrorMessage(): string

Процедурный стиль

function transliterator_get_error_message(Transliterator `$transliterator`): string

Возвращает последнее сообщение об ошибке.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`transliterator`

### Возвращаемые значения

Сообщение об ошибке или `false`, если ошибок не было или если получить его не удалось.

### Смотрите также

- Transliterator::getErrorCode() - Получить код последней ошибки
- Transliterator::listIDs() - Получить идентификаторы транслитератора

# Transliterator::listIDs

# transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Получить идентификаторы транслитератора

### Описание

Объектно-ориентированный стиль

public static function Transliterator::listIDs(): array|false

Процедурный стиль

function transliterator_list_ids(): array|false

Возвращает массив зарегистрированных идентификаторов транслитератора.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив (array) зарегистрированных идентификаторов транслитератора или `false`, если возникла ошибка.

### Примеры

Пример #1 Получение зарегистрированных идентификаторов транслитератора

    <?php
    print_r(Transliterator::listIDs());
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => ASCII-Latin
        [1] => Accents-Any
        [2] => Amharic-Latin/BGN
        [3] => Any-Accents
        [4] => Any-Publishing
    ...
        [650] => Any-ps_Latn/BGN
        [651] => Any-tk/BGN
        [652] => Any-ch_FONIPA
        [653] => Any-cs_FONIPA
        [654] => Any-cy_FONIPA
    )

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::transliterate() - Транслитерировать строку

# Transliterator::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — Транслитерировать строку

### Описание

Объектно-ориентированный стиль

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

Процедурный стиль

function transliterator_transliterate(
Transliterator|string `$transliterator`,
string `$string`,
int `$start` = 0,
int `$end` = -1
): string|false

Преобразовывает строку или её часть, используя транслитератор ICU.

### Список параметров

`transliterator`

  В процедурном варианте, Transliterator или строка, из которой может быть собран объект Transliterator.

`string`

  Строка для транслитерации.

`start`

  Начальный индекс, включительно, (в кодовых единицах UTF-16), с которого начинается часть строки, предназначенная для транслитерации. Индексация начинается с 0. Текст до этой позиции останется как есть.

`end`

  Начальный индекс, не включая, (в кодовых единицах UTF-16), которым заканчивается часть строки, предназначенная для транслитерации. Индексация начинается с 0. Текст с этой позиции останется как есть.

### Возвращаемые значения

Возвращает преобразованную строка в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Конвертация экранированной UTF-16 строки

    <?php
    $s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
    echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

    //теперь обратная операция с дополнительным символом
    $supplChar = html_entity_decode('&#x1D11E;');
    echo mb_strlen($supplChar, "UTF-8"), "\n";
    $encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
    //вывод двух кодированных UTF-16 символов
    echo $encSupplChar, "\n";
    //и назад
    echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
    ?>

Вывод приведённого примера будет похож на:

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### Смотрите также

- Transliterator::getErrorMessage() - Получить последнее сообщение об ошибке
- Transliterator::__construct() - Приватный конструктор

## Содержание

- Transliterator::__construct — Приватный конструктор
- Transliterator::create — Создать транслитератор
- Transliterator::createFromRules — Создать транслитератор на основе правил
- Transliterator::createInverse — Создать инвертированный транслитератор
- Transliterator::getErrorCode — Получить код последней ошибки
- Transliterator::getErrorMessage — Получить последнее сообщение об ошибке
- Transliterator::listIDs — Получить идентификаторы транслитератора
- Transliterator::transliterate — Транслитерировать строку

# Класс IntlBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Итератор прерывания (Break iterator) - это объект ICU предоставляющий методы для определения границ в тексте (например границы слова или предложения). В PHP класс IntlBreakIterator служит базовым классом для всех типов итераторов прерывания ICU. Есть и дополнительная функциональность, модуль intl может расширять этот класс подходящими подклассами, такими как IntlRuleBasedBreakIterator или IntlCodePointBreakIterator.

Этот класс реализует интерфейс IteratorAggregate. Итерация IntlBreakIterator порождает неотрицательные целые значения, представляющие из себя успешное нахождение границ в тексте, и равные позиции найденного символа UTF-8 отсчитанной от начала текста (позиция первого символа равна `0`). Ключи возвращённых значений представляют из себя последовательность натуральных чисел `{0, 1, 2, …}`.

## Обзор класса

class IntlBreakIterator implements IteratorAggregate {
/* Константы */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* Методы */
private function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## Предопределённые константы

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.
8.0.0 | Класс IntlBreakIterator теперь реализует интерфейс IteratorAggregate. Раньше вместо этого класс реализовывал интерфейс Traversable.

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — Закрытый конструктор, запрещающий создание экземпляров объекта

### Описание

private function IntlBreakIterator::__construct()

Экземпляры IntlBreakIterator должны быть созданы с помощью одного из статических фабричных методов.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

### Смотрите также

- IntlBreakIterator::createCharacterInstance() - Создаёт итератор прерывания для границ комбинирования последовательностей символов
- IntlBreakIterator::createCodePointInstance() - Создаёт итератор прерывания для границ кодовых точек
- IntlBreakIterator::createLineInstance() - Создаёт итератор прерывания для логически возможных разрывов строк
- IntlBreakIterator::createSentenceInstance() - Создаёт итератор прерывания для разрывов предложений
- IntlBreakIterator::createTitleInstance() - Создаёт итератор прерывания для разрывов заголовков
- IntlBreakIterator::createWordInstance() - Создаёт итератор прерывания для разрывов слов

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — Создаёт итератор прерывания для границ комбинирования последовательностей символов

### Описание

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locale`

### Возвращаемые значения

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Создаёт итератор прерывания для границ кодовых точек

### Описание

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Создаёт итератор прерывания для логически возможных разрывов строк

### Описание

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locale`

### Возвращаемые значения

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Создаёт итератор прерывания для разрывов предложений

### Описание

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locale`

### Возвращаемые значения

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Создаёт итератор прерывания для разрывов заголовков

### Описание

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locale`

### Возвращаемые значения

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Создаёт итератор прерывания для разрывов слов

### Описание

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`locale`

### Возвращаемые значения

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Возвращает индекс текущей позиции

### Описание

public function IntlBreakIterator::current(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Устанавливает позицию к первому символу в тексте

### Описание

public function IntlBreakIterator::first(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Перемещает итератор к первой границе после указанного смещения

### Описание

public function IntlBreakIterator::following(int `$offset`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`offset`

### Возвращаемые значения

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — Возвращает последний код ошибки объекта

### Описание

Объектно-ориентированный стиль (метод):

public function IntlBreakIterator::getErrorCode(): int

Процедурный стиль:

function intl_get_error_code(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — Возвращает последнее сообщение об ошибке объекта

### Описание

Объектно-ориентированный стиль (метод):

public function IntlBreakIterator::getErrorMessage(): string

Процедурный стиль:

function intl_get_error_message(): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Возвращает локаль, связанную с объектом

### Описание

public function IntlBreakIterator::getLocale(int `$type`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`type`

### Возвращаемые значения

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Создаёт итератор для перемещения фрагментов между границами

### Описание

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`type`

  Необязательный тип ключа. Возможные значения:

  - `IntlPartsIterator::KEY_SEQUENTIAL` - Значение по умолчанию. Последовательно увеличивает целые числа, используемые в качестве ключа.
  - `IntlPartsIterator::KEY_LEFT` - Байтовое смещение слева от текущей части, используемой в качестве ключа.
  - `IntlPartsIterator::KEY_RIGHT` - Байтовое смещение справа от текущей части, используемой в качестве ключа.

### Возвращаемые значения

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Возвращает сканируемый текст

### Описание

public function IntlBreakIterator::getText(): ?string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Сообщает, является ли смещение смещением границы

### Описание

public function IntlBreakIterator::isBoundary(int `$offset`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`offset`

### Возвращаемые значения

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Устанавливает позицию итератора к индексу за последним символом

### Описание

public function IntlBreakIterator::last(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Перемещает итератор к следующей границе

### Описание

public function IntlBreakIterator::next(?int `$offset` = `null`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`offset`

### Возвращаемые значения

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Устанавливает позицию итератора к первой границе перед смещением

### Описание

public function IntlBreakIterator::preceding(int `$offset`): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`offset`

### Возвращаемые значения

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Устанавливает позицию итератора на границе непосредственно перед текущей

### Описание

public function IntlBreakIterator::previous(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Устанавливает сканируемый текст

### Описание

public function IntlBreakIterator::setText(string `$text`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`text`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь метод возвращает `false` в случае ошибки; ранее он возвращал `null`.

## Содержание

- IntlBreakIterator::__construct — Закрытый конструктор, запрещающий создание экземпляров объекта
- IntlBreakIterator::createCharacterInstance — Создаёт итератор прерывания для границ комбинирования последовательностей символов
- IntlBreakIterator::createCodePointInstance — Создаёт итератор прерывания для границ кодовых точек
- IntlBreakIterator::createLineInstance — Создаёт итератор прерывания для логически возможных разрывов строк
- IntlBreakIterator::createSentenceInstance — Создаёт итератор прерывания для разрывов предложений
- IntlBreakIterator::createTitleInstance — Создаёт итератор прерывания для разрывов заголовков
- IntlBreakIterator::createWordInstance — Создаёт итератор прерывания для разрывов слов
- IntlBreakIterator::current — Возвращает индекс текущей позиции
- IntlBreakIterator::first — Устанавливает позицию к первому символу в тексте
- IntlBreakIterator::following — Перемещает итератор к первой границе после указанного смещения
- IntlBreakIterator::getErrorCode — Возвращает последний код ошибки объекта
- IntlBreakIterator::getErrorMessage — Возвращает последнее сообщение об ошибке объекта
- IntlBreakIterator::getLocale — Возвращает локаль, связанную с объектом
- IntlBreakIterator::getPartsIterator — Создаёт итератор для перемещения фрагментов между границами
- IntlBreakIterator::getText — Возвращает сканируемый текст
- IntlBreakIterator::isBoundary — Сообщает, является ли смещение смещением границы
- IntlBreakIterator::last — Устанавливает позицию итератора к индексу за последним символом
- IntlBreakIterator::next — Перемещает итератор к следующей границе
- IntlBreakIterator::preceding — Устанавливает позицию итератора к первой границе перед смещением
- IntlBreakIterator::previous — Устанавливает позицию итератора на границе непосредственно перед текущей
- IntlBreakIterator::setText — Устанавливает сканируемый текст

# Класс IntlRuleBasedBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Подкласс IntlBreakIterator, который реализует итератор прерываний ICU, чьё поведение задано набором правил. Это наиболее часто используемый тип итератора прерываний.

Правила описаны в разделе » Руководство пользователя по анализу границ ICU.

## Обзор класса

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* Наследуемые константы */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Методы */
public function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* Наследуемые методы */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — Создаёт итератор на основе набора правил

### Описание

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`rules`

`compiled`

### Возвращаемые значения

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Получить бинарные данные из скомпилированных правил

### Описание

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Получить набор правил, использовавшихся при создании этого объекта

### Описание

public function IntlRuleBasedBreakIterator::getRules(): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — Получить наибольшее значение статуса правил останова, определившее текущую позицию остановки

### Описание

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — получить значения статусов из правил останова, определивших текущую позицию остановки

### Описание

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- IntlRuleBasedBreakIterator::__construct — Создаёт итератор на основе набора правил
- IntlRuleBasedBreakIterator::getBinaryRules — Получить бинарные данные из скомпилированных правил
- IntlRuleBasedBreakIterator::getRules — Получить набор правил, использовавшихся при создании этого объекта
- IntlRuleBasedBreakIterator::getRuleStatus — Получить наибольшее значение статуса правил останова, определившее текущую позицию остановки
- IntlRuleBasedBreakIterator::getRuleStatusVec — получить значения статусов из правил останова, определивших текущую позицию остановки

# Класс IntlCodePointBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Этот итератор прерываний указывает на границы между кодами символов UTF-8.

## Обзор класса

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* Наследуемые константы */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Методы */
public function getLastCodePoint(): int
/* Наследуемые методы */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — Получить последний код символа, выданный при перемещении итератора вперёд или назад

### Описание

public function IntlCodePointBreakIterator::getLastCodePoint(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- IntlCodePointBreakIterator::getLastCodePoint — Получить последний код символа, выданный при перемещении итератора вперёд или назад

# Класс IntlDatePatternGenerator

(PHP 8 >= 8.1.0)

## Введение

Создаёт локализованные строки шаблонов формата даты и/или времени, подходящие для использования в IntlDateFormatter.

## Обзор класса

class IntlDatePatternGenerator {
/* Методы */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — Создаёт новый экземпляр IntlDatePatternGenerator

### Описание

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Создаёт новый экземпляр IntlDatePatternGenerator.

### Список параметров

`locale`

  Локаль. Если передано значение `null`, используется ini-параметр intl.default_locale.

### Возвращаемые значения

Возвращает экземпляр IntlDatePatternGenerator в случае успешного выполнения или `null` в случае возникновения ошибки.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Определяет наиболее подходящий формат даты/времени

### Описание

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Определяет, какой формат даты/времени наиболее подходит для конкретной локали.

### Список параметров

`skeleton`

  Каркас.

### Возвращаемые значения

Возвращает шаблон даты/времени ICU, принимаемый IntlDateFormatter в случае успешного выполнения, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования IntlDatePatternGenerator::getBestPattern()

    <?php

    $skeleton = 'YYYYMMdd';
    $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

    $patternGenerator = new \IntlDatePatternGenerator('de_DE');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'Немецкий: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

    $patternGenerator = new \IntlDatePatternGenerator('en_US');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'Английский: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
    ?>

Результат выполнения приведённого примера:

    Немецкий: 24.04.2021
    Английский: 04/24/2021

## Содержание

- IntlDatePatternGenerator::create — Создаёт новый экземпляр IntlDatePatternGenerator
- IntlDatePatternGenerator::getBestPattern — Определяет наиболее подходящий формат даты/времени

# Класс IntlPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Объекты данного класса можно получить из объектов IntlBreakIterator. Пока итератор прерывания предоставляет последовательность ограничителей, можно получить IntlPartsIterator для удобства получения текстовых фрагментов между двумя ограничителями.

Ключи могут представлять собой смещения от левого или правого ограничителя или могут быть просто последовательностью натуральных чисел. Смотрите IntlBreakIterator::getPartsIterator().

## Обзор класса

class IntlPartsIterator extends IntlIterator {
/* Константы */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* Методы */
public function getBreakIterator(): IntlBreakIterator
/* Наследуемые методы */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## Предопределённые константы

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — Получить IntlBreakIterator сохраняя итератор этой части

### Описание

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- IntlPartsIterator::getBreakIterator — Получить IntlBreakIterator сохраняя итератор этой части

# Класс UConverter

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Введение

## Обзор класса

class UConverter {
/* Константы */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* Методы */
public function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## Предопределённые константы

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Создать объект UConverter

### Описание

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`destination_encoding`

`source_encoding`

### Возвращаемые значения

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Конвертировать строку из одной кодировки в другую

### Описание

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`str`

`reverse`

### Возвращаемые значения

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Callback-функция по умолчанию для "from"

### Описание

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`reason`

`source`

`codePoint`

`error`

### Возвращаемые значения

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Получить псевдонимы для заданного имени

### Описание

public static function UConverter::getAliases(string `$name`): array|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`name`

### Возвращаемые значения

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Получить доступные имена канонических конверторов

### Описание

public static function UConverter::getAvailable(): array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Получить кодировку назначения

### Описание

public function UConverter::getDestinationEncoding(): string|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Получить тип конвертера назначения

### Описание

public function UConverter::getDestinationType(): int|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — Получить код последней ошибки объекта

### Описание

public function UConverter::getErrorCode(): int

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Получить последнее сообщение об ошибке в объекте

### Описание

public function UConverter::getErrorMessage(): ?string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Получить исходную кодировку

### Описание

public function UConverter::getSourceEncoding(): string|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Получить тип конвертера источника

### Описание

public function UConverter::getSourceType(): int|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Получить стандарты, связанные с именами конвертеров

### Описание

public static function UConverter::getStandards(): ?array

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Получить замену символов

### Описание

public function UConverter::getSubstChars(): string|false|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Получить строковое представление причины обратного вызова

### Описание

public static function UConverter::reasonText(int `$reason`): string

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`reason`

### Возвращаемые значения

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Установить кодировку назначения

### Описание

public function UConverter::setDestinationEncoding(string `$encoding`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`encoding`

### Возвращаемые значения

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Установить исходную кодировку

### Описание

public function UConverter::setSourceEncoding(string `$encoding`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`encoding`

### Возвращаемые значения

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Установка символов подстановки

### Описание

public function UConverter::setSubstChars(string `$chars`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`chars`

### Возвращаемые значения

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Callback-функция по умолчанию для "to"

### Описание

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`reason`

`source`

`codeUnits`

`error`

### Возвращаемые значения

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — Преобразовывает строку из одной кодировки символов в другую

### Описание

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Преобразовывает строку `str` из кодировки `fromEncoding` в `toEncoding`.

### Список параметров

`str`

  Строка (string) для преобразования.

`toEncoding`

  Требуемая кодировка результата.

`fromEncoding`

  Текущая кодировка строки `str`.

`options`

  Необязательный массив (array), который может содержать следующие ключи:

  - `'to_subst'` - подстановочный символ, используемый вместо любого символа строки `str`, который не может быть закодирован в `toEncoding`. Если ключ указан, он должен представлять один символ в целевой кодировке.

### Возвращаемые значения

Возвращает преобразованную строку или `false`, если возникла ошибка.

### Примеры

Пример #1 Преобразование из UTF-8 в UTF-16 и обратно

    <?php
    $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' в UTF-8
    $utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";

    $new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
    echo bin2hex($new_utf8_string), "\n";
    ?>

Результат выполнения приведённого примера:

    005a006f00eb
    5a6fc3ab

Пример #2 Недопустимые символы во входной строке

Если входная строка содержит последовательность байтов, которая не является допустимой в кодировке, указанной в `fromEncoding`, то перед преобразованием в `toEncoding` она заменяется кодовой точкой Unicode U+FFFD (Заменяющий символ).

    <?php
    $invalid_utf8_string = "\xC3"; // неполная многобайтовая последовательность UTF-8
    $utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";
    ?>

Результат выполнения приведённого примера:

    fffd

Пример #3 Символы, которые не могут быть закодированы

Если входная строка содержит символы, которые не могут быть представлены в кодировке `toEncoding`, они заменяются одним символом. Используемый по умолчанию символ зависит от кодировки и может управляться с помощью параметра `'to_subst'`.

    <?php
    $utf8_string = "\xE2\x82\xAC"; // € (Знак евро) не существует в ISO 8859-1

    // Замена по умолчанию в ISO 8859-1 - "\x1A" (Заменитель)
    $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
    echo bin2hex($iso8859_1_string), "\n";

    // Использование в качестве заменителя символа '?' ("\x3F").
    $iso8859_1_string = UConverter::transcode(
        $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";

    // Поскольку ISO 8859-1 не может отобразить U+FFFD, недействительная входная строка также заменяется на to_subst
    $invalid_utf8_string = "\xC3"; // неполная многобайтовая последовательность UTF-8
    $iso8859_1_string = UConverter::transcode(
        $invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";
    ?>

Результат выполнения приведённого примера:

    1a
    3f
    3f

### Смотрите также

- mb_convert_encoding() - Преобразовывает строку из одной кодировки символов в другую
- iconv() - Преобразовывает строку из одной кодировки символов в другую

## Содержание

- UConverter::__construct — Создать объект UConverter
- UConverter::convert — Конвертировать строку из одной кодировки в другую
- UConverter::fromUCallback — Callback-функция по умолчанию для "from"
- UConverter::getAliases — Получить псевдонимы для заданного имени
- UConverter::getAvailable — Получить доступные имена канонических конверторов
- UConverter::getDestinationEncoding — Получить кодировку назначения
- UConverter::getDestinationType — Получить тип конвертера назначения
- UConverter::getErrorCode — Получить код последней ошибки объекта
- UConverter::getErrorMessage — Получить последнее сообщение об ошибке в объекте
- UConverter::getSourceEncoding — Получить исходную кодировку
- UConverter::getSourceType — Получить тип конвертера источника
- UConverter::getStandards — Получить стандарты, связанные с именами конвертеров
- UConverter::getSubstChars — Получить замену символов
- UConverter::reasonText — Получить строковое представление причины обратного вызова
- UConverter::setDestinationEncoding — Установить кодировку назначения
- UConverter::setSourceEncoding — Установить исходную кодировку
- UConverter::setSubstChars — Установка символов подстановки
- UConverter::toUCallback — Callback-функция по умолчанию для "to"
- UConverter::transcode — Преобразовывает строку из одной кодировки символов в другую

# Функции Grapheme

# grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — Функция для извлечения последовательности кластеров графем по умолчанию из текстового буфера, которая должна быть закодирована в UTF-8

### Описание

Процедурный стиль

function grapheme_extract(
string `$haystack`,
int `$size`,
int `$type` = `GRAPHEME_EXTR_COUNT`,
int `$offset` = 0,
int `&$next` = `null`
): string|false

Функция для извлечения последовательности кластеров графем по умолчанию из текстового буфера, которая должна быть закодирована в UTF-8.

### Список параметров

`haystack`

  Строка для поиска.

`size`

  Максимальное количество возвращаемых элементов на основе `type`.

`type`

  Определяет тип единиц, на которые указывает параметр `size`:

  - GRAPHEME_EXTR_COUNT (по умолчанию) - `size` - это количество кластеров графемы для извлечения по умолчанию.
  - GRAPHEME_EXTR_MAXBYTES - `size` - максимальное количество возвращаемых байтов.
  - GRAPHEME_EXTR_MAXCHARS - `size` - это максимальное количество возвращаемых символов UTF-8.
`offset`

  Начальная позиция `haystack` в байтах - если задано, оно должно быть нулём или положительным значением, которое меньше или равно длине `haystack` в байтах, либо отрицательным значением, отсчитываемым от конца `haystack`. Если `offset` не указывает на первый байт символа UTF-8, начальная позиция перемещается на границу следующего символа.

`next`

  Ссылка на значение, которое будет установлено для следующей начальной позиции. Когда вызов возвращается, это может указывать на позицию первого байта за концом строки.

### Возвращаемые значения

Строка, начинающаяся со смещения `offset` и заканчивающаяся границей кластера графемы по умолчанию, которая соответствует указанным `size` и `type` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Добавлена поддержка отрицательных значений `offset`.

### Примеры

Пример #1 Пример использования grapheme_extract()

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

    ?>

Результат выполнения приведённого примера:

    o%CC%88

### Смотрите также

- grapheme_substr() - Возвращает часть строки в графемных кластерах
- » Сегментация текста в Unicode: границы кластера графемы

# grapheme_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — Разбивает строку на массив графемных кластеров

### Описание

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

Функция возвращает массив строк и работает аналогично функции str_split(), но разбивает строку по графемным кластерам — последовательностям одно- или многобайтовых кодовых точек, которыми кодируется единое для восприятия графическое представление символа. Функция разбивает строку на части заданной длины, если передали аргумент `length`; длина отдельной части измеряется не в байтах, а в графемных кластерах.

### Список параметров

`string`

  Строка (string), которую требуется разбить на части из одного или большего количества графемных кластеров. Параметр `string` принимает строку, которая соответствует стандарту UTF-8.

`length`

  Параметр `length` определяет максимум графемных кластеров в одном элементе массива.

### Возвращаемые значения

Функция grapheme_str_split() возвращает массив строк или `false`, если возникла ошибка.

### Ошибки

Функция выбросит ошибку ValueError, если значение параметра `length` окажется меньше `1`.

### Смотрите также

- str_split() - Преобразовывает строку в массив
- mb_str_split() - Возвращает массив символов многобайтовой строки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра

### Описание

Процедурный стиль

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Функция находит позицию первого вхождения подстроки без учёта регистра. Позиция вычисляется в графемных кластерах.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти.

`offset`

  Необязательный параметр `offset` указывает смещение, с которого начнётся поиск в строке `haystack`. Смещение вычисляется в графемных кластерах, а не в байтах или символах. Отрицательные смещения отсчитываются с конца строки, но позиция по-прежнему вычисляется с начала строки `haystack`, независимо от значения параметра `offset`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает позицию в виде целого числа. Функция grapheme_stripos() вернёт значение `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.
7.1.0 | Параметр `offset` теперь поддерживает отрицательные значения.

### Примеры

Пример #1 Пример поиска позиции первого вхождения подстроки функцией grapheme_stripos()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    // Ö: 'LATIN CAPITAL LETTER O WITH DIAERESIS', U+00D6, NFD
    $char_O_diaeresis_nfd = "O\xCC\x88";

    print grapheme_stripos(
        $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd,
        $char_O_diaeresis_nfd
    );

Результат выполнения приведённого примера:

    2

### Смотрите также

- grapheme_stristr() - Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_strpos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strripos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strrpos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- grapheme_strstr() - Возвращает часть строки относительно первого вхождения подстроки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — Возвращает часть строки относительно первого вхождения подстроки без учёта регистра

### Описание

Процедурный стиль

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

По умолчанию функция возвращает часть строки `haystack` от первого вхождения подстроки до конца строки `haystack`. Функция ищет подстроку без учёта регистра.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти в строке.

`beforeNeedle`

  При передаче значения `true` функция grapheme_stristr() возвращает часть строки `haystack` до первого вхождения подстроки `needle`, не включая подстроку `needle`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает часть строки `haystack`. Функция вернёт значение `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.

### Примеры

Пример #1 Пример извлечения части строки функцией grapheme_stristr()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    // Ö: 'LATIN CAPITAL LETTER O WITH DIAERESIS', U+00D6, NFD
    $char_O_diaeresis_nfd = "O\xCC\x88";

    print urlencode(grapheme_stristr(
        $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd,
        $char_O_diaeresis_nfd
    ));

Результат выполнения приведённого примера:

    o%CC%88a%CC%8A

### Смотрите также

- grapheme_stripos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strpos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strripos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strrpos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- grapheme_strstr() - Возвращает часть строки относительно первого вхождения подстроки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — Получает количество графемных кластеров в строке

### Описание

Процедурный стиль

function grapheme_strlen(string `$string`): int|false|null

Функция возвращает количество графемных кластеров в строке, а не длину в байтах или символах.

### Список параметров

`string`

  Строка по стандарту UTF-8, в которой требуется посчитать количество графемных кластеров.

### Возвращаемые значения

Функция возвращает количество графемных кластеров в строке, если выполнилась успешно, `null` или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример подсчёта графемных кластеров в строке функцией grapheme_strlen()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, D
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, D
    $char_o_diaeresis_nfd = "o\xCC\x88";

    print grapheme_strlen('abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

Результат выполнения приведённого примера:

    6

### Смотрите также

- » Сегментация текста в Юникоде: Границы графемных кластеров
- iconv_strlen() - Возвращает количество символов в строке
- mb_strlen() - Получает длину строки
- strlen() - Получает длину строки

# grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — Вычисляет позицию первого вхождения подстроки в графемных кластерах

### Описание

Процедурный стиль

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Функция находит позицию первого вхождения подстроки. Позиция вычисляется в графемных кластерах.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти.

`offset`

  Необязательный параметр `offset` указывает смещение, с которого начнётся поиск в строке `haystack`. Смещение вычисляется в графемных кластерах, а не в байтах или символах. Отрицательные смещения отсчитываются с конца строки, но позиция по-прежнему вычисляется с начала строки `haystack`, независимо от значения параметра `offset`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает позицию в виде целого числа. Функция grapheme_strpos() вернёт значение `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.
7.1.0 | Параметр `offset` теперь поддерживает отрицательные значения.

### Примеры

Пример #1 Пример использования grapheme_strpos()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    print grapheme_strpos(
        $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd,
        $char_o_diaeresis_nfd
    );

Результат выполнения приведённого примера:

    2

### Смотрите также

- grapheme_stripos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_stristr() - Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_strripos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strrpos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- grapheme_strstr() - Возвращает часть строки относительно первого вхождения подстроки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра

### Описание

Процедурный стиль

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Функция находит позицию последнего вхождения подстроки без учёта регистра. Позиция вычисляется в графемных кластерах.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти.

`offset`

  Необязательный параметр `offset` указывает смещение, с которого начнётся поиск в строке `haystack`. Смещение вычисляется в графемных кластерах, а не в байтах или символах. Отрицательные смещения отсчитываются с конца строки, но позиция по-прежнему вычисляется с начала строки `haystack`, независимо от значения параметра `offset`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает позицию в виде целого числа. Функция grapheme_strripos() вернёт `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.

### Примеры

Пример #1 Пример поиска позиции последнего вхождения подстроки функцией grapheme_strripos()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    // Ö: 'LATIN CAPITAL LETTER O WITH DIAERESIS', U+00D6, NFD
    $char_O_diaeresis_nfd = "O\xCC\x88";

    print grapheme_strripos(
        $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd,
        $char_O_diaeresis_nfd
    );

Результат выполнения приведённого примера:

    2

### Смотрите также

- grapheme_stripos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_stristr() - Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_strpos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strrpos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- grapheme_strstr() - Возвращает часть строки относительно первого вхождения подстроки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах

### Описание

Процедурный стиль

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Функция находит позицию последнего вхождения подстроки. Позиция вычисляется в графемных кластерах.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти.

`offset`

  Необязательный параметр `offset` указывает смещение, с которого начнётся поиск в строке `haystack`. Смещение вычисляется в графемных кластерах, а не в байтах или символах. Отрицательные смещения отсчитываются с конца строки, но позиция по-прежнему вычисляется с начала строки `haystack`, независимо от значения параметра `offset`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает позицию в виде целого числа. Функция grapheme_strrpos() вернёт `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.
7.1.0 | Параметр `offset` теперь поддерживает отрицательные значения.

### Примеры

Пример #1 Пример поиска позиции последнего вхождения подстроки функцией grapheme_strrpos()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    print grapheme_strrpos(
        $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd,
        $char_o_diaeresis_nfd
    );

Результат выполнения приведённого примера:

    2

### Смотрите также

- grapheme_stripos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_stristr() - Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_strpos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strripos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strstr() - Возвращает часть строки относительно первого вхождения подстроки
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — Возвращает часть строки относительно первого вхождения подстроки

### Описание

Процедурный стиль

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

По умолчанию функция возвращает часть строки `haystack` от первого вхождения подстроки до конца строки `haystack`.

### Список параметров

`haystack`

  Строка по стандарту UTF-8, в которой требуется найти подстроку.

`needle`

  Подстрока по стандарту UTF-8, которую требуется найти.

`beforeNeedle`

  При передаче значения `true` функция grapheme_strstr() возвращает часть строки `haystack` до первого вхождения подстроки `needle`, не включая подстроку `needle`.

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает часть строки `haystack`. Функция grapheme_strstr() вернёт `false`, если не найдёт подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.

### Примеры

Пример #1 Пример извлечения части строки функцией grapheme_strstr()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    print urlencode(grapheme_strstr(
        $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd,
        $char_o_diaeresis_nfd
    ));
    ?>

Результат выполнения приведённого примера:

    o%CC%88a%CC%8A

### Смотрите также

- grapheme_stristr() - Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_stripos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strpos() - Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strripos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strrpos() - Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- » Сегментация текста в Юникоде: Границы графемных кластеров

# grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — Возвращает часть строки в графемных кластерах

### Описание

Процедурный стиль

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Функция возвращает часть строки. Смещение и длина измеряются в графемных кластерах.

### Список параметров

`string`

  Входная строка по стандарту UTF-8, часть которой требуется вернуть.

`offset`

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

`length`

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

`locale`
  Идентификатор языковых и региональных параметров.

### Возвращаемые значения

Функция возвращает подстроку, которую извлекла из строки `string`, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавили необязательный параметр `locale`.
8.0.0 | Функция теперь автоматически уменьшает или увеличивает значение смещения, которое выходит за пределы строки; раньше при выходе смещения за границы строки вместо пустой строки возвращалось значение `false`.

### Примеры

Пример #1 Пример извлечения подстроки в графемных кластерах функцией grapheme_substr()

    <?php

    // Символ | Название | Кодовая точка | Форма нормализации

    // å: 'LATIN SMALL LETTER A WITH RING ABOVE', U+00E5, NFD
    $char_a_ring_nfd = "a\xCC\x8A";

    // ö: 'LATIN SMALL LETTER O WITH DIAERESIS', U+00F6, NFD
    $char_o_diaeresis_nfd = "o\xCC\x88";

    echo urlencode(grapheme_substr("ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1));

Результат выполнения приведённого примера:

    a%CC%8Abco%CC%88

### Смотрите также

- grapheme_extract() - Функция для извлечения последовательности кластеров графем по умолчанию из текстового буфера, которая должна быть закодирована в UTF-8
- » Сегментация текста в Юникоде: Границы графемных кластеров

## Содержание

- grapheme_extract — Функция для извлечения последовательности кластеров графем по умолчанию из текстового буфера, которая должна быть закодирована в UTF-8
- grapheme_str_split — Разбивает строку на массив графемных кластеров
- grapheme_stripos — Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_stristr — Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
- grapheme_strlen — Получает количество графемных кластеров в строке
- grapheme_strpos — Вычисляет позицию первого вхождения подстроки в графемных кластерах
- grapheme_strripos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
- grapheme_strrpos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах
- grapheme_strstr — Возвращает часть строки относительно первого вхождения подстроки
- grapheme_substr — Возвращает часть строки в графемных кластерах

# Функции IDN

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — Преобразовывает доменное имя в формат ASCII по спецификации IDNA

### Описание

Процедурный стиль

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Функция преобразовывает доменные имена в кодировке Юникод в формат, совместимый со стандартом ASCII, и возвращает результат в нижнем регистре. Доменные имена, в состав которых входят символы национальных алфавитов, обрабатываются по правилам механизма интернационализации доменных имён в приложениях — IDNA (англ. Internationalizing Domain Names in Applications).

### Список параметров

`domain`

  Домен с символами в кодировке UTF-8, которые требуется преобразовать.

`flags`

  Опции преобразования — комбинация констант семейства IDNA_*, кроме констант семейства IDNA_ERROR_*.

`variant`

  Константа `INTL_IDNA_VARIANT_2003` (устарела с PHP 7.2.0) для преобразования домена по правилам спецификации IDNA 2003 или константа `INTL_IDNA_VARIANT_UTS46` (доступна только с ICU 4.6) для преобразования по правилам спецификации UTS #46.

`idna_info`

  Параметр влияет на результат только при передаче константы `INTL_IDNA_VARIANT_UTS46` в параметр `variant`. Функция заполнит переменную массивом с ключами `'result'` — домен в ASCII-формате, возможно, с ошибками преобразования, `'isTransitionalDifferent'` — логическое значение, которое указывает, повлиял ли переходный механизм протокола UTS #46 на результат или мог бы повлиять, и `'errors'` — значение int, которое представляет битовую маску из констант семейства IDNA_ERROR_*.

### Возвращаемые значения

Функция возвращает доменное имя, закодированное в формате, совместимом со стандартом ASCII, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь выбрасывает исключение ValueError, если параметр `domain` пустой.
8.4.0 | Теперь выбрасывает исключение ValueError, если параметр `variant` не равен `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | Значением по умолчанию для параметра `variant` стала константа `INTL_IDNA_VARIANT_UTS46` вместо устаревшего варианта `INTL_IDNA_VARIANT_2003`.
7.2.0 | Константа `INTL_IDNA_VARIANT_2003` устарела в пользу варианта `INTL_IDNA_VARIANT_UTS46`.

### Примеры

Пример #1 Пример преобразования национального доменного имени функцией idn_to_ascii()

    <?php

    echo idn_to_ascii('täst.de');

    ?>

Результат выполнения приведённого примера:

    xn--tst-qla.de

Пример #2 Пример обработки доменного имени, которое состоит только из ASCII-символов

    <?php

    // ASCII-домены функция только приводит к нижнему регистру
    var_dump(idn_to_ascii('Example.com'));

    ?>

Результат выполнения приведённого примера:

    string(11) "example.com"

### Смотрите также

- idn_to_utf8() - Преобразование доменного имени из IDNA ASCII в Unicode

# idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — Преобразование доменного имени из IDNA ASCII в Unicode

### Описание

Процедурный стиль

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

Эта функция преобразовывает доменные имена из формата IDNA ASCII в Unicode, в кодировке UTF-8.

### Список параметров

`domain`

  Доменное имя в формате IDNA ASCII.

`flags`

  Опции преобразования - комбинация констант IDNA_* (кроме констант IDNA_ERROR_*).

`variant`

  `INTL_IDNA_VARIANT_2003` (объявлена устаревшей начиная с PHP 7.2.0) для IDNA 2003 или `INTL_IDNA_VARIANT_UTS46` (доступна только с ICU 4.6) для UTS #46.

`idna_info`

  Этот параметр используется только если используется `INTL_IDNA_VARIANT_UTS46` в `variant`. В этом случае он будет заполнен массивом с ключами `'result'`, возможными ошибочными результатами преобразования, `'isTransitionalDifferent'`, логическое выражение означает изменило или могло бы изменить результат при использовании сквозного механизма UTS #46, и `'errors'`, содержащими целочисленное представление битовой маски из констант IDNA_ERROR_*.

### Возвращаемые значения

Возвращает доменное имя, перекодированное из кодировки Unicode в кодировку UTF-8, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь выбрасывает исключение ValueError, если параметр `domain` пустой.
8.4.0 | Теперь выбрасывает исключение ValueError, если параметр `variant` не равен `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | Теперь значение по умолчанию `variant` изменено на `INTL_IDNA_VARIANT_UTS46` вместо устаревшей константы `INTL_IDNA_VARIANT_2003`.
7.2.0 | `INTL_IDNA_VARIANT_2003` объявлена устаревшей, вместо неё используйте `INTL_IDNA_VARIANT_UTS46`.

### Примеры

Пример #1 Пример использования idn_to_utf8()

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

Результат выполнения приведённого примера:

    täst.de

### Смотрите также

- idn_to_ascii() - Преобразовывает доменное имя в формат ASCII по спецификации IDNA

## Содержание

- idn_to_ascii — Преобразовывает доменное имя в формат ASCII по спецификации IDNA
- idn_to_utf8 — Преобразование доменного имени из IDNA ASCII в Unicode

# IntlChar

(PHP 7, PHP 8)

## Введение

Методы модуля IntlChar открывают доступ к информации о символах кодировки Unicode.

Методы и константы модуля повторяют имена и поведение базовой библиотеки ICU.

## Обзор класса

class IntlChar {
/* Константы */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* Методы */
public static function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## Предопределённые константы

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Special value that is returned by IntlChar::getNumericValue() when no numeric value is defined for a code point.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_UNARY_OPERATOR` int
  Для программного определения последовательностей идеографического описания. Доступно начиная с PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  Используется в математическом идентификаторе профиля в UAX 31. Доступно начиная с PHP 8.4.0.
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  Используется в математическом идентификаторе профиля в UAX 31. Доступно начиная с PHP 8.4.0.
`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

`IntlChar::BLOCK_CODE_SPECIALS` int

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

`IntlChar::BLOCK_CODE_GOTHIC` int

`IntlChar::BLOCK_CODE_DESERET` int

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAGS` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

`IntlChar::BLOCK_CODE_TAGALOG` int

`IntlChar::BLOCK_CODE_HANUNOO` int

`IntlChar::BLOCK_CODE_BUHID` int

`IntlChar::BLOCK_CODE_TAGBANWA` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

`IntlChar::BLOCK_CODE_LIMBU` int

`IntlChar::BLOCK_CODE_TAI_LE` int

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_BUGINESE` int

`IntlChar::BLOCK_CODE_CJK_STROKES` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_COPTIC` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

`IntlChar::BLOCK_CODE_TIFINAGH` int

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

`IntlChar::BLOCK_CODE_NKO` int

`IntlChar::BLOCK_CODE_BALINESE` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

`IntlChar::BLOCK_CODE_PHAGS_PA` int

`IntlChar::BLOCK_CODE_PHOENICIAN` int

`IntlChar::BLOCK_CODE_CUNEIFORM` int

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

`IntlChar::BLOCK_CODE_SUNDANESE` int

`IntlChar::BLOCK_CODE_LEPCHA` int

`IntlChar::BLOCK_CODE_OL_CHIKI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_VAI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

`IntlChar::BLOCK_CODE_SAURASHTRA` int

`IntlChar::BLOCK_CODE_KAYAH_LI` int

`IntlChar::BLOCK_CODE_REJANG` int

`IntlChar::BLOCK_CODE_CHAM` int

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

`IntlChar::BLOCK_CODE_LYCIAN` int

`IntlChar::BLOCK_CODE_CARIAN` int

`IntlChar::BLOCK_CODE_LYDIAN` int

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

`IntlChar::BLOCK_CODE_SAMARITAN` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

`IntlChar::BLOCK_CODE_TAI_THAM` int

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_LISU` int

`IntlChar::BLOCK_CODE_BAMUM` int

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

`IntlChar::BLOCK_CODE_JAVANESE` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

`IntlChar::BLOCK_CODE_TAI_VIET` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

`IntlChar::BLOCK_CODE_AVESTAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_KAITHI` int

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

`IntlChar::BLOCK_CODE_MANDAIC` int

`IntlChar::BLOCK_CODE_BATAK` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_BRAHMI` int

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

`IntlChar::BLOCK_CODE_EMOTICONS` int

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CHAKMA` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_MIAO` int

`IntlChar::BLOCK_CODE_SHARADA` int

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAKRI` int

`IntlChar::BLOCK_CODE_BASSA_VAH` int

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

`IntlChar::BLOCK_CODE_DUPLOYAN` int

`IntlChar::BLOCK_CODE_ELBASAN` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

`IntlChar::BLOCK_CODE_GRANTHA` int

`IntlChar::BLOCK_CODE_KHOJKI` int

`IntlChar::BLOCK_CODE_KHUDAWADI` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

`IntlChar::BLOCK_CODE_LINEAR_A` int

`IntlChar::BLOCK_CODE_MAHAJANI` int

`IntlChar::BLOCK_CODE_MANICHAEAN` int

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

`IntlChar::BLOCK_CODE_MODI` int

`IntlChar::BLOCK_CODE_MRO` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

`IntlChar::BLOCK_CODE_NABATAEAN` int

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

`IntlChar::BLOCK_CODE_PALMYRENE` int

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

`IntlChar::BLOCK_CODE_SIDDHAM` int

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

`IntlChar::BLOCK_CODE_TIRHUTA` int

`IntlChar::BLOCK_CODE_WARANG_CITI` int

`IntlChar::BLOCK_CODE_COUNT` int

`IntlChar::BLOCK_CODE_INVALID_CODE` int

`IntlChar::BPT_NONE` int

`IntlChar::BPT_OPEN` int

`IntlChar::BPT_CLOSE` int

`IntlChar::BPT_COUNT` int

`IntlChar::EA_NEUTRAL` int

`IntlChar::EA_AMBIGUOUS` int

`IntlChar::EA_HALFWIDTH` int

`IntlChar::EA_FULLWIDTH` int

`IntlChar::EA_NARROW` int

`IntlChar::EA_WIDE` int

`IntlChar::EA_COUNT` int

`IntlChar::UNICODE_CHAR_NAME` int

`IntlChar::UNICODE_10_CHAR_NAME` int

`IntlChar::EXTENDED_CHAR_NAME` int

`IntlChar::CHAR_NAME_ALIAS` int

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

`IntlChar::SHORT_PROPERTY_NAME` int

`IntlChar::LONG_PROPERTY_NAME` int

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

`IntlChar::DT_NONE` int

`IntlChar::DT_CANONICAL` int

`IntlChar::DT_COMPAT` int

`IntlChar::DT_CIRCLE` int

`IntlChar::DT_FINAL` int

`IntlChar::DT_FONT` int

`IntlChar::DT_FRACTION` int

`IntlChar::DT_INITIAL` int

`IntlChar::DT_ISOLATED` int

`IntlChar::DT_MEDIAL` int

`IntlChar::DT_NARROW` int

`IntlChar::DT_NOBREAK` int

`IntlChar::DT_SMALL` int

`IntlChar::DT_SQUARE` int

`IntlChar::DT_SUB` int

`IntlChar::DT_SUPER` int

`IntlChar::DT_VERTICAL` int

`IntlChar::DT_WIDE` int

`IntlChar::DT_COUNT` int

`IntlChar::JT_NON_JOINING` int

`IntlChar::JT_JOIN_CAUSING` int

`IntlChar::JT_DUAL_JOINING` int

`IntlChar::JT_LEFT_JOINING` int

`IntlChar::JT_RIGHT_JOINING` int

`IntlChar::JT_TRANSPARENT` int

`IntlChar::JT_COUNT` int

`IntlChar::JG_NO_JOINING_GROUP` int

`IntlChar::JG_AIN` int

`IntlChar::JG_ALAPH` int

`IntlChar::JG_ALEF` int

`IntlChar::JG_BEH` int

`IntlChar::JG_BETH` int

`IntlChar::JG_DAL` int

`IntlChar::JG_DALATH_RISH` int

`IntlChar::JG_E` int

`IntlChar::JG_FEH` int

`IntlChar::JG_FINAL_SEMKATH` int

`IntlChar::JG_GAF` int

`IntlChar::JG_GAMAL` int

`IntlChar::JG_HAH` int

`IntlChar::JG_TEH_MARBUTA_GOAL` int

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

`IntlChar::JG_HE` int

`IntlChar::JG_HEH` int

`IntlChar::JG_HEH_GOAL` int

`IntlChar::JG_HETH` int

`IntlChar::JG_KAF` int

`IntlChar::JG_KAPH` int

`IntlChar::JG_KNOTTED_HEH` int

`IntlChar::JG_LAM` int

`IntlChar::JG_LAMADH` int

`IntlChar::JG_MEEM` int

`IntlChar::JG_MIM` int

`IntlChar::JG_NOON` int

`IntlChar::JG_NUN` int

`IntlChar::JG_PE` int

`IntlChar::JG_QAF` int

`IntlChar::JG_QAPH` int

`IntlChar::JG_REH` int

`IntlChar::JG_REVERSED_PE` int

`IntlChar::JG_SAD` int

`IntlChar::JG_SADHE` int

`IntlChar::JG_SEEN` int

`IntlChar::JG_SEMKATH` int

`IntlChar::JG_SHIN` int

`IntlChar::JG_SWASH_KAF` int

`IntlChar::JG_SYRIAC_WAW` int

`IntlChar::JG_TAH` int

`IntlChar::JG_TAW` int

`IntlChar::JG_TEH_MARBUTA` int

`IntlChar::JG_TETH` int

`IntlChar::JG_WAW` int

`IntlChar::JG_YEH` int

`IntlChar::JG_YEH_BARREE` int

`IntlChar::JG_YEH_WITH_TAIL` int

`IntlChar::JG_YUDH` int

`IntlChar::JG_YUDH_HE` int

`IntlChar::JG_ZAIN` int

`IntlChar::JG_FE` int

`IntlChar::JG_KHAPH` int

`IntlChar::JG_ZHAIN` int

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

`IntlChar::JG_FARSI_YEH` int

`IntlChar::JG_NYA` int

`IntlChar::JG_ROHINGYA_YEH` int

`IntlChar::JG_MANICHAEAN_ALEPH` int

`IntlChar::JG_MANICHAEAN_AYIN` int

`IntlChar::JG_MANICHAEAN_BETH` int

`IntlChar::JG_MANICHAEAN_DALETH` int

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

`IntlChar::JG_MANICHAEAN_FIVE` int

`IntlChar::JG_MANICHAEAN_GIMEL` int

`IntlChar::JG_MANICHAEAN_HETH` int

`IntlChar::JG_MANICHAEAN_HUNDRED` int

`IntlChar::JG_MANICHAEAN_KAPH` int

`IntlChar::JG_MANICHAEAN_LAMEDH` int

`IntlChar::JG_MANICHAEAN_MEM` int

`IntlChar::JG_MANICHAEAN_NUN` int

`IntlChar::JG_MANICHAEAN_ONE` int

`IntlChar::JG_MANICHAEAN_PE` int

`IntlChar::JG_MANICHAEAN_QOPH` int

`IntlChar::JG_MANICHAEAN_RESH` int

`IntlChar::JG_MANICHAEAN_SADHE` int

`IntlChar::JG_MANICHAEAN_SAMEKH` int

`IntlChar::JG_MANICHAEAN_TAW` int

`IntlChar::JG_MANICHAEAN_TEN` int

`IntlChar::JG_MANICHAEAN_TETH` int

`IntlChar::JG_MANICHAEAN_THAMEDH` int

`IntlChar::JG_MANICHAEAN_TWENTY` int

`IntlChar::JG_MANICHAEAN_WAW` int

`IntlChar::JG_MANICHAEAN_YODH` int

`IntlChar::JG_MANICHAEAN_ZAYIN` int

`IntlChar::JG_STRAIGHT_WAW` int

`IntlChar::JG_COUNT` int

`IntlChar::GCB_OTHER` int

`IntlChar::GCB_CONTROL` int

`IntlChar::GCB_CR` int

`IntlChar::GCB_EXTEND` int

`IntlChar::GCB_L` int

`IntlChar::GCB_LF` int

`IntlChar::GCB_LV` int

`IntlChar::GCB_LVT` int

`IntlChar::GCB_T` int

`IntlChar::GCB_V` int

`IntlChar::GCB_SPACING_MARK` int

`IntlChar::GCB_PREPEND` int

`IntlChar::GCB_REGIONAL_INDICATOR` int

`IntlChar::GCB_COUNT` int

`IntlChar::WB_OTHER` int

`IntlChar::WB_ALETTER` int

`IntlChar::WB_FORMAT` int

`IntlChar::WB_KATAKANA` int

`IntlChar::WB_MIDLETTER` int

`IntlChar::WB_MIDNUM` int

`IntlChar::WB_NUMERIC` int

`IntlChar::WB_EXTENDNUMLET` int

`IntlChar::WB_CR` int

`IntlChar::WB_EXTEND` int

`IntlChar::WB_LF` int

`IntlChar::WB_MIDNUMLET` int

`IntlChar::WB_NEWLINE` int

`IntlChar::WB_REGIONAL_INDICATOR` int

`IntlChar::WB_HEBREW_LETTER` int

`IntlChar::WB_SINGLE_QUOTE` int

`IntlChar::WB_DOUBLE_QUOTE` int

`IntlChar::WB_COUNT` int

`IntlChar::SB_OTHER` int

`IntlChar::SB_ATERM` int

`IntlChar::SB_CLOSE` int

`IntlChar::SB_FORMAT` int

`IntlChar::SB_LOWER` int

`IntlChar::SB_NUMERIC` int

`IntlChar::SB_OLETTER` int

`IntlChar::SB_SEP` int

`IntlChar::SB_SP` int

`IntlChar::SB_STERM` int

`IntlChar::SB_UPPER` int

`IntlChar::SB_CR` int

`IntlChar::SB_EXTEND` int

`IntlChar::SB_LF` int

`IntlChar::SB_SCONTINUE` int

`IntlChar::SB_COUNT` int

`IntlChar::LB_UNKNOWN` int

`IntlChar::LB_AMBIGUOUS` int

`IntlChar::LB_ALPHABETIC` int

`IntlChar::LB_BREAK_BOTH` int

`IntlChar::LB_BREAK_AFTER` int

`IntlChar::LB_BREAK_BEFORE` int

`IntlChar::LB_MANDATORY_BREAK` int

`IntlChar::LB_CONTINGENT_BREAK` int

`IntlChar::LB_CLOSE_PUNCTUATION` int

`IntlChar::LB_COMBINING_MARK` int

`IntlChar::LB_CARRIAGE_RETURN` int

`IntlChar::LB_EXCLAMATION` int

`IntlChar::LB_GLUE` int

`IntlChar::LB_HYPHEN` int

`IntlChar::LB_IDEOGRAPHIC` int

`IntlChar::LB_INSEPARABLE` int

`IntlChar::LB_INSEPERABLE` int

`IntlChar::LB_INFIX_NUMERIC` int

`IntlChar::LB_LINE_FEED` int

`IntlChar::LB_NONSTARTER` int

`IntlChar::LB_NUMERIC` int

`IntlChar::LB_OPEN_PUNCTUATION` int

`IntlChar::LB_POSTFIX_NUMERIC` int

`IntlChar::LB_PREFIX_NUMERIC` int

`IntlChar::LB_QUOTATION` int

`IntlChar::LB_COMPLEX_CONTEXT` int

`IntlChar::LB_SURROGATE` int

`IntlChar::LB_SPACE` int

`IntlChar::LB_BREAK_SYMBOLS` int

`IntlChar::LB_ZWSPACE` int

`IntlChar::LB_NEXT_LINE` int

`IntlChar::LB_WORD_JOINER` int

`IntlChar::LB_H2` int

`IntlChar::LB_H3` int

`IntlChar::LB_JL` int

`IntlChar::LB_JT` int

`IntlChar::LB_JV` int

`IntlChar::LB_CLOSE_PARENTHESIS` int

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

`IntlChar::LB_HEBREW_LETTER` int

`IntlChar::LB_REGIONAL_INDICATOR` int

`IntlChar::LB_COUNT` int

`IntlChar::NT_NONE` int

`IntlChar::NT_DECIMAL` int

`IntlChar::NT_DIGIT` int

`IntlChar::NT_NUMERIC` int

`IntlChar::NT_COUNT` int

`IntlChar::HST_NOT_APPLICABLE` int

`IntlChar::HST_LEADING_JAMO` int

`IntlChar::HST_VOWEL_JAMO` int

`IntlChar::HST_TRAILING_JAMO` int

`IntlChar::HST_LV_SYLLABLE` int

`IntlChar::HST_LVT_SYLLABLE` int

`IntlChar::HST_COUNT` int

`IntlChar::FOLD_CASE_DEFAULT` int

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Добавлены константы `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START`, `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE`.
8.4.0 | Константы класса стали типизированными.
7.0.6 | Добавили константу `IntlChar::NO_NUMERIC_VALUE`.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Получает «возраст» кодовой точки

### Описание

public static function IntlChar::charAge(int|string `$codepoint`): ?array

Метод получает «возраст» символьного кода.

«Возраст» — версия стандарта Unicode, в которой кодовую точку впервые назначили (как несимвол или для частных нужд) или присвоили кодовой точке символ. Сведения о возрасте помогают избегать выдачи кодовых точек процессам-получателям, которые не принимают новые символы.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает номер версии Юникода в виде массива. Метод представит версию 1.3.31.2 как `[1, 3, 31, 2]`. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));

    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      int(1)
      [1]=>
      int(1)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }
    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Смотрите также

- IntlChar::getUnicodeVersion() - Получает версию стандарта Unicode
- IntlChar::getIntPropertyMinValue() - Получает минимальное значение Unicode-свойства
- IntlChar::getIntPropertyValue() - Получает значение Unicode-свойства кодовой точки

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — Получает десятичное значение десятичного символа

### Описание

public static function IntlChar::charDigitValue(int|string `$codepoint`): ?int

Метод возвращает значение десятичной цифры — символа, которым записывают числа в десятичной системе счисления.

У символов десятичных цифр общая категория — "Nd" (десятичные числа) и свойство Numeric_Type — "Decimal".

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает значение десятичной цифры, которая соответствует кодовой точке `codepoint`. Метод возвращает `-1` для символов, которые не относятся к десятичным цифрам. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));

    ?>

Результат выполнения приведённого примера:

    int(1)
    int(2)
    int(3)

### Смотрите также

- IntlChar::getNumericValue() - Получает числовое значение кодовой точки Юникода

# IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — Получает двунаправленное значение категории кодовой точки

### Описание

public static function IntlChar::charDirection(int|string `$codepoint`): ?int

Метод возвращает информацию о том, к какому типу двунаправленного письма принадлежит символ, который соответствует заданной кодовой точке. Значения категорий определяет Приложение № 9 к стандарту Юникода, которое называется » Двунаправленный алгоритм Юникода (UAX #9).

> Замечание:

> У отдельных неназначенных кодовых точек двунаправленные значения принадлежат типам R (справа налево — прим. перев.) или AL (арабское письмо — прим. перев.), поскольку кодовые точки содержатся в блоках, которые зарезервировали для сценариев с письмом справа налево.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает двунаправленное значение категории в виде значения константы из следующего списка:

- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR`
- `IntlChar::CHAR_DIRECTION_ARABIC_NUMBER`
- `IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT`
- `IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK`
- `IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE`
- `IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT`

Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
    var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
    var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — Находит Unicode-символ по имени и возвращает значение кодовой точки символа

### Описание

public static function IntlChar::charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int

Метод находит символ Юникода по имени и возвращает значение кодовой точки, которой соответствует символ.

Метод сравнивает точное название символа. Метод вернёт `null`, если имя не соответствует кодовой точке.

Имя, которое содержится в стандарте Unicode 1.0, совпадёт, только если название отличается от современного имени. Каждое имя в кодировке Unicode хранится в верхнем регистре. Расширенные имена записываются в угловых скобках строчными буквами, за которыми через дефис идёт шестнадцатеричное число в верхнем регистре.

### Список параметров

`name`

  Полное имя символа в кодировке Unicode.

`type`

  Набор имён, в котором метод будет искать символы. Константа из следующего списка:

  - `IntlChar::UNICODE_CHAR_NAME` (по умолчанию)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Возвращаемые значения

Метод возвращает целочисленное значение (int) кодовой точки Юникода, которую нашёл по имени символа, или `null`, если таблица не содержит такую кодовую точку.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
    var_dump(IntlChar::charFromName("SNOWMAN"));
    var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
    var_dump(IntlChar::charFromName("A RANDOM STRING WHICH DOESN'T CORRESPOND TO ANY UNICODE CHARACTER"));

    ?>

Результат выполнения приведённого примера:

    int(65)
    int(9731)
    int(9843)
    NULL

### Смотрите также

- IntlChar::charName() - Извлекает название Unicode-символа
- IntlChar::enumCharNames() - Перечисляет все присвоенные символы Unicode в заданном диапазоне

# IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — Получает «зеркально отражённый» символ кодовой точки Юникода

### Описание

public static function IntlChar::charMirror(int|string `$codepoint`): int|string|null

Метод сопоставляет символ, который соответствует заданной кодовой точке, с «зеркальным» символом.

Реализациям иногда требуется такое альтернативное, но упрощённое сопоставление символов со свойством Bidi_Mirrored с другим символом (кодовой точкой) Юникода, чтобы глиф по умолчанию другого символа подменял зеркальное отображение глифа по умолчанию заданного символа. Это полезно для преобразования текста в кодовые страницы с визуальным порядком и наоборот — числовых значений кодовых страниц обратно в текст, и для отображения символов, для которых невозможно выбрать глиф.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает другую кодовую точку Юникода, которая подменяет зеркальное отображение символа заданной кодовой точки, или символ самой кодовой точки `codepoint`, если такого сопоставления нет или у кодовой точки `codepoint` нет свойства Bidi_Mirrored.

Метод возвращает целое число (int), если только кодовую точку не передали как строку (string) в кодировке UTF-8, при передаче которой возвращается строка (string). Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));

    ?>

Результат выполнения приведённого примера:

    string(1) "A"
    string(1) ">"
    string(2) ")"

### Смотрите также

- IntlChar::isMirrored() - Проверяет, относится ли символ к двунаправленным
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Извлекает название Unicode-символа

### Описание

public static function IntlChar::charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string

Метод возвращает название символа в кодировке Unicode.

Параметр `type` определяет, вернёт метод «современное» название символа или название, которое определили в стандарте Unicode 1.0. Названия состоят только из «неизменяемых» символов в диапазонах A-Z и 0-9, пробела и символа «-». Метод извлекает названия символов из определений стандарта Unicode 1.0, только если они не совпадают с «современными» названиями и если стандарт ICU содержит данные для названий.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).
`type`

  Набор имён для поиска. Константа из списка:

  - `IntlChar::UNICODE_CHAR_NAME` (default)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Возвращаемые значения

Метод возвращает название символа, которое соответствует кодовой точке, или пустую строку, если у символа нет имени. Метод возвращает `null`, если кодовая точка не содержится в наборе.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charName("."));
    var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
    var_dump(IntlChar::charName("\u{2603}"));
    var_dump(IntlChar::charName("\u{0000}"));

    ?>

Результат выполнения приведённого примера:

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### Смотрите также

- IntlChar::charFromName() - Находит Unicode-символ по имени и возвращает значение кодовой точки символа
- IntlChar::enumCharNames() - Перечисляет все присвоенные символы Unicode в заданном диапазоне

# IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — Получает значение общей категории кодовой точки

### Описание

public static function IntlChar::charType(int|string `$codepoint`): ?int

Метод возвращает значение общей категории, в которую входит кодовая точка.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает тип общей категории в виде значения константы из следующего списка:

- `IntlChar::CHAR_CATEGORY_UNASSIGNED`
- `IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES`
- `IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_TITLECASE_LETTER`
- `IntlChar::CHAR_CATEGORY_MODIFIER_LETTER`
- `IntlChar::CHAR_CATEGORY_OTHER_LETTER`
- `IntlChar::CHAR_CATEGORY_NON_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_ENCLOSING_MARK`
- `IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER`
- `IntlChar::CHAR_CATEGORY_LETTER_NUMBER`
- `IntlChar::CHAR_CATEGORY_OTHER_NUMBER`
- `IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR`
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR`
- `IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR`
- `IntlChar::CHAR_CATEGORY_SURROGATE`
- `IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_START_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_END_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_MATH_SYMBOL`
- `IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL`
- `IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_OTHER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT`

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
    var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
    var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
    var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
    var_dump(IntlChar::charType("multiple chars") === null);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — Возвращает символ Юникода по значению кодовой точки

### Описание

public static function IntlChar::chr(int|string `$codepoint`): ?string

Метод возвращает строку с символом, который указали значением кодовой точки в кодировке Unicode.

Метод дополняет метод IntlChar::ord().

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает строку с символом, который указали значением кодовой точки в кодировке Unicode, или `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    $values = ["A", 63, 123, 9731];

    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }

    ?>

Результат выполнения приведённого примера:

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### Смотрите также

- IntlChar::ord() - Возвращает значение кодовой точки символа Юникода
- mb_chr() - Возвращает символ по значению кодовой точки Unicode
- chr() - Генерирует однобайтовую строку из числа

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Получает десятичное значение цифры кодовой точки в заданной системе счисления

### Описание

public static function IntlChar::digit(int|string `$codepoint`, int `$base` = 10): int|false|null

Метод возвращает десятичное значение цифры — символа, которым записывают числа и который присвоили кодовой точке Юникода, в заданной системе счисления.

Метод возвращает `false`, если основание системы счисления не входит в диапазон `2 <= radix <= 36` или если символ, который кодируется кодовой точкой `codepoint`, — недопустимая цифра для заданного основания. Метод признаёт символ корректной цифрой, если выполняется хотя бы одно условие:

- Символ — цифра, которая несёт значение числа десятичной системы счисления. Такие символы входят в общую категорию — "Nd" (десятичные числа) и содержат в свойстве Numeric_Type значение "Decimal". Значением такого символа будет десятичное число, значение которого несёт цифра десятичной системы счисления.
- Символ — заглавная латинская буква в диапазоне от "A" до "Z". Метод вычисляет значение возврата по формуле: номер заданного символа в таблице - номер кодовой точки символа 'A' + 10.
- Символ — строчная латинская буква в диапазоне от 'a' до 'z'. Метод вычисляет значение возврата по формуле: номер заданного символа в таблице - номер кодовой точки символа 'a' + 10.
- Метод распознал латинские буквы из диапазонов 0041..005A (a..z) и 0061..007A (A..Z) стандартного набора ASCII-символов или из диапазонов FF41..FF5A (a..z) и FF21..FF3A (A..Z) расширенного набора символов кодировки ASCII.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).
`base`

  Основание (значение по умолчанию равно `10`).

### Возвращаемые значения

Метод возвращает числовое значение символа в заданной системе счисления, или `false`, если символ не обозначает число с заданным основанием или выходит за рамки основания. Метод возвращает `null`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

Результат выполнения приведённого примера:

    int(0)
    int(3)
    int(10)
    bool(false)

### Смотрите также

- IntlChar::forDigit() - Получает кодовую точку символьного представления числа в заданной системе счисления
- IntlChar::charDigitValue() - Получает десятичное значение десятичного символа
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — Перечисляет все присвоенные символы Unicode в заданном диапазоне

### Описание

public static function IntlChar::enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool

Перечисляет все присвоенные символы Unicode в заданном диапазоне (включая начало диапазона и исключая конец) и для каждого из них функцию, передавая в неё код символа и его имя.

Для имён Unicode 1.0 перечисляются только те символы, имена которых отличны от их "современных" имён.

### Список параметров

`start`

  Код символа с которого начинается диапазон.

`end`

  Код символа с которого начинается диапазон. Сам этот символ в диапазон не попадёт.

`callback`

  Функция, которая будет вызвана для каждого возвращённого символа. В неё будут переданы следующие три аргумента:

  - int `$codepoint` - код символа
  - int `$nameChoice` - значение из `type`, смотрите описание ниже
  - string `$name` - Имя символа
`type`

  Категория символов для перечисления. Одна из констант:

  - `IntlChar::UNICODE_CHAR_NAME` (по умолчанию)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Теперь метод возвращает `false` в случае ошибки; ранее он возвращал `null`.

### Примеры

Пример #1 Перечисления диапазона символов

    <?php
    IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
        printf("U+%04x %s\n", $codepoint, $name);
    });
    ?>

Результат выполнения приведённого примера:

    U+2600 BLACK SUN WITH RAYS
    U+2601 CLOUD
    U+2602 UMBRELLA
    U+2603 SNOWMAN
    U+2604 COMET
    U+2605 BLACK STAR
    U+2606 WHITE STAR
    U+2607 LIGHTNING
    U+2608 THUNDERSTORM
    U+2609 SUN
    U+260a ASCENDING NODE
    U+260b DESCENDING NODE
    U+260c CONJUNCTION
    U+260d OPPOSITION
    U+260e BLACK TELEPHONE
    U+260f WHITE TELEPHONE

### Смотрите также

- IntlChar::charName() - Извлекает название Unicode-символа
- IntlChar::charFromName() - Находит Unicode-символ по имени и возвращает значение кодовой точки символа

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Перечисляет кодовые точки с их общими категориями Юникода

### Описание

public static function IntlChar::enumCharTypes(callable `$callback`): void

Метод эффективно перечисляет кодовые точки с их общими Unicode-категориями. Метод приносит пользу при построении структур данных, переборе кодовых точек, которым назначили символ, и т. д.

Метод вызывает `callback`-функцию для каждого непрерывного диапазона кодовых точек с общей категорией — «типом символа». Типы соседних диапазонов не совпадают. Стандарт Unicode гарантирует, что типам присваиваются значения от 0 до 31.

### Список параметров

`callback`

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

  - int `$start` — Начальная кодовая точка диапазона.
  - int `$end` — Конечная кодовая точка диапазона.
  - int `$name` — Тип категории — константа семейства `IntlChar::CHAR_CATEGORY_*`.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Примеры

Пример #1 Пример перечисления диапазонов кодовых точек

    <?php

    IntlChar::enumCharTypes(function($start, $end, $type) {
        printf("U+%04x through U+%04x are in category %d\n", $start, $end, $type);
    });

    ?>

Результат выполнения приведённого примера:

    U+0000 through U+0020 are in category 15
    U+0020 through U+0021 are in category 12
    U+0021 through U+0024 are in category 23
    U+0024 through U+0025 are in category 25
    U+0025 through U+0028 are in category 23
    U+0028 through U+0029 are in category 20
    U+0029 through U+002a are in category 21
    U+002a through U+002b are in category 23
    U+002b through U+002c are in category 24
    U+002c through U+002d are in category 23
    U+002d through U+002e are in category 19
    U+002e through U+0030 are in category 23
    U+0030 through U+003a are in category 9
    ...

# IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — Преобразовывает регистр кодовой точки

### Описание

public static function IntlChar::foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null

Метод сопоставляет символ с эквивалентом в нижем регистре; если у символа нет эквивалента в нижнем регистре, метод возвращает сам символ.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).
`options`

  `IntlChar::FOLD_CASE_DEFAULT` (по умолчанию) или `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### Возвращаемые значения

Метод возвращает результат простого свёртывания регистра (Simple_Case_Folding) кодовой точки, если доступно; иначе саму кодовую точку в случае успешного выполнения или `null`, если возникла ошибка.

# IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — Получает кодовую точку символьного представления числа в заданной системе счисления

### Описание

public static function IntlChar::forDigit(int `$digit`, int `$base` = 10): int

Метод определяет кодовую точку цифры в заданной системе счисления.

Метод возвращает NUL-символ с кодовой точкой `U+0000`, если значение основания недопустимо или значение цифры недопустимо в заданной системе счисления.

Допустимые значения оснований лежат в диапазоне от `2` до `36` включительно. Допустимые значения цифр лежат в диапазоне `0 <= digit < radix`.

Метод возвращает значение, которое вычисляет по формуле: десятичное значение кодовой точки символа 0 + заданное число, если основание меньше `10`. В остальных случаях метод возвращает значения по формуле: десятичное значение кодовой точки символа 'a' + заданное число - 10.

### Список параметров

`digit`

  Число, которое метод преобразует в символ, кодовую точку которого определит.

`base`

  Основание системы счисления (значение по умолчанию равно `10`).

### Возвращаемые значения

Метод возвращает порядковый номер (int), который назначили символу — цифре, которая обозначает заданное число в заданной системе счисления.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::forDigit(0));
    var_dump(IntlChar::forDigit(3));
    var_dump(IntlChar::forDigit(3, 10));
    var_dump(IntlChar::forDigit(10));

    var_dump(IntlChar::forDigit(10, 16));

    ?>

Результат выполнения приведённого примера:

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### Смотрите также

- IntlChar::digit() - Получает десятичное значение цифры кодовой точки в заданной системе счисления
- IntlChar::charDigitValue() - Получает десятичное значение десятичного символа
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — Получает символ парной скобки для кодовой точки

### Описание

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

Метод сопоставляет символ с символом парной скобки.

Символы, для которых определили свойство типа парной скобки как «открывающая» или «закрывающая» — для которых верно утверждение `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_NONE`, — метод обрабатывает аналогично методу IntlChar::charMirror(). В остальных случаях метод возвращает сам символ `codepoint`.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает значение кодовой точки парной скобки или самой кодовой точки `codepoint`, если у символа нет сопоставления с парной скобкой. Метод возвращает `null`, если возникла ошибка.

Метод возвращает целое число (int), если только кодовую точку не передали как строку (string) в кодировке UTF-8, при передаче которой возвращается строка (string). Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));

    ?>

Результат выполнения приведённого примера:

    int(93)
    string(1) "]"

### Примечания

> Замечание:

> Метод доступен с 52-й версии стандарта ICU.

### Смотрите также

- IntlChar::charMirror() - Получает «зеркально отражённый» символ кодовой точки Юникода
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — Получает блок распределения, который содержит кодовую точку символа Юникода

### Описание

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Метод возвращает блок распределения символов в пространстве кодировки Unicode, который содержит символ.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает значение с номером группы, которая содержит символ `codepoint`. Возможные значения возврата определяют константы семейства `IntlChar::BLOCK_CODE_*`. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
    var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Получает класс объединения для символа

### Описание

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Метод возвращает значение класса, который объединяет символ с другими символами, аналогичными по заданному стандартом Юникода набору свойств.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает класс объединения символа. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));

    ?>

Результат выполнения приведённого примера:

    int(0)
    int(1)
    int(232)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — Получает свойство FC_NFKC_Closure для символа

### Описание

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Метод получает свойство FC_NFKC_Closure для символа.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает строку со значением свойства FC_NFKC_Closure кодовой точки `codepoint`, или пустую строку, если свойства нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));

    ?>

Результат выполнения приведённого примера:

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Получает максимальное значение Unicode-свойства

### Описание

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Метод получает максимальное значение перечисляемого, целочисленного или двоичного свойства Юникода.

### Список параметров

`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

### Возвращаемые значения

Метод возвращает максимальное значение, которое возвращает метод IntlChar::getIntPropertyValue() для Unicode-свойства. Метод возвращает значение `<=0`, если селектор свойства выходит за пределы диапазона.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Выдуманное значение

    ?>

Результат выполнения приведённого примера:

    int(22)
    int(166)
    int(1)
    int(-1)

### Смотрите также

- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- IntlChar::getIntPropertyMinValue() - Получает минимальное значение Unicode-свойства
- IntlChar::getIntPropertyValue() - Получает значение Unicode-свойства кодовой точки
- IntlChar::getUnicodeVersion() - Получает версию стандарта Unicode

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Получает минимальное значение Unicode-свойства

### Описание

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Метод получает минимальное значение перечисляемого, целочисленного или двоичного свойства Юникода.

### Список параметров

`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

### Возвращаемые значения

Метод возвращает минимальное значение, которое возвращает метод IntlChar::getIntPropertyValue() для Unicode-свойства. Метод возвращает значение `0`, если селектор свойства выходит за пределы диапазона.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Выдуманное значение

    ?>

Результат выполнения приведённого примера:

    int(0)
    int(0)
    int(0)
    int(0)

### Смотрите также

- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- IntlChar::getIntPropertyMaxValue() - Получает максимальное значение Unicode-свойства
- IntlChar::getIntPropertyValue() - Получает значение Unicode-свойства кодовой точки
- IntlChar::getUnicodeVersion() - Получает версию стандарта Unicode

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — Получает значение Unicode-свойства кодовой точки

### Описание

public static function IntlChar::getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int

Метод получает значение перечисляемого или целочисленного свойства Юникода заданной кодовой точки. Метод также возвращает двоичные значения свойств и значения свойств маски.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).
`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

### Возвращаемые значения

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

Метод возвращает `0` вместо `false` и `1` вместо `true` для двоичных свойств Юникода.

Метод возвращает битовую маску для свойств маски.

Метод возвращает `0`, если свойство `property` выходит за пределы диапазона, или если версия Юникода вообще не содержит данных для свойства или для заданной кодовой точки.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
    var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
    var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- IntlChar::getIntPropertyMinValue() - Получает минимальное значение Unicode-свойства
- IntlChar::getIntPropertyMaxValue() - Получает максимальное значение Unicode-свойства
- IntlChar::getUnicodeVersion() - Получает версию стандарта Unicode

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Получает числовое значение кодовой точки Юникода

### Описание

public static function IntlChar::getNumericValue(int|string `$codepoint`): ?float

Метод получает числовое значение кодовой точки кодировки Unicode, которое определяет база символов Юникода.

Метод вернёт значение константы `IntlChar::NO_NUMERIC_VALUE` для символов без числовых значений в базе символов Юникода.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает числовое значение кодовой точки `codepoint`, или константу `IntlChar::NO_NUMERIC_VALUE`, если числовое значение не определили. Константу добавили в PHP 7.0.6, до этой версии вместо неё возвращалось буквальное значение как число с плавающей точкой (float): `-123456789`. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));

    ?>

Результат выполнения приведённого примера:

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Получает постоянное значение свойства по имени свойства

### Описание

public static function IntlChar::getPropertyEnum(string `$alias`): int

Метод возвращает постоянное значение свойства по названию свойства, как определяет файл базы данных Юникода — PropertyAliases.txt. Метод распознаёт короткие, длинные и другие варианты имён.

Кроме того, метод сопоставляет свойство `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` с синтетическим именем "gcm" / "General_Category_Mask". Файл PropertyAliases.txt не содержит этих имён.

Метод дополняет метод IntlChar::getPropertyName().

### Список параметров

`alias`

  Имя свойства. Имена сравниваются по принципу «свободного соответствия» (loose matching), как описывает файл базы данных Юникода — PropertyValueAliases.txt.

### Возвращаемые значения

Метод возвращает значение константы семейства `IntlChar::PROPERTY_*`, или `IntlChar::PROPERTY_INVALID_CODE`, если заданное имя не соответствует ни одному свойству.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
    var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
    var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
    var_dump(IntlChar::getPropertyEnum('Some made-up string') === IntlChar::PROPERTY_INVALID_CODE);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::getPropertyName() - Получает Unicode-имя свойства

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Получает Unicode-имя свойства

### Описание

public static function IntlChar::getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Метод возвращает Unicode-имя свойства, как определяет файл базы данных Юникода — PropertyAliases.txt.

Кроме того, метод сопоставляет свойство `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` с синтетическим именем "gcm" / "General_Category_Mask". Файл PropertyAliases.txt не содержит этих имён.

Метод дополняет метод IntlChar::getPropertyEnum().

### Список параметров

`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

  Флаг `IntlChar::PROPERTY_INVALID_CODE` лучше не использовать. Кроме того, метод вернёт `false`, если свойство `property` не выходит за пределы допустимого диапазона.

`type`

  Селектор, который определяет, какое имя требуется получить. Метод вернёт `false`, если селектор не входит в допустимый диапазон.

  Длинное имя есть у каждого значения. У большей части значений есть короткие имена, но не у каждого. Юникод разрешает дополнительные имена; если значению присвоили короткое название, метод вернёт значение `IntlChar::LONG_PROPERTY_NAME` с добавлением 1, 2 и т. д.

### Возвращаемые значения

Метод возвращает имена свойств или `false`, если свойство `property` тип имён `type` выходят за пределы допустимого диапазона.

Если тип названия `type` возвращает `false`, все бо́льшие значения типа названия `type` также вернут `false`, с одним исключением: если для `IntlChar::SHORT_PROPERTY_NAME` вернётся `false`, то `IntlChar::LONG_PROPERTY_NAME` и выше всё ещё смогут вернуть значения, которые будут отличаться от `false`.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));

    ?>

Результат выполнения приведённого примера:

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### Смотрите также

- IntlChar::getPropertyEnum() - Получает постоянное значение свойства по имени свойства

# IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — Получает значение свойства по имени значения

### Описание

public static function IntlChar::getPropertyValueEnum(int `$property`, string `$name`): int

Метод возвращает целочисленное значение свойства Юникода по имени значения, как определяет файл базы данных Юникода — PropertyValueAliases.txt. Метод распознаёт короткие, длинные и другие варианты имён.

> Замечание:

> Отдельные названия значений свойств из файла PropertyValueAliases.txt извлекаются только через флаг `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, а не `IntlChar::PROPERTY_GENERAL_CATEGORY`. К таким значениям относятся следующие категории символов (список приводит короткое и длинное название категории, а также сокращённое описание):

> - "C" / "Other" — прочие символы (управлящие, форматирования, суррогаты, частные и зарезервированные неназначенные кодовые точки и несимвольные коды)
> - "L" / "Letter" — буквы
> - "LC" / "Cased_Letter" — категория регистровых букв, которая объединяет категории: заглавных букв — Lu, строчных букв — Ll и категорию букв титульного регистра — Lt, в которую входят диграфы — символы, которые состоят из двух букв, которые закодировали как один символ, первый из которых — заглавный, например U+01F2 LATIN CAPITAL LETTER D WITH SMALL LETTER Z
> - "M" / "Mark" — метки
> - "N" / "Number" — числа
> - "P" / "Punctuation" — символы пунктуации
> - "S" / "Symbol" — символы (математические, валют, диакритические и прочие)
> - "Z" / "Separator" — символы-разделители

### Список параметров

`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

  Метод вернёт значение флага `IntlChar::PROPERTY_INVALID_CODE`, если свойство выходит за пределы допустимого диапазона, или если метод не работает с заданным значением.

`name`

  Название значения свойства, которое требуется сопоставить. Имена сравниваются по принципу «свободного соответствия» (loose matching), как описывает файл базы данных Юникода — PropertyValueAliases.txt.

### Возвращаемые значения

Метод возвращает целочисленное значение свойства, которое соответствует названию значения свойства, или `IntlChar::PROPERTY_INVALID_CODE`, если имя не совпадает ни с одним значением свойства или если свойство недопустимо.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Получает значения свойства Юникода

### Описание

public static function IntlChar::getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Метод возвращает значение свойства Юникода, как значение указали в файле базы данных Юникода — PropertyValueAliases.txt.

> Замечание:

> Отдельные названия значений свойств из файла PropertyValueAliases.txt извлекаются только через флаг `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, а не `IntlChar::PROPERTY_GENERAL_CATEGORY`. К таким значениям относятся следующие категории символов (список приводит короткое и длинное название категории, а также сокращённое описание):

> - "C" / "Other" — прочие символы (управлящие, форматирования, суррогаты, частные и зарезервированные неназначенные кодовые точки и несимвольные коды)
> - "L" / "Letter" — буквы
> - "LC" / "Cased_Letter" — категория регистровых букв, которая объединяет категории: заглавных букв — Lu, строчных букв — Ll и категорию букв титульного регистра — Lt, в которую входят диграфы — символы, которые состоят из двух букв, которые закодировали как один символ, первый из которых — заглавный, например U+01F2 LATIN CAPITAL LETTER D WITH SMALL LETTER Z
> - "M" / "Mark" — метки
> - "N" / "Number" — числа
> - "P" / "Punctuation" — символы пунктуации
> - "S" / "Symbol" — символы (математические, валют, диакритические и прочие)
> - "Z" / "Separator" — символы-разделители

### Список параметров

`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

  Метод вернёт `false`, если свойство выходит за пределы допустимого диапазона или метод не работает с заданным значением.

`value`

  Селектор для значения свойства. Метод вернёт `false`, если значение выходит за пределы допустимого диапазона.

  Как правило, допустимый диапазон значений лежит в пределах от `0` до некоторого максимума. Отдельные значения составляют ряд исключений:

  - Значения `IntlChar::PROPERTY_BLOCK` начинаются с ненулевого значения `IntlChar::BLOCK_CODE_BASIC_LATIN`
  - Значения `IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` не непрерывны и лежат в диапазоне 0..240.
`type`

  Селектор, который определяет, какое имя требуется получить. Метод вернёт `false` для селекторов вне допустимого диапазона.

  Длинное имя есть у каждого значения. У большей части значений есть короткие имена, но не у каждого. Юникод разрешает дополнительные имена; если значению присвоили короткое название, метод вернёт значение `IntlChar::LONG_PROPERTY_NAME` с добавлением 1, 2 и т. д.

### Возвращаемые значения

Метод возвращает имя или `false`, если значение свойства `property` или типа имени `type` выходит за рамки допустимого диапазона. Метод возвращает `null`, если возникла ошибка.

Если тип названия `type` возвращает `false`, все бо́льшие значения типа названия `type` также вернут `false`, с одним исключением: если для `IntlChar::SHORT_PROPERTY_NAME` вернётся `false`, то `IntlChar::LONG_PROPERTY_NAME` и выше всё ещё смогут вернуть значения, которые будут отличаться от `false`.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));

    ?>

Результат выполнения приведённого примера:

    string(16) "Greek_And_Coptic"
    string(5) "Greek"
    string(16) "Greek_And_Coptic"
    bool(false)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Получает версию стандарта Unicode

### Описание

public static function IntlChar::getUnicodeVersion(): array

Метод получает информацию о версии Юникода.

Массив версий заполняется информацией о текущей версии стандарта Unicode, с которой работают компоненты ICU. Unicode версии 3.1.1, например, вернёт массив со значениями `[3, 1, 1, 0]`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает массив, который содержит информацию о версии стандарта Unicode.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::getUnicodeVersion());

    ?>

Результат выполнения приведённого примера:

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Смотрите также

- IntlChar::charAge() - Получает «возраст» кодовой точки

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — Проверяет бинарное свойство Unicode для символа

### Описание

public static function IntlChar::hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool

Метод проверяет бинарное свойство Unicode для символа.

Стандарт Unicode, особенно в версии 3.2, определяет гораздо больше свойств, чем исходный набор в файле UnicodeData.txt.

API-интерфейсы свойств отражают свойства стандарта Unicode так, как определяет база данных символов Unicode (Unicode Character Database или UCD) и технические отчёты Unicode (Unicode Technical Reports или UTR). Подробнее свойства описывает страница » http://www.unicode.org/ucd/. Имена свойств Unicode смотрите в файле UCD PropertyAliases.txt.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).
`property`
  Свойство Юникода для поиска (см. константы семейства `IntlChar::PROPERTY_*`).

### Возвращаемые значения

Метод возвращает `true` или `false` в зависимости от значения двоичного Unicode-свойства кодовой точки `codepoint`. Метод также возвращает `false`, если значение `property` выходит за пределы допустимых значений или если версия стандарта Unicode вообще не содержит данных для этого свойства, или задали свойство не для этой кодовой точки. Функция возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки свойств

    <?php

    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- IntlChar::getIntPropertyValue() - Получает значение Unicode-свойства кодовой точки
- IntlChar::getUnicodeVersion() - Получает версию стандарта Unicode

# IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — Проверяет, относится ли кодовая точка к буквенно-цифровым символам

### Описание

public static function IntlChar::isalnum(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к буквам или цифрам. Метод возвращает `true` для символов общей категорий букв — L и десятичных цифр — Nd.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` — буква или цифра, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- ctype_alnum() - Проверяет буквенно-цифровые символы

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Проверяет, относится ли кодовая точка к символам букв

### Описание

public static function IntlChar::isalpha(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к символам букв. Метод возвращает `true` для символов общей категории букв — L, которая объединяет категории букв в верхнем — Lu, Ll, Lt, Lm и Lo.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` — буква, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isalnum() - Проверяет, относится ли кодовая точка к буквенно-цифровым символам
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- ctype_alpha() - Проверяет буквенные символы

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Проверяет, относится ли кодовая точка к базовому символу

### Описание

public static function IntlChar::isbase(int|string `$codepoint`): ?bool

Метод проверяет, относится ли кодовая точка к базовому символу. Метод возвращает `true` для общих категорий букв — L, чисел — N, протяжённых комбинирующих меток — Mc и охватывающих меток — Me.

> Замечание:

> То, как метод понимает базовые символы, отличается от определения, которое даёт глава D13 пункта 3.5 раздела «Соответствие» стандарта Unicode, которая определяет базовые символы как символы, которые не входят в общую категорию зарезервированных неназначенных кодовых точек и несимвольных кодовых точек — Cn и которые графически не сочетаются с предыдущими символами общей категории меток — M и которые не относятся ни к управляющим кодам общей категории Cc, ни к символам управления форматом общей категории Cf.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к базовым символам, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр

# IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — Проверяет, относится ли кодовая точка к символам «пустого места» или «горизонтального пробела»

### Описание

public static function IntlChar::isblank(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к символам «пустого места» или символам «горизонтального пробела», символам, которые визуально разделяют слова в строке.

Следующий список приводит эквивалентные определения:

- Метод возвращает `true` для пробельных символов Юникода со свойством White_Space, за исключением «символом управления вертикальным пробелом», где к «вертикальным пробельным символам» относятся следующие кодовые точки: U+000A (LF), U+000B (VT), U+000C (FF), U+000D (CR), U+0085 (NEL), U+2028 (LS) или U+2029 (PS).
- Метод возвращает `true` для кодовой точки табуляции — U+0009 (TAB) и символов общей категории пробельных разделителей ненулевой ширины — Zs, за исключением пробела с нулевой длиной (ZWSP, U+200B).

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к «пустым» или «горизонтальным пробелам», `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::isspace() - Проверяет, является ли символ пробельным
- IntlChar::isJavaSpaceChar() - Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
- IntlChar::isUWhiteSpace() - Проверяет, относится ли символ к пробельным
- IntlChar::isWhitespace() - Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU

# IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — Проверяет, относится ли кодовая точка к управляющим символам

### Описание

public static function IntlChar::iscntrl(int|string `$codepoint`): ?bool

Метод определяет, относит ли кодовая точка к управляющим символам.

Управляющие символы:

- 8-битные управляющие символы по стандарту ISO, в которые входят диапазоны U+0000..U+001f и U+007f..U+009f
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR` (символы управления общей категории Cc)
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR` (символы формата общей категории Cf)
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` (символы разделения строк общей категории Zl)
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` (символы разделения параграфов общей категории Zp)

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к управляющим, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::isprint() - Проверяет, является ли символ отображаемым
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - Проверяет управляющие символы

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Проверяет, определили ли кодовую точку

### Описание

public static function IntlChar::isdefined(int|string `$codepoint`): ?bool

Метод проверяет, определена ли кодовая точка, что означает, что кодовой точке назначили символ.

Метод возвращает `true` для символов всех общих категорий, за исключением категории неназначенных кодовых точек — Cn, в которую входят и несимвольные кодовые точки.

> Замечание:

> Обратите внимание, метод не считает несимвольные кодовые точки наподобие U+FDD0 «определёнными», поскольку такие кодовые точки входят в категорию Cn, тогда как суррогатные кодовые точки «определены», поскольку входят в категорию суррогатов — Cs.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` — определённый символ, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isalnum() - Проверяет, относится ли кодовая точка к буквенно-цифровым символам
- IntlChar::isupper() - Проверяет, относится ли символ к общей категории заглавных букв — Lu
- IntlChar::islower() - Проверяет, относится ли символ к общей категории строчных букв — Ll
- IntlChar::istitle() - Проверяет, относится ли кодовая точка к титульным буквам

# IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — Проверяет, относится ли кодовая точка к символам цифр

### Описание

public static function IntlChar::isdigit(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к символам цифр.

Метод возвращает `true` для символов общей категории десятичных цифр — Nd. Начиная с Unicode 4 метод работает так же, как проверка равенства символьного свойства Numeric_Type значению "Decimal".

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` — цифра, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isalnum() - Проверяет, относится ли кодовая точка к буквенно-цифровым символам
- IntlChar::isxdigit() - Проверяет, относится ли кодовая точка к шестнадцатеричной цифре
- ctype_digit() - Проверяет цифровые символы

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Проверяет, входит ли символ в категорию графических

### Описание

public static function IntlChar::isgraph(int|string `$codepoint`): ?bool

Метод проверяет, относится ли символ к категории «графических» символов — печатных символов за исключением пробельных.

Метод возвращает `true` для каждого символа, за исключением тех, которые входят в общую категорию управляющих символов — Cc, символов управления форматом — Cf, суррогатов — Cs, неназначенных символов, включая несимволы — Cn и символов-разделителей — Z.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` входит в категорию «графических» символом, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Смотрите также

- ctype_graph() - Проверяет любые печатные символы кроме пробела

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Проверяет, допускается ли игнорировать символ в идентификаторе

### Описание

public static function IntlChar::isIDIgnorable(int|string `$codepoint`): ?bool

Метод определяет, рассматривать ли символ как символ, который разрешается игнорировать в идентификаторе.

Метод возвращает `true` для символов общей категории прочих символов управления форматом — Cf и непробельных управляющих символов по стандарту ISO: диапазоны кодовых точек U+0000..U+0008, U+000E..U+001B и U+007F..U+009F.

> Замечание:

> Обратите внимание, что Юникод просто рекомендует игнорировать прочие символы форматирования категории Cf.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` разрешается игнорировать в идентификаторах, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- IntlChar::isIDStart() - Проверяет, допустима ли кодовая точка как первый символ идентификатора
- IntlChar::isIDPart() - Проверяет, допустима ли кодовая точка как часть идентификатора
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`

# IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — Проверяет, допустима ли кодовая точка как часть идентификатора

### Описание

public static function IntlChar::isIDPart(int|string `$codepoint`): ?bool

Метод определяет, допустим ли символ как часть идентификатора.

Метод возвращает `true` для символов общей категории букв — L, буквенных чисел — Nl, десятичных цифр — Nd, протяжённых и непротяжённых комбинирующих меток — Mc и Mn, соединителей пунктуации — Pc и символов, которые разрешается игнорировать в идентификаторах, как это определяет внутренняя функция библиотеки ICU — u_isIDIgnorable(c).

> Замечание:

> Почти то же самое, что и символы со свойством ID_Continue в кодировке Unicode, которые в PHP кодирует константа `IntlChar::PROPERTY_ID_CONTINUE`, за исключением того, что Юникод рекомендует игнорировать символы общей категории прочих символов форматирования — Cf, набор которых меньше набора игнорируемых символов, как их определяет метод IntlChar::isIDIgnorable().

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true` если символ кодовой точки `codepoint` разрешается игнорировать в идентификаторах, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isIDIgnorable() - Проверяет, допускается ли игнорировать символ в идентификаторе
- IntlChar::isIDStart() - Проверяет, допустима ли кодовая точка как первый символ идентификатора
- `IntlChar::PROPERTY_ID_CONTINUE`

# IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — Проверяет, допустима ли кодовая точка как первый символ идентификатора

### Описание

public static function IntlChar::isIDStart(int|string `$codepoint`): ?bool

Метод определяет, разрешает ли глава 5.16 «Идентификаторы» стандарта Unicode 3.0 символу стоять в начале идентификатора.

Метод возвращает `true` для символов общей категорий букв — L и буквенных чисел — Nl.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true` если символу с кодовой точкой `codepoint` разрешается стоять в начале идентификатора, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isIDPart() - Проверяет, допустима ли кодовая точка как часть идентификатора
- `IntlChar::PROPERTY_ID_START`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — Проверяет, относится ли кодовая точка к управляющим символам с точки зрения стандарта ISO

### Описание

public static function IntlChar::isISOControl(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к управляющим символам с точки зрения стандарта ISO.

Метод возвращает `true` для кодовых точек в диапазонах U+0000..U+001f и U+007f..U+009f, символы которых относятся к общей категории управляющих символов — Cc.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` — управляющий символ с точки зрения стандарта ISO, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::iscntrl() - Проверяет, относится ли кодовая точка к управляющим символам

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — Проверяет, допустима ли кодовая точка как часть Java-идентификатора

### Описание

public static function IntlChar::isJavaIDPart(int|string `$codepoint`): ?bool

Метод определяет, допустим ли символ как часть идентификатора языка программирования Java.

Метод дополняет метод IntlChar::isIDPart() и возвращает `true`, для символов, которые стандарт объединяет в общей категории символов денежных единиц — Sc.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символу с кодовой точкой `codepoint` разрешается быть частью идентификатора Java, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isIDIgnorable() - Проверяет, допускается ли игнорировать символ в идентификаторе
- IntlChar::isIDPart() - Проверяет, допустима ли кодовая точка как часть идентификатора
- IntlChar::isJavaIDStart() - Проверяет, допустима ли кодовая точка как первый символ Java-идентификатора
- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — Проверяет, допустима ли кодовая точка как первый символ Java-идентификатора

### Описание

public static function IntlChar::isJavaIDStart(int|string `$codepoint`): ?bool

Метод проверяет, разрешается ли символу стоять в начале Java-идентификатора.

Метод дополняет метод IntlChar::isIDStart() и возвращает `true` для символов, которые стандарт объединяет в общих категориях символов денежных единиц — Sc и символов соединителей пунктуации — Pc.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символу с кодовой точкой `codepoint` разрешается быть первым в идентификаторе Java, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isIDStart() - Проверяет, допустима ли кодовая точка как первый символ идентификатора
- IntlChar::isJavaIDPart() - Проверяет, допустима ли кодовая точка как часть Java-идентификатора
- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java

### Описание

public static function IntlChar::isJavaSpaceChar(int|string `$codepoint`): ?bool

Метод проверяет, принадлежит ли кодовая точка к пробельным символам с точки зрения языка программирования Java.

Метод возвращает `true` для символов, которые стандарт объединяет в общей категории разделителей — Z, которая не включает коды управления наподобие символа табуляции TAB или символа перевода строки Line Feed.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если кодовая точка `codepoint` — пробельный символ с точки зрения языка Java, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isJavaSpaceChar("A"));
    var_dump(IntlChar::isJavaSpaceChar(" "));
    var_dump(IntlChar::isJavaSpaceChar("\n"));
    var_dump(IntlChar::isJavaSpaceChar("\t"));
    var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Смотрите также

- IntlChar::isspace() - Проверяет, является ли символ пробельным
- IntlChar::isWhitespace() - Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU
- IntlChar::isUWhiteSpace() - Проверяет, относится ли символ к пробельным

# IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — Проверяет, относится ли символ к общей категории строчных букв — Ll

### Описание

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к общей категории Ll — буквы в нижнем регистре.

> Замечание:

> Метод пропускает ряд символов в верхнем регистре, у которых другое значение общей категории. Чтобы включить такие символы в проверку, вызывают метод IntlChar::isULowercase().

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к общей категории Ll, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isupper() - Проверяет, относится ли символ к общей категории заглавных букв — Lu
- IntlChar::istitle() - Проверяет, относится ли кодовая точка к титульным буквам
- IntlChar::tolower() - Преобразовывает символ Unicode в нижний регистр
- IntlChar::toupper() - Преобразовывает символ Unicode в верхний регистр
- `IntlChar::PROPERTY_LOWERCASE`
- ctype_lower() - Проверяет символы в нижнем регистре

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Проверяет, относится ли символ к двунаправленным

### Описание

public static function IntlChar::isMirrored(int|string `$codepoint`): ?bool

Метод проверяет, определили ли для кодовой точки Unicode-свойство Bidi_Mirrored.

Свойство двунаправленности устанавливают символам, которыми пользуются в контекстах с письмом справа налево и которые требуется отображать «зеркальными» глифами.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если для символа с кодовой точкой `codepoint` определили Unicode-свойство Bidi_Mirrored, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::charMirror() - Получает «зеркально отражённый» символ кодовой точки Юникода
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — Проверяет, является ли символ отображаемым

### Описание

public static function IntlChar::isprint(int|string `$codepoint`): ?bool

Проверяет, является ли символ отображаемым.

`true` для категорий отличных от "C" (управляющие символы).

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает `true`, если `codepoint` является отображаемым символом, `false` - если нет. В случае возникновения ошибки возвращает `null`.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::iscntrl() - Проверяет, относится ли кодовая точка к управляющим символам
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - Проверяет печатные символы

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Проверяет, является ли символ символом пунктуации

### Описание

public static function IntlChar::ispunct(int|string `$codepoint`): ?bool

Проверяет, является ли символ символом пунктуации.

`true` для символов с категорией "P" (пунктуация).

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает `true`, если `codepoint` является символом пунктуации, `false` - если нет. В случае возникновения ошибки возвращает `null`.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- ctype_punct() - Проверяет печатные символы, которые не содержат пробельных или буквенно-цифровых символов

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Проверяет, является ли символ пробельным

### Описание

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Проверяет, является ли символ пробельным.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает `true`, если `codepoint` является пробельным символом, `false` - если нет. В случае возникновения ошибки возвращает `null`.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php
    var_dump(IntlChar::isspace("A"));
    var_dump(IntlChar::isspace(" "));
    var_dump(IntlChar::isspace("\n"));
    var_dump(IntlChar::isspace("\t"));
    var_dump(IntlChar::isspace("\u{00A0}"));
    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::isJavaSpaceChar() - Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
- IntlChar::isWhitespace() - Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU
- IntlChar::isUWhiteSpace() - Проверяет, относится ли символ к пробельным
- ctype_space() - Проверяет пробельные символы

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Проверяет, относится ли кодовая точка к титульным буквам

### Описание

public static function IntlChar::istitle(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к символам букв титульного регистра. В категорию входят диграфы — символы, которые состоят из двух букв, которые закодировали как один символ, первый из которых — заглавный, например U+01F2 LATIN CAPITAL LETTER D WITH SMALL LETTER Z

Метод возвращает `true` для общей категории символов титульного регистра — Lt.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к титульным символам, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    // Латинская заглавная буква Dz с гачеком U+01C4
    var_dump(IntlChar::istitle("Ǆ"));

    // Латинская заглавная буква D с маленькой буквой Z с гачеком U+01C5
    var_dump(IntlChar::istitle("ǅ"));

    // Латинская строчная буква Dz с гачеком U+01C6
    var_dump(IntlChar::istitle("ǆ"));

    // Греческая заглавная буква Alpha с подстрочной йотой U+1FBC
    var_dump(IntlChar::istitle("ᾼ"));

    // Греческая малая буква Alpha с подстрочной йотой U+1FB3
    var_dump(IntlChar::istitle("ᾳ"));

    // Греческая заглавная буква Alpha
    var_dump(IntlChar::istitle("Α"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isupper() - Проверяет, относится ли символ к общей категории заглавных букв — Lu
- IntlChar::islower() - Проверяет, относится ли символ к общей категории строчных букв — Ll
- IntlChar::totitle() - Преобразовывает символ Unicode в титульный регистр (titlecase)

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — Проверяет, относится ли символ к алфавитным

### Описание

public static function IntlChar::isUAlphabetic(int|string `$codepoint`): ?bool

Метод проверяет, определили ли для кодовой точки Unicode-свойство Alphabetic.

Метод работает аналогично вызову `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)`.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если для символа с кодовой точкой `codepoint` определили Unicode-свойство Alphabetic, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isalpha() - Проверяет, относится ли кодовая точка к символам букв
- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- `IntlChar::PROPERTY_ALPHABETIC`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — Проверяет, относится ли символ к нижнему регистру

### Описание

public static function IntlChar::isULowercase(int|string `$codepoint`): ?bool

Метод проверяет, определили ли для кодовой точки Unicode-свойство Lowercase.

Метод работает аналогично вызову `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)`.

> Замечание:

> Метод работает не так же, как метод IntlChar::islower(), и возвращает `true` для большего количества символов.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если для символа с кодовой точкой `codepoint` определили Unicode-свойство Lowercase, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::islower() - Проверяет, относится ли символ к общей категории строчных букв — Ll
- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- `IntlChar::PROPERTY_LOWERCASE`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — Проверяет, относится ли символ к общей категории заглавных букв — Lu

### Описание

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Метод определяет, относится ли кодовая точка к общей категории Lu — буквы в верхнем регистре.

> Замечание:

> Метод пропускает ряд символов в верхнем регистре, у которых другое значение общей категории. Чтобы включить такие символы в проверку, вызывают метод IntlChar::isUUppercase().

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если символ кодовой точки `codepoint` относится к общей категории Lu, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::islower() - Проверяет, относится ли символ к общей категории строчных букв — Ll
- IntlChar::istitle() - Проверяет, относится ли кодовая точка к титульным буквам
- IntlChar::tolower() - Преобразовывает символ Unicode в нижний регистр
- IntlChar::toupper() - Преобразовывает символ Unicode в верхний регистр
- `IntlChar::PROPERTY_UPPERCASE`
- ctype_upper() - Проверяет символы в верхнем регистре

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Проверяет, относится ли символ к верхнему регистру

### Описание

public static function IntlChar::isUUppercase(int|string `$codepoint`): ?bool

Метод проверяет, определили ли для кодовой точки Unicode-свойство Uppercase.

Метод работает аналогично вызову `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)`

> Замечание:

> Метод работает не так же, как метод IntlChar::isupper(), и возвращает `true` для большего количества символов.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если для символа с кодовой точкой `codepoint` определили Unicode-свойство Uppercase, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Смотрите также

- IntlChar::isupper() - Проверяет, относится ли символ к общей категории заглавных букв — Lu
- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- `IntlChar::PROPERTY_UPPERCASE`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — Проверяет, относится ли символ к пробельным

### Описание

public static function IntlChar::isUWhiteSpace(int|string `$codepoint`): ?bool

Метод проверяет, определили ли для кодовой точки Unicode-свойство White_Space.

Метод работает аналогично вызову `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)`

> Замечание:

> Метод работает не так же, как методы IntlChar::isspace() и IntlChar::isWhitespace().

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если для символа с кодовой точкой `codepoint` определили Unicode-свойство White_Space, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isUWhiteSpace("A"));
    var_dump(IntlChar::isUWhiteSpace(" "));
    var_dump(IntlChar::isUWhiteSpace("\n"));
    var_dump(IntlChar::isUWhiteSpace("\t"));
    var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Смотрите также

- IntlChar::isspace() - Проверяет, является ли символ пробельным
- IntlChar::isWhitespace() - Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU
- IntlChar::isJavaSpaceChar() - Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
- IntlChar::hasBinaryProperty() - Проверяет бинарное свойство Unicode для символа
- `IntlChar::PROPERTY_WHITE_SPACE`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU

### Описание

public static function IntlChar::isWhitespace(int|string `$codepoint`): ?bool

Метод проверяет, принадлежит ли кодовая точка к пробельным символам с точки зрения стандартов, по которым создают компоненты интернационализации ICU.

Символ относится к пробельным символам в рамках компонентов ICU тогда и только тогда, когда удовлетворяет хотя бы одному критерию из следующего списка:

- Unicode-символ принадлежит классу Separator, который представляет категория Z — разделители, которая объединяет категории Zs — символы пробела ненулевой ширины, Zl — разделители строк, Zp — разделители параграфов, но это не неразрывный пробел U+00A0 NBSP, U+2007 Figure Space или U+202F Narrow NBSP, или это символ, которому назначили кодовую точку и название:
- U+0009 HORIZONTAL TABULATION.
- U+000A LINE FEED.
- U+000B VERTICAL TABULATION.
- U+000C FORM FEED.
- U+000D CARRIAGE RETURN.
- U+001C FILE SEPARATOR.
- U+001D GROUP SEPARATOR.
- U+001E RECORD SEPARATOR.
- U+001F UNIT SEPARATOR.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает `true`, если кодовая точка `codepoint` — пробельный символ с точки зрения стандартов, по которым создают международные компоненты Юникода — ICU, `false`, если нет. Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::iswhitespace("A"));
    var_dump(IntlChar::iswhitespace(" "));
    var_dump(IntlChar::iswhitespace("\n"));
    var_dump(IntlChar::iswhitespace("\t"));
    var_dump(IntlChar::iswhitespace("\u{00A0}"));

    ?>

Результат выполнения приведённого примера:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Смотрите также

- IntlChar::isspace() - Проверяет, является ли символ пробельным
- IntlChar::isJavaSpaceChar() - Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
- IntlChar::isUWhiteSpace() - Проверяет, относится ли символ к пробельным

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — Проверяет, относится ли кодовая точка к шестнадцатеричной цифре

### Описание

public static function IntlChar::isxdigit(int|string `$codepoint`): ?bool

Проверяет, относится ли кодовая точка к шестнадцатеричной цифре.

`true` для символов общей категории «Nd» (десятичные числа), а также латинских букв a-f и A-F как в представлениях ASCII, так и в представлении ASCII полной ширины. (То есть для букв с кодовыми точками 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

Эквивалентно `IntlChar::digit($codepoint, 16) >= 0`.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает `true`, если кодовая точка `codepoint` — это шестнадцатеричный символ, или `false` — если нет. В случае возникновения ошибки возвращает `null`.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    bool(true)
    bool(true)
    bool(false)

### Примечания

> Замечание:

> Чтобы сузить определение шестнадцатеричных цифр, принимаются только ASCII-символы:

>     <?php

>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);

>     ?>

### Смотрите также

- IntlChar::isdigit() - Проверяет, относится ли кодовая точка к символам цифр
- ctype_xdigit() - Проверяет шестнадцатеричные цифры

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Возвращает значение кодовой точки символа Юникода

### Описание

public static function IntlChar::ord(int|string `$character`): ?int

Метод возвращает значение кодовой точки, которой в кодировке Unicode назначили символ.

Метод дополняет метод IntlChar::chr().

### Список параметров

`character`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Метод возвращает целочисленное значение кодовой точки Юникода.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));

    ?>

Результат выполнения приведённого примера:

    int(65)
    int(32)
    int(9731)

### Смотрите также

- IntlChar::chr() - Возвращает символ Юникода по значению кодовой точки
- mb_ord() - Получает кодовую точку символа Unicode
- ord() - Преобразовывает первый байт строки в число от 0 до 255

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Преобразовывает символ Unicode в нижний регистр

### Описание

public static function IntlChar::tolower(int|string `$codepoint`): int|string|null

Преобразовывает символ в его эквивалент в нижнем регистре. Если такового нет, то возвращается исходный символ.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает Simple_Lowercase_Mapping для символа, если существует. Если нет, то возвращает исходный символ. В случае возникновения ошибки возвращает `null`.

Метод возвращает целое число (int), если только кодовую точку не передали как строку (string) в кодировке UTF-8, при передаче которой возвращается строка (string). Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php
    var_dump(IntlChar::tolower("A"));
    var_dump(IntlChar::tolower("a"));
    var_dump(IntlChar::tolower("Φ"));
    var_dump(IntlChar::tolower("φ"));
    var_dump(IntlChar::tolower("1"));
    var_dump(IntlChar::tolower(ord("A")));
    var_dump(IntlChar::tolower(ord("a")));
    ?>

Результат выполнения приведённого примера:

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### Смотрите также

- IntlChar::totitle() - Преобразовывает символ Unicode в титульный регистр (titlecase)
- IntlChar::toupper() - Преобразовывает символ Unicode в верхний регистр
- mb_strtolower() - Приводит строку к нижнему регистру

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Преобразовывает символ Unicode в титульный регистр (titlecase)

### Описание

public static function IntlChar::totitle(int|string `$codepoint`): int|string|null

Возвращает эквивалент символа в титульном (titlecase) регистре. Если такового нет, то возвращается исходный символ.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает Простое_Сопоставление_в_Титульном_Регистре (Simple_Titlecase_Mapping) для символа, если существует. Если нет, то возвращает исходный символ. В случае возникновения ошибки возвращает `null`.

Метод возвращает целое число (int), если только кодовую точку не передали как строку (string) в кодировке UTF-8, при передаче которой возвращается строка (string). Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    var_dump(IntlChar::totitle("Ǆ"));
    var_dump(IntlChar::totitle("ǆ"));
    var_dump(IntlChar::totitle("Φ"));
    var_dump(IntlChar::totitle("φ"));
    var_dump(IntlChar::totitle("1"));
    var_dump(IntlChar::totitle("ᾳ"));
    var_dump(IntlChar::totitle(ord("A")));
    ?>

Результат выполнения приведённого примера:

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### Смотрите также

- IntlChar::tolower() - Преобразовывает символ Unicode в нижний регистр
- IntlChar::toupper() - Преобразовывает символ Unicode в верхний регистр
- IntlChar::istitle() - Проверяет, относится ли кодовая точка к титульным буквам
- mb_convert_case() - Меняет регистр символов в строке

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Преобразовывает символ Unicode в верхний регистр

### Описание

public static function IntlChar::toupper(int|string `$codepoint`): int|string|null

Преобразовывает символ в его эквивалент в верхнем регистре. Если такого нет, то возвращается исходный символ.

### Список параметров

`codepoint`
  Целочисленное (int) значение кодовой точки (например, `0x2603` для символа U+2603 СНЕГОВИК) или символ в виде строки (string) в кодировке UTF-8 (например `"\u{2603}"`).

### Возвращаемые значения

Возвращает Simple_Uppercase_Mapping символа, если он есть; иначе возвращается исходный символ.

Метод возвращает целое число (int), если только кодовую точку не передали как строку (string) в кодировке UTF-8, при передаче которой возвращается строка (string). Метод возвращает `null`, если возникла ошибка.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php
    var_dump(IntlChar::toupper("A"));
    var_dump(IntlChar::toupper("a"));
    var_dump(IntlChar::toupper("Φ"));
    var_dump(IntlChar::toupper("φ"));
    var_dump(IntlChar::toupper("1"));
    var_dump(IntlChar::toupper(ord("A")));
    var_dump(IntlChar::toupper(ord("a")));
    ?>

Результат выполнения приведённого примера:

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### Смотрите также

- IntlChar::tolower() - Преобразовывает символ Unicode в нижний регистр
- IntlChar::totitle() - Преобразовывает символ Unicode в титульный регистр (titlecase)
- mb_strtoupper() - Приводит строку к верхнему регистру

## Содержание

- IntlChar::charAge — Получает «возраст» кодовой точки
- IntlChar::charDigitValue — Получает десятичное значение десятичного символа
- IntlChar::charDirection — Получает двунаправленное значение категории кодовой точки
- IntlChar::charFromName — Находит Unicode-символ по имени и возвращает значение кодовой точки символа
- IntlChar::charMirror — Получает «зеркально отражённый» символ кодовой точки Юникода
- IntlChar::charName — Извлекает название Unicode-символа
- IntlChar::charType — Получает значение общей категории кодовой точки
- IntlChar::chr — Возвращает символ Юникода по значению кодовой точки
- IntlChar::digit — Получает десятичное значение цифры кодовой точки в заданной системе счисления
- IntlChar::enumCharNames — Перечисляет все присвоенные символы Unicode в заданном диапазоне
- IntlChar::enumCharTypes — Перечисляет кодовые точки с их общими категориями Юникода
- IntlChar::foldCase — Преобразовывает регистр кодовой точки
- IntlChar::forDigit — Получает кодовую точку символьного представления числа в заданной системе счисления
- IntlChar::getBidiPairedBracket — Получает символ парной скобки для кодовой точки
- IntlChar::getBlockCode — Получает блок распределения, который содержит кодовую точку символа Юникода
- IntlChar::getCombiningClass — Получает класс объединения для символа
- IntlChar::getFC_NFKC_Closure — Получает свойство FC_NFKC_Closure для символа
- IntlChar::getIntPropertyMaxValue — Получает максимальное значение Unicode-свойства
- IntlChar::getIntPropertyMinValue — Получает минимальное значение Unicode-свойства
- IntlChar::getIntPropertyValue — Получает значение Unicode-свойства кодовой точки
- IntlChar::getNumericValue — Получает числовое значение кодовой точки Юникода
- IntlChar::getPropertyEnum — Получает постоянное значение свойства по имени свойства
- IntlChar::getPropertyName — Получает Unicode-имя свойства
- IntlChar::getPropertyValueEnum — Получает значение свойства по имени значения
- IntlChar::getPropertyValueName — Получает значения свойства Юникода
- IntlChar::getUnicodeVersion — Получает версию стандарта Unicode
- IntlChar::hasBinaryProperty — Проверяет бинарное свойство Unicode для символа
- IntlChar::isalnum — Проверяет, относится ли кодовая точка к буквенно-цифровым символам
- IntlChar::isalpha — Проверяет, относится ли кодовая точка к символам букв
- IntlChar::isbase — Проверяет, относится ли кодовая точка к базовому символу
- IntlChar::isblank — Проверяет, относится ли кодовая точка к символам «пустого места» или «горизонтального пробела»
- IntlChar::iscntrl — Проверяет, относится ли кодовая точка к управляющим символам
- IntlChar::isdefined — Проверяет, определили ли кодовую точку
- IntlChar::isdigit — Проверяет, относится ли кодовая точка к символам цифр
- IntlChar::isgraph — Проверяет, входит ли символ в категорию графических
- IntlChar::isIDIgnorable — Проверяет, допускается ли игнорировать символ в идентификаторе
- IntlChar::isIDPart — Проверяет, допустима ли кодовая точка как часть идентификатора
- IntlChar::isIDStart — Проверяет, допустима ли кодовая точка как первый символ идентификатора
- IntlChar::isISOControl — Проверяет, относится ли кодовая точка к управляющим символам с точки зрения стандарта ISO
- IntlChar::isJavaIDPart — Проверяет, допустима ли кодовая точка как часть Java-идентификатора
- IntlChar::isJavaIDStart — Проверяет, допустима ли кодовая точка как первый символ Java-идентификатора
- IntlChar::isJavaSpaceChar — Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
- IntlChar::islower — Проверяет, относится ли символ к общей категории строчных букв — Ll
- IntlChar::isMirrored — Проверяет, относится ли символ к двунаправленным
- IntlChar::isprint — Проверяет, является ли символ отображаемым
- IntlChar::ispunct — Проверяет, является ли символ символом пунктуации
- IntlChar::isspace — Проверяет, является ли символ пробельным
- IntlChar::istitle — Проверяет, относится ли кодовая точка к титульным буквам
- IntlChar::isUAlphabetic — Проверяет, относится ли символ к алфавитным
- IntlChar::isULowercase — Проверяет, относится ли символ к нижнему регистру
- IntlChar::isupper — Проверяет, относится ли символ к общей категории заглавных букв — Lu
- IntlChar::isUUppercase — Проверяет, относится ли символ к верхнему регистру
- IntlChar::isUWhiteSpace — Проверяет, относится ли символ к пробельным
- IntlChar::isWhitespace — Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU
- IntlChar::isxdigit — Проверяет, относится ли кодовая точка к шестнадцатеричной цифре
- IntlChar::ord — Возвращает значение кодовой точки символа Юникода
- IntlChar::tolower — Преобразовывает символ Unicode в нижний регистр
- IntlChar::totitle — Преобразовывает символ Unicode в титульный регистр (titlecase)
- IntlChar::toupper — Преобразовывает символ Unicode в верхний регистр

# Класс исключений для ошибок intl

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

## Введение

Этот класс служит для вызова исключений в случае возникновения ошибки в функциях intl. Данные исключения могут быть выброшены только если включена опция intl.use_exceptions.

## Обзор класса

class IntlException extends Exception {
/* Наследуемые свойства */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Наследуемые методы */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Класс IntlIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Введение

Этот класс представляет итератор объектов модуля intl в тех случаях, когда нельзя назначить какой-либо другой итератор для объекта данного модуля. Единственный объект итератора для использования в конструкции `foreach` может быть получен только (в соответствующей части здесь) из объектов, так что объекты данного класса служат для получения таких внутренних объектов. Для удобства данный класс также реализует интерфейс Iterator, позволяя взаимодействовать с коллекциями значений используя методы определённые в этом интерфейсе. Оба этих метода и внутренние объекты итератора сохраняют своё состояние при передачи в `foreach`. (т.е. внутренний указатель и текущее значение остаются неизменны).

Классы потомки могут предоставлять более широкую функциональность.

## Обзор класса

class IntlIterator implements Iterator {
/* Методы */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — Получить текущий элемент

### Описание

public function IntlIterator::current(): mixed

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Получить ключ текущего элемента

### Описание

public function IntlIterator::key(): mixed

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Перейти к следующему элементу

### Описание

public function IntlIterator::next(): void

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Перейти к первому элементу

### Описание

public function IntlIterator::rewind(): void

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Проверить, корректна ли текущая позиция

### Описание

public function IntlIterator::valid(): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

## Содержание

- IntlIterator::current — Получить текущий элемент
- IntlIterator::key — Получить ключ текущего элемента
- IntlIterator::next — Перейти к следующему элементу
- IntlIterator::rewind — Перейти к первому элементу
- IntlIterator::valid — Проверить, корректна ли текущая позиция

# Функции intl

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — Получить имя ошибки по её коду

### Описание

function intl_error_name(int `$errorCode`): string

Возвращает имя ошибки ICU.

### Список параметров

`errorCode`

  Код ошибки ICU.

### Возвращаемые значения

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

### Примеры

Пример #1 Пример использования intl_error_name()

    <?php
    $coll     = collator_create( 'en_RU' );
    $err_code = collator_get_error_code( $coll );

    printf( "Символическое имя для %d - %s\n.", $err_code, intl_error_name( $err_code ) );
    ?>

Вывод приведённого примера будет похож на:

    Символическое имя для -128 - U_USING_FALLBACK_WARNING.

### Смотрите также

- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя
- intl_get_error_code() - Получить код последней ошибки
- intl_get_error_message() - Получить описание ошибки

# intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — Получить код последней ошибки

### Описание

function intl_get_error_code(): int

Полезно для обработки ошибок статических методов, когда отсутствует объект для извлечения ошибки из него.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Код ошибки, возвращённый последним вызовом функции API.

### Примеры

Пример #1 Пример использования intl_get_error_code()

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### Смотрите также

- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя
- intl_error_name() - Получить имя ошибки по её коду
- intl_get_error_message() - Получить описание ошибки
- collator_get_error_code() - Получает последний код ошибки Collator
- numfmt_get_error_code() - Получает последний код ошибки средства форматирования

# intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — Получить описание ошибки

### Описание

function intl_get_error_message(): string

Получить описание последней произошедшей ошибки в функциях ICU.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Описание последней произошедшей ошибки в функциях ICU.

### Примеры

Пример #1 Пример использования intl_get_error_message()

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### Смотрите также

- intl_error_name() - Получить имя ошибки по её коду
- intl_get_error_code() - Получить код последней ошибки
- intl_is_failure() - Проверить, является ли код ошибки признаком сбоя
- collator_get_error_message() - Получает текст для кода последней ошибки Collator
- numfmt_get_error_message() - Получает последнее сообщение об ошибке средства форматирования

# intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — Проверить, является ли код ошибки признаком сбоя

### Описание

function intl_is_failure(int `$errorCode`): bool

### Список параметров

`errorCode`

  Значение, возвращённое функциями: intl_get_error_code(), collator_get_error_code() .

### Возвращаемые значения

`true`, если произошёл сбой, и `false`, если все успешно, либо просто предупреждение.

### Примеры

Пример #1 Пример использования intl_is_failure()

    <?php
    function check( $err_code )
    {
        var_export( intl_is_failure( $err_code ) );
        echo "\n";
    }

    check( U_ZERO_ERROR );
    check( U_USING_FALLBACK_WARNING );
    check( U_ILLEGAL_ARGUMENT_ERROR );
    ?>

Вывод приведённого примера будет похож на:

    false
    false
    true

### Смотрите также

- intl_get_error_code() - Получить код последней ошибки
- collator_get_error_code() - Получает последний код ошибки Collator
- Collator-getErrorCode()

## Содержание

- intl_error_name — Получить имя ошибки по её коду
- intl_get_error_code — Получить код последней ошибки
- intl_get_error_message — Получить описание ошибки
- intl_is_failure — Проверить, является ли код ошибки признаком сбоя

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Примеры
  - Основы использования модуля
- Collator — Класс Collator
  - Collator::asort — Сортирует массив с сохранением ассоциации индекса
  - Collator::compare — Сравнивает две строки Unicode
  - Collator::__construct — Создаёт новый экземпляр Collator
  - Collator::create — Создаёт новый экземпляр Collator
  - Collator::getAttribute — Получает значение атрибута сопоставления
  - Collator::getErrorCode — Получает последний код ошибки Collator
  - Collator::getErrorMessage — Получает текст для кода последней ошибки Collator
  - Collator::getLocale — Получает название локали для Collator
  - Collator::getSortKey — Получает ключ сортировки строки
  - Collator::getStrength — Получает текущую силу сопоставления
  - Collator::setAttribute — Устанавливает атрибут сопоставления
  - Collator::setStrength — Устанавливает силу сопоставления
  - Collator::sort — Сортирует массив с использованием указанного средства сортировки
  - Collator::sortWithSortKeys — Сортирует массив с использованием указанного Collator и ключей сортировки
- NumberFormatter — The NumberFormatter class
  - NumberFormatter::create — Создаёт средство форматирования чисел
  - NumberFormatter::format — Форматирует число
  - NumberFormatter::formatCurrency — Форматирует значение валюты
  - NumberFormatter::getAttribute — Получает атрибут
  - NumberFormatter::getErrorCode — Получает последний код ошибки средства форматирования
  - NumberFormatter::getErrorMessage — Получает последнее сообщение об ошибке средства форматирования
  - NumberFormatter::getLocale — Получает локаль средства форматирования
  - NumberFormatter::getPattern — Получает шаблон средства форматирования
  - NumberFormatter::getSymbol — Получает значение символа
  - NumberFormatter::getTextAttribute — Получает текстовый атрибут
  - NumberFormatter::parse — Разбирает число
  - NumberFormatter::parseCurrency — Разбирает номер валюты
  - NumberFormatter::setAttribute — Устанавливает значение для атрибута форматирования чисел
  - NumberFormatter::setPattern — Устанавливает шаблон средства форматирования
  - NumberFormatter::setSymbol — Устанавливает значение символа
  - NumberFormatter::setTextAttribute — Устанавливает текстовый атрибут
- Locale — Класс Locale
  - Locale::acceptFromHttp — Попытаться определить наилучшую локаль основываясь на заголовке HTTP "Accept-Language"
  - Locale::canonicalize — Канонизировать строку локали
  - Locale::composeLocale — Возвращает правильно упорядоченный и разделенный идентификатор локали
  - Locale::filterMatches — Проверить, соответствует ли тег фильтра языка локали
  - Locale::getAllVariants — Получение вариантов из переданной локали
  - Locale::getDefault — Получение значения локали INTL по умолчанию из опции 'default_locale'
  - Locale::getDisplayLanguage — Возвращает соответствующим образом локализованное имя языка для заданной локали
  - Locale::getDisplayName — Возвращает соответствующим образом локализованное имя локали
  - Locale::getDisplayRegion — Возвращает соответствующим образом локализованное название региона для заданной локали
  - Locale::getDisplayScript — Возвращает соответствующим образом локализованное название алфавита для заданной локали
  - Locale::getDisplayVariant — Возвращает соответствующим образом локализованное название варианта для заданной локали
  - Locale::getKeywords — Получить ключевые слова для локали
  - Locale::getPrimaryLanguage — Получить первичный язык для локали
  - Locale::getRegion — Получить регион для локали
  - Locale::getScript — Получить алфавит для локали
  - Locale::isRightToLeft — Проверяет, характерно ли для языка направление письма справа налево
  - Locale::lookup — Поиск языковых меток наиболее подходящих заданной локали
  - Locale::parseLocale — Получить ассоциативный массив всех подтегов локали
  - Locale::setDefault — Устанавливает локаль по умолчанию во время исполнения
- Normalizer — Класс Normalizer
  - Normalizer::getRawDecomposition — Извлекает свойство Decomposition_Mapping для заданного символа UTF-8
  - Normalizer::isNormalized — Проверить, соответствует ли переданная строка заданной форме нормализации
  - Normalizer::normalize — Нормализация строки
- MessageFormatter — Класс MessageFormatter
  - MessageFormatter::create — Создаёт средство форматирования сообщений
  - MessageFormatter::format — Форматирует сообщение
  - MessageFormatter::formatMessage — Быстро форматирует сообщение
  - MessageFormatter::getErrorCode — Возвращает код ошибки последней операции
  - MessageFormatter::getErrorMessage — Возвращает текст ошибки последней операции
  - MessageFormatter::getLocale — Возвращает локаль, для которой было создано средство форматирования
  - MessageFormatter::getPattern — Возвращает шаблон, используемый средством форматирования
  - MessageFormatter::parse — Разбирает строку согласно шаблону
  - MessageFormatter::parseMessage — Быстро разбирает входную строку
  - MessageFormatter::setPattern — Устанавливает шаблон, используемый средством форматирования
- IntlCalendar — Класс IntlCalendar
  - IntlCalendar::add — Добавляет количество (со знаком) времени в поле
  - IntlCalendar::after — Определяет, время этого объекта позже времени переданного объекта
  - IntlCalendar::before — Определяет, время этого объекта раньше времени переданного объекта
  - IntlCalendar::clear — Очищает поле или все поля
  - IntlCalendar::__construct — Закрытый конструктор для запрета создания экземпляров
  - IntlCalendar::createInstance — Создаёт новый объект IntlCalendar
  - IntlCalendar::equals — Сравнивает время двух объектов IntlCalendar на предмет равенства
  - IntlCalendar::fieldDifference — Вычисляет разницу между заданным временем и временем объекта
  - IntlCalendar::fromDateTime — Создаёт объект IntlCalendar из объекта DateTime или строки
  - IntlCalendar::get — Получает значение поля
  - IntlCalendar::getActualMaximum — Максимальное значение для поля с учётом текущего времени объекта
  - IntlCalendar::getActualMinimum — Минимальное значение для поля с учётом текущего времени объекта
  - IntlCalendar::getAvailableLocales — Получает массив языковых стандартов, для которых есть данные
  - IntlCalendar::getDayOfWeekType — Сообщает, является ли день будним, выходным или днём с переходом между ними
  - IntlCalendar::getErrorCode — Получает последний код ошибки объекта
  - IntlCalendar::getErrorMessage — Получает последнее сообщение об ошибке для объекта
  - IntlCalendar::getFirstDayOfWeek — Получает первый день недели для языкового стандарта календаря
  - IntlCalendar::getGreatestMinimum — Получает наибольшее локальное минимальное значение поля
  - IntlCalendar::getKeywordValuesForLocale — Получает набор значений ключевых слов языкового стандарта
  - IntlCalendar::getLeastMaximum — Получает наименьший локальный максимум поля
  - IntlCalendar::getLocale — Получает языковой стандарт, связанный с объектом
  - IntlCalendar::getMaximum — Получает глобальное максимальное значение поля
  - IntlCalendar::getMinimalDaysInFirstWeek — Получает минимальное количество дней, которое может быть в первой неделе в году или месяце
  - IntlCalendar::getMinimum — Получает глобальное минимальное значение поля
  - IntlCalendar::getNow — Получает число, представляющее текущее время
  - IntlCalendar::getRepeatedWallTimeOption — Получает поведение для обработки повторяющегося времени процессора
  - IntlCalendar::getSkippedWallTimeOption — Получает поведение для обработки пропущенного времени процессора
  - IntlCalendar::getTime — Получает время, представленное в данный момент объектом
  - IntlCalendar::getTimeZone — Получает часовой пояс объекта
  - IntlCalendar::getType — Получает тип календаря
  - IntlCalendar::getWeekendTransition — Получает время дня, когда выходные начинаются или заканчиваются
  - IntlCalendar::inDaylightTime — Определяет, переходит ли время объекта на летнее время
  - IntlCalendar::isEquivalentTo — Определяет, равен ли другой календарь, но для другого времени
  - IntlCalendar::isLenient — Определяет, является ли интерпретация даты/времени мягкой
  - IntlCalendar::isSet — Определяет, установлено ли поле
  - IntlCalendar::isWeekend — Определяет, приходятся ли определённые дата/время на выходные
  - IntlCalendar::roll — Добавляет значение в поле без переноса в более важные поля
  - IntlCalendar::set — Устанавливает поле времени или сразу несколько общих полей
  - IntlCalendar::setDate — Устанавливает поля даты
  - IntlCalendar::setDateTime — Устанавливает поля даты и времени
  - IntlCalendar::setFirstDayOfWeek — Устанавливает день, который является началом недели
  - IntlCalendar::setLenient — Устанавливает, должна ли интерпретация даты/времени быть мягкой
  - IntlCalendar::setMinimalDaysInFirstWeek — Устанавливает минимальное количество дней, которое может быть в первой неделе в году или месяце
  - IntlCalendar::setRepeatedWallTimeOption — Устанавливает поведение для обработки повторяющегося времени процессора при отрицательных переходах смещения часового пояса
  - IntlCalendar::setSkippedWallTimeOption — Устанавливает поведение для обработки пропущенного времени процессора при положительных переходах смещения часового пояса
  - IntlCalendar::setTime — Устанавливает календарное время в миллисекундах с начала эпохи Unix
  - IntlCalendar::setTimeZone — Устанавливает часовой пояс, используемый календарём
  - IntlCalendar::toDateTime — Преобразовывает объект IntlCalendar в объект DateTime
- IntlGregorianCalendar — Класс IntlGregorianCalendar
  - IntlGregorianCalendar::__construct — Конструктор класса григорианского календаря
  - IntlGregorianCalendar::createFromDate — Создаёт новый экземпляр класса IntlGregorianCalendar из даты
  - IntlGregorianCalendar::createFromDateTime — Создаёт новый экземпляр класса IntlGregorianCalendar из даты и времени
  - IntlGregorianCalendar::getGregorianChange — Получает дату изменения григорианского календаря
  - IntlGregorianCalendar::isLeapYear — Определяет, является ли данный год високосным
  - IntlGregorianCalendar::setGregorianChange — Устанавливает дату изменения в григорианском календаре
- IntlTimeZone — Класс IntlTimeZone
  - IntlTimeZone::__construct — Конструктор класса, запрещающий прямое создание экземпляра
  - IntlTimeZone::countEquivalentIDs — Получить количество идентификаторов в группе похожих часовых поясов, включая данный идентификатор
  - IntlTimeZone::createDefault — Создать новую копию часового пояса по умолчанию для текущего хоста
  - IntlTimeZone::createEnumeration — Получить перечисление из идентификаторов часовых поясов по указанной стране или смещению
  - IntlTimeZone::createTimeZone — Создать объект часового пояса по заданному идентификатору
  - IntlTimeZone::createTimeZoneIDEnumeration — Получить перечисление из идентификаторов системных часовых поясов по заданным условиям фильтрации
  - IntlTimeZone::fromDateTimeZone — Создать объект часового пояса из DateTimeZone
  - IntlTimeZone::getCanonicalID — Получает канонический системный идентификатор часового пояса или нормализованный пользовательский идентификатор часового пояса по идентификатору часового пояса
  - IntlTimeZone::getDisplayName — Получить имя часового пояса для отображения пользователю
  - IntlTimeZone::getDSTSavings — Получить количество миллисекунд, которое нужно добавить к местному поясному времени, чтобы получить летнее время
  - IntlTimeZone::getEquivalentID — Получить идентификатор в группе похожих часовых поясов, включая заданный идентификатор
  - IntlTimeZone::getErrorCode — Получить последний код об ошибке в объекте
  - IntlTimeZone::getErrorMessage — Получить последнее сообщение об ошибке в объекте
  - IntlTimeZone::getGMT — Создать часовой пояс по GMT (UTC)
  - IntlTimeZone::getIanaID — Возвращает эквивалент идентификатора часового пояса из базы часовых поясов IANA
  - IntlTimeZone::getID — Получает идентификатор часового пояса
  - IntlTimeZone::getIDForWindowsID — Преобразовать часовой пояс для Windows в системный часовой пояс
  - IntlTimeZone::getOffset — Получить необработанное значение часового пояса и смещение по Гринвичу (GMT) по заданному моменту времени
  - IntlTimeZone::getRawOffset — Получить необработанное значение смещения по Гринвичу (GMT) без учёта летнего времени
  - IntlTimeZone::getRegion — Получить код региона, соответствующего заданному идентификатору системного часового пояса
  - IntlTimeZone::getTZDataVersion — Получить версию данных о часовом поясе, который в данный момент используется в ICU
  - IntlTimeZone::getUnknown — Получить неизвестный часовой пояс («unknown»)
  - IntlTimeZone::getWindowsID — Преобразовать системный часовой пояс в часовой пояс для Windows
  - IntlTimeZone::hasSameRules — Проверить, что в другом часовом поясе используются те же самые правила и смещения, что и в первом заданном
  - IntlTimeZone::toDateTimeZone — Преобразовать в объект DateTimeZone
  - IntlTimeZone::useDaylightTime — Проверить, что в данном часовом поясе используется летнее время
- IntlDateFormatter — Класс IntlDateFormatter
  - IntlDateFormatter::create — Создаёт средство форматирования даты
  - IntlDateFormatter::format — Форматирует значение даты и времени как строку
  - IntlDateFormatter::formatObject — Форматирует объект
  - IntlDateFormatter::getCalendar — Получает тип календаря для объекта IntlDateFormatter
  - IntlDateFormatter::getDateType — Получает тип даты, используемый IntlDateFormatter
  - IntlDateFormatter::getErrorCode — Получает код ошибки последней операции
  - IntlDateFormatter::getErrorMessage — Получает текст ошибки последней операции
  - IntlDateFormatter::getLocale — Получает языковой стандарт, используемый средством форматирования
  - IntlDateFormatter::getPattern — Получает шаблон, используемый IntlDateFormatter
  - IntlDateFormatter::getTimeType — Получает тип времени, используемый IntlDateFormatter
  - IntlDateFormatter::getTimeZoneId — Получает идентификатор часового пояса, используемый IntlDateFormatter
  - IntlDateFormatter::getCalendarObject — Получает копию объекта календаря средства форматирования
  - IntlDateFormatter::getTimeZone — Получает часовой пояс средства форматирования
  - IntlDateFormatter::isLenient — Получает снисходительность, используемую для IntlDateFormatter
  - IntlDateFormatter::localtime — Разбирает строку на отдельные составляющие времени, которые возвращает в ассоциативном массиве
  - IntlDateFormatter::parse — Преобразовывает строку в значение отметки времени
  - IntlDateFormatter::parseToCalendar — Разбирает строку в метку времени, которой обновляет открытый календарь
  - IntlDateFormatter::setCalendar — Устанавливает тип календаря для средства форматирования
  - IntlDateFormatter::setLenient — Устанавливает мягкий режим анализатора
  - IntlDateFormatter::setPattern — Устанавливает шаблон, используемый IntlDateFormatter
  - IntlDateFormatter::setTimeZone — Устанавливает часовой пояс средства форматирования
- ResourceBundle — Класс ResourceBundle
  - ResourceBundle::count — Получить количество элементов в пакете
  - ResourceBundle::create — Создать пакет ресурсов
  - ResourceBundle::get — Получает данные из пакета
  - ResourceBundle::getErrorCode — Получить последний код ошибки пакета
  - ResourceBundle::getErrorMessage — Получить последнее сообщение об ошибке пакета
  - ResourceBundle::getLocales — Получить поддерживаемые локали
- Spoofchecker — Класс Spoofchecker
  - Spoofchecker::areConfusable — Проверить, являются ли строки подозрительными
  - Spoofchecker::__construct — Конструктор класса
  - Spoofchecker::isSuspicious — Проверяет, содержит ли текст подозрительные символы
  - Spoofchecker::setAllowedChars — Задаёт набор символов, допустимых при выполнении проверок
  - Spoofchecker::setAllowedLocales — Локаль для использования в проверках
  - Spoofchecker::setChecks — Установить набор проверок
  - Spoofchecker::setRestrictionLevel — Устанавливает уровень ограничения
- Transliterator — Класс Transliterator
  - Transliterator::__construct — Приватный конструктор
  - Transliterator::create — Создать транслитератор
  - Transliterator::createFromRules — Создать транслитератор на основе правил
  - Transliterator::createInverse — Создать инвертированный транслитератор
  - Transliterator::getErrorCode — Получить код последней ошибки
  - Transliterator::getErrorMessage — Получить последнее сообщение об ошибке
  - Transliterator::listIDs — Получить идентификаторы транслитератора
  - Transliterator::transliterate — Транслитерировать строку
- IntlBreakIterator — Класс IntlBreakIterator
  - IntlBreakIterator::__construct — Закрытый конструктор, запрещающий создание экземпляров объекта
  - IntlBreakIterator::createCharacterInstance — Создаёт итератор прерывания для границ комбинирования последовательностей символов
  - IntlBreakIterator::createCodePointInstance — Создаёт итератор прерывания для границ кодовых точек
  - IntlBreakIterator::createLineInstance — Создаёт итератор прерывания для логически возможных разрывов строк
  - IntlBreakIterator::createSentenceInstance — Создаёт итератор прерывания для разрывов предложений
  - IntlBreakIterator::createTitleInstance — Создаёт итератор прерывания для разрывов заголовков
  - IntlBreakIterator::createWordInstance — Создаёт итератор прерывания для разрывов слов
  - IntlBreakIterator::current — Возвращает индекс текущей позиции
  - IntlBreakIterator::first — Устанавливает позицию к первому символу в тексте
  - IntlBreakIterator::following — Перемещает итератор к первой границе после указанного смещения
  - IntlBreakIterator::getErrorCode — Возвращает последний код ошибки объекта
  - IntlBreakIterator::getErrorMessage — Возвращает последнее сообщение об ошибке объекта
  - IntlBreakIterator::getLocale — Возвращает локаль, связанную с объектом
  - IntlBreakIterator::getPartsIterator — Создаёт итератор для перемещения фрагментов между границами
  - IntlBreakIterator::getText — Возвращает сканируемый текст
  - IntlBreakIterator::isBoundary — Сообщает, является ли смещение смещением границы
  - IntlBreakIterator::last — Устанавливает позицию итератора к индексу за последним символом
  - IntlBreakIterator::next — Перемещает итератор к следующей границе
  - IntlBreakIterator::preceding — Устанавливает позицию итератора к первой границе перед смещением
  - IntlBreakIterator::previous — Устанавливает позицию итератора на границе непосредственно перед текущей
  - IntlBreakIterator::setText — Устанавливает сканируемый текст
- IntlRuleBasedBreakIterator — Класс IntlRuleBasedBreakIterator
  - IntlRuleBasedBreakIterator::__construct — Создаёт итератор на основе набора правил
  - IntlRuleBasedBreakIterator::getBinaryRules — Получить бинарные данные из скомпилированных правил
  - IntlRuleBasedBreakIterator::getRules — Получить набор правил, использовавшихся при создании этого объекта
  - IntlRuleBasedBreakIterator::getRuleStatus — Получить наибольшее значение статуса правил останова, определившее текущую позицию остановки
  - IntlRuleBasedBreakIterator::getRuleStatusVec — получить значения статусов из правил останова, определивших текущую позицию остановки
- IntlCodePointBreakIterator — Класс IntlCodePointBreakIterator
  - IntlCodePointBreakIterator::getLastCodePoint — Получить последний код символа, выданный при перемещении итератора вперёд или назад
- IntlDatePatternGenerator — Класс IntlDatePatternGenerator
  - IntlDatePatternGenerator::create — Создаёт новый экземпляр IntlDatePatternGenerator
  - IntlDatePatternGenerator::getBestPattern — Определяет наиболее подходящий формат даты/времени
- IntlPartsIterator — Класс IntlPartsIterator
  - IntlPartsIterator::getBreakIterator — Получить IntlBreakIterator сохраняя итератор этой части
- UConverter — Класс UConverter
  - UConverter::__construct — Создать объект UConverter
  - UConverter::convert — Конвертировать строку из одной кодировки в другую
  - UConverter::fromUCallback — Callback-функция по умолчанию для "from"
  - UConverter::getAliases — Получить псевдонимы для заданного имени
  - UConverter::getAvailable — Получить доступные имена канонических конверторов
  - UConverter::getDestinationEncoding — Получить кодировку назначения
  - UConverter::getDestinationType — Получить тип конвертера назначения
  - UConverter::getErrorCode — Получить код последней ошибки объекта
  - UConverter::getErrorMessage — Получить последнее сообщение об ошибке в объекте
  - UConverter::getSourceEncoding — Получить исходную кодировку
  - UConverter::getSourceType — Получить тип конвертера источника
  - UConverter::getStandards — Получить стандарты, связанные с именами конвертеров
  - UConverter::getSubstChars — Получить замену символов
  - UConverter::reasonText — Получить строковое представление причины обратного вызова
  - UConverter::setDestinationEncoding — Установить кодировку назначения
  - UConverter::setSourceEncoding — Установить исходную кодировку
  - UConverter::setSubstChars — Установка символов подстановки
  - UConverter::toUCallback — Callback-функция по умолчанию для "to"
  - UConverter::transcode — Преобразовывает строку из одной кодировки символов в другую
- Функции Grapheme
  - grapheme_extract — Функция для извлечения последовательности кластеров графем по умолчанию из текстового буфера, которая должна быть закодирована в UTF-8
  - grapheme_str_split — Разбивает строку на массив графемных кластеров
  - grapheme_stripos — Вычисляет позицию первого вхождения подстроки в графемных кластерах без учёта регистра
  - grapheme_stristr — Возвращает часть строки относительно первого вхождения подстроки без учёта регистра
  - grapheme_strlen — Получает количество графемных кластеров в строке
  - grapheme_strpos — Вычисляет позицию первого вхождения подстроки в графемных кластерах
  - grapheme_strripos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах без учёта регистра
  - grapheme_strrpos — Вычисляет позицию последнего вхождения подстроки в графемных кластерах
  - grapheme_strstr — Возвращает часть строки относительно первого вхождения подстроки
  - grapheme_substr — Возвращает часть строки в графемных кластерах
- Функции IDN
  - idn_to_ascii — Преобразовывает доменное имя в формат ASCII по спецификации IDNA
  - idn_to_utf8 — Преобразование доменного имени из IDNA ASCII в Unicode
- IntlChar
  - IntlChar::charAge — Получает «возраст» кодовой точки
  - IntlChar::charDigitValue — Получает десятичное значение десятичного символа
  - IntlChar::charDirection — Получает двунаправленное значение категории кодовой точки
  - IntlChar::charFromName — Находит Unicode-символ по имени и возвращает значение кодовой точки символа
  - IntlChar::charMirror — Получает «зеркально отражённый» символ кодовой точки Юникода
  - IntlChar::charName — Извлекает название Unicode-символа
  - IntlChar::charType — Получает значение общей категории кодовой точки
  - IntlChar::chr — Возвращает символ Юникода по значению кодовой точки
  - IntlChar::digit — Получает десятичное значение цифры кодовой точки в заданной системе счисления
  - IntlChar::enumCharNames — Перечисляет все присвоенные символы Unicode в заданном диапазоне
  - IntlChar::enumCharTypes — Перечисляет кодовые точки с их общими категориями Юникода
  - IntlChar::foldCase — Преобразовывает регистр кодовой точки
  - IntlChar::forDigit — Получает кодовую точку символьного представления числа в заданной системе счисления
  - IntlChar::getBidiPairedBracket — Получает символ парной скобки для кодовой точки
  - IntlChar::getBlockCode — Получает блок распределения, который содержит кодовую точку символа Юникода
  - IntlChar::getCombiningClass — Получает класс объединения для символа
  - IntlChar::getFC_NFKC_Closure — Получает свойство FC_NFKC_Closure для символа
  - IntlChar::getIntPropertyMaxValue — Получает максимальное значение Unicode-свойства
  - IntlChar::getIntPropertyMinValue — Получает минимальное значение Unicode-свойства
  - IntlChar::getIntPropertyValue — Получает значение Unicode-свойства кодовой точки
  - IntlChar::getNumericValue — Получает числовое значение кодовой точки Юникода
  - IntlChar::getPropertyEnum — Получает постоянное значение свойства по имени свойства
  - IntlChar::getPropertyName — Получает Unicode-имя свойства
  - IntlChar::getPropertyValueEnum — Получает значение свойства по имени значения
  - IntlChar::getPropertyValueName — Получает значения свойства Юникода
  - IntlChar::getUnicodeVersion — Получает версию стандарта Unicode
  - IntlChar::hasBinaryProperty — Проверяет бинарное свойство Unicode для символа
  - IntlChar::isalnum — Проверяет, относится ли кодовая точка к буквенно-цифровым символам
  - IntlChar::isalpha — Проверяет, относится ли кодовая точка к символам букв
  - IntlChar::isbase — Проверяет, относится ли кодовая точка к базовому символу
  - IntlChar::isblank — Проверяет, относится ли кодовая точка к символам «пустого места» или «горизонтального пробела»
  - IntlChar::iscntrl — Проверяет, относится ли кодовая точка к управляющим символам
  - IntlChar::isdefined — Проверяет, определили ли кодовую точку
  - IntlChar::isdigit — Проверяет, относится ли кодовая точка к символам цифр
  - IntlChar::isgraph — Проверяет, входит ли символ в категорию графических
  - IntlChar::isIDIgnorable — Проверяет, допускается ли игнорировать символ в идентификаторе
  - IntlChar::isIDPart — Проверяет, допустима ли кодовая точка как часть идентификатора
  - IntlChar::isIDStart — Проверяет, допустима ли кодовая точка как первый символ идентификатора
  - IntlChar::isISOControl — Проверяет, относится ли кодовая точка к управляющим символам с точки зрения стандарта ISO
  - IntlChar::isJavaIDPart — Проверяет, допустима ли кодовая точка как часть Java-идентификатора
  - IntlChar::isJavaIDStart — Проверяет, допустима ли кодовая точка как первый символ Java-идентификатора
  - IntlChar::isJavaSpaceChar — Проверяет, относится ли кодовая точка к пробельным с точки зрения языка Java
  - IntlChar::islower — Проверяет, относится ли символ к общей категории строчных букв — Ll
  - IntlChar::isMirrored — Проверяет, относится ли символ к двунаправленным
  - IntlChar::isprint — Проверяет, является ли символ отображаемым
  - IntlChar::ispunct — Проверяет, является ли символ символом пунктуации
  - IntlChar::isspace — Проверяет, является ли символ пробельным
  - IntlChar::istitle — Проверяет, относится ли кодовая точка к титульным буквам
  - IntlChar::isUAlphabetic — Проверяет, относится ли символ к алфавитным
  - IntlChar::isULowercase — Проверяет, относится ли символ к нижнему регистру
  - IntlChar::isupper — Проверяет, относится ли символ к общей категории заглавных букв — Lu
  - IntlChar::isUUppercase — Проверяет, относится ли символ к верхнему регистру
  - IntlChar::isUWhiteSpace — Проверяет, относится ли символ к пробельным
  - IntlChar::isWhitespace — Проверяет, относится ли кодовая точка к пробельным с точки зрения стандартов проекта ICU
  - IntlChar::isxdigit — Проверяет, относится ли кодовая точка к шестнадцатеричной цифре
  - IntlChar::ord — Возвращает значение кодовой точки символа Юникода
  - IntlChar::tolower — Преобразовывает символ Unicode в нижний регистр
  - IntlChar::totitle — Преобразовывает символ Unicode в титульный регистр (titlecase)
  - IntlChar::toupper — Преобразовывает символ Unicode в верхний регистр
- IntlException — Класс исключений для ошибок intl
- IntlIterator — Класс IntlIterator
  - IntlIterator::current — Получить текущий элемент
  - IntlIterator::key — Получить ключ текущего элемента
  - IntlIterator::next — Перейти к следующему элементу
  - IntlIterator::rewind — Перейти к первому элементу
  - IntlIterator::valid — Проверить, корректна ли текущая позиция
- Функции intl
  - intl_error_name — Получить имя ошибки по её коду
  - intl_get_error_code — Получить код последней ошибки
  - intl_get_error_message — Получить описание ошибки
  - intl_is_failure — Проверить, является ли код ошибки признаком сбоя

# Многобайтовые строки

# Введение

Количество символов в одних естественных языках при кодировании каждого отдельного символа восьмибитным значением не превышает количество символов в кодировке, в других языках количество символов для письменного общения не помещается в диапазон однобайтовой кодировки; байт состоит из восьми бит, каждый бит содержит одно значение: ноль или единицу, поэтому один байт представляет только 256 уникальных значений — два в восьмой степени. Схемы многобайтовых кодировок символов разработали для представления больше 256 символов в стандартной побайтовой системе.

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

Модуль `mbstring` предоставляет функции для работы с многобайтовыми строками. Такие функции помогают работать с многобайтовыми кодировками в PHP. Кроме того, модуль `mbstring` конвертирует строки из одной кодировки в другую. Модуль `mbstring` спроектировали для обработки Unicode-кодировок наподобие UTF-8 и UCS-2 и удобной работы со множеством однобайтовых кодировок, которые перечисляет раздел «Поддерживаемые кодировки символов».

# Установка и настройка

## Содержание

- Установка
- Настройка во время выполнения

## Установка

`mbstring` не входит в список модулей, устанавливаемых по умолчанию. Это значит, что изначально этот модуль отключён. Для использования функций этого модуля необходимо явно включить его с опцией `configure`. За дополнительной информацией обращайтесь в раздел Инсталляция.

Следующие настройки относятся к модулю `mbstring`.

- --enable-mbstring: Включение функций `mbstring`. Эта настройка необходима для использования функций `mbstring`.

  libmbfl необходима для работы `mbstring`. libmbfl поставляется вместе с `mbstring`. До PHP 7.3.0, если libmbfl уже установлена в системе, то можно использовать --with-libmbfl[=DIR] для использования установленной библиотеки.

- --disable-mbregex: Отключение функций регулярных выражений, поддерживающих многобайтовые кодировки.

  Oniguruma необходима для функций, работающих с регулярными выражениями с поддержкой многобайтовых кодировок. Начиная с PHP 7.4.0, для обнаружения библиотеки libonig используется pkg-config. До PHP 7.4.0 Oniguruma поставлялась вместе с `mbstring`, но можно было выполнить сборку с уже установленным libonig, передав --with-onig[=DIR].

  Возможно запретить многобайтовые регулярные выражения с возвратом с помощью опции --disable-mbregex-backtrack.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции конфигурации mbstring
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | Устарела
mbstring.http_output | "pass" | `INI_ALL` | Устарела
mbstring.internal_encoding | NULL | `INI_ALL` | Устарела
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | Объявлено устаревшим в PHP 7.2.0; удалено с PHP 8.0.0.
mbstring.encoding_translation | "0" | `INI_PERDIR` |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | `INI_ALL` |
mbstring.strict_detection | "0" | `INI_ALL` |
mbstring.regex_retry_limit | "1000000" | `INI_ALL` | Доступно, начиная с PHP 7.4.0.
mbstring.regex_stack_limit | "100000" | `INI_ALL` | Доступно, начиная с PHP 7.3.5.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`mbstring.language` string

  По умолчанию в mbstring используются настройки национального языка. Обратите внимание, что эта опция автоматически определяет `mbstring.internal_encoding`, и `mbstring.internal_encoding` должен быть помещён после `mbstring.language` в php.ini

`mbstring.encoding_translation` bool

  Включает прозрачный фильтр кодировки для входящих запросов HTTP, который выполняет обнаружение и преобразование входной кодировки во внутреннюю кодировку.

`mbstring.internal_encoding` string
  Внимание

  Функция устарела и ее удалят в будущем.

  Определяет внутреннюю кодировку символов по умолчанию.

  Пользователи должны оставить эту опцию пустой и задать вместо неё `default_charset`.

`mbstring.http_input` string
  Внимание

  Функция устарела и ее удалят в будущем.

  Определяет кодировку символов по умолчанию для HTTP-ввода.

  Пользователи должны оставить эту опцию пустой и задать вместо неё `default_charset`.

`mbstring.http_output` string
  Внимание

  Функция устарела и ее удалят в будущем.

  Определяет кодировку символов по умолчанию для HTTP-вывода (конвертация из внутренней кодировки в кодировку HTTP вывода произойдёт перед выводом).

  Пользователи должны оставить эту опцию пустой и задать вместо неё `default_charset`.

`mbstring.detect_order` string

  Определяет порядок определения кодировки символов по умолчанию. Смотрите также mb_detect_order().

`mbstring.substitute_character` string

  Определяет символ для замены недопустимых символов кодировки. Список поддерживаемых значений смотрите в описании функции mb_substitute_character().

`mbstring.func_overload` string
  Внимание

  Начиная с PHP 7.2.0 функциональность УСТАРЕЛА, а в PHP 8.0.0 функциональность УДАЛИЛИ. Полагаться на функциональность настоятельно не рекомендуют.

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

  Эта опция может быть изменена только в файле php.ini.

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  Включает строгое определение кодировки. Смотрите описание и примеры в mb_detect_encoding().

`mbstring.regex_retry_limit` int

  Ограничивает количество обратных ходов, которые могут быть выполнены во время одного совпадения mbregex.

  Эта настройка действует только при связывании с oniguruma >= 6.8.0.

`mbstring.regex_stack_limit` int

  Ограничивает глубину стека регулярных выражений mbstring.

Согласно » спецификации HTML 4.01, веб-браузерам разрешено перекодировать данные из формы, которые они получают в кодировке символов, отличной от используемой на странице. Смотрите функцию mb_http_input() для того, чтобы определить кодировку символов, используемую браузерами.

Хотя популярные браузеры способны достаточно точно определить кодировку символов данного HTML-документа, было бы лучше установить параметр `charset` в HTTP-заголовке `Content-Type` соответствующим значением с помощью header() или указать требуемое значение в параметре default_charset в ini-настройках.

Пример #1 Примеры настроек php.ini

    ; Установить язык по умолчанию
    mbstring.language        = Neutral; Установить Neutral(UTF-8) языком по умолчанию (по умолчанию)
    mbstring.language        = English; Установить английский языком по умолчанию
    mbstring.language        = Japanese; Установить японский языком по умолчанию

    ;; Установить внутреннюю кодировку по умолчанию
    ;; Примечание: Убедитесь, что используете кодировку символов, которая работает с PHP
    mbstring.internal_encoding    = UTF-8  ; Установить внутреннюю кодировку в UTF-8

    ;; Включено преобразование кодировки HTTP-ввода.
    mbstring.encoding_translation = On

    ;; Установить кодировку символов по умолчанию для HTTP-ввода
    ;; Примечание: Скрипт не может изменить установку http_input.
    mbstring.http_input           = pass    ; Нет преобразования.
    mbstring.http_input           = auto    ; Установить HTTP-ввод в auto
                                    ; "auto" расширяется в соответствии с mbstring.language
    mbstring.http_input           = SJIS    ; Установить HTTP-ввод в SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Указать порядок

    ;; Установить кодировку символов по умолчанию для HTTP-вывода
    mbstring.http_output          = pass    ; Нет преобразования.
    mbstring.http_output          = UTF-8   ; Установить кодировку HTTP-вывода в UTF-8

    ;; Установить порядок определения кодировки символов по умолчанию
    mbstring.detect_order         = auto    ; Установить порядок определения в auto
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Указать порядок

    ;; Установить символ замены по умолчанию
    mbstring.substitute_character = 12307   ; Указать значение Unicode
    mbstring.substitute_character = none    ; Не печатать символ
    mbstring.substitute_character = long    ; Примеры кодовых значений символов: U+3000,JIS+7E7E

Пример #2 Настройки php.ini для пользователей `EUC-JP`

    ;; Отключить буферизацию вывода
    output_buffering      = Off

    ;; Установить кодировку в http-заголовке
    default_charset       = EUC-JP

    ;; Установить японский языком по умолчанию
    mbstring.language = Japanese

    ;; Включено преобразование кодировки HTTP-ввода.
    mbstring.encoding_translation = On

    ;; Установить перекодировку HTTP-ввода в auto
    mbstring.http_input   = auto

    ;; Конвертировать HTTP-вывод в EUC-JP
    mbstring.http_output  = EUC-JP

    ;; Установить внутреннюю кодировку в EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Не печатать недопустимые символы
    mbstring.substitute_character = none

Пример #3 Настройки php.ini для пользователей `SJIS`

    ;; Включить буферизацию вывода
    output_buffering     = On

    ;; Установить mb_output_handler для включения перекодировки вывода
    output_handler       = mb_output_handler

    ;; Установить кодировку в http-заголовке
    default_charset      = Shift_JIS

    ;; Установить японский языком по умолчанию
    mbstring.language = Japanese

    ;; Установить перекодировку HTTP-ввода в auto
    mbstring.http_input  = auto

    ;; Конвертировать в SJIS
    mbstring.http_output = SJIS

    ;; Установить внутреннюю кодировку в EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Не печатать недопустимые символы
    mbstring.substitute_character = none

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`MB_OVERLOAD_MAIL` (int)
  Удалено с PHP 8.0.0.
`MB_OVERLOAD_STRING` (int)
  Удалено с PHP 8.0.0.
`MB_OVERLOAD_REGEX` (int)
  Удалено с PHP 8.0.0.
`MB_CASE_UPPER` (int)
  Выполняет полное преобразование в верхний регистр. Может изменить длину строки. Это режим, используемый mb_strtoupper().
`MB_CASE_LOWER` (int)
  Выполняет полное преобразование в нижний регистр. Может изменить длину строки. Это режим, используемый mb_strtolower().
`MB_CASE_TITLE` (int)
  Выполняет полное преобразование прецедента заголовка на основе свойств производного Unicode Cased и CaseIgnorable. В частности, улучшает обработку кавычек и апострофов. Может изменить длину строки.
`MB_CASE_FOLD` (int)
  Выполняет полное преобразование, которое удаляет различия регистра, присутствующие в строке. Используется для сопоставления без учёта регистра. Может изменить длину строки. Доступно с PHP 7.3.
`MB_CASE_LOWER_SIMPLE` (int)
  Выполняет простое преобразование в нижний регистр. Не меняет длину строки. Доступно с PHP 7.3.
`MB_CASE_UPPER_SIMPLE` (int)
  Выполняет простое преобразование в верхний регистр. Не меняет длину строки. Доступно с PHP 7.3.
`MB_CASE_TITLE_SIMPLE` (int)
  Выполняет простое преобразование в заглавные буквы. Не меняет длину строки. Доступно с PHP 7.3.
`MB_CASE_FOLD_SIMPLE` (int)
  Выполняет простое преобразование, которое удаляет различия регистра, присутствующие в строке. Используется для сопоставления без учёта регистра. Не меняет длину строки. Используется без учёта регистра внутренних операций модулем MBString. Доступно с PHP 7.3.
`MB_ONIGURUMA_VERSION` (string)
  Версия Oniguruma, например, `6.9.4`. Доступно с PHP 7.4.

# Краткий обзор поддерживаемых кодировок

Список поддерживаемых кодировок
Название в реестре кодировок IANA | Лежащий в основе набор символов | Описание | Дополнительная информация
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | Универсальный набор символов с 31 битом для кода символа, стандартизованный в ISO/IEC 10646 как UCS-4. Установлена синхронизация со стандартом Юникод. | Если это название используется в средствах преобразования кодировок, конвертер попытается определить порядок расположения байтов по BOM (метка порядка байтов).
ISO-10646-UCS-4 | UCS-4 | Смотрите выше. | В отличие от `UCS-4`, строки всегда принимаются закодированными в прямом порядке расположения байтов.
ISO-10646-UCS-4 | UCS-4 | Смотрите выше. | В отличие от `UCS-4`, строки всегда принимаются закодированными в обратном порядке расположения байтов.
ISO-10646-UCS-2 | UCS-2 | Универсальный набор символов с 16 битом для кода символа, стандартизованный в ISO/IEC 10646 как UCS-2. Установлена синхронизация со стандартом Юникод. | Если это название используется в средствах преобразования кодировок, конвертер попытается определить порядок расположения байтов по BOM (метка порядка байтов).
ISO-10646-UCS-2 | UCS-2 | Смотрите выше. | В отличие от `UCS-2`, строки всегда принимаются закодированными в прямом порядке расположения байтов.
ISO-10646-UCS-2 | UCS-2 | Смотрите выше. | В отличие от `UCS-2`, строки всегда принимаются закодированными в обратном порядке расположения байтов.
UTF-32 | Юникод | Формат преобразования Юникода с 32-битной шириной символа, кодовое пространство которого соответствует стандарту кодовой таблицы Юникода. Эта схема кодирования не идентична UCS-4, так как кодовое пространство Юникода ограничено 21-м битом. | Если это название используется в средствах преобразования кодировок, конвертер попытается определить порядок расположения байтов по BOM (метка порядка байтов).
UTF-32BE | Юникод | Смотрите выше | В отличие от `UTF-32`, строки всегда принимаются закодированными в прямом порядке расположения байтов.
UTF-32LE | Юникод | Смотрите выше | В отличие от `UTF-32`, строки всегда принимаются закодированными в обратном порядке расположения байтов.
UTF-16 | Юникод | Формат преобразования Юникода с 32-битной шириной кода символа. Спецификация UTF-16 отличается от UCS-2 ввиду того, что начиная с Юникод 2.0 был внедрён механизм замещения символов и теперь UTF-16 ссылается на 21-битное кодовое пространство. | Если это название используется в средствах преобразования кодировок, конвертер попытается определить порядок расположения байтов по BOM (метка порядка байтов).
UTF-16BE | Юникод | Смотрите выше. | В отличие от `UTF-16`, строки всегда принимаются закодированными в прямом порядке расположения байтов.
UTF-16LE | Юникод | Смотрите выше. | В отличие от `UTF-16`, строки всегда принимаются закодированными в обратном порядке расположения байтов.
UTF-8 | Юникод / UCS | Формат преобразования Юникода с 32-битной шириной кода символа. | нет
UTF-7 | Юникод | Безопасный для почтовых программ и решений формат преобразования Юникода, определённый в спецификации » RFC2152. | нет
(нет) | Юникод | Разновидность UTF-7, специально разработанная для использования в » протоколе IMAP. | нет
US-ASCII (предпочитаемое MIME-имя) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | ASCII (American Standard Code for Information Interchange - американский стандартный код для обмена информацией) - широко используемая 7-битная кодировка. Также стандартизована как международный стандарт ISO 646. | (нет)
EUC-JP (предпочитаемое MIME-имя) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | Объединение US-ASCII / JIS X0201:1997 (часть hankaku kana) / JIS X0208:1990 / JIS X0212:1990 | Как видно из названия, эта кодировка используется в основном в Unix системах или им подобных. Исходная схема кодирования Extended UNIX Code легла в основу стандарта ISO 2022. | Набор символов, на который ссылается EUC-JP отличен от набора для IBM932 / CP932, которые используются в OS/2® и Microsoft® Windows®. Для обеспечения взаимодействия между этими платформами используйте кодировку EUCJP-WIN.
Shift_JIS (предпочитаемое MIME-имя) / MS_Kanji / csShift_JIS | Объединение JIS X0201:1997 / JIS X0208:1997 | Shift_JIS был разработан в начале 80-х, когда Японские текстовые процессоры для рядовых пользователей только выходили на рынок, чтобы сохранить совместимость со схемой кодирования JIS X 0201:1976. В соответствии с определением IANA, кодовая таблица Shift_JIS несколько отличается от IBM932 / CP932. Тем не менее, названия "SJIS" / "Shift_JIS" ошибочно используются для обращения к этим кодовым таблицам. | Для кодовой таблицы CP932, используйте кодировку SJIS-WIN.
(none) | Объединение JIS X0201:1997 / JIS X0208:1997 / IBM расширения / NEC расширения | Несмотря на то, что эта "кодировка" использует ту же схему кодирования, что и EUC-JP, наборы символов, лежащий в их основе, различны. Таким образом, некоторые коды ссылаются на отличные от EUC-JP символы. | нет
Windows-31J / csWindows31J | Объединение JIS X0201:1997 / JIS X0208:1997 / IBM расширения / NEC расширения | Несмотря на то, что эта "кодировка" использует ту же схему кодирования, что и Shift_JIS, наборы символов, лежащий в их основе, различны. Таким образом, некоторые коды ссылаются на отличные от Shift_JIS символы. | (нет)
ISO-2022-JP (предпочитаемое MIME-имя) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | (нет)
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |

# Основы японских многобайтовых кодировок

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

- Один символ занимает в памяти до шести байтов.
- Бо́льшая часть японских многобайтовых символов выглядит в 2 раза шире, чем однобайтовые символы. Такие символы по-японски называются zen-kaku что означает «полноширинный». Другие, более узкие символы называются han-kaku, что означает «полуширинные». Конкретные графические свойства символов зависят от шрифта, которым они отображаются.
- В отдельных кодировках символов карту кодов конкретной области кодов — в диапазоне от `00` до `7f` в шестнадцатеричной форме — изменяют последовательностями сдвига — escape-последовательностями, которые определяет стандарт ISO-2022.
- При сетевом обмене по протоколам SMTP и NNTP японские символы передают в кодировке ISO-2022-JP; заголовки HTTP-сообщения, а также заголовки и тело полезной нагрузки HTTP-сообщения перекодируют по правилам RFC-стандартов. Даже если перекодировка не нужна, она всё же не помешает, поскольку отдельные популярные пользовательские агенты не умеют распознавать другие методы кодирования.
- Веб-страницам для служб мобильной связи наподобие » i-mode и » EZweb требуется кодировка Shift_JIS.
- Службы мобильной связи наподобие » i-mode и » EZweb поддерживают эмодзи.

# Ввод и вывод HTTP

Механизм преобразования кодировок ввода-вывода HTTP также способен конвертировать двоичные данные. Пользователи должны сами следить за преобразованием кодировки символов, если в качестве ввода-вывода HTTP передаются двоичные данные.

> Замечание:

> Если для атрибута HTML-формы `enctype` установлено значение `multipart/form-data`, а для директивы `mbstring.encoding_translation` в файле php.ini установлено значение On, переменные и имена загружаемых файлов в POST-запросах конвертируются во внутреннюю кодировку скрипта автоматически. Однако это не относится к ключам запроса.

- Ввод HTTP

  Невозможно контролировать преобразование символов HTTP-ввода из PHP-скрипта. Отключить преобразование символов HTTP-ввода можно в файле php.ini.

  Пример #1 Отключение преобразования кодировки HTTP-ввода в файле php.ini

      ;; Отключение конвертации
      mbstring.http_input = pass
      ;; Отключение конвертации
      mbstring.encoding_translation = Off

  Если PHP работает как модуль Apache, можно переопределить эти настройки в каждой директиве виртуального хоста (Virtual Host) в файле конфигурации httpd.conf или для каждой директории в файле .htaccess. Дополнительная информация дана в разделе «Конфигурация» и к руководству по работе с веб-сервером Apache.

- Вывод HTTP

  Есть несколько способов включить преобразование кодировки символов вывода. Один из них — файл php.ini, другой — вызов функции ob_start() с передачей в `ob_start` функции mb_output_handler() в качестве callback-функции.

Пример #2 Пример настройки php.ini

    ;; Включение преобразования кодировки символов вывода для всех PHP-страниц

    ;; Включение буферизации вывода
    output_buffering    = On

    ;; Установка функции mb_output_handler в качестве значения директивы для включения конвертации вывода
    output_handler      = mb_output_handler

Пример #3 Пример скрипта

    <?php

    // Включение преобразования кодировки символов вывода только для этой страницы

    // Установка кодировки символов HTTP-вывода в значение SJIS
    mb_http_output('SJIS');

    // Запуск буферизации и определение функции «mb_output_handler» в качестве
    // callback-функции
    ob_start('mb_output_handler');

    ?>

# Поддерживаемые кодировки символов

В настоящее время модулем `mbstring` поддерживаются следующие кодировки символов. Любая из этих кодировок символов может быть указана в параметре `encoding` функций `mbstring`.

Следующие кодировки символов поддерживаются в этом модуле PHP:

- UCS-4*
- UCS-4BE
- UCS-4LE*
- UCS-2
- UCS-2BE
- UCS-2LE
- UTF-32*
- UTF-32BE*
- UTF-32LE*
- UTF-16*
- UTF-16BE*
- UTF-16LE*
- UTF-7
- UTF7-IMAP
- UTF-8*
- ASCII*
- EUC-JP*
- SJIS*
- eucJP-win*
- SJIS-win*
- ISO-2022-JP
- ISO-2022-JP-MS
- CP932
- CP51932
- SJIS-mac (alias: MacJapanese)
- SJIS-Mobile#DOCOMO (alias: SJIS-DOCOMO)
- SJIS-Mobile#KDDI (alias: SJIS-KDDI)
- SJIS-Mobile#SOFTBANK (alias: SJIS-SOFTBANK)
- UTF-8-Mobile#DOCOMO (alias: UTF-8-DOCOMO)
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B (alias: UTF-8-KDDI)
- UTF-8-Mobile#SOFTBANK (alias: UTF-8-SOFTBANK)
- ISO-2022-JP-MOBILE#KDDI (alias: ISO-2022-JP-KDDI)
- JIS
- JIS-ms
- CP50220
- CP50220raw
- CP50221
- CP50222
- ISO-8859-1*
- ISO-8859-2*
- ISO-8859-3*
- ISO-8859-4*
- ISO-8859-5*
- ISO-8859-6*
- ISO-8859-7*
- ISO-8859-8*
- ISO-8859-9*
- ISO-8859-10*
- ISO-8859-13*
- ISO-8859-14*
- ISO-8859-15*
- ISO-8859-16*
- byte2be
- byte2le
- byte4be
- byte4le
- BASE64
- HTML-ENTITIES (alias: HTML)
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- HZ
- EUC-TW*
- CP950
- BIG-5*
- EUC-KR*
- UHC (alias: CP949)
- ISO-2022-KR
- Windows-1251 (alias: CP1251)
- Windows-1252 (alias: CP1252)
- CP866 (alias: IBM866)
- KOI8-R*
- KOI8-U*
- ArmSCII-8 (alias: ArmSCII8)

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

Любая запись в php.ini, которая принимает имя кодировки, может также использовать значения "`auto`" и "`pass`". Функции `mbstring`, которые принимают имя кодировки, также могут использовать значение "`auto`".

Если установлено значение "`pass`", преобразование кодировки не производится.

Если установлено значение "`auto`", оно расширяется списком кодировок, определённым в NLS (настройках национального языка). Например, если NLS установлен в `Japanese`, предполагается, что значение будет из списка "`ASCII,JIS,UTF-8,EUC-JP,SJIS`".

Смотрите также mb_detect_order()

# Механизм перегрузки функций

Внимание

Начиная с PHP 7.2.0 функциональность УСТАРЕЛА, а в PHP 8.0.0 функциональность УДАЛИЛИ. Полагаться на функциональность настоятельно не рекомендуют.

Зачастую заставить работать существующее PHP-приложение в многобайтовом окружении становится трудоёмкой задачей. Причина состоит в том, что большую часть PHP-приложений написали со стандартными функциями обработки строк наподобие substr(), которые не умеют работать со строками в многобайтовых кодировках.

Модуль mbstring поддерживает механизм «перегрузки функций», который сообщает приложению о работе с многобайтовой кодировкой, без модификации кода, который отвечает за работу со строками. Например, при включении перегрузки функций вместо функции substr() вызывается функция mb_substr(). Этот механизм часто помогает переносить в многобайтовое окружение приложения, которые поддерживают только однобайтовые кодировки.

Для активации механизма перегрузки функций потребуется задать настройке `mbstring.func_overload` в php.ini положительное значение, которое представляет собой комбинацию битовых масок для определения категорий функций, которые требуется перегружать. Число 1 перегружает функции mail(), 2 — строковые функции, 4 — функций регулярных выражений. Например, если значение настройки равно 7, то почтовые, строковые и функции регулярных выражений станут перегружаться. Список перегружаемых функций приведён ниже.

Функции, которые перегрузятся
значение настройки mbstring.func_overload | исходная функция | перегруженная функция
--- | --- | ---
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

> Замечание:

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

# Требования, предъявляемые к кодировкам символов в PHP

Типы кодировок, использование которых в PHP безопасно.

- Однобайтовые кодировки,

  - имеющие ASCII-совместимую (совместимую с ISO646) разметку в диапазоне с `00h` по `7fh`.

- Многобайтовые кодировки,

  - имеющие ASCII-совместимую разметку в диапазоне с `00h` по `7fh`.
  - не использующие escape-последовательности ISO2022.
  - не использующие значения в байтах с `00h` по `7fh` по отдельности, когда эти байты представляют один символ.

Далее приведены примеры кодировок, использование которых в PHP нежелательно.

    JIS, SJIS, ISO-2022-JP, BIG-5

Даже если PHP-скрипт написан в рекомендуемой кодировке, он может оказаться неработоспособным. Зачастую так происходит, когда кодированные строки появляются в скрипте в качестве идентификаторов или литералов. Можно исключить большую часть таких ситуаций путём использования функции фильтрации кодировок во входящих HTTP-запросах (функция есть в модуле `mbstring`).

> Замечание:

> Крайне не рекомендуется использовать SJIS, BIG5, CP936, CP949 и GB18030 в качестве внутренних кодировок, если вы недостаточно разбираетесь в устройстве парсера, сканера и кодировки.

> Замечание:

> Если вы подключаетесь к базе данных средствами PHP, рекомендуется использовать одинаковые кодировки для базы данных и в качестве `внутренней кодировки`. Это облегчит разработку и повысит быстродействие.

> Если вы используете PostgreSQL, совпадение кодировок в базе данных и используемой в PHP необязательно, так как PostgreSQL поддерживает автоматическое преобразование кодировок между СУБД и клиентом.

# Функции для работы с многобайтовыми строками

# Ссылки

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

- Материалы по Юникоду

  » http://www.unicode.org/

- Информация о символах японской, корейской и китайской кодировок

  » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

# mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — Проверяет, допустима ли строка для заданной кодировки

### Описание

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

Проверяет, допустим ли заданный поток байтов для заданной кодировки. Если значение параметра `value` — массив (array), то все ключи и значения проверяются рекурсивно. Функция полезна для предотвращения атаки, которая называется «Атака неправильной кодировкой».

### Список параметров

`value`

  Поток байтов или массив (array) для проверки. Если не задан, функция проверит все входные данные с начала запроса.

  Внимание

  Начиная с PHP 8.1.0 пропуск этого параметра или передача значения `null` устарели.

`encoding`

  Ожидаемая кодировка.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Вызов функции с `null` в качестве параметра `value` или без аргумента устарело.
8.0.0 | Параметры `value` и `encoding` могут принимать значение `null`.
7.2.0 | Функция теперь также принимает массив (array) в `value`. Ранее поддерживались только строки (string).

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Возвращает символ по значению кодовой точки Unicode

### Описание

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

Функция возвращает символ, который соответствует значению кодовой точки Юникода, которое кодирует заданная кодировка.

Функция дополняет функцию mb_ord().

### Список параметров

`codepoint`

  Значение кодовой точки Unicode, например, кодовая точка `128024` для символа U+1F418 СЛОН.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает строку, которая содержит запрошенный символ, если символ представлен в заданной кодировке, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример проверки кодовых точек

    <?php

    $values = [65, 63, 0x20AC, 128024];
    foreach ($values as $value) {
        var_dump(mb_chr($value, 'UTF-8'));
        var_dump(mb_chr($value, 'ISO-8859-1'));
    }

    ?>

Результат выполнения приведённого примера:

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_ord() - Получает кодовую точку символа Unicode
- IntlChar::ord() - Возвращает значение кодовой точки символа Юникода
- chr() - Генерирует однобайтовую строку из числа

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — Меняет регистр символов в строке

### Описание

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

Функция преобразовывает регистр символов в строке (string) способом, который указали в параметре `mode`.

### Список параметров

`string`

  Строка (string), которую требуется преобразовать.

`mode`

  Режим преобразования. Параметр принимает значение константы из списка: `MB_CASE_UPPER`, `MB_CASE_LOWER`, `MB_CASE_TITLE`, `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE` или `MB_CASE_FOLD_SIMPLE`.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает строку `string`, которую преобразовала способом, который указали в параметре `mode`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Реализовали правила условного регистра для греческой буквы сигма, которые применяются только к режимам `MB_CASE_LOWER` и `MB_CASE_TITLE`, но не к режимам `MB_CASE_LOWER_SIMPLE` и `MB_CASE_TITLE_SIMPLE`.
7.3.0 | Добавили поддержку режимов для параметра `mode`: `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE` и `MB_CASE_FOLD_SIMPLE`.

### Примеры

Пример #1 Пример изменения регистра символов в строке функцией mb_convert_case()

    <?php

    $str = "у мэри был маленький ягнёнок и она его очень любила";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;

    ?>

Пример #2 Пример изменения функцией mb_convert_case() регистра символов в строке с нелатинским текстом в кодировке UTF-8

    <?php

    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;

    ?>

### Примечания

В отличие от стандартных функций преобразования регистра наподобие strtolower() и strtoupper(), регистр меняется на основе свойств символа Юникода. Поэтому на поведение этой функции не влияют региональные настройки системы, и она умеет конвертировать символы с Unicode-свойством 'alphabetic' наподобие символа буквы «а» с умлаутом — ä.

Подробнее о свойствах Юникода рассказывает страница » http://www.unicode.org/reports/tr21/.

### Смотрите также

- mb_strtolower() - Приводит строку к нижнему регистру
- mb_strtoupper() - Приводит строку к верхнему регистру
- strtolower() - Приводит строку к нижнему регистру
- strtoupper() - Приводит строку к верхнему регистру
- ucfirst() - Переводит первый символ строки в верхний регистр
- ucwords() - Переводит в верхний регистр первый символ каждого слова в строке

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — Преобразовывает строку из одной кодировки символов в другую

### Описание

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

Функция преобразовывает значение параметра `string` из кодировки `from_encoding`, или текущей внутренней кодировки, в кодировку `to_encoding`. При передаче в параметр `string` массива (array) функция рекурсивно преобразует каждое string-значение массива.

### Список параметров

`string`

  Строка (string) или массив (array), для преобразования.

`to_encoding`

  Кодировка результата.

`from_encoding`

  Текущая кодировка для интерпретации строки `string`. Набор кодировок указывают в массиве (array) или в строке со списком значений через запятую, тогда PHP попытается определить правильную кодировку по тому же алгоритму, которым определяет кодировку функция mb_detect_encoding().

  При пропуске параметра `from_encoding` или установке значения `null` функция опирается на настройку директивы mbstring.internal_encoding, если директиву установили, иначе на значение директивы default_charset.

  Допустимые значения параметров `to_encoding` и `from_encoding` перечисляет страница «Поддерживаемые кодировки символов».

### Возвращаемые значения

Функция возвращает или закодированную строку (string), или закодированный массив (array), или `false`, если возникла ошибка.

### Ошибки

Начиная с PHP 8.0.0 функция выбросит ошибку ValueError, если значением параметра `to_encoding` или параметра `from_encoding` окажется недопустимая кодировка. До PHP 8.0.0 вместо этого выдавалась ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Функция mb_convert_encoding() больше не возвращает следующие нетекстовые кодировки: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` и `"8 bit"`.
8.0.0 | Функция mb_convert_encoding() теперь выбрасывает ошибку ValueError при передаче в параметр `to_encoding` недопустимой кодировки.
8.0.0 | Функция mb_convert_encoding() теперь выбрасывает ошибку ValueError при передаче в параметр `from_encoding` недопустимой кодировки.
8.0.0 | Параметр `from_encoding` теперь принимает значение `null`.
7.2.0 | Функция теперь также принимает массив (array) как значение параметра `string`. Раньше поддерживались только значения string.

### Примеры

Пример #1 Пример изменения кодировки строки функцией mb_convert_encoding()

    <?php

    /* Преобразовывает строку в кодировку SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* Преобразовывает из кодировки EUC-JP в кодировку UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* Автоматически определяется кодировка среди JIS, eucjp-win, sjis-win, затем преобразовывается в UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* Если директива mbstring.language равна "Japanese", значение кодировки "auto" будет расширено до "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");

    ?>

### Смотрите также

- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов
- UConverter::transcode() - Преобразовывает строку из одной кодировки символов в другую
- iconv() - Преобразовывает строку из одной кодировки символов в другую

# mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — Преобразовывает одну кодировку "kana" в другую: "zen-kaku", "han-kaku" и другие

### Описание

function mb_convert_kana(string `$string`, string `$mode` = "KV", ?string `$encoding` = `null`): string

Функция преобразовывает кодировку значения с типом string, которое принимает параметр `string`, из "han-kaku" в "zen-kaku". Функция полезна только для японского языка.

### Список параметров

`string`

  Исходная строка (string).

`mode`

  Параметры преобразования.

  Режим устанавливается комбинацией следующих параметров.

  Возможные параметры преобразования
  Настройка | Описание
  --- | ---
  `r` | Преобразование "zen-kaku" букв в "han-kaku"
  `R` | Преобразование "han-kaku" букв в "zen-kaku"
  `n` | Преобразование "zen-kaku" чисел в "han-kaku"
  `N` | Преобразование "han-kaku" чисел в "zen-kaku"
  `a` | Преобразование "zen-kaku" букв и чисел в "han-kaku"
  `A` | Преобразование "han-kaku" букв и чисел в "zen-kaku" (Для настроек "a", "A" символы берутся из диапазона U+0021 — U+007E, исключая U+0022, U+0027, U+005C, U+007E)
  `s` | Преобразование "zen-kaku" пробела в "han-kaku" (U+3000 → U+0020)
  `S` | Преобразование "han-kaku" пробела в "zen-kaku" (U+0020 → U+3000)
  `k` | Преобразование "zen-kaku kata-kana" в "han-kaku kata-kana"
  `K` | Преобразование "han-kaku kata-kana" в "zen-kaku kata-kana"
  `h` | Преобразование "zen-kaku hira-gana" в "han-kaku kata-kana"
  `H` | Преобразование "han-kaku kata-kana" в "zen-kaku hira-gana"
  `c` | Преобразование "zen-kaku kata-kana" в "zen-kaku hira-gana"
  `C` | Преобразование "zen-kaku hira-gana" в "zen-kaku kata-kana"
  `V` | Свёртывает фонемы и преобразовывает их в символ. Указывается вместе с "K", "H"

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает преобразованную строку (string).

### Ошибки

Функция выбрасывает ошибку ValueError, если в параметр `mode` передали недопустимую комбинацию режимов наподобие `"sS"`.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Функция теперь выбрасывает ошибку ValueError при недопустимой комбинации режимов в параметре `mode`.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример преобразования кодировки функцией mb_convert_kana()

    <?php

    /* Преобразование символов "han-kaku" "kata-kana" в "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Преобразование "han-kaku" "kata-kana" в "zen-kaku" "kata-kana"
       и "zen-kaku" буквенно-цифровых символов в "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";

    ?>

Результат выполнения приведённого примера:

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — Преобразовывает символы в переменной(-ых) из одной кодировки в другую

### Описание

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

Конвертирует символы в переменных `var` и `vars` из кодировки, указанной в параметре `from_encoding`, в кодировку, указанную в параметре `to_encoding`.

Функция mb_convert_variables() объединяет строки из массива или объекта для определения их кодировки, так как в случае коротких строк определить кодировку часто не удаётся. Поэтому недопустимо помещать в один массив или объект строки в разных кодировках.

### Список параметров

`to_encoding`

  Кодировка, в которую необходимо перекодировать строку (string).

`from_encoding`

  Параметр `from_encoding` задаётся в виде массива (array) или строки (string) с разделёнными запятой кодировками, функция попытается определить кодировку исходной строки на основе списка кодировок, заданных в параметре `from-coding`. Если параметр `from_encoding` не задан, будет выбрана кодировка, из INI-директивы с именем `detect_order`.

`var`

  Параметр `var` — это ссылка на переменную, которую нужно преобразовать. Это может быть строка (string), массив (array) или объект (object). Функция mb_convert_variables() предполагает, что для всех параметров задана одинаковая кодировка.

`vars`

  Дополнительные `var`.

### Возвращаемые значения

Возвращает исходную кодировку в случае успешного выполнения или `false` в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования функции mb_convert_variables()

    <?php
    /* Преобразование переменных $post1, $post2 во внутреннюю кодировку скрипта */
    $interenc = mb_internal_encoding();
    $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — Декодирует строку в MIME-заголовке

### Описание

function mb_decode_mimeheader(string `$string`): string

Функция декодирует строку (string) поля заголовка MIME, которую передали аргументе `string` и в которой слова закодировали последовательностью обыкновенных печатаемых ASCII-символов по правилам стандарта RFC 2047.

### Список параметров

`string`

  Строка (string), которую требуется декодировать.

### Возвращаемые значения

Функция возвращает строку (string), которую декодировала во внутреннюю кодировку скрипта.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Подчеркивания преобразовываются в пробелы по правилам стандарта » RFC 2047.

### Смотрите также

- mb_encode_mimeheader() - Кодирует строку для заголовка MIME

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — Декодирует числовые HTML-сущности в символы

### Описание

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

Функция преобразовывает числовые HTML-сущности строки `string` в символы на основе диапазонов кодовых точек.

### Список параметров

`string`

  Декодируемая строка (string).

`map`

  Параметр `map` принимает массив, который определяет диапазоны кодовых точек для преобразования.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает преобразованную строку (string).

### Ошибки

Функция теперь выбрасывает ошибку ValueError, если список `map` содержит значения кроме int.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция mb_decode_numericentity() теперь выбрасывает ошибку ValueError, если список `map` содержит значения кроме int.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример формата для установки параметра `map`

    <?php

    $convmap = array(
        int start_code1, int end_code1, int offset1, int mask1,
        int start_code2, int end_code2, int offset2, int mask2,
        // ........
        int start_codeN, int end_codeN, int offsetN, int maskN
    );
    // Значениями start_codeN и end_codeN определяется диапазон кодовых точек Юникода.
    // К кодовой точке исходного символа добавляется смещение offsetN и выполняется побитовая операция 'И' со значением маски maskN,
    // а полученное значение затем преобразовывается в числовую ссылку на символ.

    ?>

Пример #2 Пример экранирования строки JavaScript-кода через параметр `map`

    <?php

    function escape_javascript_string($str)
    {
        $map = [
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,0,0, // 49
            0,0,0,0,0,0,0,0,1,1,
            1,1,1,1,1,0,0,0,0,0,
            0,0,0,0,0,0,0,0,0,0,
            0,0,0,0,0,0,0,0,0,0,
            0,1,1,1,1,1,1,0,0,0, // 99
            0,0,0,0,0,0,0,0,0,0,
            0,0,0,0,0,0,0,0,0,0,
            0,0,0,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1, // 149
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1, // 199
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1,
            1,1,1,1,1,1,1,1,1,1, // 249
            1,1,1,1,1,1,1, // 255
        ];

        // Кодировка символа UTF-8
        $mblen = mb_strlen($str, 'UTF-8');
        $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));

        for ($i=0, $encoded=''; $i < $mblen; $i++) {
            $u = substr($utf32, $i * 8, 8);
            $v = base_convert($u, 16, 10);

            if ($v < 256 && $map[$v]) {
                $encoded .= '\\x' . substr($u, 6,2);
            } else if ($v == 2028) {
                $encoded .= '\\u2028';
            } else if ($v == 2029) {
                $encoded .= '\\u2029';
            } else {
                $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
            }
        }

        return $encoded;
    }

    // Данные для теста
    $convmap = [ 0x0, 0xffff, 0, 0xffff ];
    $msg = '';

    for ($i=0; $i < 1000; $i++) {
        // Функцией chr() невозможно сгенерировать правильные данные в кодировке UTF-8 с кодовыми точками больше 128,
        // поэтому вызывается функция mb_decode_numericentity()
        $msg .= mb_decode_numericentity('&#' . $i . ';', $convmap, 'UTF-8');
    }

    // var_dump($msg);
    var_dump(escape_javascript_string($msg));

    ?>

### Смотрите также

- mb_encode_numericentity() - Кодирует символы в числовые HTML-сущности

# mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Определяет кодировку символов

### Описание

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

Функция определяет наиболее вероятную кодировку символов значения с типом string в параметре `string` путём проверки списка кандидатов по порядку.

Начиная с PHP 8.1 функция возвращает не первую возможную кодировку, а проверяет каждую допустимую кодировку в списке `encodings` и эвристически определяет наиболее правильную.

Надёжность автоматического определения предполагаемой кодировки символов не достигает 100 %; без дополнительной информации это похоже на расшифровку зашифрованной строки без ключа. Лучше явно указать кодировку символов, которая хранится или передаётся с данными, например в HTTP-заголовке Content-Type.

Функция полезнее при вызове с многобайтовыми кодировками, поскольку не каждая последовательность байтов образует допустимую строку. Функция отклонит кодировку, если входная строка содержит такую последовательность.

Внимание

# Неточность результата

Название функции вводит в заблуждение: функция «угадывает» кодировку, а не «обнаруживает».

Догадки неточны, поэтому функцией невозможно точно определить правильную кодировку символов.

### Список параметров

`string`

  Проверяемая строка (string).

`encodings`

  Список кодировок символов для проверки. Список определяется как массив строк или как строка со списком кодировок через запятую.

  При пропуске параметра `encodings` или установке для параметра значения `null` выбирается текущий порядок определения кодировки, который установили в директиве mbstring.detect_order настроек конфигурации или функцией mb_detect_order().

`strict`

  Управляет поведением, когда строка в параметре `string` недопустима ни для одной перечисленной в параметре `encodings` кодировки. При передаче в параметр `strict` значения `false` возвращается первая совпавшая кодировка; при установке для параметра `strict` значения `true` возвращается значение `false`.

  Значение по умолчанию для параметра `strict` также устанавливается в директиве mbstring.strict_detection настроек конфигурации.

### Возвращаемые значения

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

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Функция mb_detect_encoding() больше не возвращает следующие нетекстовые кодировки: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` и `"8 bit"`.

### Примеры

Пример #1 Пример определения кодировки функцией mb_detect_encoding()

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // Определение кодировки символов с текущим порядком определения
    var_dump(mb_detect_encoding($str));

    // Значение "auto" раскрывается в соответствии с директивой mbstring.language
    var_dump(mb_detect_encoding($str, "auto"));

    // Установка параметра "encodings" списком значений через запятую
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // Установка параметра "encodings" массивом
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));

Результат выполнения приведённого примера:

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

Пример #2 Действие параметра `strict`

    <?php

    // Строка "áéóú" в кодировке ISO-8859-1
    $str = "\xE1\xE9\xF3\xFA";

    // Строка недопустима для кодировок ASCII или UTF-8, но UTF-8 считается более близким соответствием
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // При обнаружении допустимой кодировки параметр strict не изменяет результат
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));

Результат выполнения приведённого примера:

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

Иногда одна и та же последовательность байтов образовывает допустимую строку в нескольких кодировках символов, и невозможно узнать, какая интерпретация подразумевалась. Например, среди многих других байтовая последовательность "\xC4\xA2" допустима для:

- «Ä¢» (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS с последующим U+00A2 CENT SIGN), закодированная в одной из кодировок — ISO-8859-1, ISO-8859-15 или Windows-1252
- «ФЂ» (U+0424 CYRILLIC CAPITAL LETTER EF с последующим U+0402 CYRILLIC CAPITAL LETTER DJE), закодированная в ISO-8859-5
- «Ģ» (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA), закодированная в UTF-8

Пример #3 Действие порядка кодировок при совпадении нескольких кандидатов

    <?php

    $str = "\xC4\xA2";

    // Строка действительна в каждой из трёх кодировок,
    // но вернётся не первая возможная, а наиболее корректная
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // С php8.1 вернётся кодировка ISO-8859-1, а не UTF-8
    var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
    var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));

    ?>

Результат выполнения приведённого примера:

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### Смотрите также

- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — Устанавливает или получает порядок определения кодировки символов

### Описание

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

Устанавливает порядок автоматического определения кодировки символов в значение, переданное в параметр `encoding`.

### Список параметров

`encoding`

  Параметр `encoding` — массив (array) или разделённый запятыми список кодировок символов. Подробнее о существующих в PHP кодировках символов рассказано в разделе «Поддерживаемые кодировки символов».

  Если параметр `encoding` не задан или равен `null`, функция вернёт текущий порядок определения кодировок символов в виде массива.

  Эта настройка влияет на работу функций mb_detect_encoding() и mb_send_mail().

  Модуль `mbstring` содержит следующие фильтры определения кодировок. Если для следующих кодировок существует недопустимая последовательность байтов, определение кодировки завершится неудачно:

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  Модуль `mbstring` определяет кодировку `ISO-8859-*` как `ISO-8859-*`.

  Определение кодировок `UTF-16`, `UTF-32`, `UCS2` и `UCS4` всегда будет неудачным.

### Возвращаемые значения

При установке порядка определения кодировки: возвращает `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

При получении порядка определения кодировки: возвращает массив кодировок в установленном порядке.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример использования функции mb_detect_order()

    <?php
    /* Установка порядка определения списком перечисленных кодировок */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* Установка порядка определения массивом */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* Отображение текущего порядка обнаружения */
    echo implode(", ", mb_detect_order());
    ?>

Пример #2 Пример бесполезных порядков определения

    ; Всегда определяет как ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; Всегда определяет как UTF-8, так как ASCII/UTF-7 —
    ; подмножество UTF-8
    detect_order = UTF-8, ASCII, UTF-7

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_http_input() - Определяет кодировку символов входных данных HTTP-запроса
- mb_http_output() - Устанавливает или получает кодировку символов HTTP-вывода
- mb_send_mail() - Отправляет закодированное электронное письмо

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — Кодирует строку для заголовка MIME

### Описание

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

Функция кодирует строку (string), которую передали в аргументе `string`, по схеме кодирования MIME-заголовка.

### Список параметров

`string`

  Строка (string), которую требуется закодировать. Параметр принимает строку, кодировка которой совпадает с кодировкой, которую возвращает функция mb_internal_encoding().

`charset`

  Параметр `charset` определяет название набора символов, в котором представляется строка `string`. Значение по умолчанию определяется настройкой национального языка по умолчанию (англ. NLS, National Language Setting), которую устанавливает директива `mbstring.language`.

`transfer_encoding`

  Параметр `transfer_encoding` определяет схему MIME-кодирования. Параметр принимает либо значение `«B»`, которое указывает кодировку Base64, либо значение `«Q»`, которое указывает кодировку Quoted-Printable. Значение по умолчанию равно `«B»`.

`newline`

  Параметр `newline` определяет EOL-метку конца строки (англ. end-of-line), которой функция mb_encode_mimeheader() переносит строки (англ. line-folding). Line-folding — термин стандарта » RFC 2822, который означает разбиение строки, длина которой превышает конкретную величину, на несколько строк. Длину разбиения строки жёстко закодировали и установили значение в 74 символа. Значение по умолчанию определили последовательностью символов `«\r\n»`, или CRLF.

`indent`

  Отступ первой строки — количество символов в заголовке перед параметром `string`.

### Возвращаемые значения

Функция возвращает версию строки (string), которую преобразовала в ASCII-представление.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | `NUL`-байты больше не отбрасываются при кодировании строк по правилам синтаксиса QP-кодировки (англ. Quoted-Printable), а кодируются как `=00`. Нулевой байт — байт со значением 0, который в наборах символов назначают нулевой кодовой точке.
8.0.0 | Параметры `charset` и `transfer_encoding` теперь принимают значение `null`.

### Примеры

Пример #1 Пример кодировки строки для заголовка MIME функцией mb_encode_mimeheader()

    <?php

    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;

    ?>

Результат выполнения приведённого примера:

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### Примечания

> Замечание:

> Функция не переносит строки в высокоуровневых точках разрыва строк на основе контекста наподобие границ слов и аналогичных. Такое поведение иногда загромождает исходную строку неожиданными пробелами.

### Смотрите также

- mb_decode_mimeheader() - Декодирует строку в MIME-заголовке

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Кодирует символы в числовые HTML-сущности

### Описание

function mb_encode_numericentity(
string `$string`,
array `$map`,
?string `$encoding` = `null`,
bool `$hex` = `false`
): string

Функция преобразовывает символы строки `string` в числовые HTML-сущности на основе диапазонов кодовых точек.

### Список параметров

`string`

  Кодируемая строка (string).

`map`

  Параметр `map` принимает массив, который определяет диапазоны кодовых точек для преобразования.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.
`hex`

  Параметр указывает, возвращать ли HTML-сущность в шестнадцатеричной нотации; иначе числовая ссылка на символ возвращается в десятичной нотации.

### Возвращаемые значения

Функция возвращает преобразованную строку (string).

### Ошибки

Функция теперь выбрасывает ошибку ValueError, если список `map` содержит значения кроме int.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция mb_encode_numericentity() теперь выбрасывает ошибку ValueError, если список `map` содержит значения кроме int.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример формата для установки параметра `map`

    <?php

    $convmap = array(
        int start_code1, int end_code1, int offset1, int mask1,
        int start_code2, int end_code2, int offset2, int mask2,
        // ........
        int start_codeN, int end_codeN, int offsetN, int maskN
    );
    // Значения start_codeN и end_codeN определяют диапазон кодовых точек Юникода.
    // К кодовой точке исходного символа добавляется смещение offsetN и выполняется побитовая операция 'И' со значением маски maskN,
    // а полученное значение затем преобразовывается в числовую HTML-сущность.

    ?>

Пример #2 Пример кодирования символа функцией mb_encode_numericentity()

    <?php

    $str = "aAæÆあア𩸽";

    /* Преобразование каждого UTF8-символа длиной до 4 байтов в числовую HTML-сущность */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Преобразование только 2- и 4-байтовых UTF8-символов в числовую HTML-сущность */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];

    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    ?>

Результат выполнения приведённого примера:

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### Смотрите также

- mb_decode_numericentity() - Декодирует числовые HTML-сущности в символы

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Получает псевдонимы известного типа кодировки

### Описание

function mb_encoding_aliases(string `$encoding`): array

Функция возвращает массив псевдонимов для известного типа кодировки `encoding`.

### Список параметров

`encoding`

  Кодировка, для которой будут проверены псевдонимы.

### Возвращаемые значения

Функция возвращает индексный массив с псевдонимами кодировки.

### Ошибки

Функция выбрасывает исключение ValueError, если кодировка `encoding` неизвестна.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Если параметр `encoding` неизвестен, теперь выбрасывается исключение ValueError; раньше функция выдавала ошибку уровня `E_WARNING` и возвращала `false`.

### Примеры

Пример #1 Пример использования функции mb_encoding_aliases()

    <?php
    $encoding        = 'ASCII';
    $known_encodings = mb_list_encodings();

    if (in_array($encoding, $known_encodings)) {

        $aliases = mb_encoding_aliases($encoding);
        print_r($aliases);

    } else {

        echo "Неизвестная кодировка ($encoding).\n";

    }
    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => ANSI_X3.4-1968
        [1] => iso-ir-6
        [2] => ANSI_X3.4-1986
        [3] => ISO_646.irv:1991
        [4] => US-ASCII
        [5] => ISO646-US
        [6] => us
        [7] => IBM367
        [8] => cp367
        [9] => csASCII
    )

### Смотрите также

- mb_list_encodings() - Возвращает массив поддерживаемых кодировок

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок

### Описание

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Выполняет поиск совпадения с регулярным выражением с поддержкой многобайтовых кодировок.

### Список параметров

`pattern`

  Шаблон поиска.

`string`

  Строка (string) поиска.

`matches`

  Если найдены совпадения для подстроки в скобках шаблона `pattern` и функция вызвана с третьим аргументом `matches`, совпадения будут сохранены в массиве `matches`. Если совпадения не будут найдены, то параметру `matches` будет установлено значение в виде пустого массива.

  Элемент $matches[1] будет содержать первую слева подстроку в скобках; элемент $matches[2] — вторую и так далее. Элемент $matches[0] будет содержать копию всей строки.

### Возвращаемые значения

Возвращает `true`, если шаблон `pattern` соответствует строке `string`, иначе `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь в случае успешного завершения эта функция возвращает `true`. Раньше она возвращала байтовую длину найденного вхождения, если в строке `string` было найдено совпадение шаблону `pattern` и был установлен параметр `matches`. Если необязательный параметр `matches` не был задан или длина проверяемой строки равнялась `0`, функция возвращала `1`.
7.1.0 | Теперь функция mb_ereg() устанавливает параметр `matches` равным пустому массиву (array), если ничего не найдено. Ранее параметр `matches` не изменялся.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_eregi() - Находит соответствие регулярному выражению с поддержкой многобайтовых символов без учёта регистра

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — Определяет, соответствует ли многобайтовая строка регулярному выражению

### Описание

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

Определяет, совпадает ли многобайтовая строка с регулярным выражением.

> Замечание: Соответствие регулярному выражению `pattern` будет выполняться только с начала строки `string`.

### Список параметров

`pattern`

  Шаблон регулярного выражения.

`string`

  Оцениваемая строка (string).

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает `true`, если строка `string` совпадает с регулярным выражением `pattern`, иначе `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `options` теперь принимает значение null.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg() - Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок

# mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — Заменяет по регулярному выражению с поддержкой многобайтовых кодировок

### Описание

function mb_ereg_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Сканирует строку `string` для поиска совпадений с шаблоном `pattern`, затем заменяет совпавший текст на значение параметра `replacement`.

### Список параметров

`pattern`

  Шаблон регулярного выражения.

  В шаблоне `pattern` можно указывать многобайтовые символы.

`replacement`

  Текст замены.

`string`

  Проверяемая строка (string).

`options`
  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает результирующую строку в случае успешного выполнения или `false` в случае возникновения ошибки. Если строка `string` недопустима для текущей кодировки, возвращается значение `null`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `options` теперь может принимать значение null.
7.1.0 | Функция проверяет, допустима ли строка `string` для текущей кодировки.
7.1.0 | Модификатор `e` объявлен устаревшим.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

Внимание

Никогда не указывайте модификатор `e` при работе с данными, которые получили из недостоверных источников. Автоматическое экранирование этих данных не выполняется (в отличие от функции preg_replace()). Несоблюдение этих требований с высокой вероятностью создаст риск выполнения удалённого кода в приложении.

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_eregi_replace() - Заменяет по регулярному выражению с поддержкой многобайтовых символов без учёта регистра

# mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — Выполняет поиск и замену по регулярному выражению с поддержкой многобайтовых кодировок, обрабатывая совпадения callback-функцией

### Описание

function mb_ereg_replace_callback(
string `$pattern`,
callable `$callback`,
string `$string`,
?string `$options` = `null`
): string|false|null

Проверяет строку `string` на совпадение с шаблоном `pattern`, затем заменяет найденный текст выводом функции `callback`.

Поведение этой функции почти идентично функции mb_ereg_replace(), за исключением того, что вместо строки замены `replacement` необходимо определять функцию `callback`.

### Список параметров

`pattern`

  Шаблон регулярного выражения.

  В параметре `pattern` можно указывать многобайтовые символы.

`callback`

  Callback-функция, которая будет вызвана и получит массив совпавших в строке `string` элементов. Callback-функция должна возвращать строку замены.

  Передаваемая в параметр `callback` функции mb_ereg_replace_callback() callback-функция часто нужна только в одном месте. Можно использовать анонимные функции, чтобы определить callback-функцию внутри вызова функции mb_ereg_replace_callback(). Поступая так, разработчик получает всю информацию о вызове в одном месте и не загрязняет пространство имён функций именем callback-функции, которая больше нигде не потребуется.

`string`

  Строка (string) для проверки.

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает результирующую строку в случае успешного выполнения или `false` в случае возникновения ошибки. Если строка `string` недопустима для текущей кодировки, возвращается значение `null`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `options` теперь может принимать значение null.
7.1.0 | Функция проверяет, допустима ли строка `string` для текущей кодировки.

### Примеры

Пример #1 Пример использования функции mb_ereg_replace_callback()

    <?php

    // этот текст был утверждён в 2002
    // мы хотим обновить его для 2003
    $text = "День смеха — 04/01/2002\n";
    $text.= "Последнее Рождество было 12/24/2001\n";

    // callback-функция
    function next_year($matches)
    {
      // как обычно: в $matches[0] будет полное совпадение
      // $matches[1] — совпадение для первого подшаблона,
      // заключённое в «(...)» и т. д.
      return $matches[1] . ($matches[2] + 1);
    }

    echo mb_ereg_replace_callback(
        "(\d{2}/\d{2}/)(\d{4})",
        "next_year",
        $text,
    );

    ?>

Результат выполнения приведённого примера:

    День смеха - 04/01/2003
    Последнее Рождество было 12/24/2002

Пример #2 Пример использования функции mb_ereg_replace_callback() с анонимной функцией

    <?php
    // этот текст был утверждён в 2002
    // мы хотим обновить его для 2003
    $text = "День смеха — 04/01/2002\n";
    $text.= "Последнее Рождество было 12/24/2001\n";

    echo mb_ereg_replace_callback(
        "(\d{2}/\d{2}/)(\d{4})",
        function ($matches) {
            return $matches[1] . ($matches[2] + 1);
        },
        $text,
    );
    ?>

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_replace() - Заменяет по регулярному выражению с поддержкой многобайтовых кодировок
- Анонимные функции

# mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — Находит соответствие предопределённой строки в многобайтовой кодировке регулярному выражению

### Описание

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

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

### Список параметров

`pattern`

  Шаблон поиска.

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает `true`, если многобайтная строка соответствует регулярному выражению, иначе `false`. Строка (string) для поиска соответствий задаётся функцией mb_ereg_search_init(). Если параметр `pattern` не задан, будет использовано предыдущее выражение.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `pattern` и `options` теперь могут принимать значение null.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_init() - Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

# mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — Возвращает начальную позицию следующего совпадения с регулярным выражением

### Описание

function mb_ereg_search_getpos(): int

Возвращает начальную позицию следующего совпадения с регулярным выражением.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает начальную позицию следующего совпадения с регулярным выражением для функций mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). Позиция представлена байтами с начала строки.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_setpos() - Задаёт начальную позицию в строке, с которой начнётся поиск соответствий регулярному выражению

# mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — Получает последнее совпадение строки в многобайтовой кодировке регулярному выражению

### Описание

function mb_ereg_search_getregs(): array|false

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

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив (array), содержащий совпавшие с регулярным выражением подстроки, полученные после срабатывания функций mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). Если совпадений несколько, то первый элемент будет содержать совпавшую подстроку, второй будет содержать первую сгруппированную в скобках часть, третий элемент будет содержать вторую сгруппированную в скобках часть и так далее. Функция вернёт `false` в случае возникновения ошибки.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_init() - Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

# mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

### Описание

function mb_ereg_search_init(string `$string`, ?string `$pattern` = `null`, ?string `$options` = `null`): bool

Функция mb_ereg_search_init() задаёт значения параметров `string` и `pattern` для функций, которые ищут соответствия строк в многобайтовых кодировках регулярному выражению. С этими значениями работают функции mb_ereg_search(), mb_ereg_search_pos() и mb_ereg_search_regs().

### Список параметров

`string`

  Строка поиска.

`pattern`

  Шаблон поиска.

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `pattern` и `options` теперь могут принимать значение null.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_regs() - Возвращает совпавшую с регулярным выражением часть строки

# mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — Возвращает позицию и длину совпавшего с регулярным выражением участка многобайтовой строки

### Описание

function mb_ereg_search_pos(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

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

Строка для поиска задаётся функцией mb_ereg_search_init(). Если она не определена, будет использована строка, заданная ранее.

### Список параметров

`pattern`

  Шаблон, текст регулярного выражения.

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает массив (array), содержащий два элемента. Первый элемент — смещение в байтах, с которого начинается совпадение относительно начала искомой строки, и второй элемент — длина совпадения в байтах.

В случае возникновения ошибки возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `pattern` и `options` теперь могут принимать значение null.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_init() - Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

# mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — Возвращает совпавшую с регулярным выражением часть строки

### Описание

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Возвращает совпавшую с регулярным выражением часть строки.

### Список параметров

`pattern`

  Шаблон поиска.

`options`

  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает массив (array), в первом элементе которого будет подстрока совпавшей части, во втором сгруппированная в скобках первая часть, в третьем сгруппированная в скобках вторая часть и так далее, если будет найдено соответствие регулярному выражению строки в многобайтовой кодировке. В случае возникновения ошибки возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `pattern` и `options` теперь могут принимать значение null.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_init() - Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

# mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — Задаёт начальную позицию в строке, с которой начнётся поиск соответствий регулярному выражению

### Описание

function mb_ereg_search_setpos(int `$offset`): bool

Функция mb_ereg_search_setpos() задаёт начальную позицию, с которой начнётся поиск соответствий регулярному выражению функцией mb_ereg_search().

### Список параметров

`offset`

  Устанавливаемая позиция. Если передано отрицательное число, отсчёт идёт с конца строки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
7.1.0 | Добавлена поддержка параметром `offset` отрицательных значений.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_search_init() - Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению

# mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — Находит соответствие регулярному выражению с поддержкой многобайтовых символов без учёта регистра

### Описание

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

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

### Список параметров

`pattern`

  Шаблон поиска.

`string`

  Строка (string) поиска.

`matches`

  Если найдены совпадения для подстроки `pattern`, заключённой в скобки, и функция вызвана с заданным третьим параметром `matches`, совпадения будут сохранены в массиве `matches`. Если совпадений не найдено, параметр `matches` станет пустым массивом.

  Элемент $matches[1] будет содержать первую (слева) подстроку, заключённую в скобки; элемент $regs[2] — вторую и так далее. Элемент $matches[0] будет содержать копию всей найденной строки.

### Возвращаемые значения

Возвращает `true`, если шаблон `pattern` соответствует строке `string`, иначе `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь эта функция возвращает `true` в случае успешного выполнения. Раньше, если был задан параметр `matches` и в строке `string` было найдено вхождение шаблона `pattern`, возвращалась длинна найденной подстроки в байтах. Если параметр `matches` не задавался или длина найденной подстроки равнялась `0`, функция возвращала `1`.
7.1.0 | Функция mb_eregi() устанавливает значение параметра `matches` равным пустому массиву, если ничего не найдено. Ранее при отсутствии совпадений параметр `matches` не изменялся.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg() - Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок

# mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — Заменяет по регулярному выражению с поддержкой многобайтовых символов без учёта регистра

### Описание

function mb_eregi_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Сканирует строку `string` для поиска совпадений с шаблоном `pattern`, затем заменяет совпавший текст на значение, переданное в параметр `replacement`.

### Список параметров

`pattern`

  Шаблон регулярного выражения. Можно указывать многобайтовые символы. Регистр будет проигнорирован.

`replacement`

  Текст замены.

`string`

  Строка (string) поиска.

`options`
  Вариант поиска. Объяснение дано в описании функции mb_regex_set_options().

### Возвращаемые значения

Возвращает результирующую строку (string) в случае успешного выполнения или `false` в случае возникновения ошибки. Если строка `string` недопустима для текущей кодировки, возвращает `null`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `options` теперь может принимать значение `null`.
7.1.0 | Функция проверяет, является ли строка `string` допустимой для текущей кодировки.
7.1.0 | Модификатор `e` объявлен устаревшим.

### Примечания

> Замечание: Для этой функции будет использована внутренняя кодировка или кодировка, установленная функцией mb_regex_encoding().

Внимание

Никогда не указывайте модификатор `e` при работе с данными, которые получили из недостоверных источников. Автоматическое экранирование этих данных не выполняется (в отличие от функции preg_replace()). Несоблюдение этих требований с высокой вероятностью создаст риск выполнения удалённого кода в приложении.

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg_replace() - Заменяет по регулярному выражению с поддержкой многобайтовых кодировок

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — Получает внутренние настройки модуля mbstring

### Описание

function mb_get_info(string `$type` = "all"): array|string|int|false|null

Функция mb_get_info() возвращает внутренние параметры настроек модуля mbstring.

### Список параметров

`type`

  Если параметр `type` не задали или задали как `"all"`, возвращается массив (array), который содержит элементы `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` и `"strict_detection"`.

  Если параметр `type` задали как `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` или `"strict_detection"`, возвращается настройка заданного параметра.

### Возвращаемые значения

Функция возвращает массив (array) информации о параметрах, если параметр `type` не определили, иначе значение заданного параметра `type` или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `type` больше не поддерживает значения `"func_overload"` и `"func_overload_list"`.

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_http_output() - Устанавливает или получает кодировку символов HTTP-вывода

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — Определяет кодировку символов входных данных HTTP-запроса

### Описание

function mb_http_input(?string `$type` = `null`): array|string|false

Определяет кодировку символов входных данных HTTP-запроса.

### Список параметров

`type`

  Строка запроса задаёт тип входных данных. Значение `«G»` для GET запроса, `«P»` для POST запроса, `«C»` для COOKIE, `«S»` для строк, `«L»` для списка и `«I»` для всего вместе (будет возвращён массив (array)). Если аргумент опущен, функция вернёт последний обработанный тип входных данных.

### Возвращаемые значения

Возвращает название кодировки символов для заданного типа (`type`) или массив имён символьных кодировок, если параметр `type` задан как `«I»`. Если функция mb_http_input() не может обработать HTTP-запрос, она вернёт `false`.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `type` некорректно.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция mb_http_input() теперь выбрасывает ошибку ValueError, если значение параметра `type` некорректно.
8.0.0 | Параметр `type` теперь может принимать значение `null`.

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_http_output() - Устанавливает или получает кодировку символов HTTP-вывода
- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — Устанавливает или получает кодировку символов HTTP-вывода

### Описание

function mb_http_output(?string `$encoding` = `null`): string|bool

Устанавливает/получает кодировку символов HTTP-вывода. Выходные данные после работы этой функции будут преобразованы из внутренней кодировки к значению параметра `encoding`.

### Список параметров

`encoding`

  Если задан параметр `encoding`, функция mb_http_output() устанавливает кодировку выходных символов HTTP в значение параметра `encoding`.

  Если аргумент `encoding` опущен, функция mb_http_output() возвращает текущую кодировку символов вывода HTTP.

### Возвращаемые значения

Если аргумент `encoding` опущен, функция mb_http_output() возвращает текущую кодировку символов вывода HTTP. В противном случае Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `encoding` содержит нулевые байты.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция mb_http_output() теперь выбрасывает ошибку ValueError, если значение параметра `encoding` содержит нулевые байты.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_http_input() - Определяет кодировку символов входных данных HTTP-запроса
- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — Устанавливает или получает внутреннюю кодировку символов файла скрипта

### Описание

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

Функция устанавливает или получает внутреннюю кодировку скрипта.

### Список параметров

`encoding`

  Параметр `encoding` — имя кодировки символов, в которую преобразуется кодировка входных данных HTTP-запроса, из которой преобразуется кодировка HTTP-вывода, а также это имя кодировки по умолчанию для функций модуля mbstring, которые работают со строками. Обратите внимание: внутренняя кодировка и кодировка для многобайтовых регулярных выражений — не одно и то же.

### Возвращаемые значения

Если аргумент `encoding` установили, функция Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. При этом кодировка символов для многобайтовых регулярных выражений не изменяется. Функция возвращает имя текущей внутренней кодировки символов, если аргумент `encoding` не установили.

### Ошибки

Начиная с PHP 8.0.0 функция выбрасывает исключение ValueError, если в параметр `encoding` передали недопустимое значение кодировки. До PHP 8.0.0 вместо этого функция выдавала ошибку уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.
8.0.0 | Теперь функция выбрасывает исключение ValueError, если в параметр `encoding` передали недопустимое значение кодировки. Раньше вместо этого функция выдавала ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Пример использования функции mb_internal_encoding()

    <?php

    /* Установка внутренней кодировки в UTF-8 */
    mb_internal_encoding("UTF-8");

    /* Вывод на экран текущей внутренней кодировки */
    echo mb_internal_encoding();

    ?>

### Смотрите также

- mb_http_input() - Определяет кодировку символов входных данных HTTP-запроса
- mb_http_output() - Устанавливает или получает кодировку символов HTTP-вывода
- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов
- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения

# mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — Устанавливает или получает текущий язык

### Описание

function mb_language(?string `$language` = `null`): string|bool

Устанавливает/получает текущий язык.

### Список параметров

`language`

  Функцией кодируют сообщения электронной почты. Допустимые языки перечислены в следующей таблице. Функция mb_send_mail() использует параметр для кодирования электронной почты.

  Язык | Кодировка | Кодирование | Псевдоним
  --- | --- | --- | ---
  Немецкий язык/de (German) | ISO-8859-15 | Quoted-Printable | Немецкий язык (Deutsch)
  Английский язык/en | ISO-8859-1 | Quoted-Printable |
  Армянский язык/hy | ArmSCII-8 | Quoted-Printable |
  Японский язык/ja | ISO-2022-JP | BASE64 |
  Корейский язык/ko | ISO-2022-KR | BASE64 |
  neutral | UTF-8 | BASE64 |
  Русский язык/ru | KOI8-R | Quoted-Printable |
  Турецкий язык/tr | ISO-8859-9 | Quoted-Printable |
  Украинский язык/ua | KOI8-U | Quoted-Printable |
  uni | UTF-8 | BASE64 | Универсальный
  Упрощённый китайский язык/zh-cn | HZ | BASE64 |
  Традиционный китайский язык/zh-tw | BIG-5 | BASE64 |

### Возвращаемые значения

Если параметр `language` задан и допустим, функция возвращает `true`. В противном случае она вернёт `false`. Если параметр `language` опущен или равен `null`, функция вернёт текущее значение языка в виде строки (string).

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь параметр `language` может принимать значение `null`.

### Смотрите также

- mb_send_mail() - Отправляет закодированное электронное письмо

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Преобразовывает первый символ строки в нижний регистр

### Описание

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

Функция выполняет операцию, аналогичную функции lcfirst(), но умеет безопасно обрабатывать строки, в которых символы кодируются переменным количеством байтов, и возвращает строку `string`, первый символ которой привела к нижнему регистру.

### Список параметров

`string`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.
`encoding`
  Кодировка строки.

### Возвращаемые значения

Функция возвращает преобразованную строку.

### Смотрите также

- mb_ucfirst() - Преобразовывает первый символ строки в верхний регистр
- lcfirst() - Переводит первый символ строки в нижний регистр

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — Возвращает массив поддерживаемых кодировок

### Описание

function mb_list_encodings(): array

Функция возвращает массив с поддерживаемыми кодировками.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает индексный массив.

### Ошибки

Функция не выдаёт ошибок.

### Примеры

Пример #1 Пример получения списка поддерживаемых кодировок функцией mb_list_encodings()

    <?php

    print_r(mb_list_encodings());

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => pass
        [1] => auto
        [2] => wchar
        [3] => byte2be
        [4] => byte2le
        [5] => byte4be
        [6] => byte4le
        [7] => BASE64
        [8] => UUENCODE
        [9] => HTML-ENTITIES
        [10] => Quoted-Printable
        [11] => 7bit
        [12] => 8bit
        [13] => UCS-4
        [14] => UCS-4BE
        [15] => UCS-4LE
        [16] => UCS-2
        [17] => UCS-2BE
        [18] => UCS-2LE
        [19] => UTF-32
        [20] => UTF-32BE
        [21] => UTF-32LE
        [22] => UTF-16
        [23] => UTF-16BE
        [24] => UTF-16LE
        [25] => UTF-8
        [26] => UTF-7
        [27] => UTF7-IMAP
        [28] => ASCII
        [29] => EUC-JP
        [30] => SJIS
        [31] => eucJP-win
        [32] => SJIS-win
        [33] => JIS
        [34] => ISO-2022-JP
        [35] => Windows-1252
        [36] => ISO-8859-1
        [37] => ISO-8859-2
        [38] => ISO-8859-3
        [39] => ISO-8859-4
        [40] => ISO-8859-5
        [41] => ISO-8859-6
        [42] => ISO-8859-7
        [43] => ISO-8859-8
        [44] => ISO-8859-9
        [45] => ISO-8859-10
        [46] => ISO-8859-13
        [47] => ISO-8859-14
        [48] => ISO-8859-15
        [49] => EUC-CN
        [50] => CP936
        [51] => HZ
        [52] => EUC-TW
        [53] => BIG-5
        [54] => EUC-KR
        [55] => UHC
        [56] => ISO-2022-KR
        [57] => Windows-1251
        [58] => CP866
        [59] => KOI8-R
    )

### Смотрите также

- mb_encoding_aliases() - Получает псевдонимы известного типа кодировки

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — Удаляет пробельные или другие символы в начале строки

### Описание

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Функция выполняет операцию, аналогичную функции ltrim(), но умеет безопасно обрабатывать строки, в которых символы кодируются переменным количеством байтов. Функция удаляет в начале строки пробельные символы, или символы, которые указали во втором аргументе.

Без второго аргумента функция mb_ltrim() удалит следующие символы:

- `" "` (Unicode U+0020), стандартный пробел.
- `"\t"` (Unicode U+0009), символ табуляции.
- `"\n"` (Unicode U+000A), новая строка (символ перевода строки).
- `"\r"` (Unicode U+000D), возврат каретки.
- `"\0"` (Unicode U+0000), NUL-байт.
- `"\v"` (Unicode U+000B), символ вертикальной табуляции.
- `"\f"` (Unicode U+000C), перевод формы.
- `"\u00A0"` (Unicode U+00A0), NO-BREAK SPACE (неразрывный пробел).
- `"\u1680"` (Unicode U+1680), OGHAM SPACE MARK (огамический знак пробела).
- `"\u2000"` (Unicode U+2000), EN QUAD (пробел в виде узкого «квадрата»).
- `"\u2001"` (Unicode U+2001), EM QUAD (пробел в виде широкого «квадрата»).
- `"\u2002"` (Unicode U+2002), EN SPACE (узкий пробел).
- `"\u2003"` (Unicode U+2003), EM SPACE (широкий пробел).
- `"\u2004"` (Unicode U+2004), THREE-PER-EM SPACE (треть широкого пробела).
- `"\u2005"` (Unicode U+2005), FOUR-PER-EM SPACE (четверть широкого пробела).
- `"\u2006"` (Unicode U+2006), SIX-PER-EM SPACE (одна шестая широкого пробела).
- `"\u2007"` (Unicode U+2007), FIGURE SPACE (цифровой пробел).
- `"\u2008"` (Unicode U+2008), PUNCTUATION SPACE (пунктуационный пробел).
- `"\u2009"` (Unicode U+2009), THIN SPACE (тонкий пробел).
- `"\u200A"` (Unicode U+200A), HAIR SPACE (самый тонкий пробел).
- `"\u2028"` (Unicode U+2028), LINE SEPARATOR (разделительная линия).
- `"\u2029"` (Unicode U+2029), PARAGRAPH SEPARATOR (разделительная параграф).
- `"\u202F"` (Unicode U+202F), NARROW NO-BREAK SPACE (узкий неразрывный пробел).
- `"\u205F"` (Unicode U+205F), MEDIUM MATHEMATICAL SPACE (средний математический пробел).
- `"\u3000"` (Unicode U+3000), IDEOGRAPHIC SPACE (пробел шириной в иероглиф).
- `"\u0085"` (Unicode U+0085), NEXT LINE (NEL) (следующая строка; одновременно переводит строку и возвращает позицию печати к началу строки).
- `"\u180E"` (Unicode U+180E), MONGOLIAN VOWEL SEPARATOR (монгольская гласная разделитель).

### Список параметров

`string`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.
`characters`
  Необязательный параметр `characters` принимает список символов, которые требуется удалить.
`encoding`
  Кодировка строки.

### Возвращаемые значения

Функция возвращает строку `string`, в начале которой удалила пробельные символы.

### Смотрите также

- mb_trim() - Удаляет пробельные или другие символы в начале и конце строки
- mb_rtrim() - Удаляет пробелы или другие символы в конце строки
- ltrim() - Удаляет пробельные или другие символы в начале строки

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — Получает кодовую точку символа Unicode

### Описание

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

Функция возвращает значение кодовой точки Unicode заданного символа.

Функция дополняет функцию mb_chr().

### Список параметров

`string`

  Строка.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает кодовую точку Unicode первого символа строки (`string`) или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Простой пример использования функции mb_ord()

    <?php

    var_dump(mb_ord("A", "UTF-8"));
    var_dump(mb_ord("🐘", "UTF-8"));
    var_dump(mb_ord("\x80", "ISO-8859-1"));
    var_dump(mb_ord("\x80", "Windows-1252"));

    ?>

Результат выполнения приведённого примера:

int(65)
int(128024)
int(128)
int(8364)

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_chr() - Возвращает символ по значению кодовой точки Unicode
- IntlChar::ord() - Возвращает значение кодовой точки символа Юникода
- ord() - Преобразовывает первый байт строки в число от 0 до 255

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — Преобразовывает кодировку символов в буфере вывода, выступая в роли callback-функции

### Описание

function mb_output_handler(string `$string`, int `$status`): string

Функция mb_output_handler() — это callback-функция функции ob_start(). Функция mb_output_handler() преобразовывает символы буфера вывода из внутренней кодировки символов в кодировку HTTP-вывода.

### Список параметров

`string`

  Содержимое буфера вывода.

`status`

  Состояние буфера вывода.

### Возвращаемые значения

Возвращает преобразованную строку (string).

### Примеры

Пример #1 Пример использования функции mb_output_handler()

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### Примечания

> Замечание:

> Если нужно вывести двоичные данные, изображение например, необходимо передать заголовок Content-Type функцией header() до того, как любые двоичные данные будут переданы клиенту (например, header("Content-Type: image/png")). Если заголовок Content-Type передан, преобразование кодировок выходных символов не выполняется.

> Заметьте, если отправлен заголовок «Content-Type: text/*», пересылаемые данные будут рассмотрены как текст; произойдёт преобразование.

### Смотрите также

- ob_start() - Включает буферизацию вывода

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — Разбирает данные запросов GET, POST, COOKIE и устанавливает значения глобальных переменных

### Описание

function mb_parse_str(string `$string`, array `&$result`): bool

Разбирает запросы GET/POST/COOKIE и устанавливает значения глобальных переменных. Поскольку PHP не работает с исходными данными POST/COOKIE, её можно использовать только для работы с данными GET-запроса. Функция разбирает URL-кодированные данные, определяет кодировку, преобразовывает символы во внутреннюю кодировку скрипта и заносит значения переменных в массив `result` или в глобальные переменные.

### Список параметров

`string`

  URL-кодированные данные.

`result`

  Массив (array), содержащий декодированные и преобразованные во внутреннюю кодировку значения.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Второй параметр стал обязательным.
7.2.0 | Вызов функции mb_parse_str() без второго параметра объявлен устаревшим.

### Смотрите также

- mb_detect_order() - Устанавливает или получает порядок определения кодировки символов
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — Получает строку кодировки MIME

### Описание

function mb_preferred_mime_name(string `$encoding`): string|false

Получает строку (string) MIME-кодировки для заданной кодировки.

### Список параметров

`encoding`

  Кодировка.

### Возвращаемые значения

Возвращает MIME-кодировку `charset` в виде строки (string) для кодировки символов `encoding`, или `false`, если кодировке `encoding` невозможно сопоставить MIME-кодировку.

### Примеры

Пример #1 Пример использования функции mb_preferred_mime_name()

    <?php

    $outputenc = "sjis-win";
    mb_http_output($outputenc);
    ob_start("mb_output_handler");
    header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
    ?>

# mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — Устанавливает или получает кодировку символов для многобайтового регулярного выражения

### Описание

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Функция устанавливает или получает кодировку символов для многобайтового регулярного выражения.

### Список параметров

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Если параметр `encoding` установили, функция Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка. При этом внутренняя кодировка символов не изменяется. Функция возвращает имя текущей кодировки символов для многобайтовых регулярных выражений, если параметр `encoding` не установили.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_ereg() - Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок

# mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — Устанавливает или получает значение по умолчанию для настроек функций mbregex

### Описание

function mb_regex_set_options(?string `$options` = `null`): string

Устанавливает параметры по умолчанию, описанные в параметре `options`, для функций регулярных выражений, работающих со строками в многобайтных кодировках.

### Список параметров

`options`

  Настройки, которые нужно задать. Это строка, в которой каждый символ отвечает за какую-то настройку. Чтобы установить режим, необходимо указать его символ в конце строки, однако, можно задать только один режим, но несколько опций.

  Настройки регулярных выражений
  Настройка | Описание | Список изменений
  --- | --- | ---
  i | Включение неоднозначных совпадений |
  x | Включает форму расширенного шаблона |
  m | `'.'` совпадения с переводами строк |
  s | `«^»` → `«\A»`, `«$»` → `«\Z»` |
  p | То же, что и объединение настроек `m` и `s` |
  l | Поиск совпадений с наибольшей длиной |
  n | Игнорировать пустые совпадения |
  e | Вычисление кода результата функцией eval() | Объявлено устаревшим в PHP 7.1.0 и удалено в PHP 8.0.0

  > Замечание:

  > Настройка `«e»` не даёт эффекта при установке через функцию mb_regex_set_options(). Её указывают с функциями mb_ereg_replace() или mb_eregi_replace().

  Синтаксические режимы регулярных выражений (может быть задан только один)
  Режим | Описание
  --- | ---
  j | Java (Sun java.util.regex)
  u | Регулярные выражения GNU
  g | grep
  c | Emacs
  r | Ruby
  z | Perl
  b | Регулярные выражения POSIX Basic
  d | Регулярные выражения POSIX Extended

### Возвращаемые значения

Возвращает предыдущие настройки. Если параметр `options` опущен или равен `null`, возвращает строку (string), которая описывает текущие параметры.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Если параметр `options` задан и не равен `null`, возвращаются предыдущие параметры. Ранее возвращались текущие параметры.
8.0.0 | Параметр `options` теперь может принимать значение `null`.
8.0.0 | Опция `«e»` теперь выбрасывает исключение ValueError.
7.1.0 | Опция `«e»` теперь выдаёт ошибку уровня ValueError.

### Смотрите также

- mb_split() - Разбивает многобайтовую строку регулярным выражением
- mb_ereg() - Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок
- mb_eregi() - Находит соответствие регулярному выражению с поддержкой многобайтовых символов без учёта регистра

# mb_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — Удаляет пробелы или другие символы в конце строки

### Описание

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Функция выполняет операцию, аналогичную функции rtrim(), но умеет безопасно обрабатывать строки, в которых символы кодируются переменным количеством байтов. Функция возвращает строку `string`, в конце которой удалила пробельные символы, или символы, которые указали во втором аргументе.

Без второго аргумента функция mb_rtrim() удалит следующие символы:

- `" "` (Unicode U+0020), стандартный пробел.
- `"\t"` (Unicode U+0009), символ табуляции.
- `"\n"` (Unicode U+000A), новая строка (символ перевода строки).
- `"\r"` (Unicode U+000D), возврат каретки.
- `"\0"` (Unicode U+0000), NUL-байт.
- `"\v"` (Unicode U+000B), символ вертикальной табуляции.
- `"\f"` (Unicode U+000C), перевод формы.
- `"\u00A0"` (Unicode U+00A0), NO-BREAK SPACE (неразрывный пробел).
- `"\u1680"` (Unicode U+1680), OGHAM SPACE MARK (огамический знак пробела).
- `"\u2000"` (Unicode U+2000), EN QUAD (пробел в виде узкого «квадрата»).
- `"\u2001"` (Unicode U+2001), EM QUAD (пробел в виде широкого «квадрата»).
- `"\u2002"` (Unicode U+2002), EN SPACE (узкий пробел).
- `"\u2003"` (Unicode U+2003), EM SPACE (широкий пробел).
- `"\u2004"` (Unicode U+2004), THREE-PER-EM SPACE (треть широкого пробела).
- `"\u2005"` (Unicode U+2005), FOUR-PER-EM SPACE (четверть широкого пробела).
- `"\u2006"` (Unicode U+2006), SIX-PER-EM SPACE (одна шестая широкого пробела).
- `"\u2007"` (Unicode U+2007), FIGURE SPACE (цифровой пробел).
- `"\u2008"` (Unicode U+2008), PUNCTUATION SPACE (пунктуационный пробел).
- `"\u2009"` (Unicode U+2009), THIN SPACE (тонкий пробел).
- `"\u200A"` (Unicode U+200A), HAIR SPACE (самый тонкий пробел).
- `"\u2028"` (Unicode U+2028), LINE SEPARATOR (разделительная линия).
- `"\u2029"` (Unicode U+2029), PARAGRAPH SEPARATOR (разделительная параграф).
- `"\u202F"` (Unicode U+202F), NARROW NO-BREAK SPACE (узкий неразрывный пробел).
- `"\u205F"` (Unicode U+205F), MEDIUM MATHEMATICAL SPACE (средний математический пробел).
- `"\u3000"` (Unicode U+3000), IDEOGRAPHIC SPACE (пробел шириной в иероглиф).
- `"\u0085"` (Unicode U+0085), NEXT LINE (NEL) (следующая строка; одновременно переводит строку и возвращает позицию печати к началу строки).
- `"\u180E"` (Unicode U+180E), MONGOLIAN VOWEL SEPARATOR (монгольская гласная разделитель).

### Список параметров

`string`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.
`characters`
  Необязательный параметр `characters` принимает список символов, которые требуется удалить.
`encoding`
  Кодировка строки.

### Возвращаемые значения

Функция возвращает преобразованную строку.

### Смотрите также

- mb_trim() - Удаляет пробельные или другие символы в начале и конце строки
- mb_ltrim() - Удаляет пробельные или другие символы в начале строки
- rtrim() - Удаляет пробельные или другие символы в конце строки

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Заменяет неправильно сформированные последовательности байтов символом-заменителем

### Описание

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

Преобразовывает набор символов из заданной кодировки или кодировки по умолчанию, если кодировка не была указана, в ту же кодировку. Это заменяет все недопустимые последовательности байтов заменяющим символом.

### Список параметров

`string`

  Входная строка.

`encoding`

  Кодировка для интерпретации параметра `string`. Если значение опущено или равно `null`, будет использовано значение директивы mbstring.internal_encoding, если она установлена, иначе будет использовано значение директивы default_charset.

### Возвращаемые значения

Возвращает результат в виде строки (string) с заменёнными недопустимыми последовательностями байтов.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — Отправляет закодированное электронное письмо

### Описание

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

Отправляет сообщение электронной почты. Заголовки и сообщения преобразовываются и кодируются в соответствии с настройкой функции mb_language(). Это функция-обёртка для функции mail(), так что можно почитать и описание функции mail().

### Список параметров

`to`

  Электронные адреса получателей. Несколько адресов в аргументе `to` перечисляются через запятую. Значение этого аргумента не кодируется автоматически.

`subject`

  Тема письма.

`message`

  Текст письма.

`additional_headers` (необязательный)

  Строка или массив, которые будут вставлены в конец заголовка письма.

  Обычно указывают, чтобы добавить дополнительные заголовки (From, Cc, и Bcc). Несколько дополнительных заголовков должны разделяться символом CRLF (\r\n). Этот параметр нужно проверить, чтобы злоумышленники не могли внедрить нежелательные заголовки.

  Если передан массив, то его ключи будут именами заголовков, а значения соответствующими значениями заголовка.

  > Замечание:

  > При отправке письма оно обязано содержать заголовок `From`. Его можно задать в параметре `additional_headers` или через опцию в php.ini.

  > Если этого не сделать, то это приведёт к сообщение об ошибке, примерно такого содержания: `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. Заголовок `From` также устанавливает и заголовок `Return-Path` в Windows.

  > Замечание:

  > Если письмо не было доставлено, попробуют указать только символ LF (\n). Есть почтовые агенты Unix (особенно » qmail), которые автоматически заменяют символ LF на символ CRLF (что дублирует символ CR при заданном символе CRLF). Это единственное решение, так как это поведение не соответствует стандарту » RFC 2822.

`additional_params`

  Параметр `additional_params` — это параметр командной строки MTA. Он полезен для задания корректного заголовка Return-Path при использовании функции sendmail.

  Этот параметр экранируется функцией escapeshellcmd() автоматически, чтобы предотвратить запуск других команд. Функция escapeshellcmd() не даёт запускать команды, но допускает добавление дополнительных аргументов, поэтому нужно проверять эту опцию, чтобы обеспечить безопасность.

  Поскольку функция escapeshellcmd() выполняется автоматически, нельзя использовать ряд символов, которые разрешены в email-адресах. Нельзя использовать функцию mail() для программ, которые требуют указания таких символов.

  Пользователь, от имени которого запущен веб-сервер, должен быть добавлен в список доверенных пользователей в конфигурации почтового агента sendmail, чтобы предотвратить добавление заголовка X-Warning в сообщение, если отправитель письма задан параметром (-f). Для пользователей агента sendmail — это файл /etc/mail/trusted-users.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Теперь параметр `additional_params` может принимать значение `null`.
7.2.0 | Теперь в параметр `additional_headers` можно передавать массив.

### Смотрите также

- mail() - Отправляет электронную почту
- mb_encode_mimeheader() - Кодирует строку для заголовка MIME
- mb_language() - Устанавливает или получает текущий язык

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — Разбивает многобайтовую строку регулярным выражением

### Описание

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

Функция разбивает многобайтную строку `string` путём сопоставления с регулярным выражением `pattern` и возвращает массив (array).

### Список параметров

`pattern`

  Шаблон регулярного выражения.

`string`

  Значение string, которое требуется разбить.

`limit`
  При установке необязательного параметра `limit` функция разобьёт строку на части, количество которых не превышает значения `limit`.

### Возвращаемые значения

Функция возвращает результат разбиения в виде массива (array) или `false`, если возникла ошибка.

### Примечания

> Замечание: Кодировка символов, указанная функцией mb_regex_encoding(), будет по умолчанию использована для этой функции.

### Смотрите также

- mb_regex_encoding() - Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_ereg() - Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок
- explode() - Разбивает строку разделителем

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Дополняет мультибайтовую строку другой мультибайтовой строкой до заданной длины

### Описание

function mb_str_pad(
string `$string`,
int `$length`,
string `$pad_string` = " ",
int `$pad_type` = `STR_PAD_RIGHT`,
?string `$encoding` = `null`
): string

Эта функция возвращает строку `string`, дополненную слева, справа или с обеих сторон до заданной длины, где длина измеряется в кодовых точках Юникода. Если необязательный аргумент `pad_string` не передан, то строка `string` будет дополнена пробелами, иначе она будет дополнена символами параметра `pad_string` до нужной длины.

### Список параметров

`string`

  Входная строка.

`length`

  Если значение параметра `length` отрицательно, меньше или равно длине входной строки, то дополнения не происходит и возвращается исходная строка `string`.

`pad_string`

  > Замечание:

  > Строка `pad_string` может быть урезана, если необходимое количество дополняемых символов не делится нацело на длину строки `pad_string`.

`pad_type`

  Необязательный аргумент `pad_type`, возможные значения: `STR_PAD_RIGHT`, `STR_PAD_LEFT`, или `STR_PAD_BOTH`. По умолчанию будет использована константа `STR_PAD_RIGHT`.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает дополненную строку.

### Примеры

Пример #1 Пример использования функции mb_str_pad()

    <?php
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT));  // string(18) "❤❓❇❤▶▶"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH));  // string(18) "❤❓▶▶❤❓"

    var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT));   // string(10) "祝祝🎉"
    ?>

# mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — Возвращает массив символов многобайтовой строки

### Описание

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

Функция возвращает массив строк и работает аналогично функции str_split(), но поддерживает кодировки с переменным размером символов и кодировки с фиксированным размером символов из 1, 2 или 4 байтов. Функция разобьёт строку на части заданной длины, если указали параметр `length`; длина отдельной части измеряется не в байтах, а в символах. Кодировку символов строки указывают в необязательном параметре `encoding`, и это хорошая практика.

### Список параметров

`string`

  Строка (string), которую требуется разбить на отдельные символы или части из двух или большего количества символов.

`length`

  Функция составит и вернёт массив, каждый элемент которого состоит не из одного, а из заданного количества символов.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

  Строка, которая указывает поддерживаемую кодировку.

### Возвращаемые значения

Функция возвращает массив строк.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.
8.0.0 | Функция больше не возвращает `false`, если возникла ошибка.

### Смотрите также

- str_split() - Преобразовывает строку в массив
- grapheme_str_split() - Разбивает строку на массив графемных кластеров
- explode() - Разбивает строку разделителем

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — Получает часть строки

### Описание

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Функция mb_strcut() вырезает подстроку из строки так же, как функция mb_substr(), но оперирует байтами, а не символами. Если начало вырезаемой части попадает между байтами одного символа, функция вырежет подстроку, начиная с первого байта этого символа. Это существенное отличие от функции substr(), которая просто вырежет подстроку, начиная с середины символа, и этим нарушит последовательность байтов в строке.

### Список параметров

`string`

  Обрезаемая строка.

`start`

  Если значение параметра `start` неотрицательное, возвращённая строка начнётся с позиции `start` в байтах от начала строки `string`, считая с нуля. Например, в строке «`abcdef`» байт в позиции `0` — это «`a`», байт в позиции `2` — «`c`» и т. д.

  Если значение параметра `start` отрицательное, возвращаемая строка будет начинаться с байта `start` с обратным отсчётом от конца строки `string`. Однако, если величина отрицательного `start` превышает длину строки, возвращаемая часть начнётся с начала параметра `string`.

`length`

  Длина подстроки в байтах. Если не указана, то передаётся значение `NULL` и вырезаются все байты до конца строки.

  Если значение параметра `length` отрицательное, возвращаемая строка будет заканчиваться байтом `length` с обратным отсчётом от конца строки `string`. Однако, если величина отрицательного значения `length` превышает число символов после позиции `start`, будет возвращена пустая строка.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает часть строки `string`, которую задали аргументами `start` и `length`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Поведение для некорректных строк `UTF-8` и `UTF-16` стало более согласованным.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_substr() - Возвращает часть строки
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — Получает строку, обрезанную до заданной ширины

### Описание

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

Обрезает строку (string), переданную в параметр `string`, до заданой в параметре `width` ширины символов, где символы половинной ширины рассчитываются как `1`, а символы полной ширины — как `2`. Подробнее о ширине восточноазиатских символов рассказано в приложении » http://www.unicode.org/reports/tr11/.

### Список параметров

`string`

  Исходная строка.

`start`

  Смещение от начала строки. Количество символов от начала строки (первый символ стоит в позиции 0). Если указано отрицательное число, то отсчёт будет идти с конца строки.

`width`

  Ширина, до которой необходимо обрезать строку. Если задано отрицательное значение ширины, отсчёт будет идти с конца строки.

  > Замечание:

  > Передача отрицательного значения ширины устарела с PHP 8.3.0.

`trim_marker`

  Строка, которая заместит конец обрезанной строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает обрезанную строку. Если задан четвёртый параметр `trim_marker`, то его значением замещаются символы в конце строки, так, чтобы суммарный размер был не более ширины `width`.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Передача отрицательного значения в параметр `width` функции mb_strimwidth() устарела.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.
7.1.0 | Добавлена поддержка отрицательных значений для параметров `start` и `width`.

### Примеры

Пример #1 Пример использования функции mb_strimwidth()

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // Выведет "Hello W..."
    ?>

### Смотрите также

- mb_strwidth() - Возвращает ширину строки
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — Ищет в строке позицию первого вхождения подстроки, без учёта регистра

### Описание

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Функция mb_stripos() возвращает позицию первого вхождения подстроки `needle` в строку `haystack`. Функция mb_stripos(), в отличие от функции mb_strpos(), не чувствительна к регистру символов. Функция вернёт значение `false`, если не найдёт в строке подстроку `needle`.

### Список параметров

`haystack`

  Строка, в которой требуется найти позицию первого вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`offset`

  Начальная позиция поиска в строке `haystack`. Отрицательные смещения отсчитываются с конца строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает числовую позицию первого вхождения подстроки `needle` в строку `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Ошибки

- Функция выбросит ошибку ValueError, если значение параметра `offset` превысит длину строки `haystack`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.
7.1.0 | Добавили поддержку отрицательных значений параметром `offset`.

### Смотрите также

- stripos() - Возвращает позицию первого вхождения подстроки без учёта регистра
- strpos() - Ищет позицию первого вхождения подстроки
- mb_strpos() - Ищет в строке позицию первого вхождения подстроки

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — Возвращает часть строки до или после первого вхождения подстроки, без учёта регистра

### Описание

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

Функция mb_stristr() ищет в строке `haystack` первое вхождение подстроки `needle` и возвращает часть строки `haystack`. Функция mb_stristr(), в отличие от функции mb_strstr(), не учитывает регистр. Функция возвращает значение `false`, если строка не содержит подстроку `needle`.

### Список параметров

`haystack`

  Строка, часть которой требуется получить — до или после первого вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`before_needle`

  Параметр определяет, какую часть строки `haystack` возвращает функция. При установке значения `true` функция возвращает часть строки `haystack` от начала до первого вхождения подстроки `needle`, за исключением искомой подстроки. При установке значения `false` возвращается часть строки `haystack` от первого вхождения подстроки `needle` до конца строки, включая искомую подстроку.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает часть строки `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- stristr() - Регистронезависимый вариант функции strstr
- strstr() - Находит первое вхождение подстроки
- mb_strstr() - Возвращает часть строки до или после первого вхождения подстроки

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — Получает длину строки

### Описание

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

Функция получает длину строки (string).

### Список параметров

`string`

  Строка (string), длина которой измеряется.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает количество символов в строке (string) аргумента `string` на основе кодировки символов, которую определили в параметре `encoding`. Функция воспринимает многобайтовый символ как 1 символ.

### Ошибки

Функция выдаёт ошибку уровня `E_WARNING`, если не знает кодировку.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- grapheme_strlen() - Получает количество графемных кластеров в строке
- iconv_strlen() - Возвращает количество символов в строке
- strlen() - Получает длину строки

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — Ищет в строке позицию первого вхождения подстроки

### Описание

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Функция ищет в строке `haystack` позицию первого вхождения подстроки `needle`.

Функция выполняет безопасную многобайтовую операцию strpos() на основе количества символов, а не байтов. Первый символ стоит на позиции 0, позиция второго символа — 1 и так далее.

### Список параметров

`haystack`

  Строка, в которой требуется найти позицию первого вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`. Функция не приводила нестроковые значения параметра к целочисленным и не интерпретировала результат приведения как кодовую точку символа, как это делала функция strpos().

`offset`

  Начальная позиция поиска. Значение по умолчанию равно 0. Отрицательные смещения отсчитываются с конца строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает числовую позицию первого вхождения подстроки `needle` в строку (string) `haystack`. Функция возвращает значение `false`, если строка не содержит подстроку `needle`.

### Ошибки

- Функция выбросит ошибку ValueError, если значение параметра `offset` превысит длину строки `haystack`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.
7.1.0 | Добавили поддержку отрицательных значений параметром `offset`.

### Смотрите также

- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- strpos() - Ищет позицию первого вхождения подстроки

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — Возвращает часть строки до или после последнего вхождения подстроки

### Описание

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

Функция mb_strrchr() ищет в строке `haystack` последнее вхождение подстроки `needle` и возвращает часть строки `haystack`. Функция возвращает значение `false`, если строка не содержит подстроку `needle`.

### Список параметров

`haystack`

  Строка, часть которой требуется получить — до или после последнего вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`before_needle`

  Параметр определяет, какую часть строки `haystack` возвращает функция. При установке значения `true` функция возвращает часть строки `haystack` от начала до последнего вхождения подстроки `needle`. При установке значения `false` возвращается часть строки `haystack` от последнего вхождения подстроки `needle` до конца строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает часть строки `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- strrchr() - Находит последнее вхождение символа в строке
- mb_strstr() - Возвращает часть строки до или после первого вхождения подстроки
- mb_strrichr() - Возвращает часть строки до или после последнего вхождения подстроки, без учёта регистра

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — Возвращает часть строки до или после последнего вхождения подстроки, без учёта регистра

### Описание

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

Функция mb_strrichr() ищет в строке `haystack` последнее вхождение подстроки `needle` и возвращает часть строки `haystack`. Функция mb_strrichr(), в отличие от функции mb_strrchr(), не чувствительна к регистру символов. Функция возвращает значение `false`, если строка не содержит подстроку `needle`.

### Список параметров

`haystack`

  Строка, часть которой требуется получить — до или после последнего вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`before_needle`

  Параметр определяет, какую часть строки `haystack` возвращает функция. При установке значения `true` функция возвращает часть строки `haystack` от начала до последнего вхождения подстроки `needle`. При установке значения `false` возвращается часть строки `haystack` от последнего вхождения подстроки `needle` до конца строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает часть строки `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_stristr() - Возвращает часть строки до или после первого вхождения подстроки, без учёта регистра
- mb_strrchr() - Возвращает часть строки до или после последнего вхождения подстроки

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — Ищет в строке позицию последнего вхождения подстроки, без учёта регистра

### Описание

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Функция mb_strripos() выполняет безопасную многобайтовую операцию strripos() на основе количества символов, а не байтов. Функция отсчитывает позицию подстроки `needle` с начала строки `haystack`. Первый символ стоит на позиции 0, позиция второго символа — 1 и так далее. Функция mb_strripos(), в отличие от функции mb_strrpos(), не чувствительна к регистру.

### Список параметров

`haystack`

  Строка, в которой требуется найти позицию последнего вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`offset`

  Положительные значения указывают произвольную начальную позицию поиска символов в строке `haystack`. Отрицательные значения остановят поиск в произвольной точке до конца строки `haystack`.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает числовую позицию последнего вхождения подстроки `needle` в строку `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Ошибки

- Функция выбросит ошибку ValueError, если значение параметра `offset` превысит длину строки `haystack`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- strripos() - Ищет в строке позицию последнего вхождения подстроки, без учёта регистра
- strrpos() - Возвращает позицию последнего вхождения подстроки в строку
- mb_strrpos() - Ищет в строке позицию последнего вхождения подстроки

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — Ищет в строке позицию последнего вхождения подстроки

### Описание

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Функция выполняет безопасную многобайтовую операцию strrpos() на основе количества символов, а не байтов. Функция отсчитывает позицию подстроки `needle` с начала строки `haystack`. Первый символ стоит на позиции 0, позиция второго символа — 1 и так далее.

### Список параметров

`haystack`

  Строка (string), в которой требуется найти последнее вхождение подстроки `needle`.

`needle`

  Подстрока (string) для поиска в строке `haystack`.

`offset`
  Положительные значения указывают произвольную начальную позицию поиска символов в строке `haystack`. Отрицательные значения остановят поиск в произвольной точке до конца строки `haystack`.
`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает числовую позицию последнего вхождения подстроки `needle` в строку (string) `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Ошибки

- Функция выбросит ошибку ValueError, если значение параметра `offset` превысит длину строки `haystack`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Запретили передачу названия кодировки для параметра `encoding` в третьем аргументе вместо параметра `offset`.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_strpos() - Ищет в строке позицию первого вхождения подстроки
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта
- strrpos() - Возвращает позицию последнего вхождения подстроки в строку

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — Возвращает часть строки до или после первого вхождения подстроки

### Описание

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

Функция mb_strstr() находит первое вхождение подстроки `needle` в строку `haystack` и возвращает часть строки `haystack`. Функция возвращает значение `false`, если строка не содержит подстроку `needle`.

### Список параметров

`haystack`

  Строка, часть которой требуется получить — до или после первого вхождения подстроки `needle`.

`needle`

  Подстрока для поиска в строке `haystack`.

`before_needle`

  Параметр определяет, какую часть строки `haystack` возвращает функция. При установке значения `true` функция возвращает часть строки `haystack` от начала до первого вхождения подстроки `needle`, за исключением искомой подстроки. При установке значения `false` возвращается часть строки `haystack` от первого вхождения подстроки `needle` до конца строки, включая искомую подстроку.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает часть строки `haystack` или значение `false`, если строка не содержит подстроку `needle`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `needle` теперь принимает пустую строку.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- stristr() - Регистронезависимый вариант функции strstr
- strstr() - Находит первое вхождение подстроки
- mb_stristr() - Возвращает часть строки до или после первого вхождения подстроки, без учёта регистра

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — Приводит строку к нижнему регистру

### Описание

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

Функция возвращает строку `string`, в которой преобразовала алфавитные символы в нижний регистр.

### Список параметров

`string`

  Строка (string), которую требуется привести к нижнему регистру.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает строку (`string`), в которой привела к нижнему регистру каждый алфавитный символ.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Реализовали правила условного регистра для греческой буквы сигма.

### Примеры

Пример #1 Пример приведения строки к нижнему регистру функцией mb_strtolower()

    <?php

    $str = "У Мэри Был Маленький Ягнёнок и Она Его Очень ЛЮБИЛА";
    $str = mb_strtolower($str);
    echo $str; // Выведет у мэри был маленький ягнёнок и она его очень любила

    ?>

Пример #2 Пример приведения строки с нелатинскими буквами к нижнему регистру функцией mb_strtolower()

    <?php

    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // Выведет τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός

    ?>

### Примечания

В отличие от функции strtolower(), термин «алфавитный» в этой функции определяется Юникод-свойствами символа. Поэтому поведение этой функции не зависит от региональных настроек системы, и она умеет преобразовывать символы с Юникод-свойством 'alphabetic' наподобие символа буквы «а» с умлаутом — ä.

Дополнительная информация о свойствах Юникода доступна по ссылке » http://www.unicode.org/reports/tr21/.

### Смотрите также

- mb_strtoupper() - Приводит строку к верхнему регистру
- mb_convert_case() - Меняет регистр символов в строке
- strtolower() - Приводит строку к нижнему регистру

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — Приводит строку к верхнему регистру

### Описание

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

Функция возвращает строку `string`, в которой привела алфавитные символы к верхнему регистру.

### Список параметров

`string`

  Строка (string), которую требуется привести к верхнему регистру.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Функция возвращает строку (`string`), в которой привела к верхнему регистру каждый алфавитный символ.

### Примеры

Пример #1 Пример приведения строки к верхнему регистру функцией mb_strtoupper()

    <?php

    $str = "У Мэри Был Маленький Ягнёнок и Она Его Очень ЛЮБИЛА";
    $str = mb_strtoupper($str);
    echo $str; // Выведет У МЭРИ БЫЛ МАЛЕНЬКИЙ ЯГНЁНОК И ОНА ЕГО ОЧЕНЬ ЛЮБИЛА

    ?>

Пример #2 Пример приведения строки с нелатинскими буквами к верхнему регистру функцией mb_strtoupper()

    <?php

    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // Выведет ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ

    ?>

### Примечания

В отличие от функции strtoupper(), термин «алфавитный» в этой функции определяется Юникод-свойствами символа. Поэтому поведение этой функции не зависит от региональных настроек системы, и она умеет преобразовывать символы с Юникод-свойством 'alphabetic' наподобие символа буквы «а» с умлаутом — ä.

Дополнительная информация о свойствах Юникода доступна по ссылке » http://www.unicode.org/reports/tr21/.

### Смотрите также

- mb_strtolower() - Приводит строку к нижнему регистру
- mb_convert_case() - Меняет регистр символов в строке
- strtoupper() - Приводит строку к верхнему регистру

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — Возвращает ширину строки

### Описание

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

Возвращает ширину строки (string) `string`, где символы половинной ширины считаются `1`, а символы полной ширины считаются `2`. Смотрите » http://www.unicode.org/reports/tr11/ для получения подробной информации о ширине символов Восточной Азии.

Символы полной ширины: `U+1100`-`U+115F`, `U+11A3`-`U+11A7`, `U+11FA`-`U+11FF`, `U+2329`-`U+232A`, `U+2E80`-`U+2E99`, `U+2E9B`-`U+2EF3`, `U+2F00`-`U+2FD5`, `U+2FF0`-`U+2FFB`, `U+3000`-`U+303E`, `U+3041`-`U+3096`, `U+3099`-`U+30FF`, `U+3105`-`U+312D`, `U+3131`-`U+318E`, `U+3190`-`U+31BA`, `U+31C0`-`U+31E3`, `U+31F0`-`U+321E`, `U+3220`-`U+3247`, `U+3250`-`U+32FE`, `U+3300`-`U+4DBF`, `U+4E00`-`U+A48C`, `U+A490`-`U+A4C6`, `U+A960`-`U+A97C`, `U+AC00`-`U+D7A3`, `U+D7B0`-`U+D7C6`, `U+D7CB`-`U+D7FB`, `U+F900`-`U+FAFF`, `U+FE10`-`U+FE19`, `U+FE30`-`U+FE52`, `U+FE54`-`U+FE66`, `U+FE68`-`U+FE6B`, `U+FF01`-`U+FF60`, `U+FFE0`-`U+FFE6`, `U+1B000`-`U+1B001`, `U+1F200`-`U+1F202`, `U+1F210`-`U+1F23A`, `U+1F240`-`U+1F248`, `U+1F250`-`U+1F251`, `U+20000`-`U+2FFFD`, `U+30000`-`U+3FFFD`. Все остальные символы относятся к символам полуширины.

### Список параметров

`string`

  Исходная строка (string).

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает ширину строки (string) `string`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример использования функции mb_strwidth()

    <?php

    var_dump(
        mb_strwidth('a'),       // латинская строчная буква а
        mb_strwidth("\u{ff41}") // латинская строчная буква а полной ширины
    );
    ?>

Результат выполнения приведённого примера:

    int(1)
    int(2)

### Смотрите также

- mb_strimwidth() - Получает строку, обрезанную до заданной ширины
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — Устанавливает или получает символ замены

### Описание

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

Задаёт замещающий символ на случай, когда кодировка входных данных задана неверно или код символа не существует в кодировке выходных данных. Недопустимые символы могут быть заменены на `«none»` (нет вывода), строку (string) или числовое значение (int) (код символа Юникода).

Эта настройка влияет на поведение следующих функций: mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), mb_scrub() и mb_send_mail().

### Список параметров

`substitute_character`

  Задаёт значение Юникода в виде целого числа (int) или одной из следующих строк string:

  - `«none»`: нет вывода
  - `«long»`: код конечного (в выходной кодировке) символа (например: `U+3000`, `JIS+7E7E`)
  - `«entity»`: сущность конечного (в выходной кодировке) символа (например: `&#x200;`)

### Возвращаемые значения

Если аргумент `substitute_character` установили, функция вернёт `true` в случае успешного выполнения, иначе `false`. Функция вернёт текущую настройку, если символ `substitute_character` не установили.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Передача пустой строки в параметр `substitute_character` больше не поддерживается; вместо этого передают значение `"none"`.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример использования функции mb_substitute_character()

    <?php

    /* Установка замещающего символа Unicode U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* Задаём шестнадцатеричный формат */
    mb_substitute_character("long");

    /* Отображение текущей настройки */
    echo mb_substitute_character();

    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — Возвращает часть строки

### Описание

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Выполняет многобайтовую безопасную операцию substr(), основываясь на количестве символов. Позиция отсчитывается от начала строки (string) `string`. Позиция первого символа — 0, второго — 1 и т. д.

### Список параметров

`string`

  Строка, из которой извлекается подстрока.

`start`

  Если значение параметра `start` неотрицательное, возвращённая строка начнётся с позиции `start` от начала строки `string`, считая с нуля. Например, в строке «`abcdef`», символ в позиции `0` — это «`a`», символ в позиции `2` — «`c`» и т. д.

  Если значение параметра `start` отрицательное, возвращаемая строка начнётся с `start`-го символа с конца строки `string`.

`length`

  Максимальное количество символов подстроки, возвращаемых из строки `string`. Если не указан или равен `NULL` — извлекаются все символы до конца строки.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает часть строки `string`, заданную параметрами `start` и `length`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Для некорректных строк (содержащих ошибки кодировки) индексы символов теперь интерпретируются так же, как и в большинстве других функций mbstring. Это означает, что индексы символов, которые возвращает функция mb_strpos(), можно передавать напрямую.
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Смотрите также

- mb_strcut() - Получает часть строки
- mb_internal_encoding() - Устанавливает или получает внутреннюю кодировку символов файла скрипта

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — Возвращает количество вхождений подстроки

### Описание

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

Подсчитывает, сколько раз подстрока `needle` встречается в строке `haystack`.

### Список параметров

`haystack`

  Строка (string) для проверки.

`needle`

  Строка (string) для поиска.

`encoding`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.

### Возвращаемые значения

Возвращает количество вхождений подстроки `needle` в строку `haystack`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `encoding` теперь принимает значение `null`.

### Примеры

Пример #1 Пример использования функции mb_substr_count()

    <?php
    echo mb_substr_count("Это просто проверка", "то"); // выведет на экран 2
    ?>

### Смотрите также

- mb_strpos() - Ищет в строке позицию первого вхождения подстроки
- mb_substr() - Возвращает часть строки
- substr_count() - Возвращает количество вхождений подстроки

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Удаляет пробельные или другие символы в начале и конце строки

### Описание

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Функция выполняет операцию, аналогичную функции trim(), но умеет безопасно обрабатывать строки, в которых символы кодируются переменным количеством байтов. Функция возвращает строку `string`, в начале и конце которой удалила пробельные символы, или символы, которые указали во втором аргументе. Без второго аргумента функция mb_trim() удалит следующие символы:

- `" "` (Unicode U+0020), стандартный пробел.
- `"\t"` (Unicode U+0009), символ табуляции.
- `"\n"` (Unicode U+000A), новая строка (символ перевода строки).
- `"\r"` (Unicode U+000D), возврат каретки.
- `"\0"` (Unicode U+0000), NUL-байт.
- `"\v"` (Unicode U+000B), символ вертикальной табуляции.
- `"\f"` (Unicode U+000C), перевод формы.
- `"\u00A0"` (Unicode U+00A0), NO-BREAK SPACE (неразрывный пробел).
- `"\u1680"` (Unicode U+1680), OGHAM SPACE MARK (огамический знак пробела).
- `"\u2000"` (Unicode U+2000), EN QUAD (пробел в виде узкого «квадрата»).
- `"\u2001"` (Unicode U+2001), EM QUAD (пробел в виде широкого «квадрата»).
- `"\u2002"` (Unicode U+2002), EN SPACE (узкий пробел).
- `"\u2003"` (Unicode U+2003), EM SPACE (широкий пробел).
- `"\u2004"` (Unicode U+2004), THREE-PER-EM SPACE (треть широкого пробела).
- `"\u2005"` (Unicode U+2005), FOUR-PER-EM SPACE (четверть широкого пробела).
- `"\u2006"` (Unicode U+2006), SIX-PER-EM SPACE (одна шестая широкого пробела).
- `"\u2007"` (Unicode U+2007), FIGURE SPACE (цифровой пробел).
- `"\u2008"` (Unicode U+2008), PUNCTUATION SPACE (пунктуационный пробел).
- `"\u2009"` (Unicode U+2009), THIN SPACE (тонкий пробел).
- `"\u200A"` (Unicode U+200A), HAIR SPACE (самый тонкий пробел).
- `"\u2028"` (Unicode U+2028), LINE SEPARATOR (разделительная линия).
- `"\u2029"` (Unicode U+2029), PARAGRAPH SEPARATOR (разделительная параграф).
- `"\u202F"` (Unicode U+202F), NARROW NO-BREAK SPACE (узкий неразрывный пробел).
- `"\u205F"` (Unicode U+205F), MEDIUM MATHEMATICAL SPACE (средний математический пробел).
- `"\u3000"` (Unicode U+3000), IDEOGRAPHIC SPACE (пробел шириной в иероглиф).
- `"\u0085"` (Unicode U+0085), NEXT LINE (NEL) (следующая строка; одновременно переводит строку и возвращает позицию печати к началу строки).
- `"\u180E"` (Unicode U+180E), MONGOLIAN VOWEL SEPARATOR (монгольская гласная разделитель).

### Список параметров

`string`
  Параметр `encoding` указывает кодировку символов. При пропуске параметра или передаче значения `null` функция интерпретирует символы в предустановленной кодировке модуля.
`characters`
  Необязательный параметр `characters` принимает список символов, которые требуется удалить.
`encoding`
  Кодировка строки.

### Возвращаемые значения

Функция возвращает обрезанную строку.

### Смотрите также

- mb_ltrim() - Удаляет пробельные или другие символы в начале строки
- mb_rtrim() - Удаляет пробелы или другие символы в конце строки
- trim() - Удаляет пробельные или другие символы в начале и конце строки

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Преобразовывает первый символ строки в верхний регистр

### Описание

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

Функция выполняет операцию, аналогичную функции ucfirst(), но умеет безопасно обрабатывать строки, в которых символы кодируются переменным количеством байтов. Функция возвращает строку `string`, первый символ которой привела к верхнему регистру.

### Список параметров

`string`
  Входная строка.
`encoding`
  Кодировка строки.

### Возвращаемые значения

Функция возвращает преобразованную строку.

### Примечания

> Замечание:

> В отличие от стандартных функций сворачиваия и разворачивания регистра наподобие strtolower() и strtoupper(), преобразование регистра выполняется на основе свойств символов Юникода. Поэтому поведение функции не зависит от региональных настроек, а функция умеет преобразовывать символы с Юникод-свойством 'alphabetic' наподобие символа буквы «а» с умлаутом — ä.

Дополнительная информация о свойствах символов Юникода доступна по ссылке » http://www.unicode.org/reports/tr21/.

### Смотрите также

- mb_lcfirst() - Преобразовывает первый символ строки в нижний регистр
- mb_convert_case() - Меняет регистр символов в строке
- ucfirst() - Переводит первый символ строки в верхний регистр

## Содержание

- mb_check_encoding — Проверяет, допустима ли строка для заданной кодировки
- mb_chr — Возвращает символ по значению кодовой точки Unicode
- mb_convert_case — Меняет регистр символов в строке
- mb_convert_encoding — Преобразовывает строку из одной кодировки символов в другую
- mb_convert_kana — Преобразовывает одну кодировку "kana" в другую: "zen-kaku", "han-kaku" и другие
- mb_convert_variables — Преобразовывает символы в переменной(-ых) из одной кодировки в другую
- mb_decode_mimeheader — Декодирует строку в MIME-заголовке
- mb_decode_numericentity — Декодирует числовые HTML-сущности в символы
- mb_detect_encoding — Определяет кодировку символов
- mb_detect_order — Устанавливает или получает порядок определения кодировки символов
- mb_encode_mimeheader — Кодирует строку для заголовка MIME
- mb_encode_numericentity — Кодирует символы в числовые HTML-сущности
- mb_encoding_aliases — Получает псевдонимы известного типа кодировки
- mb_ereg — Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок
- mb_ereg_match — Определяет, соответствует ли многобайтовая строка регулярному выражению
- mb_ereg_replace — Заменяет по регулярному выражению с поддержкой многобайтовых кодировок
- mb_ereg_replace_callback — Выполняет поиск и замену по регулярному выражению с поддержкой многобайтовых кодировок, обрабатывая совпадения callback-функцией
- mb_ereg_search — Находит соответствие предопределённой строки в многобайтовой кодировке регулярному выражению
- mb_ereg_search_getpos — Возвращает начальную позицию следующего совпадения с регулярным выражением
- mb_ereg_search_getregs — Получает последнее совпадение строки в многобайтовой кодировке регулярному выражению
- mb_ereg_search_init — Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению
- mb_ereg_search_pos — Возвращает позицию и длину совпавшего с регулярным выражением участка многобайтовой строки
- mb_ereg_search_regs — Возвращает совпавшую с регулярным выражением часть строки
- mb_ereg_search_setpos — Задаёт начальную позицию в строке, с которой начнётся поиск соответствий регулярному выражению
- mb_eregi — Находит соответствие регулярному выражению с поддержкой многобайтовых символов без учёта регистра
- mb_eregi_replace — Заменяет по регулярному выражению с поддержкой многобайтовых символов без учёта регистра
- mb_get_info — Получает внутренние настройки модуля mbstring
- mb_http_input — Определяет кодировку символов входных данных HTTP-запроса
- mb_http_output — Устанавливает или получает кодировку символов HTTP-вывода
- mb_internal_encoding — Устанавливает или получает внутреннюю кодировку символов файла скрипта
- mb_language — Устанавливает или получает текущий язык
- mb_lcfirst — Преобразовывает первый символ строки в нижний регистр
- mb_list_encodings — Возвращает массив поддерживаемых кодировок
- mb_ltrim — Удаляет пробельные или другие символы в начале строки
- mb_ord — Получает кодовую точку символа Unicode
- mb_output_handler — Преобразовывает кодировку символов в буфере вывода, выступая в роли callback-функции
- mb_parse_str — Разбирает данные запросов GET, POST, COOKIE и устанавливает значения глобальных переменных
- mb_preferred_mime_name — Получает строку кодировки MIME
- mb_regex_encoding — Устанавливает или получает кодировку символов для многобайтового регулярного выражения
- mb_regex_set_options — Устанавливает или получает значение по умолчанию для настроек функций mbregex
- mb_rtrim — Удаляет пробелы или другие символы в конце строки
- mb_scrub — Заменяет неправильно сформированные последовательности байтов символом-заменителем
- mb_send_mail — Отправляет закодированное электронное письмо
- mb_split — Разбивает многобайтовую строку регулярным выражением
- mb_str_pad — Дополняет мультибайтовую строку другой мультибайтовой строкой до заданной длины
- mb_str_split — Возвращает массив символов многобайтовой строки
- mb_strcut — Получает часть строки
- mb_strimwidth — Получает строку, обрезанную до заданной ширины
- mb_stripos — Ищет в строке позицию первого вхождения подстроки, без учёта регистра
- mb_stristr — Возвращает часть строки до или после первого вхождения подстроки, без учёта регистра
- mb_strlen — Получает длину строки
- mb_strpos — Ищет в строке позицию первого вхождения подстроки
- mb_strrchr — Возвращает часть строки до или после последнего вхождения подстроки
- mb_strrichr — Возвращает часть строки до или после последнего вхождения подстроки, без учёта регистра
- mb_strripos — Ищет в строке позицию последнего вхождения подстроки, без учёта регистра
- mb_strrpos — Ищет в строке позицию последнего вхождения подстроки
- mb_strstr — Возвращает часть строки до или после первого вхождения подстроки
- mb_strtolower — Приводит строку к нижнему регистру
- mb_strtoupper — Приводит строку к верхнему регистру
- mb_strwidth — Возвращает ширину строки
- mb_substitute_character — Устанавливает или получает символ замены
- mb_substr — Возвращает часть строки
- mb_substr_count — Возвращает количество вхождений подстроки
- mb_trim — Удаляет пробельные или другие символы в начале и конце строки
- mb_ucfirst — Преобразовывает первый символ строки в верхний регистр

- Установка и настройка
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Краткий обзор поддерживаемых кодировок
- Основы японских многобайтовых кодировок
- Ввод и вывод HTTP
- Поддерживаемые кодировки символов
- Механизм перегрузки функций
- Требования, предъявляемые к кодировкам символов в PHP
- Функции для работы с многобайтовыми строками
  - mb_check_encoding — Проверяет, допустима ли строка для заданной кодировки
  - mb_chr — Возвращает символ по значению кодовой точки Unicode
  - mb_convert_case — Меняет регистр символов в строке
  - mb_convert_encoding — Преобразовывает строку из одной кодировки символов в другую
  - mb_convert_kana — Преобразовывает одну кодировку "kana" в другую: "zen-kaku", "han-kaku" и другие
  - mb_convert_variables — Преобразовывает символы в переменной(-ых) из одной кодировки в другую
  - mb_decode_mimeheader — Декодирует строку в MIME-заголовке
  - mb_decode_numericentity — Декодирует числовые HTML-сущности в символы
  - mb_detect_encoding — Определяет кодировку символов
  - mb_detect_order — Устанавливает или получает порядок определения кодировки символов
  - mb_encode_mimeheader — Кодирует строку для заголовка MIME
  - mb_encode_numericentity — Кодирует символы в числовые HTML-сущности
  - mb_encoding_aliases — Получает псевдонимы известного типа кодировки
  - mb_ereg — Находит совпадение регулярному выражению с поддержкой многобайтовых кодировок
  - mb_ereg_match — Определяет, соответствует ли многобайтовая строка регулярному выражению
  - mb_ereg_replace — Заменяет по регулярному выражению с поддержкой многобайтовых кодировок
  - mb_ereg_replace_callback — Выполняет поиск и замену по регулярному выражению с поддержкой многобайтовых кодировок, обрабатывая совпадения callback-функцией
  - mb_ereg_search — Находит соответствие предопределённой строки в многобайтовой кодировке регулярному выражению
  - mb_ereg_search_getpos — Возвращает начальную позицию следующего совпадения с регулярным выражением
  - mb_ereg_search_getregs — Получает последнее совпадение строки в многобайтовой кодировке регулярному выражению
  - mb_ereg_search_init — Настраивает строку и регулярное выражение для поиска соответствий строки в многобайтовой кодировке регулярному выражению
  - mb_ereg_search_pos — Возвращает позицию и длину совпавшего с регулярным выражением участка многобайтовой строки
  - mb_ereg_search_regs — Возвращает совпавшую с регулярным выражением часть строки
  - mb_ereg_search_setpos — Задаёт начальную позицию в строке, с которой начнётся поиск соответствий регулярному выражению
  - mb_eregi — Находит соответствие регулярному выражению с поддержкой многобайтовых символов без учёта регистра
  - mb_eregi_replace — Заменяет по регулярному выражению с поддержкой многобайтовых символов без учёта регистра
  - mb_get_info — Получает внутренние настройки модуля mbstring
  - mb_http_input — Определяет кодировку символов входных данных HTTP-запроса
  - mb_http_output — Устанавливает или получает кодировку символов HTTP-вывода
  - mb_internal_encoding — Устанавливает или получает внутреннюю кодировку символов файла скрипта
  - mb_language — Устанавливает или получает текущий язык
  - mb_lcfirst — Преобразовывает первый символ строки в нижний регистр
  - mb_list_encodings — Возвращает массив поддерживаемых кодировок
  - mb_ltrim — Удаляет пробельные или другие символы в начале строки
  - mb_ord — Получает кодовую точку символа Unicode
  - mb_output_handler — Преобразовывает кодировку символов в буфере вывода, выступая в роли callback-функции
  - mb_parse_str — Разбирает данные запросов GET, POST, COOKIE и устанавливает значения глобальных переменных
  - mb_preferred_mime_name — Получает строку кодировки MIME
  - mb_regex_encoding — Устанавливает или получает кодировку символов для многобайтового регулярного выражения
  - mb_regex_set_options — Устанавливает или получает значение по умолчанию для настроек функций mbregex
  - mb_rtrim — Удаляет пробелы или другие символы в конце строки
  - mb_scrub — Заменяет неправильно сформированные последовательности байтов символом-заменителем
  - mb_send_mail — Отправляет закодированное электронное письмо
  - mb_split — Разбивает многобайтовую строку регулярным выражением
  - mb_str_pad — Дополняет мультибайтовую строку другой мультибайтовой строкой до заданной длины
  - mb_str_split — Возвращает массив символов многобайтовой строки
  - mb_strcut — Получает часть строки
  - mb_strimwidth — Получает строку, обрезанную до заданной ширины
  - mb_stripos — Ищет в строке позицию первого вхождения подстроки, без учёта регистра
  - mb_stristr — Возвращает часть строки до или после первого вхождения подстроки, без учёта регистра
  - mb_strlen — Получает длину строки
  - mb_strpos — Ищет в строке позицию первого вхождения подстроки
  - mb_strrchr — Возвращает часть строки до или после последнего вхождения подстроки
  - mb_strrichr — Возвращает часть строки до или после последнего вхождения подстроки, без учёта регистра
  - mb_strripos — Ищет в строке позицию последнего вхождения подстроки, без учёта регистра
  - mb_strrpos — Ищет в строке позицию последнего вхождения подстроки
  - mb_strstr — Возвращает часть строки до или после первого вхождения подстроки
  - mb_strtolower — Приводит строку к нижнему регистру
  - mb_strtoupper — Приводит строку к верхнему регистру
  - mb_strwidth — Возвращает ширину строки
  - mb_substitute_character — Устанавливает или получает символ замены
  - mb_substr — Возвращает часть строки
  - mb_substr_count — Возвращает количество вхождений подстроки
  - mb_trim — Удаляет пробельные или другие символы в начале и конце строки
  - mb_ucfirst — Преобразовывает первый символ строки в верхний регистр

# Pspell

# Введение

Внимание

Модуль УСТАРЕЛ, а начиная с PHP 8.4.0 модуль УДАЛИЛИ из сборки.

Функции проверяют правописание слова и предлагают варианты исправления.

# Установка и настройка

## Содержание

- Требования
- Установка
- Типы ресурсов

## Требования

Чтобы скомпилировать PHP с поддержкой pspell, требуется библиотека aspell, которая доступна для скачивания по адресу » http://aspell.net/.

## Установка

## PHP 8.4

Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 8.4.0

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/pspell.

## PHP < 8.4

Модуль включают путём компиляции PHP с параметром --with-pspell[=dir].

> Замечание: Примечание для пользователей интерфейса Win32

> Модуль работает в ОС Windows, только когда системной переменной PATH доступны DLL-файлы. Раздел FAQ «Как добавить PHP-каталог в переменную PATH в Windows» рассказывает, как это сделать. Не рекомендуют копировать DLL-файлы из директории PHP в системную папку Windows, хотя это тоже решает проблему, поскольку системная переменная PATH содержит путь к системной директории по умолчанию. Для работы модуля в переменной PATH потребуются следующие файлы: Файл aspell-15.dll из папки bin с установленной программой aspell.

> Для поддержки интерфейса Win32 потребуется программа Aspell по крайней мере версии 0.50.

## Типы ресурсов

До PHP 8.1.0 модуль работал с двумя типами ресурсов. Первый — идентификатор ссылки словаря, второй — ресурс, который содержит конфигурацию pspell.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Функции Pspell

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Добавляет слово в персональный список слов

### Описание

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() добавляет слово в персональный список слов. Если вы использовали pspell_new_config() вместе с pspell_config_personal() для открытия словаря, вы можете сохранить список слов позднее с помощью pspell_save_wordlist().

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.
`word`

  Добавляемое слово.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Добавляет слово в список слов в текущей сессии

### Описание

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() добавляет слово в список слов, ассоциированный с текущей сессией. Эта функция очень похожа на функцию pspell_add_to_personal()

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.
`word`

  Добавляемое слово.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Проверяет слово

### Описание

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() проверяет орфографию слова.

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.
`word`

  Проверяемое слово.

### Возвращаемые значения

Возвращает `true`, если орфография верна, в противном случае возвращает `false`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_check()

    <?php
    $pspell = pspell_new("en");

    if (pspell_check($pspell, "testt")) {
        echo "Это верное написание";
    } else {
        echo "К сожалению, неправильное написание";
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Очищает текущую сессию

### Описание

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() очищает текущую сессию. Текущий список слов очищается, и, например, если попытаться сохранить его с помощью pspell_save_wordlist(), ничего не произойдёт.

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_clear_session($pspell);
    pspell_save_wordlist($pspell);    //Слово "Vlad" не будет сохранено
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Создаёт конфигурацию, используемую для открытия словаря

### Описание

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Создаёт конфигурацию, используемую для открытия словаря.

pspell_config_create() обладает синтаксисом, очень похожим на синтаксис pspell_new(). Фактически, использование pspell_config_create() сразу после pspell_new_config() даст точно такой же результат. Однако, после создания новой конфигурации, также можно использовать функции pspell_config_*() до вызова pspell_new_config() для получения преимуществ от некоторой дополнительной функциональности.

Более подробную информацию и примеры можно найти в руководстве по pspell на сайте:» http://aspell.net/.

### Список параметров

`language`

  Параметр language - это код языка, который состоит из двухбуквенного кода языка по стандарту ISO 639 и необязательного двубуквенного кода страны по стандарту ISO 3166 после тире или подчёркивания.

`spelling`

  Параметр spelling определяет вариант проверки орфографии для языков с более чем одним вариантом правописания, таких как английский. Известные значения: 'american', 'british', и 'canadian'.

`jargon`

  Параметр jargon содержит дополнительную информацию для различения двух различных списков слов, имеющих одинаковые параметры language и spelling.

`encoding`

  Параметр encoding - это кодировка, в которой, как ожидается, даны слова. Допустимые значения: 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Это параметр ещё не проверен достаточно хорошо, поэтому будьте осторожны при его использовании.

### Возвращаемые значения

Возвращает экземпляр PSpell\Config.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Возвращает экземпляр PSpell\Config; ранее возвращался ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_create()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "en");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Расположение файлов с языковыми данными

### Описание

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Расположение основного списка слов

### Описание

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Игнорирует слова длиной менее N символов

### Описание

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() должна быть использована для конфигурации до вызова pspell_new_config(). Эта функция позволяет пропускать короткие слова при проверке орфографии.

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`min_length`

  Слова длиной менее `min_length` символов будут пропущены.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_ignore()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");    //Сообщение об ошибке не будет сгенерировано
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Изменяет режим количества возвращаемых вариантов исправления

### Описание

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() должна быть использована для конфигурации до вызова pspell_new_config(). Эта функция определяет, сколько вариантов исправления будет возвращать функция pspell_suggest().

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`mode`

  Параметр mode - это режим, в котором будет работать проверка орфографии. Доступно несколько режимов:

  - `PSPELL_FAST` - Быстрый режим (наименьшее число вариантов исправления)
  - `PSPELL_NORMAL` - Нормальный режим (больше вариантов исправления)
  - `PSPELL_BAD_SPELLERS` - Медленный режим (много вариантов исправления)

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_mode()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Устанавливает файл, содержащий персональный список слов

### Описание

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Устанавливает файл, содержащий персональный список слов. Персональный список слов будет загружен и использован в дополнение к стандартному после того, как вы вызовете pspell_new_config(). Это тот же самый файл, в который функция pspell_save_wordlist() сохранит персональный список слов.

pspell_config_personal() должна быть использована для конфигурации до вызова pspell_new_config().

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`filename`

  Персональный список слов. Если файл не существует, он будет создан. Файл должен быть доступен для записи любому, кто запускает PHP (например, nobody).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Устанавливает файл, содержащий замещающие пары

### Описание

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Устанавливает файл, содержащий замещающие пары.

Замещающие пары повышают качество проверки орфографии. Когда слово написано с ошибками, а правильный вариант не найден в списке, pspell_store_replacement() может быть использована для того, чтобы сохранить замещающую пару, а pspell_save_wordlist() - чтобы сохранить список слов вместе с замещающими парами.

pspell_config_repl() должна быть использована для конфигурации до вызова pspell_new_config().

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`filename`

  Файл должен быть доступен для записи любому, кто запускает PHP (например, nobody).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_repl()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Рассматривает объединённые слова как правильные сложные слова

### Описание

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

Функция определяет, будут ли объединённые слова рассматриваться как правильные сложные слова. Так, "thecat" будет считаться правильным сложным словом, хотя между артиклем и словом должен быть пробел. Изменение этой установки влияет только на результаты, возвращаемые функцией pspell_check(); pspell_suggest() будет продолжать выдавать варианты исправления.

pspell_config_runtogether() должна быть использована для конфигурации до вызова pspell_new_config().

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`allow`

  `true`, если объединённые слова должны рассматриваться как правильные сложные слова, `false` в противном случае.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_config_runtogether()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "thecat");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

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

### Описание

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

pspell_config_save_repl() определяет, будет ли pspell_save_wordlist() сохранять замещающие пары вместе со списком слов. Обычно нет необходимости использовать эту функцию, поскольку, если используется pspell_config_repl(), замещающие пары будут сохранены pspell_save_wordlist() в любом случае, и, если она не используется, замещающие пары не будут сохраняться.

pspell_config_save_repl() должна быть использована для конфигурации до вызова pspell_new_config().

### Список параметров

`config`
  Экземпляр класса PSpell\Config.
`save`

  `true`, если замещающие пары должны сохраняться, `false` в противном случае.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Загружает новый словарь

### Описание

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() открывает новый словарь и возвращает экземпляр PSpell\Dictionary для использования в других функциях pspell.

Более подробную информацию и примеры можно найти в руководстве по pspell на сайте:» http://aspell.net/.

### Список параметров

`language`

  Параметр language - это код языка, который состоит из двухбуквенного кода языка по стандарту ISO 639 и необязательного двубуквенного кода страны по стандарту ISO 3166 после тире или подчёркивания.

`spelling`

  Параметр spelling определяет вариант проверки орфографии для языков с более чем одним вариантом правописания, таких как английский. Известные значения: 'american', 'british', и 'canadian'.

`jargon`

  Параметр jargon содержит дополнительную информацию для различения двух различных списков слов, имеющих одинаковые параметры language и spelling.

`encoding`

  Параметр encoding это кодировка, в которой, как ожидается, даны слова. Допустимые значения: 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. Этот параметр ещё не проверен достаточно хорошо, поэтому будьте осторожны при его использовании.

`mode`

  Параметр mode - это режим, в котором будет работать проверка орфографии. Доступно несколько режимов:

  - `PSPELL_FAST` - Быстрый режим (наименьшее число вариантов исправления)
  - `PSPELL_NORMAL` - Нормальный режим (больше вариантов исправления)
  - `PSPELL_BAD_SPELLERS` - Медленный режим (много вариантов исправления)
  - `PSPELL_RUN_TOGETHER` - рассматривает объединённые слова как правильные сложные слова. То есть, "thecat" будет считаться правильным сложным словом, хотя между артиклем и словом должен быть пробел. Изменение этой установки влияет только на результаты, возвращаемые функцией pspell_check(); pspell_suggest() будет продолжать выдавать варианты исправления.
  Mode - это битовая маска, сконструированная из различных перечисленных выше констант. Однако, `PSPELL_FAST`, `PSPELL_NORMAL` и `PSPELL_BAD_SPELLERS` являются взаимоисключающими, так что вы должны выбрать только одну из них.

### Возвращаемые значения

Возвращает экземпляр PSpell\Dictionary в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Возвращает экземпляр PSpell\Dictionary; ранее возвращался ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                               (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Загружает новый словарь с установками на основе заданной конфигурации

### Описание

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() открывает новый словарь с параметрами, заданными в `config`, созданной с помощью pspell_config_create() и модифицированной с помощью функций pspell_config_*(). Этот метод даёт наибольшую гибкость и имеет все функциональные возможности, предоставляемые pspell_new() и pspell_new_personal().

### Список параметров

`config`

  Параметр `config` - это параметр возвращённый функцией pspell_config_create() после того, как конфигурация была создана.

### Возвращаемые значения

Возвращает экземпляр PSpell\Dictionary в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `config` теперь ожидает экземпляр класса PSpell\Config; раньше параметр ждал ресурс (resource).
8.1.0 | Возвращает экземпляр PSpell\Dictionary; ранее возвращался ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_new_config()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    ?>

# pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — Загружает новый словарь с персональным списком слов

### Описание

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() открывает новый словарь с персональным списком слов. Список слов может быть модифицирован и сохранён функцией pspell_save_wordlist(), если потребуется. Однако замещающие пары не сохраняются. Для сохранения замещающих пар вы должны создать конфигурацию, используя pspell_config_create(), установить файл персонального списка слов функцией pspell_config_personal(), установить файл для замещающих пар функцией pspell_config_repl(), и открыть новый словарь с помощью pspell_new_config().

Более подробную информацию и примеры можно найти в руководстве по pspell на сайте:» http://aspell.net/.

### Список параметров

`filename`

  Файл, в который будут сохранены слова, добавленные в персональный список. Это должен быть абсолютный путь к файлу, начинающийся с '/', так как иначе он будет относительным к $HOME, которым является "/root" для большинства систем, что, вероятно, не то, что вам нужно.

`language`

  Код языка, который состоит из двухбуквенного кода языка по стандарту ISO 639 и необязательного двубуквенного кода страны по стандарту ISO 3166 после тире или подчёркивания.

`spelling`

  Определяет вариант проверки орфографии для языков с более чем одним вариантом правописания, таких как английский. Известные значения: 'american', 'british', и 'canadian'.

`jargon`

  Дополнительная информацию для различения двух различных списков слов, имеющих одинаковые параметры language и spelling.

`encoding`

  Кодировка, в которой, как ожидается, даны слова. Допустимые значения: `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16`, `machine unsigned 32`.

`mode`

  Режим, в котором будет работать проверка орфографии. Доступно несколько режимов:

  - `PSPELL_FAST` - Быстрый режим (наименьшее число вариантов исправления)
  - `PSPELL_NORMAL` - Нормальный режим (больше вариантов исправления)
  - `PSPELL_BAD_SPELLERS` - Медленный режим (много вариантов исправления)
  - `PSPELL_RUN_TOGETHER` - рассматривает объединённые слова как правильные сложные слова. То есть, "thecat" будет считаться правильным сложным словом, хотя между артиклем и словом должен быть пробел. Изменение этой установки влияет только на результаты, возвращаемые функцией pspell_check(); pspell_suggest() будет продолжать выдавать варианты исправления.
  Mode - это битовая маска, сконструированная из различных перечисленных выше констант. Однако, `PSPELL_FAST`, `PSPELL_NORMAL` и `PSPELL_BAD_SPELLERS` являются взаимоисключающими, так что вы должны выбрать только одну из них.

### Возвращаемые значения

Возвращает экземпляр PSpell\Dictionary в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Возвращает экземпляр PSpell\Dictionary; ранее возвращался ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Сохраняет персональный список слов в файле

### Описание

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() сохраняет персональный список слов текущей сессии. Расположение файлов для сохранения указывается с помощью pspell_config_personal() и (необязательно) pspell_config_repl().

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_add_to_personal()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Сохраняет замещающую пару для слова

### Описание

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() сохраняет замещающую пару для слова, так что замена позднее может быть возвращена функцией pspell_suggest(). Чтобы использовать преимущества этой функции, следует открыть словарь с помощью pspell_new_personal(). Чтобы навсегда сохранить замещающую пару, необходимо использовать pspell_config_personal() и pspell_config_repl() для того, чтобы указать путь, куда сохранить пользовательские списки слов, а затем воспользоваться pspell_save_wordlist() для записи изменений на диск.

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.
`misspelled`

  Слово с ошибкой.

`correct`

  Исправленное написание для слова с ошибкой (`misspelled`).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_store_replacement()

    <?php
    $pspell_config = pspell_config_create("en");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);

    pspell_store_replacement($pspell, $misspelled, $correct);
    pspell_save_wordlist($pspell);
    ?>

### Примечания

> Замечание:

> Функция не будет работать, если у вас нет pspell .11.2 и aspell .32.5 или выше.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Предлагает варианты исправления слова

### Описание

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() возвращает массив возможных вариантов исправления заданного слова.

### Список параметров

`dictionary`
  Экземпляр класса PSpell\Dictionary.
`word`

  Проверяемое слово.

### Возвращаемые значения

Возвращает массив возможных вариантов исправления.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `dictionary` теперь ожидает экземпляр класса PSpell\Dictionary; раньше параметр ждал ресурс (resource).

### Примеры

Пример #1 Пример использования pspell_suggest()

    <?php
    $pspell = pspell_new("en");

    if (!pspell_check($pspell, "testt")) {
        $suggestions = pspell_suggest($pspell, "testt");

        foreach ($suggestions as $suggestion) {
            echo "Возможный вариант исправления: $suggestion<br />";
        }
    }
    ?>

## Содержание

- pspell_add_to_personal — Добавляет слово в персональный список слов
- pspell_add_to_session — Добавляет слово в список слов в текущей сессии
- pspell_check — Проверяет слово
- pspell_clear_session — Очищает текущую сессию
- pspell_config_create — Создаёт конфигурацию, используемую для открытия словаря
- pspell_config_data_dir — Расположение файлов с языковыми данными
- pspell_config_dict_dir — Расположение основного списка слов
- pspell_config_ignore — Игнорирует слова длиной менее N символов
- pspell_config_mode — Изменяет режим количества возвращаемых вариантов исправления
- pspell_config_personal — Устанавливает файл, содержащий персональный список слов
- pspell_config_repl — Устанавливает файл, содержащий замещающие пары
- pspell_config_runtogether — Рассматривает объединённые слова как правильные сложные слова
- pspell_config_save_repl — Определяет, сохранять ли список замещающих пар вместе со списком слов
- pspell_new — Загружает новый словарь
- pspell_new_config — Загружает новый словарь с установками на основе заданной конфигурации
- pspell_new_personal — Загружает новый словарь с персональным списком слов
- pspell_save_wordlist — Сохраняет персональный список слов в файле
- pspell_store_replacement — Сохраняет замещающую пару для слова
- pspell_suggest — Предлагает варианты исправления слова

# Класс PSpell\Dictionary

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `pspell` в PHP 8.1.0.

## Обзор класса

final class PSpell\Dictionary {
}

# Класс PSpell\Config

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `pspell config` в PHP 8.1.0.

## Обзор класса

final class PSpell\Config {
}

- Установка и настройка
  - Требования
  - Установка
  - Типы ресурсов
- Предопределённые константы
- Функции Pspell
  - pspell_add_to_personal — Добавляет слово в персональный список слов
  - pspell_add_to_session — Добавляет слово в список слов в текущей сессии
  - pspell_check — Проверяет слово
  - pspell_clear_session — Очищает текущую сессию
  - pspell_config_create — Создаёт конфигурацию, используемую для открытия словаря
  - pspell_config_data_dir — Расположение файлов с языковыми данными
  - pspell_config_dict_dir — Расположение основного списка слов
  - pspell_config_ignore — Игнорирует слова длиной менее N символов
  - pspell_config_mode — Изменяет режим количества возвращаемых вариантов исправления
  - pspell_config_personal — Устанавливает файл, содержащий персональный список слов
  - pspell_config_repl — Устанавливает файл, содержащий замещающие пары
  - pspell_config_runtogether — Рассматривает объединённые слова как правильные сложные слова
  - pspell_config_save_repl — Определяет, сохранять ли список замещающих пар вместе со списком слов
  - pspell_new — Загружает новый словарь
  - pspell_new_config — Загружает новый словарь с установками на основе заданной конфигурации
  - pspell_new_personal — Загружает новый словарь с персональным списком слов
  - pspell_save_wordlist — Сохраняет персональный список слов в файле
  - pspell_store_replacement — Сохраняет замещающую пару для слова
  - pspell_suggest — Предлагает варианты исправления слова
- PSpell\Dictionary — Класс PSpell\Dictionary
- PSpell\Config — Класс PSpell\Config

# GNU Recode

# Введение

Внимание

Модуль больше не поддерживается.

Модуль предоставляет интерфейс к библиотеке GNU Recode. Библиотека конвертирует файлы из одной кодировки в другую. Ошибочные символы пропускаются или заменяются наиболее подходящими, если конвертацию не получается сделать абсолютно точно. Библиотека распознает и умеет оперировать приблизительно 150 кодировками. Поддерживается большинство кодировок стандарта » RFC 1345.

> Замечание: С PHP 7.4.0 модуль отделили и переместили в репозиторий » PECL. Вместо этого попробуйте использовать «Многобайтовые строки» или модуль iconv.

> Замечание: Для Windows-платформ этот модуль недоступен.

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Для работы модуля требуется установить в систему библиотеку GNU Recode 3.5 или выше. Пакет доступен для скачивания по ссылке » http://directory.fsf.org/All_GNU_Packages/recode.html.

Внимание

Библиотека Recode 3.6 в ряде случаев добавляет странные символы после преобразованных строк. Поэтому безопаснее использовать Recode v3.5, либо одну из доступных альтернатив наподобие модулей iconv или mbstring.

## Установка

## PHP 7.4

Модуль переместили в репозиторий » PECL и он больше не поставляется с PHP 7.4.0

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/recode.

## PHP < 7.4

Для использования модуля необходимо скомпилировать PHP с опцией --with-recode[=DIR].

Внимание

При загрузке модуля может произойти аварийное завершение PHP во время запуска, если recode загружается после mysql или imap. Загрузка модуля перед ними решает проблему. Это происходит из-за того, что и recode и imap используют C-библиотеки со своими собственными функциями `hash_lookup()`, а в случае mysql и recode, функцию `hash_insert`.

Внимание

Модуль IMAP нельзя собирать вместе с модулями перекодировки или с модулем YAZ, поскольку модули используют одни и те же внутренние символы. Замечание: В Yaz 2.0 и выше этот недостаток устранили.

# Функции Recode

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — Псевдоним recode_string()

### Описание

Псевдоним функции recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Перекодирует из одного файла в другой в соответствии с заданными параметрами

### Описание

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Перекодирует файл, заданный дескриптором `input` в файл, заданный дескриптором `output` в соответствии с `request`.

### Список параметров

`request`
  Выбранный тип запроса на перекодировку
`input`
  Локальный файловый ресурс (resource) `input`
`output`
  Локальный файловый ресурс (resource) `output`

### Возвращаемые значения

Возвращает `false`, если возникли какие-либо трудности или `true` в случае успешного выполнения.

### Примеры

Пример #1 Пример использования recode_file()

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### Примечания

На данный момент эта функция не работает с дескрипторами, ссылающимися на удалённые файлы (URL). Оба файловых дескриптора должны указывать на локальные файлы.

### Смотрите также

- fopen() - Открывает файл или URL-адрес

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Перекодирует строку в соответствии с заданными параметрами

### Описание

function recode_string(string `$request`, string `$string`): string

Перекодирует строку `string` в соответствии с `request`.

### Список параметров

`request`
  Выбранный тип запроса на перекодировку
`string`
  Строка для перекодировки

### Возвращаемые значения

Возвращает перекодированную строку (string) или `false`, если возникли какие-либо проблемы с перекодировкой.

### Примеры

Пример #1 Пример использования recode_string()

    <?php
    echo recode_string("us..flat", "The following character has a diacritical mark: á");
    ?>

### Примечания

Простой запрос на перекодировку может быть "lat1..iso646-de".

### Смотрите также

- Более подробно о запросах на перекодировку читайте в документации, которая входит в дистрибутив GNU Recode.
- mb_convert_encoding() - Преобразовывает строку из одной кодировки символов в другую
- UConverter::transcode() - Преобразовывает строку из одной кодировки символов в другую
- iconv() - Преобразовывает строку из одной кодировки символов в другую

## Содержание

- recode — Псевдоним recode_string
- recode_file — Перекодирует из одного файла в другой в соответствии с заданными параметрами
- recode_string — Перекодирует строку в соответствии с заданными параметрами

- Установка и настройка
  - Требования
  - Установка
- Функции Recode
  - recode — Псевдоним recode_string
  - recode_file — Перекодирует из одного файла в другой в соответствии с заданными параметрами
  - recode_string — Перекодирует строку в соответствии с заданными параметрами

- Enchant — Библиотека проверки правописания Enchant
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Функции Enchant
  - EnchantBroker — Класс EnchantBroker
  - EnchantDictionary — Класс EnchantDictionary
- Gender — Определение пола по имени
  - Установка и настройка
  - Примеры
  - Gender\Gender — Класс Gender\Gender
- Gettext
  - Установка и настройка
  - Функции gettext
- iconv
  - Установка и настройка
  - Предопределённые константы
  - Функции iconv
- intl — Функции интернационализации
  - Установка и настройка
  - Предопределённые константы
  - Примеры
  - Collator — Класс Collator
  - NumberFormatter — The NumberFormatter class
  - Locale — Класс Locale
  - Normalizer — Класс Normalizer
  - MessageFormatter — Класс MessageFormatter
  - IntlCalendar — Класс IntlCalendar
  - IntlGregorianCalendar — Класс IntlGregorianCalendar
  - IntlTimeZone — Класс IntlTimeZone
  - IntlDateFormatter — Класс IntlDateFormatter
  - ResourceBundle — Класс ResourceBundle
  - Spoofchecker — Класс Spoofchecker
  - Transliterator — Класс Transliterator
  - IntlBreakIterator — Класс IntlBreakIterator
  - IntlRuleBasedBreakIterator — Класс IntlRuleBasedBreakIterator
  - IntlCodePointBreakIterator — Класс IntlCodePointBreakIterator
  - IntlDatePatternGenerator — Класс IntlDatePatternGenerator
  - IntlPartsIterator — Класс IntlPartsIterator
  - UConverter — Класс UConverter
  - Функции Grapheme
  - Функции IDN
  - IntlChar
  - IntlException — Класс исключений для ошибок intl
  - IntlIterator — Класс IntlIterator
  - Функции intl
- Многобайтовые строки
  - Установка и настройка
  - Предопределённые константы
  - Краткий обзор поддерживаемых кодировок
  - Основы японских многобайтовых кодировок
  - Ввод и вывод HTTP
  - Поддерживаемые кодировки символов
  - Механизм перегрузки функций
  - Требования, предъявляемые к кодировкам символов в PHP
  - Функции для работы с многобайтовыми строками
- Pspell
  - Установка и настройка
  - Предопределённые константы
  - Функции Pspell
  - PSpell\Dictionary — Класс PSpell\Dictionary
  - PSpell\Config — Класс PSpell\Config
- Recode — GNU Recode
  - Установка и настройка
  - Функции Recode

# Обработка и генерация изображений

# Изменяемая информация об изображении

# Введение

С модулем EXIF работают с метаданными изображений. Например, EXIF-функции вызывают, чтобы прочитать метаданные изображений с цифровых камер — работают с информацией, которую хранят заголовки. Обычно заголовки встречаются в изображениях форматов JPEG и TIFF.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

Модуль будет работать, только если PHP скомпилировали с опцией `--enable-exif`. PHP компилируют также с опцией `--enable-mbstring`, чтобы включить модуль mbstring, который даёт поддержку многобайтовых кодировок в EXIF-тегах.

## Установка

Чтобы включить поддержку exif, сконфигурируйте PHP с опцией --enable-exif

Пользователи Windows должны включить DLL-файлы php_mbstring.dll и php_exif.dll в php.ini. DLL php_mbstring.dll должна быть загружена до DLL php_exif.dll, так что настройте ваш php.ini соответствующим образом.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Exif поддерживает автоматическое преобразование кодировок символов Unicode и JIS пользовательских комментариев, когда модуль mbstring доступен. При этом комментарий сначала декодируется с использованием указанного набора символов. Затем результат кодируется в другом наборе символов, который должен совпадать с вашим `HTTP`-выводом.

Опции конфигурации Exif
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
exif.encode_unicode | "ISO-8859-15" | `INI_ALL` |
exif.decode_unicode_motorola | "UCS-2BE" | `INI_ALL` |
exif.decode_unicode_intel | "UCS-2LE" | `INI_ALL` |
exif.encode_jis | "" | `INI_ALL` |
exif.decode_jis_motorola | "JIS" | `INI_ALL` |
exif.decode_jis_intel | "JIS" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`exif.encode_unicode` string
  `exif.encode_unicode` определяет набор символов UNICODE при обработке пользовательских комментариев. По умолчанию это ISO-8859-15, который должен работать для большинства не азиатских стран. Эта установка может быть пустой или обязана быть кодировкой, поддерживаемой mbstring. Если она пустая, используется текущая внутренняя кодировка mbstring.
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` определяет внутреннюю кодировку символов изображения для Unicode-кодированных пользовательских комментариев, если изображение имеет байтовый порядок motorola (big-endian). Эта установка не может быть пустой, но вы можете указать список кодировок, поддерживаемых mbstring. По умолчанию UCS-2BE.
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` определяет внутреннюю кодировку символов изображения для Unicode-кодированных пользовательских комментариев, если изображение имеет байтовый порядок intel (little-endian). Эта установка не может быть пустой, но вы можете указать список кодировок, поддерживаемых mbstring. По умолчанию UCS-2LE.
`exif.encode_jis` string
  `exif.encode_jis` определяет набор символов JIS для обработки пользовательских комментариев. По умолчанию - пустое значение, которое заставляет функции использовать текущую внутреннюю кодировку mbstring.
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` определяет внутреннюю кодировку символов изображения для JIS-кодированных пользовательских комментариев, если изображение имеет байтовый порядок motorola (big-endian). Эта установка не может быть пустой, но вы можете указать список кодировок, поддерживаемых mbstring. По умолчанию JIS.
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` определяет внутреннюю кодировку символов изображения для JIS-кодированных пользовательских комментариев, если изображение имеет байтовый порядок intel (little-endian). Эта установка не может быть пустой, но вы можете указать список кодировок, поддерживаемых mbstring. По умолчанию JIS.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`EXIF_USE_MBSTRING` (int)
  Эта константа равна `1` если разрешено mbstring, или `0`, если нет.

Функция exif_imagetype() отображает связанные встроенные константы.

# Exif Функции

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — Determine the type of an image

### Описание

function exif_imagetype(string `$filename`): int|false

exif_imagetype() считывает начальные байты изображения и проверяет их сигнатуру.

exif_imagetype() может использоваться, чтобы избежать вызовов других exif-функций с неподдерживаемыми аргументами. Также при взаимодействии с $_SERVER['HTTP_ACCEPT'] можно проверять, будет ли изображение отображаться в браузере.

### Список параметров

`filename`
  Изображение, тип которого требуется определить.

### Возвращаемые значения

Если корректная сигнатура обнаружена, функция вернёт соответствующую типу изображения константу. В противном случае функция вернёт `false`. Возвращаемое значение то же, что и во втором аргументе при возврате из функции getimagesize(), однако exif_imagetype() значительно быстрее.

Следующие определённые константы представляют возможные возвращаемые значения функции exif_imagetype():

Константы Imagetype
Значение | Константа
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II` (порядок байт intel)
8 | `IMAGETYPE_TIFF_MM` (порядок байт motorola)
9 | `IMAGETYPE_JPC`
10 | `IMAGETYPE_JP2`
11 | `IMAGETYPE_JPX`
12 | `IMAGETYPE_JB2`
13 | `IMAGETYPE_SWC`
14 | `IMAGETYPE_IFF`
15 | `IMAGETYPE_WBMP`
16 | `IMAGETYPE_XBM`
17 | `IMAGETYPE_ICO`
18 | `IMAGETYPE_WEBP`
19 | `IMAGETYPE_AVIF`
20 | `IMAGETYPE_HEIF`

> Замечание: В случаях, когда невозможно считать количество байтов из файла достаточное для определения типа изображения, функция exif_imagetype() вызовет предупреждение уровня `E_NOTICE` и вернёт `false`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавлена поддержка HEIF.
8.1.0 | Добавлена поддержка AVIF.
7.1.0 | Добавлена поддержка WebP.

### Примеры

Пример #1 Пример использования exif_imagetype()

    <?php
    if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
        echo 'Картинка не gif';
    }
    ?>

### Смотрите также

- image_type_to_mime_type() - Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- getimagesize() - Получает размер изображения

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — Читает заголовки EXIF из файлов изображений

### Описание

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

Функция exif_read_data() читает заголовки EXIF из файлов изображений. Так читают метаданные, которые генерируют цифровые фотоаппараты.

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

Значения `Height` и `Width` функция вычисляет аналогично вычислениям функции getimagesize(), так что эти параметры не обязаны присутствовать в заголовке. `html` — текстовая строка, которая задаёт высоту и ширину, которую можно использовать в обычном HTML.

Если Exif-заголовок содержит сообщение об авторских правах, само сообщение может содержать 2 значения. Стандарт Exif 2.10 не описывает эту ситуацию, поэтому раздел `COMPUTED` будет содержать оба этих значения в полях `Copyright.Photographer` и `Copyright.Editor`. В то же время разделы `IFD0` будут содержать массив байтов с NULL-символом в качестве разделителя этих двух значений либо только первое значение, если тип файла определился неверно (нормальная ситуация для Exif). Раздел `COMPUTED` будет также содержать `Copyright`, который бывает либо исходной строкой, либо списком из владельца фотографии и редактора через запятую.

Тег `UserComment` содержит те же проблемы, что и Copyright. Он может хранить 2 значения. Первое — кодировку, второе — само значение. В этом случае раздел `IFD` содержит либо кодировку, либо массив байтов. Раздел `COMPUTED` будет хранить оба этих значения в полях `UserCommentEncoding` и `UserComment`. Содержимое тега `UserComment` будет доступно в любом случае, поэтому лучше использовать этот тег вместо раздела `IFD0`.

Также exif_read_data() проверяет EXIF-теги на соответствие спецификации EXIF (» http://exif.org/Exif2-2.PDF, стр. 20).

### Список параметров

`file`
  Местоположение файла с изображением. Может быть как путём к файлу, так и потоковым ресурсом (можно использовать обёртки).
`required_sections`

  Список разделённых запятой разделов, которые должны быть представлены в результирующем массиве (array). Если ни один из разделов найти не удастся, функция вернёт `false`.

  FILE | FileName, FileSize, FileDateTime, SectionsFound
  COMPUTED | html, Width, Height, IsColor, и другие. Height и Width вычисляются аналогично getimagesize(), поэтому их не обязательно включать в заголовок. `html` — текстовая строка, задающая высоту/ширину, которую можно использовать в обычном HTML.
  ANY_TAG | Любая информация заключённая в тег, например, `IFD0`, `EXIF`, ...
  IFD0 | Все данные тега IFD0. В обычных изображениях в нем хранится размер изображения.
  THUMBNAIL | Если файл содержит второй раздел `IFD`, то считается, что у изображения есть эскиз. Вся информация об эскизе хранится в этом разделе.
  COMMENT | Заголовки комментариев JPEG изображений.
  EXIF | Раздел EXIF является подразделом `IFD0`. Он содержит более детальную информацию об изображении. Большинство его записей зависят от фотоаппарата.

`as_arrays`
  Определяет, формировать ли разделы в виде массивов. Разделы `required_sections`, `COMPUTED`, `THUMBNAIL` и `COMMENT` всегда делаются массивами, так как они могут содержать значения, имена которых будут конфликтовать с именами в других разделах.
`read_thumbnail`
  Если `true`, будет прочитан сам эскиз. В противном случае будет прочитана только информация в тегах.

### Возвращаемые значения

Возвращает ассоциативный массив (array), в котором ключами будут имена заголовков, а значениями — значения соответствующие этим заголовкам. Если никаких данных вернуть нельзя, exif_read_data() вернёт `false`.

### Ошибки

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

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `required_sections` теперь допускает значение null.
7.2.0 | Параметр `file` переименовали в `stream` и принимает как локальный путь к файлу, так и потоковый ресурс.
7.2.0 | Добавили поддержку следующих форматов EXIF: Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### Примеры

Пример #1 Пример использования функции exif_read_data()

    <?php

    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "Функция не нашла данные заголовка.<br />\n" : "Изображение содержит заголовки<br />\n";

    $exif = exif_read_data('tests/test2.jpg', 0, true);
    echo "test2.jpg:<br />\n";

    foreach ($exif as $key => $section) {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }

    ?>

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

Вывод приведённого примера будет похож на:

    test1.jpg:
    Функция не нашла данные заголовка.
    test2.jpg:
    FILE.FileName: test2.jpg
    FILE.FileDateTime: 1017666176
    FILE.FileSize: 1240
    FILE.FileType: 2
    FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
    COMPUTED.html: width="1" height="1"
    COMPUTED.Height: 1
    COMPUTED.Width: 1
    COMPUTED.IsColor: 1
    COMPUTED.ByteOrderMotorola: 1
    COMPUTED.UserComment: Exif test image.
    COMPUTED.UserCommentEncoding: ASCII
    COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
    COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
    COMPUTED.Copyright.Editor: Edited by M.Boerger.
    IFD0.Copyright: Photo (c) M.Boerger
    IFD0.UserComment: ASCII
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.JPEGInterchangeFormatLength: 523
    COMMENT.0: Comment #1.
    COMMENT.1: Comment #2.
    COMMENT.2: Comment #3end
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.Thumbnail.Height: 1
    THUMBNAIL.Thumbnail.Height: 1

Пример #2 Использование функции exif_read_data() с потоковым ресурсом (доступно с PHP 7.2.0)

    <?php

    // Открываем файл в бинарном режиме
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Ошибка: Невозможно открыть файл для чтения';
        exit;
    }

    // Попытка прочитать заголовки exif
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Ошибка: невозможно прочитать заголовки exif';
        exit;
    }

    // Напечатать заголовки 'COMPUTED'
    echo 'Заголовки EXIF:' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }

    ?>

Вывод приведённого примера будет похож на:

    EXIF Headers:
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### Примечания

> Замечание: Если модуль mbstring включили, то exif будет пытаться обрабатывать Юникод и брать кодировку как указано в параметрах конфигурации exif.decode_unicode_motorola и exif.decode_unicode_intel. Модуль exif не будет пытаться определить кодировку сам, правильную кодировку для декодирования указывает пользователь путём установки одной из двух INI-директив перед вызовом функции exif_read_data().

> Замечание: Если параметр `file` указали для передачи в функцию потока, поток должен быть перематываемым. Обратите внимание, что файловый позиционный указатель не изменится после завершения работы функции.

### Смотрите также

- exif_thumbnail() - Получает встроенное превью изображения
- getimagesize() - Получает размер изображения
- Протоколы и обёртки

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — Получение имени заголовка по его индексу

### Описание

function exif_tagname(int `$index`): string|false

### Список параметров

`index`
  ID тега, имя которого требуется получить.

### Возвращаемые значения

Возвращает имя заголовка или `false`, если `index` не является ранее определённым идентификатором EXIF тега.

### Примеры

Пример #1 Пример использования exif_tagname()

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

Результат выполнения приведённого примера:

    256: ImageWidth
    257: ImageLength

### Смотрите также

- exif_imagetype() - Determine the type of an image
- » EXIF спецификация
- » EXIF теги

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — Получает встроенное превью изображения

### Описание

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() считывает встроенное превью изображения.

Если вы хотите получить эскиз посредством этой функции, вам необходимо отправить mimetype-информацию, использовав header() функцию.

Иногда exif_thumbnail() не может создать изображение, но может определить его размер. В таких случаях она возвращает `false`, но задаёт аргументам `width` и `height` правильные значения.

### Список параметров

`file`
  Местоположение файла с изображением. Может быть как путём к файлу, так и потоковым ресурсом.
`width`
  Возвращаемая ширина эскиза.
`height`
  Возвращаемая высота эскиза.
`image_type`
  Возвращаемый тип эскиза. Это либо TIFF, либо JPEG.

### Возвращаемые значения

Возвращает встроенный эскиз или `false`, если изображение не содержит эскиза.

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Параметр `file` переименован в `stream` и может принимать как локальный путь к файлу, так и потоковый ресурс.

### Примеры

Пример #1 Пример использования exif_thumbnail()

    <?php
    $image = exif_thumbnail('/path/to/image.jpg', $width, $height, $type);

    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // нет доступного превью, здесь можно обработать ошибку
        echo 'Нет доступного эскиза';
    }
    ?>

### Примечания

> Замечание: Если параметр `file` использован для передачи потока в функцию, то этот поток должен быть перематываемым. Обратите внимание, что файловый позиционный указатель не будет изменён после завершения работы этой функции.

### Смотрите также

- exif_read_data() - Читает заголовки EXIF из файлов изображений
- image_type_to_mime_type() - Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — Псевдоним exif_read_data()

Внимание

Начиная с PHP 7.2.0 псевдоним УСТАРЕЛ, а в PHP 8.0.0 псевдоним УДАЛИЛИ.

### Описание

Псевдоним функции exif_read_data().

### Список изменений

Версия | Описание
--- | ---
7.2.0 | Этот псевдоним был объявлен устаревшим.

## Содержание

- exif_imagetype — Determine the type of an image
- exif_read_data — Читает заголовки EXIF из файлов изображений
- exif_tagname — Получение имени заголовка по его индексу
- exif_thumbnail — Получает встроенное превью изображения
- read_exif_data — Псевдоним exif_read_data

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
- Предопределённые константы
- Exif Функции
  - exif_imagetype — Determine the type of an image
  - exif_read_data — Читает заголовки EXIF из файлов изображений
  - exif_tagname — Получение имени заголовка по его индексу
  - exif_thumbnail — Получает встроенное превью изображения
  - read_exif_data — Псевдоним exif_read_data

# Обработка изображений и модуль GD

# Введение

PHP не ограничен созданием только HTML-страничек. Он также позволяет создавать и работать с файлами изображений в различных форматах, включая GIF, PNG, JPEG, WBMP, и XPM. Что ещё удобнее, PHP разрешает выводить изображение в потоке непосредственно в браузер. Для этого необходимо скомпилировать PHP с графическим модулем GD, который содержит функции для работы с изображениями. Для работы с модулем GD могут потребоваться другие модули (в зависимости от формата изображений, с которыми потребовалось работать).

Функции работы с изображениями в PHP помогают получать размер изображений следующих форматов: JPEG, GIF, PNG, SWF, TIFF и JPEG2000.

С модулем EXIF доступна работа с информацией, которуюх хранят заголовки JPEG- и TIFF-изображений. Таким способом читают метаданные, которые сгенерировали цифровые фотокамеры. Модуль EXIF не требуется библиотеке GD.

> Замечание: Раздел требований рассказывает, как расширить возможности чтения, записи и модификации изображений. Чтобы читать метаданные изображений с цифровых фотокамер, необходим уже упомянутый модуль EXIF.

> Замечание: Функция getimagesize() работает без модуля GD.

Предостережение

Тогда как поставляемая с PHP версия модуля GD использует менеджер памяти Zend для распределения памяти, системная версия этого не делает, поэтому директива memory_limit не учитывается.

Модуль GD поддерживает ряд форматов. Ниже приводится список этих форматов и пометки о доступности, включая поддержку чтения и записи.

Форматы, которые поддерживает модуль GD
Формат | Поддержка чтения | Поддержка записи | Примечания
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | Доступен с PHP 7.2.0

Несмотря на открытость доступа к чтению и записи большей части форматов в приведённой таблице, это не означает, что PHP собрали с поддержкой этих форматов. Чтобы узнать, какие форматы включили для модуля GD при сборке, пользуются функцией gd_info(). Дополнительную информацию даёт раздел об установке.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения
- Типы ресурсов

## Требования

Через модуль GD (доступ к скачиванию даёт страница » http://www.libgd.org/) создают и изменяют изображения.

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

> Замечание: Требуется libgd-2.1.0 или выше. Как альтернативой пользуются модулем GD, который входит в дистрибутив PHP.

> Замечание: Для работы модуля GD требуется модуль zlib >= 1.2.0.4.

Иногда требуется усовершенствовать функции модуля GD для работы с бо́льшим количеством графических форматов.

Форматы изображений, которые поддерживает модуль GD
Формат изображения | Необходимая библиотека | Замечания
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | При сборке библиотеки jpeg (перед сборкой PHP) необходимо использовать опцию --enable-shared на этапе конфигурирования. Если этого не сделать, на этапе конфигурирования PHP-сборки выдаётся ошибка `libjpeg.(a|so) not found`.
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Скорее всего, система уже содержит библиотеку, если раньше в систему установили окружение X-Environment.
`webp` |  |

Иногда требуется усовершенствовать функции модуля GD для работы с бо́льшим набором шрифтов. PHP поддерживает библиотеку » FreeType 2.

## Установка

Для поддержки модуля GD необходимо сконфигурировать PHP с опцией --with-gd[=DIR], где DIR — директория установки GD. Чтобы использовать рекомендованную разработчиками встроенную версию библиотеки GD, указывают опцию конфигурации --with-gd. Библиотека GD требует наличия библиотек libpng и libjpeg для компиляции. С PHP 7.4.0 опция --with-gd становится --enable-gd (нужно ли вообще включать модуль) и --with-external-gd (чтобы выбрать внешнюю библиотеку libgd, а не встроенную).

В Windows-системах необходимо включить DLL-библиотеку модуля GD php_gd.dll в файле php.ini. До PHP 8.0.0 DLL-файл назывался php_gd2.dll.

Модуль GD усовершенствуют во время конфигурации PHP через опцию `--with-XXXX` для работы с бо́льшим количеством графических форматов.

Поддерживаемые форматы изображений
Формат изображения | Опция при конфигурировании
--- | ---
`avif` | Поддержку формата avif включает опция --with-avif. Доступ к опции открыли в PHP 8.1.0.
`jpeg` | Формата jpeg — --with-jpeg-dir=DIR. Включая поддержку Jpeg 6b, 7 или 8. В PHP 7.4.0 опцию изменили на --with-jpeg.
`png` | Формат png — --with-png-dir=DIR. Внимание, модулю libpng требуется модуль zlib, поэтому при конфигурации добавляют опцию --with-zlib-dir[=DIR]. С PHP 7.4.0 опции --with-png-dir и --with-zlib-dir удалили. Теперь модули libpng и zlib обязательны.
`xpm` | Формат xpm — --with-xpm-dir=DIR. Если во время конфигурации не удаётся найти необходимую библиотеку, указывают путь к модулю X11. В PHP 7.4.0 опцию заменили на --with-xpm.
`webp` | Формат webp — --with-webp-dir=DIR.

> Замечание: При компиляции PHP с модулем libpng требуется указать ту же версию libpng, с которой собрали модуль GD.

Модуль GD усовершенствуют во время конфигурирования PHP через опцию `--with-XXXX` для работы с бо́льшим количеством шрифтов.

Поддерживаемые библиотеки шрифтов
Библиотека шрифтов | Опция при конфигурировании
--- | ---
`FreeType 2` | Поддержку шрифта FreeType 2 включает опция --with-freetype-dir=DIR. С PHP 7.4.0 вместо этого указывают опцию --with-freetype, которая зависит от команды pkg-config.
`Собственная строковая функция шрифтов в формате TrueType` | Поддержку собственной строковой функции для шрифтов в формате TrueType включает опция --enable-gd-native-ttf. (Опция не действует, её удалили в PHP 7.2.0.)

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки изображения
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`gd.jpeg_ignore_warning` bool

  Игнорировать предупреждения (но не ошибки), которые сгенерировала библиотека libjpeg(-turbo).

Список изменений опции `gd.jpeg_ignore_warning`
Версия | Описание
--- | ---
7.1.0 | Значение по умолчанию опции gd.jpeg_ignore_warning изменили с 0 на 1.

Смотрите также директивы настройки модуля exif.

Внимание

Функции для работы с изображениями требовательны к памяти. Убедитесь, что значение опции memory_limit достаточно, если работаете со встроенным модулем GD.

## Типы ресурсов

Модуль определяет следующие типы ресурсов:

Список типов ресурсов в модуле GD
Имя | Описание | Замечания
--- | --- | ---
`gd` | Ресурс изображения, с которым работают функции наподобие imagecreatefrompng(). | До PHP 8.0.0.
`gd font` | Ресурс шрифта, который внутренне создаёт функция imageloadfont(). | До PHP 8.1.0.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

`GD_VERSION` (string)
  Версия модуля GD, с которой скомпилировали PHP.
`GD_MAJOR_VERSION` (int)
  Полнофункциональная версия модуля GD, с которой скомпилировали PHP.
`GD_MINOR_VERSION` (int)
  Сокращённая версия модуля GD, с которой скомпилировали PHP.
`GD_RELEASE_VERSION` (int)
  Рабочая версия модуля GD, с которой скомпилировали PHP.
`GD_EXTRA_VERSION` (string)
  Дополнительная (beta/rc..) версия модуля GD, с которой скомпилировали PHP.
`GD_BUNDLED` (int)
  Если используется распространяемая с PHP версия модуля GD, константа принимает значение 1, иначе 0.
`IMG_AVIF` (int)
  Возвращается как значение функции imagetypes(). (Доступно с PHP 8.1.0)
`IMG_BMP` (int)
  Возвращается как значение функции imagetypes().
`IMG_GIF` (int)
  Возвращается как значение функции imagetypes().
`IMG_JPG` (int)
  Возвращается как значение функции imagetypes().
`IMG_JPEG` (int)
  Возвращается как значение функции imagetypes().

  > Замечание:

  > Значение этой константы равно значению константы `IMG_JPG`

`IMG_PNG` (int)
  Возвращается как значение функции imagetypes().
`IMG_TGA` (int)
  Возвращается как значение функции imagetypes(). (Доступно с PHP 7.4.0)
`IMG_WBMP` (int)
  Возвращается как значение функции imagetypes().
`IMG_XPM` (int)
  Возвращается как значение функции imagetypes().
`IMG_WEBP` (int)
  Возвращается как значение функции imagetypes(). (Доступно с PHP 7.0.10)
`IMG_WEBP_LOSSLESS` (int)
  (Доступно с PHP 8.1.0)
`IMG_COLOR_TILED` (int)
  Специальный вариант цвета для замены цвета, который определили функциями imagecolorallocate() и imagecolorallocatealpha().
`IMG_COLOR_STYLED` (int)
  Специальный вариант цвета для замены цвета, который определили функциями imagecolorallocate() и imagecolorallocatealpha().
`IMG_COLOR_BRUSHED` (int)
  Специальный вариант цвета для замены цвета, который определили функциями imagecolorallocate() и imagecolorallocatealpha().
`IMG_COLOR_STYLEDBRUSHED` (int)
  Специальный вариант цвета для замены цвета, который определили функциями imagecolorallocate() и imagecolorallocatealpha().
`IMG_COLOR_TRANSPARENT` (int)
  Специальный вариант цвета для замены цвета, который определили функциями imagecolorallocate() и imagecolorallocatealpha().
`IMG_AFFINE_TRANSLATE` (int)
  Константа типа аффинного преобразования; константу указывают как значение аргумента функции imageaffinematrixget() .
`IMG_AFFINE_SCALE` (int)
  Константа типа аффинного преобразования; константу указывают как значение аргумента функции imageaffinematrixget() .
`IMG_AFFINE_ROTATE` (int)
  Константа типа аффинного преобразования; константу указывают как значение аргумента функции imageaffinematrixget() .
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  Константа типа аффинного преобразования; константу указывают как значение аргумента функции imageaffinematrixget() .
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  Константа типа аффинного преобразования; константу указывают как значение аргумента функции imageaffinematrixget() .
`IMG_ARC_ROUNDED` (int)
  Константа стиля, константу указывают как значение аргумента функции imagefilledarc().

  > Замечание:

  > Значение этой константы равно значению константы `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  Константа стиля, константу указывают как значение аргумента функции imagefilledarc().
`IMG_ARC_CHORD` (int)
  Константа стиля, константу указывают как значение аргумента функции imagefilledarc().
`IMG_ARC_NOFILL` (int)
  Константа стиля, константу указывают как значение аргумента функции imagefilledarc().
`IMG_ARC_EDGED` (int)
  Константа стиля, константу указывают как значение аргумента функции imagefilledarc().
`IMG_GD2_RAW` (int)
  Константа типа, константу указывают как значение аргумента функции imagegd2().
`IMG_GD2_COMPRESSED` (int)
  Константа типа, константу указывают как значение аргумента функции imagegd2().
`IMG_EFFECT_REPLACE` (int)
  Эффект альфа-смешения, константу указывают как значение аргумента функции imagelayereffect().
`IMG_EFFECT_ALPHABLEND` (int)
  Эффект альфа-смешения, константу указывают как значение аргумента функции imagelayereffect().
`IMG_EFFECT_NORMAL` (int)
  Эффект альфа-смешения, константу указывают как значение аргумента функции imagelayereffect().
`IMG_EFFECT_OVERLAY` (int)
  Эффект альфа-смешения, константу указывают как значение аргумента функции imagelayereffect().
`IMG_EFFECT_MULTIPLY` (int)
  Эффект альфа-смешения, константу указывают как значение аргумента функции imagelayereffect().
`IMG_FILTER_NEGATE` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_GRAYSCALE` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_BRIGHTNESS` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_CONTRAST` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_COLORIZE` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_EDGEDETECT` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_EMBOSS` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_MEAN_REMOVAL` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_SMOOTH` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_PIXELATE` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter().
`IMG_FILTER_SCATTER` (int)
  Специальный фильтр GD, константу указывают как значение аргумента функции imagefilter(). (Доступна с PHP 7.4.0)
`IMAGETYPE_GIF` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JPEG` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JPEG2000` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_PNG` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_SWF` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_PSD` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_BMP` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_WBMP` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_XBM` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_TIFF_II` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_TIFF_MM` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_IFF` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JB2` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JPC` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JP2` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_JPX` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_SWC` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_ICO` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_WEBP` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension(). (Доступно с PHP 7.1.0)
`IMAGETYPE_AVIF` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension(). (Доступно с PHP 8.1.0)
`IMAGETYPE_HEIF` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension(). (Доступно с PHP 8.5.0)
`IMAGETYPE_UNKNOWN` (int)
  Константа типа изображения, константу указывают как значение аргумента функций image_type_to_mime_type() и image_type_to_extension().
`IMAGETYPE_COUNT` (int)
  Количество констант типа изображения (включая тип unknown), которые поддерживают функции image_type_to_mime_type() и image_type_to_extension()
`PNG_NO_FILTER` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_FILTER_NONE` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_FILTER_SUB` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_FILTER_UP` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_FILTER_AVG` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_FILTER_PAETH` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`PNG_ALL_FILTERS` (int)
  Специальный фильтр PNG filter, константу указывают как значение аргумента функции imagepng().
`IMG_FLIP_VERTICAL` (int)
  Константу указывают как значение аргумента функции imageflip(), доступна с PHP 5.5.0.
`IMG_FLIP_HORIZONTAL` (int)
  Константу указывают как значение аргумента функции imageflip(), доступна с PHP 5.5.0.
`IMG_FLIP_BOTH` (int)
  Константу указывают как значение аргумента функции imageflip(), доступна с PHP 5.5.0.
`IMG_BELL` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BESSEL` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BILINEAR_FIXED` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BICUBIC_FIXED` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BICUBIC` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BLACKMAN` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BOX` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_BSPLINE` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_CATMULLROM` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_GAUSSIAN` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_GENERALIZED_CUBIC` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_HERMITE` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_HAMMING` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_HANNING` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_MITCHELL` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_POWER` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_QUADRATIC` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_SINC` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_NEAREST_NEIGHBOUR` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_WEIGHTED4` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_TRIANGLE` (int)
  Константу указывают как значение аргумента функции imagesetinterpolation(), доступна с PHP 5.5.0.
`IMG_CROP_BLACK` (int)
  Обрезает чёрный фон.
`IMG_CROP_DEFAULT` (int)
  То же, что `IMG_CROP_TRANSPARENT`. До PHP 7.4.0 встроенная библиотека libgd возвращалась к `IMG_CROP_SIDES`, если у изображения не было прозрачного цвета.
`IMG_CROP_SIDES` (int)
  Использует 4 угла изображения, чтобы попытаться обнаружить фон для обрезки.
`IMG_CROP_THRESHOLD` (int)
  Обрезает изображение по заданным параметрам `threshold` и `color`.
`IMG_CROP_TRANSPARENT` (int)
  Обрезает прозрачный фон.
`IMG_CROP_WHITE` (int)
  Обрезает белый фон.

# Примеры

## Содержание

- Создаёт PNG-изображение средствами PHP
- Добавление водяных знаков на изображения через альфа-каналы
- Создание полупрозрачного водяного знака функцией imagecopymerge

## Создаёт PNG-изображение средствами PHP

Пример #1 Пример создания изображения в формате PNG средствами PHP

    <?php

    header("Content-type: image/png");
    $string = $_GET['text'];
    $im     = imagecreatefrompng("images/button1.png");
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
    imagestring($im, 3, $px, 9, $string, $orange);
    imagepng($im);

    ?>

Этот пример можно было бы вызвать на странице с тегом: `<img src="button.php?text=text">`. Приведённый скрипт button.php возьмёт строку `"text"`, наложит её поверх базового изображения `"images/button1.png"` и выведет конечное изображение. Это удобный способ не создавать новую кнопку каждый раз, когда требуется изменить текст кнопки. Этот метод генерирует кнопку динамически.

## Добавление водяных знаков на изображения через альфа-каналы

Пример #1 Добавление водяных знаков на изображения через альфа-каналы

    <?php

    // Загрузка штампа и фото, для которого применяется водяной знак (называется штамп или печать)
    $stamp = imagecreatefrompng('stamp.png');
    $im = imagecreatefromjpeg('photo.jpeg');

    // Установка полей для штампа и получение высоты/ширины штампа
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Копирование изображения штампа на фотографию путём смещения края
    // и ширины фотографии для расчёта позиционирования штампа.
    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // Вывод изображения
    header('Content-type: image/png');
    imagepng($im);

    ?>

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

## Создание полупрозрачного водяного знака функцией imagecopymerge()

Пример #1 Пример создания полупрозрачного водяного знака функцией imagecopymerge()

    <?php

    // Загрузка штампа и фото, для которого применяется водяной знак (называется штамп или печать)
    $im = imagecreatefromjpeg('photo.jpeg');

    // Сначала создаём изображение штампа вручную через модуль GD
    $stamp = imagecreatetruecolor(100, 70);
    imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
    imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
    imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
    imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

    // Установка полей для штампа и получение высоты/ширины штампа
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Слияние штампа с фотографией. Прозрачность 50 %
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // Сохранение изображения в файл
    imagepng($im, 'photo_stamp.png');

    ?>

В примере функция imagecopymerge() объединяет штамп с исходным изображением. Так устанавливают прозрачность штампа — в примере установили прозрачность на уровне 50 % непрозрачности (opacity). На практике это принесло бы пользу для защиты авторских прав, поскольку полупрозрачные водяные знаки трудно удалить, но при этом изображения видны зрителям.

# Функции GD и функции для работы с изображениями

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — Вывод информации о текущей установленной GD библиотеке

### Описание

function gd_info(): array

Получает информацию о версии и возможностях установленной GD библиотеки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив.

Элементы массива, возвращаемого из gd_info()
Атрибут | Смысловое значение
--- | ---
GD Version | Строка (string), содержащая версию `libgd`.
FreeType Support | bool значение. `true`, если компонент FreeType Support установлен.
FreeType Linkage | Строка (string), содержащая описание, каким образом подключён компонент FreeType. Ожидаемые значения: 'with freetype', 'with TTF library', и 'with unknown library'. Этот элемент будет определён, только если `FreeType Support` имеет значение `true`.
GIF Read Support | bool значение. `true`, если включена поддержка чтения (reading) `GIF` изображений.
GIF Create Support | bool значение. `true`, если включена поддержка записи (creating) `GIF` изображений.
JPEG Support | bool значение. `true`, если включена поддержка `JPEG`.
PNG Support | bool значение. `true`, если включена поддержка `PNG`.
WBMP Support | bool значение. `true`, если включена поддержка `WBMP`.
XBM Support | bool значение. `true`, если включена поддержка `XBM`.
WebP Support | bool значение. `true`, если включена поддержка `WebP`.
AVIF Support | bool значение. `true`, если включена поддержка `AVIF`. Доступно, начиная с PHP 8.1.0.

### Примеры

Пример #1 Пример использования gd_info()

    <?php
    var_dump(gd_info());
    ?>

Вывод приведённого примера будет похож на:

    array(10) {
      ["GD Version"]=>
      string(24) "bundled (2.1.0 compatible)"
      ["FreeType Support"]=>
      bool(false)
      ["GIF Read Support"]=>
      bool(true)
      ["GIF Create Support"]=>
      bool(false)
      ["JPEG Support"]=>
      bool(false)
      ["PNG Support"]=>
      bool(true)
      ["WBMP Support"]=>
      bool(true)
      ["XBM Support"]=>
      bool(false)
      ["WebP Support"]=>
      bool(false)
      ["AVIF Support"]=>
      bool(false)
    }

### Смотрите также

- imagepng() - Выводит PNG-изображение в браузер или файл
- imagejpeg() - Выводит изображение в браузер или записывает в файл
- imagegif() - Выводит изображение в браузер или записывает в файл
- imagewbmp() - Выводит изображение в браузер или записывает в файл
- imagewebp() - Вывод WebP-изображение в браузер или файл
- imageavif() - Выводит изображение в браузер или записывает в файл
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой

# getimagesize

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

getimagesize — Получает размер изображения

### Описание

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

Функция getimagesize() определяет размер поддерживаемого графического файла и возвращает размеры изображения, тип файла и текстовую строку `height/width`, которые указывают в атрибутах HTML-тега `IMG` и в HTTP-заголовках типа содержимого.

Функция getimagesize() также умеет возвращать дополнительные сведения об изображении в параметре `image_info`.

Предостережение

Функция ожидает, что путь к файлу в аргументе `filename` указывает на корректный файл изображения. При передаче пути не на файл изображения функция иногда неправильно определяет файл как изображение и успешно возвращает результат, но но массив содержит бессмысленные значения.

Функцией getimagesize() не проверяют, представляет ли собой файл допустимое изображение. Для проверки графических файлов пользуются решениями наподобие модуля Fileinfo, которые разработали для таких целей.

> Замечание: Обратите внимание, отдельные части JPC- и JP2-изображений часто содержат компоненты с разной глубиной цвета, тогда элемент "bits" содержит максимальное значение, которое обнаружила функция. Файлы в формате JP2 также иногда содержат множественные кодовые потоки `multiple JPEG 2000 codestreams`, тогда функция getimagesize() вернёт значения первого потока кода, который обнаружит в корне файла.

> Замечание: Сведения об иконках извлекаются из иконки с наибольшим битрейтом.

> Замечание: Изображения в формате GIF состоят из одного или нескольких кадров, где каждый кадр иногда занимает только часть изображения. Размер изображения, который возвращается функцией getimagesize(), указывает общий размер, который функция считала из дескриптора логического экрана.

### Список параметров

`filename`

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

`image_info`

  Необязательный параметр заполняется дополнительной информацией, которую модуль извлекает из файла изображения. В текущей реализации доступно извлечение APP-маркеров JPG-изображений в виде ассоциативного массива. Отдельные программы через эти APP-маркеры встраивают текст в изображение. Чаще остальных встраивают » IPTC-сведения в APP13-маркер. Для преобразования двоичных данных APP13-маркера во что-то удобное для чтения вызывают функцию iptcparse().

  > Замечание:

  > Параметр `image_info` поддерживает только файлы в формате JFIF.

### Возвращаемые значения

Функция возвращает массив из 7 элементов. Не каждый тип изображения содержит элементы с каналами `channels` и битрейтом `bits`.

Индексы 0 и 1 содержат ширину и высоту изображения.

> Замечание:

> Отдельные форматы файлов хранят набор изображений или вообще не содержат изображений. Для таких форматов функцией getimagesize() невозможно определить размер изображения. Функция getimagesize() вернёт нули как значения высоты и ширины.

> Замечание: Функция getimagesize() не учитывает метаданные изображения, поэтому когда, например, значения Exif-флага `Orientation` поворачивают изображение на 90 или 270 градусов, индексы 0 и 1 меняются местами: индекс 0 содержит высоту, а индекс 1 — ширину.

Индекс 2 содержит константу семейства `IMAGETYPE_*`, которая обозначает тип изображения.

Индекс 3 содержит строку со значениями ширины и высоты изображения `height="yyy" width="xxx"`, которые указывают в атрибутах тега IMG.

`mime` — MIME-тип, который соответствует изображению. Эти сведения помогают корректно обрабатывать изображения на основании заголовка `Content-Type`:

Пример #1 Функция getimagesize() и MIME-типы

    <?php

    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");

    if ($size && $fp) {
        header("Content-Type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // Ошибка
    }

Элемент `channels` принимает значение 3 для RGB-картинок и 4 для цветовой модели CMYK.

`bits` — количество битов для каждого цвета.

Для отдельных типов изображений присутствие значений `channels` и `bits` иногда сбивает с толку. Формат GIF, например, представляет каждый пиксель 3-канальным цветом, но количество битов для хранения каждого пикселя невозможно однозначно вычислить для анимированных GIF-изображений, если опираться на глобальную таблицу цветов, поскольку кадры анимированного изображения часто содержит локальную палитру цветов.

Функция вернёт `false`, если возникнет ошибка.

### Ошибки

При недоступности файла по пути `filename` функция getimagesize() выдаёт ошибку уровня `E_WARNING`. При ошибке чтения файла функция getimagesize() выдаёт ошибку уровня `E_NOTICE`.

С PHP 8.0.0 при передаче в параметр `filename` пустой строки выбрасывается ошибка ValueError.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Функция теперь возвращает фактические размеры, биты и каналы изображений в формате AVIF; раньше размеры сообщались как `0x0`, а биты и каналы не сообщались вообще.
8.0.0 | Функция теперь выбрасывает ошибку ValueError, если в параметр `filename` передали пустую строку; раньше выдавалась ошибка уровня `E_WARNING`, и функция возвращала значение `false`.
7.1.0 | Добавили поддержку формата WebP.

### Примеры

Пример #2 Пример получения размера изображения функцией getimagesize()

    <?php

    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"пример getimagesize()\" />";

Пример #3 Пример получения размера изображения по URL-адресу функцией getimagesize

    <?php

    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // Названия файлов с пробелами требуется правильно кодировать
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

Пример #4 Пример возврата IPTC-метаданных функцией getimagesize()

    <?php

    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }

### Примечания

> Замечание: Этой функции не требуется библиотека GD.

### Смотрите также

- image_type_to_mime_type() - Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- exif_imagetype() - Determine the type of an image
- exif_read_data() - Читает заголовки EXIF из файлов изображений
- exif_thumbnail() - Получает встроенное превью изображения
- imagesx() - Получение ширины изображения
- imagesy() - Получение высоты изображения

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — Получение размера изображения из строки данных

### Описание

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

Функция работает идентично функции getimagesize() с той разницей, что getimagesizefromstring() принимает данные изображения в виде строки в качестве первого аргумента вместо имени файла.

Для уточнения, как функция работает, обращайтесь к документации к функции getimagesize().

### Список параметров

`string`

  Данные изображения в виде строки.

`image_info`

  Смотрите getimagesize().

### Возвращаемые значения

Смотрите getimagesize().

### Примеры

Пример #1 Пример использования getimagesizefromstring()

    <?php
    $img = '/path/to/test.png';

    // Открыть как файл
    $size_info1 = getimagesize($img);

    // Открыть как строку
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### Смотрите также

- getimagesize() - Получает размер изображения

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — Получает расширение файла для типа изображения

### Описание

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

Функция возвращает расширение файла для константы семейства `IMAGETYPE_*`.

### Список параметров

`image_type`

  Константа семейства `IMAGETYPE_*`.

`include_dot`

  Добавлять ли точку к расширению. Значение по умолчанию равняется `true`.

### Возвращаемые значения

Функция возвращает строку с расширением файла, которое соответствует типу изображения, или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример получения расширения файла для типа изображения функцией image_type_to_extension()

    <?php

    // Создаём изображение
    $im = imagecreatetruecolor(100, 100);

    // Сохраняем изображение
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));

    ?>

### Примечания

> Замечание: Этой функции не требуется библиотека GD.

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

### Описание

function image_type_to_mime_type(int `$image_type`): string

Функция image_type_to_mime_type() определяет Mime-тип для константы IMAGETYPE.

### Список параметров

`image_type`

  Одна из констант `IMAGETYPE_*`.

### Возвращаемые значения

Возвращаемые значения приведены ниже

Возвращаемые значения и Константы
`image_type` | Возвращаемое значение
--- | ---
`IMAGETYPE_GIF` | `image/gif`
`IMAGETYPE_JPEG` | `image/jpeg`
`IMAGETYPE_PNG` | `image/png`
`IMAGETYPE_SWF` | `application/x-shockwave-flash`
`IMAGETYPE_PSD` | `image/psd`
`IMAGETYPE_BMP` | `image/bmp`
`IMAGETYPE_TIFF_II` (порядок байт intel) | `image/tiff`
`IMAGETYPE_TIFF_MM` (порядок байт motorola) | `image/tiff`
`IMAGETYPE_JPC` | `application/octet-stream`
`IMAGETYPE_JP2` | `image/jp2`
`IMAGETYPE_JPX` | `application/octet-stream`
`IMAGETYPE_JB2` | `application/octet-stream`
`IMAGETYPE_SWC` | `application/x-shockwave-flash`
`IMAGETYPE_IFF` | `image/iff`
`IMAGETYPE_WBMP` | `image/vnd.wap.wbmp`
`IMAGETYPE_XBM` | `image/xbm`
`IMAGETYPE_ICO` | `image/vnd.microsoft.icon`
`IMAGETYPE_WEBP` | `image/webp`
`IMAGETYPE_AVIF` | `image/avif`
`IMAGETYPE_HEIF` | `image/heif`

### Примеры

Пример #1 Пример использования image_type_to_mime_type()

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### Примечания

> Замечание: Этой функции не требуется библиотека GD.

### Смотрите также

- getimagesize() - Получает размер изображения
- exif_imagetype() - Determine the type of an image
- exif_read_data() - Читает заголовки EXIF из файлов изображений
- exif_thumbnail() - Получает встроенное превью изображения

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — Выводит изображение в браузер или записывает в файл

Внимание

Начиная с PHP 7.3.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

Функция image2wbmp() выводит или сохраняет WBMP-версию изображения `image`.

### Список параметров

`image`

  Ресурс изображения, который вернула функция создания изображения наподобие imagecreatetruecolor().

`filename`

  Путь для сохранения файла. Без установки параметра функция выведет исходные данные изображения напрямую в поток вывода.

`foreground`

  Через этот параметр устанавливают цвет переднего плана путём установки идентификатора, который получили функцией imagecolorallocate(). Цвет переднего плана по умолчанию чёрный.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Примеры

Пример #1 Пример использования image2wbmp()

    <?php

    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // Вывод потока

    ?>

### Смотрите также

- imagewbmp() - Выводит изображение в браузер или записывает в файл

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — Вернуть изображение, содержащее аффинно-преобразованное изображение src, используя дополнительную область ограничения

### Описание

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`affine`

  Массив с ключами от 0 до 5.

`clip`

  Массив с ключами "x", "y", "width" и "height"; или `null`.

### Возвращаемые значения

Возвращает объект с аффинным изображением в случае успешного выполнения или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | `clip` теперь допускает значение null.
8.0.0 | В случае успешного выполнения функция теперь возвращает экземпляр GDImage; ранее возвращался ресурс (resource).

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Конкатенирует две аффинные матрицы преобразования

### Описание

function imageaffinematrixconcat(array `$matrix1`, array `$matrix2`): array|false

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

### Список параметров

`matrix1`

  Аффинная матрица преобразования (массив с ключами от `0` до `5` и значениями с плавающей точкой).

`matrix2`

  Аффинная матрица преобразования (массив с ключами от `0` до `5` и значениями с плавающей точкой).

### Возвращаемые значения

Аффинная матрица преобразования (массив с ключами от `0` до `5` и значениями с плавающей точкой) или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования imageaffinematrixconcat()

    <?php
    $m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    $m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
    $matrix = imageaffinematrixconcat($m1, $m2);
    print_r($matrix);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### Смотрите также

- imageaffine() - Вернуть изображение, содержащее аффинно-преобразованное изображение src, используя дополнительную область ограничения
- imageaffinematrixget() - Получает матрицу аффинного преобразования

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Получает матрицу аффинного преобразования

### Описание

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Возвращает матрицу аффинного преобразования.

### Список параметров

`type`

  Одна из констант `IMG_AFFINE_*`.

`options`

  Если `type` равен `IMG_AFFINE_TRANSLATE` или `IMG_AFFINE_SCALE`, `options` должен быть массивом (array) с ключами `x` и `y`, оба имеют значения типа float.

  Если `type` равен `IMG_AFFINE_ROTATE`, `IMG_AFFINE_SHEAR_HORIZONTAL` или `IMG_AFFINE_SHEAR_VERTICAL`, `options` должен быть числом с плавающей точкой (float), определяющим угол.

### Возвращаемые значения

Матрица аффинного преобразования (массив с ключами от `0` до `5` и значениями с плавающей точкой) или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования imageaffinematrixget()

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### Смотрите также

- imageaffine() - Вернуть изображение, содержащее аффинно-преобразованное изображение src, используя дополнительную область ограничения
- imageaffinematrixconcat() - Конкатенирует две аффинные матрицы преобразования

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — Устанавливает режим сопряжения цветов для изображения

### Описание

function imagealphablending(GdImage `$image`, bool `$enable`): true

Функция imagealphablending() устанавливает режим сопряжения цветов для truecolor-изображений при рисовании. В режиме сопряжения альфа-компонент цвета, который передаётся функциям рисования наподобие imagesetpixel(), определяет силу просачивания цвета нижележащего слоя через накладываемое изображение. В результате, модуль gd автоматически сопрягает текущий цвет в каждой точке с цветом рисуемого поверх изображения и сохраняет результат сопряжения в изображении. Сопряжённые пиксели не сохраняют прозрачность. В режиме без сопряжения цвет рисуемого поверх изображения пикселя буквально копируется вместе со своим альфа-компонентом, заменяя пиксель в исходном изображении. Режим сопряжения недоступен при рисовании на палитровых изображениях.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`enable`

  Указывает, включать ли режим сопряжения. Включён (`true`) по умолчанию для truecolor-изображений, для остальных по умолчанию выключен (`false`).

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример установки режима сопряжения цветов функцией imagealphablending()

    <?php

    // Создаём изображение
    $im = imagecreatetruecolor(100, 100);

    // Включаем режим сопряжения цветов
    imagealphablending($im, true);

    // Рисуем прямоугольник
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // Устанавливаем заголовок с MIME-типом изображения
    header('Content-Type: image/png');

    imagepng($im);

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — Определяет, применять ли функции сглаживания

### Описание

function imageantialias(GdImage `$image`, bool `$enable`): true

Функция задействует механизмы сглаживания при рисовании линий и замкнутых многоугольников. Функция не поддерживает альфа-компоненты, выполняет операции прямого смешивания цветов и работает только с полноцветными truecolor-изображениями.

Для сглаженных примитивов стили и толщина не поддерживаются.

Сглаженные примитивы совместно с прозрачным фоном иногда дают неожиданный результат. Метод смешивания обрабатывает цвет фона наравне с другими цветами. Отсутствие поддержки альфа-компонента не даёт применять метод сглаживания на основе альфа-канала.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`enable`

  Параметр определяет, включать ли сглаживание.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
7.2.0 | Функция imageantialias() теперь доступна и при сборке PHP с системной библиотекой GD; раньше требовалось компилировать PHP только с библиотекой, которая входит в комплект исходных файлов интерпретатора.

### Примеры

Пример #1 Пример сравнения сглаженной и несглаженной линий

    <?php

    // Создаём два изображения
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // Включаем сглаживание для одного изображения
    imageantialias($aa, true);

    // Устанавливаем цвета
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // Рисуем линии
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // Объединяем два изображения для вывода: слева — со сглаживанием, справа — без
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // Устанавливаем заголовок с MIME-типом изображения
    header('Content-type: image/png');

    imagepng($aa);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение

# imagearc

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

imagearc — Рисует дугу

### Описание

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

Функция imagearc() рисует дугу окружности с заданными координатами центра.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`center_x`

  Координата центра по оси x.

`center_y`

  Координата центра по оси y.

`width`

  Ширина дуги.

`height`

  Высота дуги.

`start_angle`

  Угол начала дуги в градусах.

`end_angle`

  Угол окончания дуги в градусах. 0° соответствует положению 3 часа, дуга рисуется по часовой стрелке.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования окружности функцией imagearc()

    <?php

    // Создаём изображение 200 на 200 пикселей
    $img = imagecreatetruecolor(200, 200);

    // Создаём набор цветов
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // Рисуем голову
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);

    // Рот
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);

    // Глаза
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header("Content-type: image/png");
    imagepng($img);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagefilledarc() - Рисует и заливает дугу
- imageellipse() - Рисует эллипс
- imagefilledellipse() - Рисует эллипс с заливкой

# imageavif

(PHP 8 >= 8.1.0)

imageavif — Выводит изображение в браузер или записывает в файл

### Описание

function imageavif(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$speed` = -1
): bool

Функция выводит или сохраняет растровое изображение в формате AVIF, которое указали в параметре `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

`quality`

  Необязательный параметр `quality` варьируется в диапазоне от 0 (худшее качество, файл меньшего размера) до 100 (лучшее качество, файл большего размера). При передаче значения `-1` для параметра устанавливается значение по умолчанию: `52`.

`speed`

  Необязательный параметр `speed` варьируется в диапазоне от 0 (медленнее, файл меньшего размера) до 10 (быстрее, файл большего размера). При передаче значения `-1` для параметра устанавливается значение по умолчанию: `6`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `quality` или `speed` недопустимо.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError при недопустимом значении в параметре `quality` или `speed`.

### Смотрите также

- imagepng() - Выводит PNG-изображение в браузер или файл
- imagewbmp() - Выводит изображение в браузер или записывает в файл
- imagejpeg() - Выводит изображение в браузер или записывает в файл
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Выводит BMP-изображение в браузер или файл

### Описание

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Функция выводит или сохраняет BMP-версию изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

  > Замечание:

  > `null` недействителен, если аргумент `compressed` не используется.

`compressed`

  Сжимать ли BMP-файл с кодировкой длин серий (RLE).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Параметр `compressed` теперь принадлежит логическому значению bool; раньше параметр был целым числом (int).

### Примеры

Пример #1 Сохранение BMP-файла

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'BMP with PHP', $text_color);

    // Сохраняем изображение
    imagebmp($im, 'php.bmp');

    ?>

# imagechar

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

imagechar — Рисует символ по горизонтали

### Описание

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Функция imagechar() рисует первый символ аргумента `char` на изображении с идентификатором `image` с координатами `x` и `y` цветом `color`. Координаты отсчитываются с левого верхнего угла.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().
`x`

  Координата начала рисования по оси x.

`y`

  Координата начала рисования по оси y.

`char`

  Символ для рисования.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования символа функцией imagechar()

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Рисует чёрный символ "P" в левом верхнем углу
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecharup() - Рисует символ по вертикали
- imageloadfont() - Загружает новый шрифт

# imagecharup

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

imagecharup — Рисует символ по вертикали

### Описание

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Функция рисует символ `char` вертикально на заданных координатах изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().
`x`

  Координата начала рисования по оси x.

`y`

  Координата начала рисования по оси y.

`char`

  Символ, который требуется нарисовать.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования символа функцией imagecharup()

    <?php

    $im = imagecreate(100, 100);

    // Рисуем первую букву строки вертикально: при повороте "N" станет выглядеть как "Z"
    $string = 'Note that the first letter is a N';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Рисует чёрный символ "Z" на белом фоне
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagechar() - Рисует символ по горизонтали
- imageloadfont() - Загружает новый шрифт

# imagecolorallocate

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

imagecolorallocate — Создание цвета для изображения

### Описание

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

Возвращает идентификатор цвета в соответствии с заданными RGB компонентами.

imagecolorallocate() должна вызываться для создания каждого цвета, который будет использоваться в изображении `image`.

> Замечание:

> Первый вызов imagecolorallocate() задаёт цвет фона в палитровых изображениях - изображениях, созданных функцией imagecreate().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

Эти аргументы могут принимать либо целочисленные значение в диапазоне от 0 до 255, либо шестнадцатеричные в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Идентификатор цвета, либо `false` в случае возникновения ошибки.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagecolorallocate()

    <?php

    $im = imagecreate(100, 100);

    // делаем фон красным
    $background = imagecolorallocate($im, 255, 0, 0);

    // создадим несколько цветов
    $white = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // шестнадцатеричный способ
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    ?>

### Смотрите также

- imagecolorallocatealpha() - Создаёт цвет для изображения
- imagecolordeallocate() - Удаляет цвет из палитры изображения

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — Создаёт цвет для изображения

### Описание

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

Функция imagecolorallocatealpha() работает аналогично функции imagecolorallocate(), но ещё добавляет к цвету параметр `alpha`, который отвечает за прозрачность.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

`alpha`

  Значение в диапазоне от `0` до `127`. `0` означает непрозрачный цвет, `127` означает полную прозрачность.

Параметры `red`, `green` и `blue` принимают либо целочисленные значения в диапазоне от 0 до 255, либо шестнадцатеричные значения в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Функция возвращает идентификатор цвета или `false`, если при создании цвета возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagecolorallocatealpha()

    <?php

    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // Создаём белый фон с чёрной рамкой
    $back = imagecolorallocate($image, 255, 255, 255);
    $border = imagecolorallocate($image, 0, 0, 0);
    imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
    imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

    $yellow_x = 100;
    $yellow_y = 75;
    $red_x    = 120;
    $red_y    = 165;
    $blue_x   = 187;
    $blue_y   = 125;
    $radius   = 150;

    // Создаём цвета с альфа-компонентом
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // Рисуем 3 пересекающиеся окружности
    imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
    imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
    imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

    // Помним о выводе правильного заголовка!
    header('Content-Type: image/png');

    // И наконец — вывод
    imagepng($image);

    ?>

Вывод приведённого примера будет похож на:

Пример #2 Преобразование типичных альфа-значений для использования с imagecolorallocatealpha()

Обычно альфа-значения `0` обозначают полностью прозрачные пиксели, а альфа-канал имеет 8 битов. Чтобы преобразовать такие альфа-значения для совместимости с imagecolorallocatealpha(), достаточно немного простой арифметики:

    <?php

    $alpha8 = 0; // На 100 % прозрачный
    var_dump(127 - ($alpha8 >> 1));

    $alpha8 = 255; // Непрозрачный
    var_dump(127 - ($alpha8 >> 1));

    ?>

Результат выполнения приведённого примера:

    int(127)
    int(0)

### Смотрите также

- imagecolorallocate() - Создание цвета для изображения
- imagecolordeallocate() - Удаляет цвет из палитры изображения

# imagecolorat

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

imagecolorat — Получение индекса цвета пиксела

### Описание

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

Возвращает индекс цвета пиксела на заданных координатах на изображении `image`.

Если передаётся truecolor-изображение, функция возвращает целочисленное RGB значение для пиксела. Для выделения отдельных компонентов красного, зелёного или синего каналов используйте битовый сдвиг и маскирование:

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x`

  x-координата пиксела.

`y`

  y-координата пиксела.

### Возвращаемые значения

Возвращает индекс цвета или `false`, если возникла ошибка.

Внимание

Функция возвращает как логическое значение `false`, так и нелогическое значение, которое приводится к `false`. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Доступ к компонентам RGB цвета

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;

    var_dump($r, $g, $b);
    ?>

Вывод приведённого примера будет похож на:

    int(119)
    int(123)
    int(180)

Пример #2 Удобочитаемые RGB значения с использованием imagecolorsforindex()

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

Вывод приведённого примера будет похож на:

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### Смотрите также

- imagecolorset() - Устанавливает набор цветов для индекса палитры
- imagecolorsforindex() - Получение цветов, соответствующих индексу
- imagesetpixel() - Рисует точку

# imagecolorclosest

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

imagecolorclosest — Получает ближайший индекс цвета

### Описание

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Функция возвращает индекс цвета в палитре изображения, «ближайшего» к заданному RGB-значению.

«Расстояние» между цветами в палитре рассчитывается геометрически, как если бы RGB-значения представлялись в виде точек в трёхмерном пространстве.

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

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

Параметры цвета разрешается указывать либо целочисленными значениями в диапазоне от 0 до 255, либо шестнадцатеричными значениями в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Функция возвращает ближайший к заданному индекс цвета в палитре изображения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Поиск набора цветов изображения

    <?php

    // Создание изображения и преобразование его в палитровое
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Цвета для поиска (RGB)
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // Проход по каждому цвету и поиск ближайшего к нему в палитре.
    // Возврат номера по порядку, RGB искомого цвета и найденное RGB соответствие
    foreach ($colors as $id => $rgb) {
        $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

        echo "#$id: Поиск ($rgb[0], $rgb[1], $rgb[2]); Ближайшее сходство: $result.\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    #0: Поиск (254, 145, 154); Ближайшее сходство: (252, 150, 148).
    #1: Поиск (153, 145, 188); Ближайшее сходство: (148, 150, 196).
    #2: Поиск (153, 90, 145); Ближайшее сходство: (148, 90, 156).
    #3: Поиск (255, 137, 92); Ближайшее сходство: (252, 150, 92).

### Смотрите также

- imagecolorexact() - Получает индекс цвета
- imagecolorclosestalpha() - Получает ближайший индекс цвета с учётом прозрачности
- imagecolorclosesthwb() - Получает индекс цвета с заданными тоном, белизной и затемнением

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — Получает ближайший индекс цвета с учётом прозрачности

### Описание

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Функция возвращает «ближайший» к заданному RGB-значению и `alpha`-уровню индекс цвета в палитре изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

`alpha`

  Значение в диапазоне от `0` до `127`. `0` означает непрозрачность, `127` означает абсолютную прозрачность.

Параметры цвета могут быть либо целочисленными в диапазоне от 0 до 255, либо шестнадцатеричными в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Возвращает индекс цвета в палитре изображения, ближайшего к заданному.

### Примеры

Пример #1 Поиск набора цветов изображения

    <?php

    // Создание изображения и преобразование его в палитровое
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Цвета для поиска  (RGB)
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // Проход по каждому цвету и поиск ближайшего к нему в палитре.
    // Возврат номера по порядку, RGB искомого цвета и найденное RGB соответствие
    foreach ($colors as $id => $rgb) {
        $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

        echo "#$id: Поиск ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Ближайшее сходство: $result.\n";
    }

    ?>

Вывод приведённого примера будет похож на:

    #0: Поиск (254, 145, 154, 50); Ближайшее сходство: (252, 150, 148, 0).
    #1: Поиск (153, 145, 188, 127); Ближайшее сходство: (148, 150, 196, 0).
    #2: Поиск (153, 90, 145, 0); Ближайшее сходство: (148, 90, 156, 0).
    #3: Поиск (255, 137, 92, 84); Ближайшее сходство: (252, 150, 92, 0).

### Смотрите также

- imagecolorexactalpha() - Получает индекс цвета и альфа-компонента
- imagecolorclosest() - Получает ближайший индекс цвета
- imagecolorclosesthwb() - Получает индекс цвета с заданными тоном, белизной и затемнением

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — Получает индекс цвета с заданными тоном, белизной и затемнением

### Описание

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Функция получает индекс цвета с наиболее близкими к заданному цвету значениями тона, белизны и затемнения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

### Возвращаемые значения

Функци возвращает целочисленный индекс цвета с наиболее близкими к заданному цвету значениями тона, белизны и затемнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример получения индекса цвета функцией imagecolorclosesthwb()

    <?php

    $im = imagecreatefromgif('php.gif');

    echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);

    ?>

Вывод приведённого примера будет похож на:

    HWB: 33

### Смотрите также

- imagecolorclosest() - Получает ближайший индекс цвета

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — Удаляет цвет из палитры изображения

### Описание

function imagecolordeallocate(GdImage `$image`, int `$color`): true

Удаляет из палитры изображения цвет, который добавили функцией imagecolorallocate() или imagecolorallocatealpha().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`color`

  Идентификатор цвета.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример удаления цвета функцией imagecolordeallocate()

    <?php

    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);

### Смотрите также

- imagecolorallocate() - Создание цвета для изображения
- imagecolorallocatealpha() - Создаёт цвет для изображения

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — Получает индекс цвета

### Описание

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Функция возвращает индекс цвета в палитре изображения.

В изображениях, которые создали из файла, функция распознаёт только цвета самого рисунка, поэтому игнорирует цвета, которые содержит палитра, но не включает изображение.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

### Возвращаемые значения

Функция возвращает индекс цвета в палитре изображения или -1, если палитра не содержит такого цвета.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Получение цветов логотипа GD

    <?php

    // Создаём изображение
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = array();
    $colors[] = imagecolorexact($im, 255, 0, 0);
    $colors[] = imagecolorexact($im, 0, 0, 0);
    $colors[] = imagecolorexact($im, 255, 255, 255);
    $colors[] = imagecolorexact($im, 100, 255, 52);

    print_r($colors);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### Смотрите также

- imagecolorclosest() - Получает ближайший индекс цвета

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — Получает индекс цвета и альфа-компонента

### Описание

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Функция возвращает индекс цвета и альфа-компонента в палитре изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

`alpha`

  Значение в диапазоне от `0` до `127`. `0` означает непрозрачность, `127` означает абсолютную прозрачность.

Параметры цвета разрешается указывать либо целочисленными значениями в диапазоне от 0 до 255, либо шестнадцатеричными значениями в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Функция возвращает индекс цвета и альфа-компонента в палитре изображения или -1, если палитра не содержит такого цвета.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Получение цветов логотипа GD

    <?php

    // Создаём изображение
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = array();
    $colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
    $colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
    $colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
    $colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

    print_r($colors);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### Смотрите также

- imagecolorclosestalpha() - Получает ближайший индекс цвета с учётом прозрачности

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — Приближает цвета палитрового изображения к truecolor-версии

### Описание

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

Функция подгоняет цвета палитрового изображения к truecolor-версии

### Список параметров

`image1`

  Объект truecolor-изображения.

`image2`

  Объект палитрового изображения с тем же размером, что и изображение `image1`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `image1` и `image2` теперь ожидают экземпляр класса GdImage; раньше ожидался тип resource.

### Примеры

Пример #1 Пример подгонки цветов функцией imagecolormatch()

    <?php

    // Создаём изображение
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // Добавляем ряд цветов в изображение $im2
    $colors   = array();
    $colors[] = imagecolorallocate($im2, 255, 36, 74);
    $colors[] = imagecolorallocate($im2, 40, 0, 240);
    $colors[] = imagecolorallocate($im2, 82, 100, 255);
    $colors[] = imagecolorallocate($im2, 84, 63, 44);

    // Задаём соответствия цветов truecolor-цветам изображения
    imagecolormatch($im1, $im2);

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — Получает идентификатор конкретного цвета или его ближайший аналог

### Описание

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Функция обязательно вернёт идентификатор выбранного цвета или его ближайшую возможную альтернативу.

В изображениях, которые создали из файла, функция распознаёт только цвета самого рисунка, поэтому игнорирует цвета, которые содержит палитра, но не включает изображение.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

### Возвращаемые значения

Возвращает цветовой идентификатор.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример получения цветов из изображения функцией imagecoloresolve()

    <?php

    // Загрузить изображение
    $im = imagecreatefromgif('phplogo.gif');

    // Получить ближайшие цвета на изображении
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200);

    // Вывод
    print_r($colors);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Смотрите также

- imagecolorclosest() - Получает ближайший индекс цвета

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — Получает идентификатор конкретного цвета и альфа-компонента или его ближайший аналог

### Описание

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Функция обязательно вернёт идентификатор для выбранного цвета или его ближайшую возможную альтернативу.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

`alpha`

  Значение в диапазоне от `0` до `127`. `0` означает непрозрачность, `127` означает абсолютную прозрачность.

Параметры цвета разрешается указывать либо целочисленными значениями в диапазоне от 0 до 255, либо шестнадцатеричными значениями в диапазоне от 0x00 до 0xFF.

### Возвращаемые значения

Функция возвращает индекс цвета.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример получения цветов из изображения функцией imagecoloresolvealpha()

    <?php

    // Загрузка изображения
    $im = imagecreatefromgif('phplogo.gif');

    // Получение ближайших цветов
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // Вывод
    print_r($colors);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Смотрите также

- imagecolorclosestalpha() - Получает ближайший индекс цвета с учётом прозрачности

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — Устанавливает набор цветов для индекса палитры

### Описание

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

Функция устанавливает соответствие индекса в палитре заданному цвету. Это полезно, когда требуется создать эффект наподобие заливки цветом, но без заливки.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`color`

  Индекс в палитре.

`red`

  Значение красного компонента цвета.

`green`

  Значение зелёного компонента цвета.

`blue`

  Значение синего компонента цвета.

`alpha`

  Значение альфа компонента.

### Возвращаемые значения

Функция возвращает `null`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagecolorset()

    <?php

    // Создание изображения размером 300x100
    $im = imagecreate(300, 100);

    // Установка красного цвета фона
    imagecolorallocate($im, 255, 0, 0);

    // Получение индекса цвета фона
    $bg = imagecolorat($im, 0, 0);

    // Установка синего цвета фона
    imagecolorset($im, $bg, 0, 0, 255);

    // Вывод изображения в браузер
    header('Content-Type: image/png');

    imagepng($im);

    ?>

### Смотрите также

- imagecolorat() - Получение индекса цвета пиксела

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — Получение цветов, соответствующих индексу

### Описание

function imagecolorsforindex(GdImage `$image`, int `$color`): array

Получение цветов, соответствующих заданному индексу.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`color`

  Индекс цвета.

### Возвращаемые значения

Возвращает ассоциативный массив с красным, зелёным, синим и альфа ключами, содержащий соответствующие значения для заданного индекса цвета.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Функция imagecolorsforindex() теперь выбрасывает исключение ValueError, если параметр `color` вне допустимого диапазона; ранее вместо этого возвращалось значение `false`.

### Примеры

Пример #1 Пример использования imagecolorsforindex()

    <?php

    // открываем изображение
    $im = imagecreatefrompng('nexen.png');

    // получаем цвет
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // делаем его удобочитаемым
    $color_tran = imagecolorsforindex($im, $color_index);

    // что здесь ?
    print_r($color_tran);

    ?>

Вывод приведённого примера будет похож на:

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### Смотрите также

- imagecolorat() - Получение индекса цвета пиксела
- imagecolorexact() - Получает индекс цвета

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — Определяет количество цветов в палитре изображения

### Описание

function imagecolorstotal(GdImage `$image`): int

Функция возвращает количество цветов в палитре изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Функция возвращает количество цветов в палитре изображения или 0 для truecolor-изображений.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример получения количества цветов в изображении функцией imagecolorstotal()

    <?php

    // Создание изображения
    $im = imagecreatefromgif('php.gif');

    echo 'Всего цветов в изображении: ' . imagecolorstotal($im);

    ?>

Вывод приведённого примера будет похож на:

    Всего цветов в изображении: 128

### Смотрите также

- imagecolorat() - Получение индекса цвета пиксела
- imagecolorsforindex() - Получение цветов, соответствующих индексу
- imageistruecolor() - Определяет, относится ли изображение к изображениям truecolor

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — Определяет цвет как прозрачный

### Описание

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

Функция получает или устанавливает прозрачность цвета в изображении `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает идентификатор нового (или текущего, если ничего не изменилось) цвета. При установке для параметра `color` значения `null`, когда в изображении нет прозрачных цветов, функция вернёт `-1`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Параметр `color` теперь принимает значение `null`.

### Примеры

Пример #1 Пример определения цвета прозрачным функцией imagecolortransparent()

    <?php

    // Создадим изображение размером 55x30
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Сделаем фон прозрачным
    imagecolortransparent($im, $black);

    // Нарисуем красный прямоугольник
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // Сохраним изображение
    imagepng($im, './imagecolortransparent.png');

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание: Прозрачность копируется только функцией imagecopymerge() и для truecolor-изображений. При вызове функции imagecopy() или палитрового изображения значение альфа-компонента не копируется.

> Замечание:

> Прозрачный цвет — свойство изображения, прозрачность не относится к свойствам цвета. При установке прозрачности цвета отдельные области изображения этого цвета, которые нарисовали прежде, станут прозрачными.

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — Наложение искривляющей матрицы 3х3, используя коэффициент и смещение

### Описание

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

Накладывает искривляющую матрицу на изображение, используя заданный коэффициент и смещение.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`matrix`

  Матрица 3x3: массив из трёх массивов по 3 значения с плавающей точкой в каждом.

`divisor`

  Делитель результата искривления, используется для нормализации.

`offset`

  Смещение цвета.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Создание рельефа на логотипе PHP.net

    <?php
    $image = imagecreatefromgif('http://www.php.net/images/php.gif');

    $emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
    imageconvolution($image, $emboss, 1, 127);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

Результат выполнения приведённого примера:

Пример #2 Размытие по Гауссу

    <?php
    $image = imagecreatetruecolor(180,40);

    // Пишет текст и применяет размытие к изображению
    imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
    $gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
    imageconvolution($image, $gaussian, 16, 0);

    // Переписывает текст для сравнения
    imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

Результат выполнения приведённого примера:

### Смотрите также

- imagefilter() - Применяет фильтр к изображению

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — Копирует часть изображения

### Описание

function imagecopy(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`
): true

Функция копирует на исходном изображении `src_image` область шириной `src_width` и высотой `src_height` и помещает скопированную часть на целевое изображение `dst_image`. Координаты левого верхнего угла области на исходном изображении определяют параметры `src_x` и `src_y`, а на целевом — `dst_x` и `dst_y`.

### Список параметров

`dst_image`

  Ресурс целевого изображения.

`src_image`

  Ресурс исходного изображения.

`dst_x`

  Координата точки по оси x на целевом изображении.

`dst_y`

  Координата точки по оси y на целевом изображении.

`src_x`

  Координата точки по оси x на исходном изображении.

`src_y`

  Координата точки по оси y на исходном изображении.

`src_width`

  Ширина области на исходном изображении.

`src_height`

  Высота области на исходном изображении.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `dst_image` и `src_image` теперь ожидают объект GdImage; раньше параметры ожидали тип resource.

### Примеры

Пример #1 Пример обрезки логотипа PHP.net

    <?php

    // Создаём изображение
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // Копируем часть изображения
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/gif');
    imagegif($dest);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecrop() - Обрезает изображение до заданного прямоугольника

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — Копирует часть изображения с наложением

### Описание

function imagecopymerge(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Функция копирует на исходном изображении `src_image` область шириной `src_width` и высотой `src_height` и помещает скопированную часть на целевое изображение `dst_image`. Координаты левого верхнего угла области на исходном изображении определяют параметры `src_x` и `src_y`, а на целевом — `dst_x` и `dst_y`.

### Список параметров

`dst_image`

  Ресурс целевого изображения.

`src_image`

  Ресурс исходного изображения.

`dst_x`

  Координата точки по оси x на целевом изображении.

`dst_y`

  Координата точки по оси y на целевом изображении.

`src_x`

  Координата точки по оси x на исходном изображении.

`src_y`

  Координата точки по оси y на исходном изображении.

`src_width`

  Ширина области на исходном изображении.

`src_height`

  Высота области на исходном изображении.

`pct`
  Два изображения совмещаются в зависимости от параметра `pct`, который варьируется в диапазоне от 0 до 100. Когда параметр `pct` = 0, наложение не выполняется. Со значением 100 поведение функции аналогично функции imagecopy() для палитровых изображений, несмотря на поддержку прозрачности для truecolor-изображений.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `dst_image` и `src_image` теперь ожидают объект GdImage; раньше параметры ожидали тип resource.

### Примеры

Пример #1 Пример совмещения двух копий логотипа PHP.net с 75-процентной прозрачностью

    <?php

    // Создаём изображение
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Копируем и накладываем части
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/gif');
    imagegif($dest);

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — Копирует часть изображения с наложением в градациях серого

### Описание

function imagecopymergegray(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Функция копирует на исходном изображении `src_image` область шириной `src_width` и высотой `src_height` и помещает скопированную часть на целевое изображение `dst_image`. Координаты левого верхнего угла области на исходном изображении определяют параметры `src_x` и `src_y`, а на целевом — `dst_x` и `dst_y`.

Функция работает аналогично функции imagecopymerge(), за исключением сохранения насыщенности цвета исходного изображения при наложении путём преобразования цветов пикселей конечного изображения в градации серого перед копированием.

### Список параметров

`dst_image`

  Ресурс целевого изображения.

`src_image`

  Ресурс исходного изображения.

`dst_x`

  Координата точки по оси x на целевом изображении.

`dst_y`

  Координата точки по оси y на целевом изображении.

`src_x`

  Координата точки по оси x на исходном изображении.

`src_y`

  Координата точки по оси y на исходном изображении.

`src_width`

  Ширина области на исходном изображении.

`src_height`

  Высота области на исходном изображении.

`pct`
  Функция преобразует исходное изображение `src_image` в изображение в градациях серого на основе значения параметра `pct`: при значении 0 изображение становится серым, а со значением 100 остаётся без изменений. При передаче в параметр `pct` значения 100 функция ведёт себя аналогично функции imagecopy(), но игнорирует альфа-компонент для палитровых изображений; при этом для truecolor-изображений альфа-прозрачность поддерживается.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `dst_image` и `src_image` теперь ожидают объект GdImage; раньше параметры ожидали тип resource.

### Примеры

Пример #1 Пример копирования фрагмента изображения функцией imagecopymergegray()

    <?php

    // Создаём изображении
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Копируем фрагмент изображения и накладываем в оттенках серого с непрозрачностью 20 %
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/gif');
    imagegif($dest);

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — Копирует и изменяет размер части изображения с ресемплированием

### Описание

function imagecopyresampled(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

Функция imagecopyresampled() копирует прямоугольную область одного изображения на другое с плавной интерполяцией значений пикселей, за счёт которой изображение сохраняет чёткость даже при уменьшении размера.

Функция imagecopyresampled() копирует на изображении `src_image` прямоугольную область шириной `src_width` и высотой `src_height` и помещает скопированную часть в прямоугольную область шириной `dst_width` и высотой `dst_height` на целевом изображении `dst_image`. Координаты левого верхнего угла области на исходном изображении определяют параметры `src_x` и `src_y`, а на целевом — `dst_x` и `dst_y`.

Функция растянет или сожмёт фрагмент изображения, если координаты или размер исходного и целевого изображений не совпадают. Координаты отсчитываются от левого верхнего угла изображения. При совпадении аргументов `dst_image` и `src_image` функция копирует области внутри одного изображения, но когда области перекрываются — выдаёт непредсказуемый результат.

### Список параметров

`dst_image`

  Ресурс целевого изображения.

`src_image`

  Ресурс исходного изображения.

`dst_x`

  Координата точки по оси x на целевом изображении.

`dst_y`

  Координата точки по оси y на целевом изображении.

`src_x`

  Координата точки по оси x на исходном изображении.

`src_y`

  Координата точки по оси y на исходном изображении.

`dst_width`

  Ширина области на целевом изображении.

`dst_height`

  Высота области на целевом изображении.

`src_width`

  Ширина области на исходном изображении.

`src_height`

  Высота области на исходном изображении.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Тип возврата изменился на `true`; раньше возвращался тип bool.
8.0.0 | Параметры `dst_image` и `src_image` теперь принимают объект GdImage; раньше принимался тип resource.

### Примеры

Пример #1 Простой пример

В примере изображение сжимается до половины исходного размера.

    <?php

    // Файл
    $filename = 'test.jpg';
    $percent = 0.5;

    // Тип содержимого
    header('Content-Type: image/jpeg');

    // Получение новых размеров
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // Ресемплирование
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // Вывод
    imagejpeg($image_p, null, 100);

Вывод приведённого примера будет похож на:

Пример #2 Пример ресемплирования изображения с сохранением пропорций

В примере изображение сжимается до 200 пикселей по большей стороне — ширине или высоте.

    <?php

    // Файл
    $filename = 'test.jpg';

    // Установка максимума ширины и высоты
    $width = 200;
    $height = 200;

    // Тип содержимого
    header('Content-Type: image/jpeg');

    // Получение новых размеров
    list($width_orig, $height_orig) = getimagesize($filename);

    $ratio_orig = $width_orig / $height_orig;

    if ($width / $height > $ratio_orig) {
        $width = $height * $ratio_orig;
    } else {
        $height = $width / $ratio_orig;
    }

    // Ресемплирование
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // Вывод
    imagejpeg($image_p, null, 100);

Вывод приведённого примера будет похож на:

### Примечания

> Замечание:

> Из-за ограничения количества цветов палитровых изображений значением 255 + 1 цвет возникает проблема. Для ресемплирования или фильтрации изображений часто требуется больше 255 цветов, поэтому функция вычисляет новый цвет пикселя методом аппроксимации. При обработке палитровых изображений функция пытается добавить в палитру новый цвет, а если создать цвет невозможно, вычисляет теоретический ближайший. Иногда расчёт даёт странный результат: цвет не кажется близким, а изображение выглядит пустым. С полноцветными целевыми изображениями, которые, например, создаёт функция imagecreatetruecolor(), ресемплирование работает без ошибок.

### Смотрите также

- imagecopyresized() - Копирует и изменяет размер части изображения
- imagescale() - Масштабировать изображение по заданной ширине и высоте
- imagecrop() - Обрезает изображение до заданного прямоугольника

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — Копирует и изменяет размер части изображения

### Описание

function imagecopyresized(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

Функция imagecopyresized() копирует прямоугольную область одного изображения на другое. Параметр `dst_image` — целевое изображение, а `src_image` — идентификатор исходного изображения.

Функция imagecopyresized() копирует на изображении `src_image` прямоугольную область шириной `src_width` и высотой `src_height` и помещает скопированную часть в прямоугольную область шириной `dst_width` и высотой `dst_height` на целевом изображении `dst_image`. Координаты левого верхнего угла области на исходном изображении определяют параметры `src_x` и `src_y`, а на целевом — `dst_x` и `dst_y`.

Функция растянет или сожмёт фрагмент изображения, если координаты или размер исходного и целевого изображений не совпадают. Координаты отсчитываются от левого верхнего угла изображения. При совпадении аргументов `dst_image` и `src_image` функция копирует области внутри одного изображения, но когда области перекрываются — выдаёт непредсказуемый результат.

### Список параметров

`dst_image`

  Ресурс целевого изображения.

`src_image`

  Ресурс исходного изображения.

`dst_x`

  Координата точки по оси x на целевом изображении.

`dst_y`

  Координата точки по оси y на целевом изображении.

`src_x`

  Координата точки по оси x на исходном изображении.

`src_y`

  Координата точки по оси y на исходном изображении.

`dst_width`

  Ширина области на целевом изображении.

`dst_height`

  Высота области на целевом изображении.

`src_width`

  Ширина области на исходном изображении.

`src_height`

  Высота области на исходном изображении.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `dst_image` и `src_image` теперь принимают объект GdImage; раньше принимался тип resource.

### Примеры

Пример #1 Пример изменения размера изображения

В примере размер изображения уменьшается в два раза.

    <?php

    // Файл и новый размер
    $filename = 'test.jpg';
    $percent = 0.5;

    // Тип содержимого
    header('Content-Type: image/jpeg');

    // Получение нового размера
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Загрузка
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Изменение размера
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Вывод
    imagejpeg($thumb);

Вывод приведённого примера будет похож на:

Пример выведет изображение в половинном размере. Функция imagecopyresampled() обрабатывает изображения с меньшей потерей качества.

### Примечания

> Замечание:

> Из-за ограничения количества цветов палитровых изображений значением 255 + 1 цвет возникает проблема. Для ресемплирования или фильтрации изображений часто требуется больше 255 цветов, поэтому функция вычисляет новый цвет пикселя методом аппроксимации. При обработке палитровых изображений функция пытается добавить в палитру новый цвет, а если создать цвет невозможно, вычисляет теоретический ближайший. Иногда расчёт даёт странный результат: цвет не кажется близким, а изображение выглядит пустым. С полноцветными целевыми изображениями, которые, например, создаёт функция imagecreatetruecolor(), ресемплирование работает без ошибок.

### Смотрите также

- imagecopyresampled() - Копирует и изменяет размер части изображения с ресемплированием
- imagescale() - Масштабировать изображение по заданной ширине и высоте
- imagecrop() - Обрезает изображение до заданного прямоугольника

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — Создаёт новое палитровое изображение

### Описание

function imagecreate(int `$width`, int `$height`): GdImage|false

Функция imagecreate() возвращает идентификатор пустого изображения заданного размера.

Рекомендуют пользоваться функцией imagecreatetruecolor() вместо функции imagecreate(), поскольку она обрабатывает изображения с максимально возможным качеством. Если необходимо вывести палитру изображения, то функцию imagetruecolortopalette() вызывают непосредственно перед сохранением изображения функцией imagepng() или imagegif().

### Список параметров

`width`

  Ширина изображения.

`height`

  Высота изображения.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция теперь возвращает экземпляр GDImage; ранее возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания нового GD-потока изображения и вывод изображения

    <?php

    header("Content-Type: image/png");

    $im = @imagecreate(110, 20)
        or die("Невозможно создать поток изображения");

    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);
    imagepng($im);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() возвращает объект изображения, представляющий изображение, полученное из данного имени файла.

### Список параметров

`filename`

  Путь до растрового изображения AVIF.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefrombmp(string `$filename`): GdImage|false

Функция imagecreatefrombmp() возвращает идентификатор изображения, которое получили по названию файла.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к BMP-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Конвертирование BMP-изображения в PNG-изображения, используя imagecreatefrombmp()

    <?php

    // Загрузить BMP-файл
    $im = imagecreatefrombmp('./example.bmp');

    // Преобразовать в PNG-файл с настройками по умолчанию
    imagepng($im, './example.png');

    ?>

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — Создаёт новое изображение на основе GD-файла или URL-адреса

### Описание

function imagecreatefromgd(string `$filename`): GdImage|false

Функция создаёт новое изображение на основе GD-файла или URL-адреса

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к GD-файлу.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания нового изображения функцией imagecreatefromgd()

    <?php

    // Загрузка изображения
    $im = @imagecreatefromgd('./test.gd');

    // Проверка, загрузилось ли изображение
    if (!$im) {
        die('Не получилось загрузить изображение!');
    }

    // Операции с изображением выполняют здесь

    // Сохранение изображения
    imagegd($im, './test_updated.gd');

    ?>

### Примечания

Внимание

Форматы GD и GD2 — проприетарные форматы изображений библиотеки libgd. Форматы устарели и применяются только в целях разработки и тестирования.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — Создаёт новое изображение на основе GD2-файла или URL-адреса

### Описание

function imagecreatefromgd2(string `$filename`): GdImage|false

Функция создаёт новое изображение на основе GD2-файла или URL-адреса

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к GD2-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания изображения функцией imagecreatefromgd2()

    <?php

    // Загрузка gd2-изображения
    $im = imagecreatefromgd2('./test.gd2');

    // Применение эффекта к изображению, этот код
    // инвертирует цвета
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // Сохранение изображения
    imagegd2($im, './test_updated.gd2');

    ?>

### Примечания

Внимание

Форматы GD и GD2 — проприетарные форматы изображений библиотеки libgd. Форматы устарели и применяются только в целях разработки и тестирования.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — Создаёт новое изображение на основе части GD2-файла или URL-адреса

### Описание

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

Функция создаёт новое изображение на основе части GD2-файла или URL-адреса.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к GD2-изображению.

`x`

  x-координата точки исходного изображения.

`y`

  y-координата точки исходного изображения.

`width`

  Ширина области на исходном изображении.

`height`

  Высота области на исходном изображении.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания изображения функцией imagecreatefromgd2part()

    <?php

    // Для этого примера нам сначала потребуется узнать размер изображения
    $image = getimagesize('./test.gd2');

    // Создание изображения
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // Добавим рельеф на изображение
    if (function_exists('imagefilter')) {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // Сохранение изображения
    imagegd2($im, './test_emboss.gd2');

    ?>

### Примечания

Внимание

Форматы GD и GD2 — проприетарные форматы изображений библиотеки libgd. Форматы устарели и применяются только в целях разработки и тестирования.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromgif(string `$filename`): GdImage|false

Функция imagecreatefromgif() возвращает объект изображения, которое получили по названию файла.

Предостережение

При чтении анимированных GIF-файлов в память возвращается указатель на ресурс изображения только для первого фрейма. Размер изображения не вегда соответствует тому, что возвращает функция getimagesize().

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к GIF-картинке.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример обработки ошибки при загрузке изображения в формате GIF

    <?php

    function LoadGif($imgname)
    {
        /* Пытаемся открыть */
        $im = @imagecreatefromgif($imgname);

        /* При неудаче */
        if (!$im) {
            /* Создаём пустое изображение */
            $im = imagecreatetruecolor (150, 30);
            $bgc = imagecolorallocate ($im, 255, 255, 255);
            $tc = imagecolorallocate ($im, 0, 0, 0);

            imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

            /* Выводим сообщение об ошибке */
            imagestring ($im, 1, 5, 5, 'Ошибка загрузки ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);

    ?>

Вывод приведённого примера будет похож на:

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromjpeg(string `$filename`): GdImage|false

Функция imagecreatefromjpeg() возвращает идентификатор изображения, которое получили по названию файла.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к JPEG-картинке.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример обработки ошибки при загрузке изображения в формате JPEG

    <?php

    function LoadJpeg($imgname)
    {
        /* Пытаемся открыть */
        $im = @imagecreatefromjpeg($imgname);

        /* Если не удалось */
        if (!$im) {
            /* Создаём пустое изображение */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Выводим сообщение об ошибке */
            imagestring($im, 1, 5, 5, 'Ошибка загрузки ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);

    ?>

Вывод приведённого примера будет похож на:

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefrompng(string `$filename`): GdImage|false

Функция imagecreatefrompng() возвращает идентификатор изображения, которое получили по названию файла.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к PNG-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример обработки ошибки при загрузке изображения в формате PNG

    <?php

    function LoadPNG($imgname)
    {
        /* Пытаемся открыть */
        $im = @imagecreatefrompng($imgname);

        /* Если не удалось */
        if (!$im) {
            /* Создаём пустое изображение */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Выводим сообщение об ошибке */
            imagestring($im, 1, 5, 5, 'Ошибка загрузки ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);

    ?>

Вывод приведённого примера будет похож на:

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — Создаёт новое изображение из представленного строкой потока

### Описание

function imagecreatefromstring(string `$data`): GdImage|false

Функция imagecreatefromstring() возвращает идентификатор изображения, которое функция получила из параметра `data`. PHP-сборка, если поддерживает, будет автоматически определять типы изображений: JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP и AVIF.

### Список параметров

`data`

  Строка, которая содержит данные изображения.

### Возвращаемые значения

Функция вернёт объект изображения, если выполнилась успешно. Функция вернёт `false`, если модуль не поддерживает тип изображения, не распознаёт формат данных или изображение повреждено и загружается.

### Ошибки

Функция imagecreatefromstring() выдаёт ошибку уровня E_WARNING, если не распознала формат данных.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше функция возвращала ресурс (resource).
7.3.0 | Добавили поддержку формата WEBP, если модуль libgd поддерживает такой формат.

### Примеры

Пример #1 Пример создания нового изображения функцией imagecreatefromstring()

    <?php

    $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
           . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
           . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
           . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg=='
    ;

    $data = base64_decode($data);

    $im = imagecreatefromstring($data);

    if ($im !== false) {
        header('Content-Type: image/png');
        imagepng($im);
    } else {
        echo 'Возникла ошибка.';
    }

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecreatefromjpeg() - Создаёт новое изображение из файла или URL-адреса
- imagecreatefrompng() - Создаёт новое изображение из файла или URL-адреса
- imagecreatefromgif() - Создаёт новое изображение из файла или URL-адреса
- imagecreatetruecolor() - Создаёт новое truecolor-изображение

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() возвращает объект изображения, представляющий изображение, полученное из данного имени файла.

### Список параметров

`filename`

  Путь к изображению Truevision TGA.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | В случае успешного выполнения функция теперь возвращает экземпляр GDImage; ранее возвращался ресурс (resource).

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromwbmp(string `$filename`): GdImage|false

Функция imagecreatefromwbmp() возвращает идентификатор изображения, которое получили по названию файла.

> Замечание: Изображения в формате WBMP представляют файлы в формате Wireless Bitmaps, а не Windows Bitmaps. Последние загружаются функцией imagecreatefrombmp().

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к WBMP-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример обработки ошибки при загрузке изображения в формате WBMP

    <?php

    function LoadWBMP($imgname)
    {
        /* Пытаемся открыть */
        $im = @imagecreatefromwbmp($imgname);

        /* Если не удалось */
        if (!$im) {
            /* Создаём пустое изображение */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Выводим сообщение об ошибке */
            imagestring($im, 1, 5, 5, 'Ошибка загрузки ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/vnd.wap.wbmp');

    $img = LoadWBMP('bogus.image');

    imagewbmp($img);

    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromwebp(string `$filename`): GdImage|false

Функция imagecreatefromwebp() возвращает идентификатор изображения, которое получили по названию файла. Обратите внимание, что функция не читает анимированные файлы в формате WebP.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к WebP-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример конвертации WebP-изображения в JPEG-изображение функцией imagecreatefromwebp()

    <?php

    // Загрузить WebP-файл
    $im = imagecreatefromwebp('./example.webp');

    // Сконвертировать его в jpeg-файл со 100%-качеством
    imagejpeg($im, './example.jpeg', 100);

    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromxbm(string `$filename`): GdImage|false

Функция imagecreatefromxbm() возвращает идентификатор изображения, которое получили по названию файла.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к XBM-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример преобразования XBM-изображения в изображение в формате PNG функцией imagecreatefromxbm()

    <?php

    // Загрузка xbm файла
    $xbm = imagecreatefromxbm('./example.xbm');

    // Преобразование в PNG-файл
    imagepng($xbm, './example.png');

    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — Создаёт новое изображение из файла или URL-адреса

### Описание

function imagecreatefromxpm(string `$filename`): GdImage|false

Функция imagecreatefromxpm() возвращает идентификатор изображения, которое получили по названию файла.

Подсказка

Вместо названий файлов функция принимает URL-адреса, если включили директиву fopen wrappers. Подробнее об определении названия файла рассказывает описание функции fopen(). Раздел «Протоколы и обёртки» также даёт ссылки на информацию о поддерживаемых обёртках, содержит замечания по работе с обёртками и приводит список предопределённых переменных, которые они дают.

### Список параметров

`filename`

  Путь к XPM-изображению.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример создания изображения функцией imagecreatefromxpm()

    <?php

    // Проверка поддержки изображений в формате XPM
    if (!(imagetypes() & IMG_XPM)) {
        die('Формат XPM не поддерживается!');
    }

    // Создание изображения
    $xpm = imagecreatefromxpm('./example.xpm');

    // Операции с изображением

    // PHP не поддерживает запись XPM-изображений,
    // поэтому сохраним изображение
    // как JPEG-файл качеством 100 %
    imagejpeg($xpm, './example.jpg', 100);

    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — Создаёт новое truecolor-изображение

### Описание

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

Функция imagecreatetruecolor() возвращает объект, который представляет чёрное изображение заданного размера.

### Список параметров

`width`

  Ширина изображения.

`height`

  Высота изображения.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше функция возвращала ресурс (resource).

### Примеры

Пример #1 Пример создания нового потока GD-изображения и вывод картинки

    <?php

    header ('Content-Type: image/png');

    $im = @imagecreatetruecolor(120, 20)
          or die('Невозможно инициализировать GD-поток');

    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);
    imagepng($im);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecreate() - Создаёт новое палитровое изображение

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Обрезает изображение до заданного прямоугольника

### Описание

function imagecrop(GdImage `$image`, array `$rectangle`): GdImage|false

Функция обрезает изображение до заданной прямоугольной области и возвращает полученное изображение. Функция не изменяет изображение в аргументе `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`rectangle`

  Обрезанный прямоугольник в виде массива (array) с ключами `x`, `y`, `width` и `height`.

### Возвращаемые значения

Функция возвращает объект обрезанного изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример обрезки изображения функцией imagecrop()

Пример показывает, как обрезать изображение до квадратной области.

    <?php

    $im = imagecreatefrompng('example.png');
    $size = min(imagesx($im), imagesy($im));
    $im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);

    if ($im2 !== FALSE) {
        imagepng($im2, 'example-cropped.png');
    }

    ?>

### Смотрите также

- imagecropauto() - Обрезает изображение автоматически на основе заданного режима

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — Обрезает изображение автоматически на основе заданного режима

### Описание

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

Функция автоматически обрезает изображение на основе заданного режима `mode`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`mode`

  Константа из следующего списка:

  `IMG_CROP_DEFAULT`
    То же, что и `IMG_CROP_TRANSPARENT`. До PHP 7.4.0 встроенный модуль libgd выбирал режим `IMG_CROP_SIDES`, если у изображения не было прозрачного цвета.
  `IMG_CROP_TRANSPARENT`
    Обрезает прозрачный фон.
  `IMG_CROP_BLACK`
    Обрезает чёрный фон.
  `IMG_CROP_WHITE`
    Обрезает белый фон.
  `IMG_CROP_SIDES`
    Анализирует 4 угла изображения, чтобы попытаться обнаружить фон для обрезки.
  `IMG_CROP_THRESHOLD`
    Обрезает изображение по заданным допуску `threshold` и цвету `color`.
`threshold`

  Параметр определяет допуск в процентах, который функция не превысит при сравнении цвета изображения и цвета обрезки. Метод расчёта цветовой разницы основан на цветовом расстоянии в кубе RGB(a).

  Учитывается только в режиме `IMG_CROP_THRESHOLD`.

  > Замечание: До PHP 7.4.0 встроенная библиотека libgd работала по другому алгоритму, поэтому один и тот же порог `threshold` выдавал разные результаты для системной и встроенной библиотеки libgd.

`color`

  Значение RGB-цвета или индекс палитры.

  Учитывается только в режиме `IMG_CROP_THRESHOLD`.

### Возвращаемые значения

Функция возвращает объект обрезанного изображения, если выполнилась успешно, или `false`, если возникла ошибка. Функция возвращает `false` и при обрезке всего изображения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Функция теперь возвращает объект класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).
7.4.0 | Поведение функции imagecropauto() во встроенной библиотеке libgd синхронизировали с поведением системной библиотеки libgd: режим `IMG_CROP_DEFAULT` больше не откатывается к режиму `IMG_CROP_SIDES`, а пороговая обрезка теперь работает по тому же алгоритму, что и системная библиотека libgd.
7.4.0 | Значение режима `mode` по умолчанию изменили на `IMG_CROP_AUTO`. Раньше значением по умолчанию было `-1`, что соответствует режиму `IMG_CROP_DEFAULT`, но передача значения `-1` теперь устарела.

### Примеры

Пример #1 Правильная обработка автообрезки

Как отмечает раздел возвращаемого значения, функция imagecropauto() возвращает `false`, если обрезала всё изображение. В этом примере ресурс изображения `$im` автоматически обрезается, только если есть, что обрезать; иначе продолжается работа с исходным изображением.

    <?php

    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);

    if ($cropped !== false) { // При возврате нового объекта изображения
        $im = $cropped;       // Назначаем обрезанное изображение переменной $im
    }

    ?>

### Смотрите также

- imagecrop() - Обрезает изображение до заданного прямоугольника

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — Рисует пунктирную линию

### Описание

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Функция устарела. Вместо неё вызывают функции imagesetstyle() и imageline(). Точка с координатами 0, 0 соответствует верхнему левому углу изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x1`

  Координата начала отрезка по оси x.

`y1`

  Координата начала отрезка по оси y.

`x2`

  Координата конца отрезка по оси x.

`y2`

  Координата конца отрезка по оси y.

`color`

  Цвет линии. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования пунктирной линии функцией imagedashedline()

    <?php

    // Создаём изображение размером 100 на 100 пикселей
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Рисуем вертикальную пунктирную линию
    imagedashedline($im, 50, 25, 50, 75, $white);

    // Сохраняем изображение
    imagepng($im, './dashedline.png');

Вывод приведённого примера будет похож на:

Пример #2 Альтернатива функции imagedashedline()

    <?php

    // Создаём изображение размером 100 на 100 пикселей
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Определяем стиль: первые 4 пикселя белые, следующие 4 — прозрачные.
    // Чередование цветов пикселей создаёт эффект пунктира
    $style = array(
        $white,
        $white,
        $white,
        $white,
        IMG_COLOR_TRANSPARENT,
        IMG_COLOR_TRANSPARENT,
        IMG_COLOR_TRANSPARENT,
        IMG_COLOR_TRANSPARENT
    );

    imagesetstyle($im, $style);

    // Рисуем пунктирную линию
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // Сохраненяем изображение
    imagepng($im, './imageline.png');

### Смотрите также

- imagesetstyle() - Устанавливает стиль рисования линий
- imageline() - Рисует отрезок

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — Уничтожает изображение

Внимание

Начиная с PHP 8.5.0 функция УСТАРЕЛА. Полагаться на функцию настоятельно не рекомендуют.

### Описание

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> Замечание: Функция стала бесполезной. До PHP 8.0.0 функция закрывала ресурс.

До PHP 8.0.0 функция imagedestroy() освобождала память, связанную с ресурсом `image`. Начиная с PHP 8.0.0 модуль GD работает с объетами вместо ресурсов.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.5.0 | Функция устарела.
8.0.0 | Функция стала NOP (англ. No Operation) и ни на что не влияет.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример уничтожения изображения функцией imagedestroy() до PHP 8.0.0

    <?php

    // Создаём изображение размером 100 на 100 пикселей
    $im = imagecreatetruecolor(100, 100);

    // Изменение или сохранение изображения

    // Освобождаем память
    imagedestroy($im);

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — Рисует эллипс

### Описание

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Функция рисует эллипс с центром в заданных координатах.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`center_x`

  Координата центра по оси x.

`center_y`

  Координата центра по оси y.

`width`

  Ширина эллипса.

`height`

  Высота эллипса.

`color`

  Цвет эллипса. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования эллипса функцией imageellipse()

    <?php

    // Создаём пустое изображение
    $image = imagecreatetruecolor(400, 300);

    // Определяем цвет фона
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Закрашиваем фон цветом
    imagefill($image, 0, 0, $bg);

    // Устанавливаем цвет эллипса
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Рисуем эллипс
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header("Content-type: image/png");
    imagepng($image);

Вывод приведённого примера будет похож на:

### Примечания

> Замечание:

> Функция imageellipse() игнорирует установку толщины линии функцией imagesetthickness().

### Смотрите также

- imagefilledellipse() - Рисует эллипс с заливкой
- imagearc() - Рисует дугу

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — Заливает фон

### Описание

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Функция заливает область на изображении `image`. Координаты определяют точку начала заливки. Цвет заливки задаётся параметром `color`. Координаты 0, 0 — верхний левый угол.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x`

  Координата начальной точки по оси x.

`y`

  Координата начальной точки по оси y.

`color`

  Цвет заливки. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример заливки фона функцией imagefill()

    <?php

    $im = imagecreatetruecolor(100, 100);

    // Устанавливаем красный фон
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecolorallocate() - Создание цвета для изображения

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — Рисует и заливает дугу

### Описание

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

Функция рисует дугу с центром в заданных координатах изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`center_x`

  Координата центра по оси x.

`center_y`

  Координата центра по оси y.

`width`

  Ширина дуги.

`height`

  Высота дуги.

`start_angle`

  Угол начала дуги в градусах.

`end_angle`

  Угол окончания дуги в градусах. 0° соответствует положению 3-го часа. Дуга рисуется по часовой стрелке.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

`style`

  Комбинация констант через побитовое ИЛИ:

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  Стили `IMG_ARC_PIE` и `IMG_ARC_CHORD` взаимно исключают друг друга; стиль `IMG_ARC_CHORD` только соединяет начало и конец дуги прямой линией; стиль `IMG_ARC_PIE` рисует между точками часть окружности. Стиль `IMG_ARC_NOFILL` означает, что требуются только границы, без заливки. Стиль `IMG_ARC_EDGED` в сочетании со стилем `IMG_ARC_NOFILL` означает, что начало и конец дуги соединяются с центром — удобный способ получить контур сектора в форме «куска пирога», а не заливку.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример создания трёхмерного пирога

    <?php

    // Создаём изображение
    $image = imagecreatetruecolor(100, 100);

    // Определяем цвета
    $white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
    $gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
    $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
    $navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
    $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
    $red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
    $darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

    // Создаём 3D-эффект
    for ($i = 60; $i > 50; $i--) {
       imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
    }

    imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-type: image/png');
    imagepng($image);

Вывод приведённого примера будет похож на:

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — Рисует эллипс с заливкой

### Описание

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Функция рисует эллипс с центром в заданных координатах изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`center_x`

  Координата центра по оси x.

`center_y`

  Координата центра по оси y.

`width`

  Ширина эллипса.

`height`

  Высота эллипса.

`color`

  Цвет заливки. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования эллипса с заливкой функцией imagefilledellipse()

    <?php

    // Создаём пустое изображение
    $image = imagecreatetruecolor(400, 300);

    // Заливаем фон
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Устанавливаем цвет заливки эллипса
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Рисуем белый эллипс
    imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header("Content-type: image/png");
    imagepng($image);

Вывод приведённого примера будет похож на:

### Примечания

> Замечание:

> Функция imageellipse() игнорирует установку толщины линии функцией imagesetthickness().

### Смотрите также

- imageellipse() - Рисует эллипс
- imagefilledarc() - Рисует и заливает дугу

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — Рисует закрашенный многоугольник

### Описание

Сигнатура, которая действует с PHP 8.0.0 (не поддерживается с именованными аргументами)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Альтернативная сигнатура (устарела с PHP 8.1.0)

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

Функция imagefilledpolygon() создаёт закрашенный многоугольник в изображении `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`points`

  Массив с `x`- и `y`-координатами последовательных вершин многоугольника.

`num_points`

  Общее количество точек (вершин), должно быть не меньше 3.

  При вызове функции согласно сигнатуре без этого параметра массив `points` должен содержать чётное количество элементов, тогда значение параметра `num_points` функция вычислит как `count($points) / 2`.
`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `num_points` устарел.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования закрашенного многоугольника функцией imagefilledpolygon()

    <?php

    // Установка массива точек для многоугольника
    $values = array(
        40,  50,  // Point 1 (x, y)
        20,  240, // Point 2 (x, y)
        60,  60,  // Point 3 (x, y)
        240, 20,  // Point 4 (x, y)
        50,  40,  // Point 5 (x, y)
        10,  10   // Point 6 (x, y)
    );

    // Создание изображения
    $image = imagecreatetruecolor(250, 250);

    // Определение цветов
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // Заливка фона
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // Рисование многоугольника
    imagefilledpolygon($image, $values, $blue);

    // Вывод изображения
    header('Content-type: image/png');
    imagepng($image);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagepolygon() - Рисует многоугольник

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — Рисует прямоугольник с заливкой

### Описание

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Функция создаёт на изображении `image` прямоугольник и заливает фигуру цветом `color`. Границы прямоугольника задаются двумя точками — координатами противоположных углов. Координаты 0, 0 — левый верхний угол изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x1`

  Координата 1-й точки по оси x.

`y1`

  Координата 1-й точки по оси y.

`x2`

  Координата 2-й точки по оси x.

`y2`

  Координата 2-й точки по оси y.

`color`

  Цвет заливки. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования прямоугольника с заливкой функцией imagefilledrectangle()

    <?php

    // Создаём изображение размером 55 на 30 пикселей
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Рисуем прямоугольник
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // Сохраняем изображение
    imagepng($im, './imagefilledrectangle.png');

Вывод приведённого примера будет похож на:

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — Заливает область изображения

### Описание

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

Функция imagefilltoborder() заливает область изображения. Цвет границы области задаётся параметром `border_color`. Заливка начинается в точке с координатами `x`, `y`. Начало координат — левый верхний угол изображения. Область закрашивается цветом `color`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x`

  Координата начала заливки по оси x.

`y`

  Координата начала заливки по оси y.

`border_color`

  Цвет границы заливки. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

`color`

  Цвет заливки. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример заливки эллипса

    <?php

    // Создаём изображение и устанавливаем белый фон
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // Рисуем эллипс и заливаем чёрным цветом
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // Устанавливаем цвет границы заливки
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // Заливаем область
    imagefilltoborder($im, 50, 50, $border, $fill);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

### Примечания

Алгоритм не запоминает, какие пиксели уже установил, а решение о заливке пикселя принимает на основе цвета пикселя. Поэтому при установке для заливки цвета, который уже содержится в изображении, функция иногда выдаёт нежелательный результат.

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Применяет фильтр к изображению

### Описание

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

Функция imagefilter() применяет фильтр `filter` к изображению `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`filter`

  Параметр `filter` принимает следующие значения:

  - `IMG_FILTER_NEGATE`: Инвертирует все цвета изображения.
  - `IMG_FILTER_GRAYSCALE`: Преобразует цвета изображения в градации серого путём преобразования компонент красного, зелёного и синего в их сумму с учётом весов, таких же как при вычислении яркости (Y') по рекомендации REC.601. Альфа-канал сохраняется. Для изображений с палитрой результат иногда отличается из-за ограничений, которые накладывает палитра.
  - `IMG_FILTER_BRIGHTNESS`: Изменяет яркость изображения. Уровень яркость устанавливают через параметр `args`. Диапазон яркости принимает значения от -255 до 255.
  - `IMG_FILTER_CONTRAST`: Изменяет контрастность изображения. Уровень контрастности устанавливают через параметр `args`.
  - `IMG_FILTER_COLORIZE`: То же, что и `IMG_FILTER_GRAYSCALE`, за исключением того, что разрешается указать цвет. Аргументы `args`, `arg2` и `arg3` устанавливают каналы `red`, `green`, `blue`, а аргумент `arg4` устанавливает канал `alpha`. Диапазон каждого канала принимает значения от 0 до 255.
  - `IMG_FILTER_EDGEDETECT`: Использует определение границ для их подсветки.
  - `IMG_FILTER_EMBOSS`: Добавляет рельеф.
  - `IMG_FILTER_GAUSSIAN_BLUR`: Размывает изображение методом Гаусса.
  - `IMG_FILTER_SELECTIVE_BLUR`: Размывает изображение.
  - `IMG_FILTER_MEAN_REMOVAL`: Использует усреднение для достижения эффекта «эскиза».
  - `IMG_FILTER_SMOOTH`: Делает границы более плавными, а изображение менее чётким. Уровень гладкости устанавливают через параметр `args`.
  - `IMG_FILTER_PIXELATE`: Применяет эффект пикселирования. Размер блока устанавливают через параметр `args`, а режим эффекта пикселизации через параметр `arg2`.
  - `IMG_FILTER_SCATTER`: Применяет эффект рассеивания к изображению. Силу эффекта определяют параметрами `args` и `arg2`, а аргумент `arg3` передают дополнительно, чтобы применить эффект только к конкретным цветам пикселей.
`args`

  - `IMG_FILTER_BRIGHTNESS`: Уровень яркости.
  - `IMG_FILTER_CONTRAST`: Уровень контрастности.
  - `IMG_FILTER_COLORIZE`: Значение красного компонента цвета.
  - `IMG_FILTER_SMOOTH`: Уровень сглаживания.
  - `IMG_FILTER_PIXELATE`: Размер блока в пикселях.
  - `IMG_FILTER_SCATTER`: Уровень уменьшения эффекта. Значению нельзя быть больше или равным уровню добавления эффекта, который установили в параметре `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE`: Значение зелёного компонента цвета.
  - `IMG_FILTER_PIXELATE`: Определяет, применять ли усовершенствованный эффект пикселизации. Значение по умолчанию равняется `false`.
  - `IMG_FILTER_SCATTER`: Уровень добавления эффекта.
`arg3`

  - `IMG_FILTER_COLORIZE`: Значение синего компонента цвета.
  - `IMG_FILTER_SCATTER`: Необязательный массив значений индексации цвета для применения эффекта.
`arg4`

  - `IMG_FILTER_COLORIZE`: Альфа-канал, значение между 0 и 127. Значение 0 обозначает непрозрачность, а 127 соответствует абсолютной прозрачности.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение аргумента `sub` или `plus` приведёт к переполнению или недополнению со значением `IMG_FILTER_SCATTER` для параметра `filter`.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `sub` или `plus` приведёт к переполнению или недополнению со значением `IMG_FILTER_SCATTER` для параметра `filter`.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
7.4.0 | Добавили поддержку рассеивания — `IMG_FILTER_SCATTER`.

### Примеры

Пример #1 Пример наложения фильтра на изображение функцией imagefilter() с фильтром grayscale

    <?php

    $im = imagecreatefrompng('dave.png');

    if ($im && imagefilter($im, IMG_FILTER_GRAYSCALE)) {
        echo 'Изображение преобразовано к градациям серого.';

        imagepng($im, 'dave.png');
    } else {
        echo 'Преобразование не удалось.';
    }

    ?>

Пример #2 Пример наложения фильтра функцией imagefilter() с фильтром яркости

    <?php
    $im = imagecreatefrompng('sean.png');

    if ($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20)) {
        echo 'Яркость изображения изменена.';

        imagepng($im, 'sean.png');

    } else {
        echo 'Изменить яркость не удалось.';
    }

    ?>

Пример #3 Пример наложения фильтра функцией imagefilter() с фильтром colorize

    <?php

    $im = imagecreatefrompng('philip.png');

    /* R, G, B, so 0, 255, 0 is green */
    if ($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0)) {
        echo 'Изображение преобразовано к оттенкам зеленого.';

        imagepng($im, 'philip.png');
    } else {
        echo 'Преобразование не удалось.';
    }

    ?>

Пример #4 Пример наложения фильтра функцией imagefilter() с фильтром negate

    <?php

    // Определим функцию negate(), которую получится перенести в PHP
    // без функции imagefilter()
    function negate($im)
    {
        if (function_exists('imagefilter')) {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for ($x = 0; $x < imagesx($im); ++$x) {
            for ($y = 0; $y < imagesy($im); ++$y) {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return (true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if ($im && negate($im)) {
        echo 'Изображение инвертировано успешно.';

        imagejpeg($im, 'kalle.jpg', 100);
    } else {
        echo 'Инвертировать изображение не удалось.';
    }

    ?>

Пример #5 Пример наложения фильтра функцией imagefilter() с фильтром pixelate

    <?php

    // Загрузка PHP логотипа, нам нужно 2 штуки
    // для сравнения
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Подопытный экземпляр
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Применение пикселирования к каждому изображению с размером блока в 3 пикселя
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Совмещение различий в выходном изображении
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Вывод различий
    header('Content-Type: image/png');
    imagepng($output);

    ?>

Вывод приведённого примера будет похож на:

Пример #6 Пример наложения фильтра функцией imagefilter() с фильтром scatter

    <?php

    // Загрузка изображения
    $logo = imagecreatefrompng('./php.png');

    // Применение очень мягкого эффекта рассеивания к изображению
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Вывов изображения с эффектом рассеивания
    header('Content-Type: image/png');
    imagepng($logo);

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание: Результат фильтра `IMG_FILTER_SCATTER` всегда случайный.

### Смотрите также

- imageconvolution() - Наложение искривляющей матрицы 3х3, используя коэффициент и смещение

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Отражает изображение по осям

### Описание

function imageflip(GdImage `$image`, int `$mode`): true

Функция отражает изображение `image` по горизонтали и (или) по вертикали. Направление отражения задаётся параметром `mode`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`mode`

  Режим отражения задаётся константой семейства `IMG_FLIP_*`:

  Константа | Описание
  --- | ---
  `IMG_FLIP_HORIZONTAL` | Переворачивает изображение по горизонтали.
  `IMG_FLIP_VERTICAL` | Переворачивает изображение по вертикали.
  `IMG_FLIP_BOTH` | Переворачивает изображение и по горизонтали, и по вертикали.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример отражения изображения по вертикали

В примере режим отражения определяет константа `IMG_FLIP_VERTICAL`.

    <?php

    // Файл
    $filename = 'phplogo.png';

    // Тип изображения
    header('Content-type: image/png');

    // Загрузка
    $im = imagecreatefrompng($filename);

    // Переворачиваем по вертикали
    imageflip($im, IMG_FLIP_VERTICAL);

    // Выводим изображение
    imagejpeg($im);

Вывод приведённого примера будет похож на:

Пример #2 Пример отражения изображения по горизонтали

В примере режим отражения определяет константа `IMG_FLIP_HORIZONTAL`.

    <?php

    // Файл
    $filename = 'phplogo.png';

    // Тип изображения
    header('Content-type: image/png');

    // Загрузка
    $im = imagecreatefrompng($filename);

    // Переворачиваем по горизонтали
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // Выводим изображение
    imagejpeg($im);

Вывод приведённого примера будет похож на:

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — Получение высоты шрифта

### Описание

function imagefontheight(GdFont|int `$font`): int

Возвращает высоту в пикселах символа заданного шрифта.

### Список параметров

`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().

### Возвращаемые значения

Возвращает высоту в пикселах.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).

### Примеры

Пример #1 Пример использования imagefontheight() на встроенных шрифтах

    <?php
    echo 'Font height: ' . imagefontheight(4);
    ?>

Вывод приведённого примера будет похож на:

    Font height: 16

Пример #2 Использование imagefontheight() вместе с imageloadfont()

    <?php
    // загрузка .gdf шрифта
    $font = imageloadfont('anonymous.gdf');

    echo 'Высота шрифта: ' . imagefontheight($font);
    ?>

Вывод приведённого примера будет похож на:

    Font height: 43

### Смотрите также

- imagefontwidth() - Получение ширины шрифта
- imageloadfont() - Загружает новый шрифт

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — Получение ширины шрифта

### Описание

function imagefontwidth(GdFont|int `$font`): int

Возвращает ширину символа шрифта.

### Список параметров

`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().

### Возвращаемые значения

Возвращает ширину в пикселах

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).

### Примеры

Пример #1 Использование imagefontwidth() на встроенных шрифтах

    <?php
    echo 'Ширина шрифта: ' . imagefontwidth(4);
    ?>

Вывод приведённого примера будет похож на:

    Font width: 8

Пример #2 Использование imagefontwidth() вместе с imageloadfont()

    <?php
    // загрузка .gdf шрифта
    $font = imageloadfont('anonymous.gdf');

    echo 'Ширина шрифта: ' . imagefontwidth($font);
    ?>

Вывод приведённого примера будет похож на:

    Font width: 23

### Смотрите также

- imagefontheight() - Получение высоты шрифта
- imageloadfont() - Загружает новый шрифт

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта

### Описание

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Функция рассчитывает и возвращает обрамляющую рамку в пикселях для текста, который выводится на экран библиотекой FreeType.

> Замечание:

> До PHP 8.0.0 функция imageftbbox() была расширенной версией функции imagettfbbox(), которая дополнительно поддерживала параметр `options`. Начиная с 8.0.0 функция imagettfbbox() стала псевдонимом функции imageftbbox().

### Список параметров

`size`

  Размер шрифта в типографских пунктах.

`angle`

  Угол в градусах, под которым функция измерит значение аргумента `string`.

`font_filename`

  Название файла TrueType-шрифта в виде локального пути или URL-адреса. В зависимости от версии библиотеки GD, с которой работает PHP, функция попытается найти файлы, названия которых не начинаются с символа '/', путём добавления к названию файла расширения '.ttf' и поиска по пути к шрифту, который определяет библиотека.

`string`

  Строка, которую требуется измерить.

`options`

  Возможные ключи массива `options`
  Ключ | Тип | Значение
  --- | --- | ---
  `linespacing` | float | Определяет межстрочный интервал при отрисовке

### Возвращаемые значения

Функция imageftbbox() возвращает массив из 8 элементов, которые представляют координаты четырёх точек — вершин рамки обрамления текста:

0 | нижний левый угол, координата X
1 | нижний левый угол, координата Y
2 | нижний правый угол, координата X
3 | нижний правый угол, координата Y
4 | верхний правый угол, координата X
5 | верхний правый угол, координата Y
6 | верхний левый угол, координата X
7 | верхний левый угол, координата Y

Точки располагаются относительно текста независимо от угла `angle`, поэтому «верхний левый» обозначает верхний левый угол, если смотреть на текст горизонтально.

Функция возвращает `false`, если возникла ошибка.

### Примеры

Пример #1 Пример определения границ обрамления функцией imageftbbox()

    <?php

    // Создание изображения размером 300x150
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Установка белого фона
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Установка пути к файлу шрифта
    $font = './arial.ttf';

    // Создание рамки вокруг текста
    $bbox = imageftbbox(10, 0, $font, 'Группа документирования языка PHP');

    // Установка координат для осей X и Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    imagefttext($im, 10, 0, $x, $y, $black, $font, 'Группа документирования языка PHP');

    // Вывод в браузер
    header('Content-Type: image/png');

    imagepng($im);

    ?>

### Примечания

> Замечание: Эта функция доступна только в случае, если PHP был скомпилирован с поддержкой freetype (--with-freetype-dir=DIR)

### Смотрите также

- imagefttext() - Наносит текст на изображение путём рендеринга шрифта библиотекой FreeType 2
- imagettfbbox() - Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — Наносит текст на изображение путём рендеринга шрифта библиотекой FreeType 2

### Описание

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> Замечание:

> До PHP 8.0.0 функция imagefttext() была расширенной версией функции imagettftext(), которая дополнительно поддерживала параметр `options`. Начиная с PHP 8.0.0 функция imagettftext() стала псевдонимом функции imagefttext().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`size`

  Размер шрифта в типографских пунктах.

`angle`

  Угол в градусах, 0 градусов обозначает расположение текста слева направо. Положительные значения обозначают поворот текста против часовой стрелки. Например, текст с поворотом на 90 градусов читается снизу вверх.

`x`

  Координаты `x` и `y` определяют отправную точку первого символа текста — приблизительно левый нижний угол символа. Определение базовой точки этой функцией отличается от функции imagestring(), в которой координаты `x` и `y` определяют верхний левый угол первого символа. Например, «верхнюю левую» точку определяют координаты 0, 0.

`y`

  y-координата. Это позиция базовой линии шрифта, в общем случае она не совпадает с низшей точкой в символе.

`color`

  Индекс цвета текста, см. описание функции imagecolorexact().

`font_filename`

  Путь к TrueType-шрифту.

  В зависимости от версии библиотеки GD, с которой работает PHP, если аргумент `font_filename` не начинается с символа `/`, функция добавит к названию файла расширение `.ttf`, и библиотека попытается найти это название файла по пути, который определяет библиотека.

  Часто расположение файла шрифта в каталоге скрипта исключает проблемы с включением файлов.

      <?php

      // Установка переменной окружения для модуля GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Название шрифта для написания текста. Обратите внимание, что название файла не содержит расширения .ttf
      $font = 'SomeFont';

      ?>

`text`

  Текст для вставки в изображение.

`options`

  Возможные значения ключей массива `options`
  Ключ | Тип | Значение
  --- | --- | ---
  `linespacing` | float | Определяет межстрочный интервал при отрисовке

### Возвращаемые значения

Функция возвращает массив, который определяет четыре точки обрамления начиная с нижнего левого угла и двигаясь против часовой стрелки:

0 | нижняя левая x-координата
1 | нижняя левая y-координата
2 | нижняя правая x-координата
3 | нижняя правая y-координата
4 | верхняя правая x-координата
5 | верхняя правая y-координата
6 | верхняя левая x-координата
7 | верхняя левая y-координата

Функция возвращает `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример отрисовки текста на изображении функцией imagefttext()

    <?php

    // Создание изображения размером 300x100
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Установка красного фона
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // Установка пути к ttf-файлу шрифта
    $font_file = './arial.ttf';

    // Отрисовка текста 'PHP Manual' шрифтом 13-го размера
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // Вывод изображения
    header('Content-Type: image/png');

    imagepng($im);

    ?>

### Примечания

> Замечание: Эта функция доступна только в случае, если PHP был скомпилирован с поддержкой freetype (--with-freetype-dir=DIR)

### Смотрите также

- imageftbbox() - Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
- imagettftext() - Рисует текст на изображении шрифтом TrueType

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — Применяет гамма-коррекцию к GD-изображению

### Описание

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

Функция применяет гамма-коррекцию к изображению `image` по заданным входным и выходным настройкам.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`input_gamma`

  Входная настройка гаммы.

`output_gamma`

  Выходная настройка гаммы.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример гамма-коррекции изображения функцией imagegammacorrect()

    <?php

    // Создаём изображение
    $im = imagecreatefromgif('php.gif');

    // Корректируем гамму, на выходе 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // Сохраняем изображение
    imagegif($im, './php_gamma_corrected.gif');

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — Выводит GD-изображение в браузер или файл

### Описание

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

Функция выводит или сохраняет изображение в формате GD, которое указали в параметре `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.3 | Параметр `file` теперь принимает значение `null`.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
7.2.0 | Функция imagegd() теперь разрешает выводить полноцветные truecolor-изображения. Раньше функция неявно преобразовывала такие изображения к палитре.

### Примеры

Пример #1 Пример вывода GD-изображения

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Выводим изображение
    imagegd($im);

    ?>

Пример #2 Пример сохранения GD-изображения

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Сохраняем GD-изображение.
    // Файлы GD-изображений сохраняют в формате .gd,
    // подробнее о формате файлов рассказывает страница http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');

    ?>

### Примечания

> Замечание:

> В формате GD часто быстро загружают части изображений. Обратите внимание, что формат GD поддерживают только GD-совместимые приложения.

Внимание

Форматы GD и GD2 — проприетарные форматы изображений библиотеки libgd. Форматы устарели и применяются только в целях разработки и тестирования.

### Смотрите также

- imagegd2() - Выводит GD2-изображение в браузер или файл

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — Выводит GD2-изображение в браузер или файл

### Описание

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

Функция выводит или сохраняет изображение `image` в формате GD2.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

`chunk_size`

  Размер части изображения.

`mode`

  Параметр принимает значение `IMG_GD2_RAW` или `IMG_GD2_COMPRESSED`. Значение по умолчанию равняется `IMG_GD2_RAW`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.3 | Параметр `file` теперь принимает значение `null`.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример вывода GD2-изображения

    <?php

    // Создание пустого изображения и добавление на него текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Простая Текстовая Строка", $text_color);

    // Вывод изображения
    imagegd2($im);

    ?>

Пример #2 Пример сохранения GD2-изображения

    <?php

    // Создание пустого изображения и добавление на него текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "Простая Текстовая Строка", $text_color);

    // Сохранение изображения
    // Файлы GD2-изображений сохраняют в формате .gd,
    // подробнее о формате файлов рассказывает страница http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');

    ?>

### Примечания

> Замечание:

> В формате GD2 часто быстро загружают части изображений. Обратите внимание, что формат GD2 поддерживают только GD2-совместимые приложения.

Внимание

Форматы GD и GD2 — проприетарные форматы изображений библиотеки libgd. Форматы устарели и применяются только в целях разработки и тестирования.

### Смотрите также

- imagegd() - Выводит GD-изображение в браузер или файл

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Получить отсекающий прямоугольник

### Описание

function imagegetclip(GdImage `$image`): array

imagegetclip() возвращает текущий отсекающий прямоугольник, т.е. область, за пределами которой не будут отрисовываться пиксели.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Функция возвращает индексированный массив с координатами отсекающим прямоугольником, который имеет следующие записи:

- x-координата верхнего левого угла
- y-координата верхнего левого угла
- x-координата нижнего правого угла
- y-координата нижнего правого угла

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagegetclip()

Установка и извлечение отсекающего прямоугольника.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

Результат выполнения приведённого примера:

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### Смотрите также

- imagesetclip() - Устанавливает прямоугольник отсечения

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Получает метод интерполяции

### Описание

function imagegetinterpolation(GdImage `$image`): int

Получает текущий установленный метод интерполяции `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Возвращает метод интерполяции.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Смотрите также

- imagesetinterpolation() - Устанавливает метод интерполяции

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — Выводит изображение в браузер или записывает в файл

### Описание

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

Функция imagegif() создаёт изображение в формате GIF в файле или ресурсе потока, который указали в аргументе `file`. Функция берёт за основу изображение `image`. Аргумент `image` — изображение, которое возвращает функция imagecreate() или функции семейства `imagecreatefrom*`.

Функция создаст файл в формате GIF87a, если только изображение не сделали прозрачным функцией imagecolortransparent(), тогда функция создаст изображение в формате GIF89a.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример вывода изображения функцией imagegif()

    <?php

    // Создание изображения
    $im = imagecreatetruecolor(100, 100);

    // Создание белого фона
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    // Отрисовка текста на изображении
    imagestring($im, 3, 40, 20, 'GD библиотека', 0xFFBA00);

    // Вывод изображения в браузер
    header('Content-Type: image/gif');

    imagegif($im);

    ?>

Пример #2 Пример преобразования PNG-изображения в формат GIF функцией imagegif()

    <?php

    // Загрузка PNG-файла
    $png = imagecreatefrompng('./php.png');

    // Сохранение файла в формате GIF
    imagegif($png, './php.gif');

    // Готово
    echo 'Преобразование PNG-файла в GIF-файл завершилось успешно!';

    ?>

### Примечания

> Замечание:

> Следующий фрагмент кода помогает писать переносимые PHP-приложения и автоматически определяет доступный тип GD-изображения. Замените строки `header ("Content-Type: image/gif"); imagegif ($im);` на более гибкую последовательность:

>     <?php

>     // Создание нового изображения
>     $im = imagecreatetruecolor(100, 100);

>     // Какие-либо операции с изображением

>     // Обработка вывода
>     if (function_exists('imagegif')) {
>         // Для GIF-файлов
>         header('Content-Type: image/gif');

>         imagegif($im);
>     } elseif (function_exists('imagejpeg')) {
>         // Для JPEG-файлов
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     } elseif (function_exists('imagepng')) {
>         // Для PNG-файлов
>         header('Content-Type: image/png');

>         imagepng($im);
>     } elseif (function_exists('imagewbmp')) {
>         // Для WBMP-файлов
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     } else {
>         die('На этом PHP-сервере нет поддержки изображений');
>     }

>     ?>

> Замечание:

> Проверить поддержку формата помогает функция imagetypes():

>     <?php

>     if (imagetypes() & IMG_GIF) {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     } elseif (imagetypes() & IMG_JPG) {
>         /* ... и т. д. */
>     }

>     ?>

### Смотрите также

- imagepng() - Выводит PNG-изображение в браузер или файл
- imagewbmp() - Выводит изображение в браузер или записывает в файл
- imagejpeg() - Выводит изображение в браузер или записывает в файл
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Захватывает изображение с экрана

### Описание

function imagegrabscreen(): GdImage|false

Функция делает скриншот.

> Замечание:

> Функция доступна только в ОС Windows.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).

### Примеры

Пример #1 Пример захвата экранного изображения функцией imagegrabscreen()

Пример показывает, как сделать снимок экрана и сохранить его как PNG-изображение.

    <?php

    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");

    ?>

### Смотрите также

- imagegrabwindow() - Захватывает изображение окна

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Захватывает изображение окна

### Описание

function imagegrabwindow(int `$handle`, bool `$client_area` = `false`): GdImage|false

Функция делает снимок окна или его клиентской части через Windows-дескриптор (свойство COM-объекта HWND).

> Замечание:

> Функция доступна только в ОС Windows.

### Список параметров

`handle`

  ID-идентификатор HWND-дескриптора окна.

`client_area`

  Включает клиентскую часть окна приложения.

### Возвращаемые значения

Функция возвращает объект изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Функция выдаёт ошибку уровня E_NOTICE выдаётся, если в аргументе `handle` передали недопустимый дескриптор окна. Функция выдаёт ошибку уровня E_WARNING, если API-интерфейс ОС Windows устарел.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).
8.0.0 | Параметр `client_area` теперь ожидает логическое значение bool; раньше ожидалось значение с типом int.

### Примеры

Пример #1 Пример захвата изображения окна функцией imagegrabwindow()

Захват окна, например браузера IE.

    <?php

    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $im = imagegrabwindow($handle);
    $browser->Quit();
    imagepng($im, "iesnap.png");

    ?>

Захват окна с содержимым, например браузера IE.

    <?php

    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $browser->Navigate("http://www.libgd.org");

    /* Браузер всё ещё работает? */
    while ($browser->Busy) {
        com_message_pump(4000);
    }

    $im = imagegrabwindow($handle, 0);
    $browser->Quit();
    imagepng($im, "iesnap.png");

    ?>

### Смотрите также

- imagegrabscreen() - Захватывает изображение с экрана

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — Включает или выключает интерлейсинг

### Описание

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

Функция imageinterlace() переключает состояние бита интерлейсинга.

Установка бита интерлейсинга для изображения в формате JPEG создаёт изображение в формате прогрессивного JPEG.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`enable`

  Со значением `true` изображение становится чересстрочным, со значением `false` бит интерлейсинга выключается. При передаче значения `null` поведение интерлейсинга не изменяется.

### Возвращаемые значения

При установке для изображения бита интерлейсинга функция возвращает `true`, иначе возвращает значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.5 | Функция imageinterlace() теперь возвращает значение с типом bool; раньше функция возвращала значение с типом int, ненулевое для изображений с интерлейсингом, иначе 0.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Параметр `enable` теперь ожидает значение с типом bool; раньше ожидалось значение с типом int.

### Примеры

Пример #1 Пример включения интерлейсинга функцией imageinterlace()

    <?php

    // Создание нового изображения
    $im = imagecreatefromgif('php.gif');

    // Включение интерлейсинга
    imageinterlace($im, true);

    // Сохранение изображения
    imagegif($im, './php_interlaced.gif');

    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — Определяет, относится ли изображение к изображениям truecolor

### Описание

function imageistruecolor(GdImage `$image`): bool

Функция imageistruecolor() определяет, относится ли изображение `image` к truecolor-изображениям.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Функция возвращает `true`, если изображение в аргументе `image` относится к изображениям с истинными цветами, иначе возвращает значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример простого определения принадлежности экземпляров изображения к truecolor-изображениям функцией imageistruecolor()

    <?php

    // Переменная $im — экземпляр изображения

    // Проверка изображения
    if (!imageistruecolor($im)) {
        // Создание нового экземпляра изображения с истинными цветами
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // Копирование поверх пикселей
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // или вызвать функцию imagepalettetotruecolor()
    }

    // Продолжить работу с экземпляром изображения

    ?>

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- imagepalettetotruecolor() - Преобразовывает изображение на основе палитры в настоящий цвет

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — Выводит изображение в браузер или записывает в файл

### Описание

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Функция imagejpeg() создаёт файл в формате JPEG из изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

`quality`

  Необязательный параметр, который принимает значения в диапазоне от 0 — низкое качество, файл меньшего размера, — до 100 для высокого качества при наибольшем размере файла. Значение по умолчанию равняется `-1` и устанавливает качество IJG по умолчанию — около 75.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример вывода JPEG-изображения в браузер

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Устанавливаем заголовок для типа содержимого image/jpeg
    header('Content-Type: image/jpeg');

    // Выводим изображение
    imagejpeg($im);

    ?>

Вывод приведённого примера будет похож на:

Пример #2 Пример сохранения JPEG-изображения в файл

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Сохраняем изображение в файл 'simpletext.jpg'
    imagejpeg($im, 'simpletext.jpg');

    ?>

Пример #3 Пример вывода JPEG-изображения в браузер с качеством 75 %

    <?php

    // Создаём пустое изображение и добавляем текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Устанавливаем заголовок для типа содержимого image/jpeg
    header('Content-Type: image/jpeg');

    // Передаём в параметр file значение NULL, чтобы пропустить его, и устанавливаем качество 75 %
    imagejpeg($im, NULL, 75);

    ?>

### Примечания

> Замечание:

> Для вывода данных в формате Progressive JPEG потребуется путём вызова функции imageinterlace() включить для изображения интерлейсинг.

### Смотрите также

- imagepng() - Выводит PNG-изображение в браузер или файл
- imagegif() - Выводит изображение в браузер или записывает в файл
- imagewbmp() - Выводит изображение в браузер или записывает в файл
- imageinterlace() - Включает или выключает интерлейсинг
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — Устанавливает флаг альфа-смешивания, чтобы создать эффекты наложения изображений

### Описание

function imagelayereffect(GdImage `$image`, int `$effect`): true

Функция устанавливает флаг альфа-смешивания, чтобы создать эффекты наложения изображений.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`effect`

  Константа из следующего списка:

  `IMG_EFFECT_REPLACE`
    Заменять пиксели; аналогично передаче `true` в функцию imagealphablending()
  `IMG_EFFECT_ALPHABLEND`
    Использовать обычное сопряжение цветов; аналогично передаче `false` в функцию imagealphablending()
  `IMG_EFFECT_NORMAL`
    Аналогична константе `IMG_EFFECT_ALPHABLEND`.
  `IMG_EFFECT_OVERLAY`
    В результате наложения картинки с этим эффектом чёрные и белые пиксели фона изображения останутся так же чёрными и белыми, а серые поменяют цвет на цвет пикселя накладываемого изображения.
  `IMG_EFFECT_MULTIPLY`
    Оверлеи с множителем эффекта.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
7.2.0 | Добавили эффект `IMG_EFFECT_MULTIPLY`; для работы эффекта требуется системная библиотека libgd >= 2.1.1 или библиотека libgd, которая входит в комплект исходных файлов интерпретатора.

### Примеры

Пример #1 Пример установки флага альфа-смешивания функцией imagelayereffect()

    <?php

    // Настраиваем изображение
    $im = imagecreatetruecolor(100, 100);

    // Устанавливаем фон
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Применяем флаг альфа-смешивания для наложения
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // Рисуем два серых эллипса
    imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
    imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
    imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — Рисует отрезок

### Описание

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Функция рисует линию между двумя точками.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x1`

  Координата первой точки по оси x.

`y1`

  Координата первой точки по оси y.

`x2`

  Координата второй точки по оси x.

`y2`

  Координата второй точки по оси y.

`color`

  Цвет линии. Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования жирной линии

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* Способ хорошо работает только с ортогональными прямыми
        imagesetthickness($image, $thick);
        return imageline($image, $x1, $y1, $x2, $y2, $color);
        */
        if ($thick == 1) {
            return imageline($image, $x1, $y1, $x2, $y2, $color);
        }

        $t = $thick / 2 - 0.5;
        if ($x1 == $x2 || $y1 == $y2) {
            return imagefilledrectangle(
                $image,
                round(min($x1, $x2) - $t),
                round(min($y1, $y2) - $t),
                round(max($x1, $x2) + $t),
                round(max($y1, $y2) + $t),
                $color
            );
        }

        $k = ($y2 - $y1) / ($x2 - $x1); // y = kx + q
        $a = $t / sqrt(1 + pow($k, 2));

        $points = array(
            round($x1 - (1 + $k) * $a),
            round($y1 + (1 - $k) * $a),
            round($x1 - (1 - $k) * $a),
            round($y1 - (1 + $k) * $a),
            round($x2 + (1 + $k) * $a),
            round($y2 - (1 - $k) * $a),
            round($x2 + (1 - $k) * $a),
            round($y2 + (1 + $k) * $a),
        );

        imagefilledpolygon($image, $points, 4, $color);

        return imagepolygon($image, $points, 4, $color);
    }

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- imagecolorallocate() - Создание цвета для изображения

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — Загружает новый шрифт

### Описание

function imageloadfont(string `$filename`): GdFont|false

Функция imageloadfont() загружает пользовательский битмап, новый шрифт, и возвращает его идентификатор.

### Список параметров

`filename`

  Формат файла шрифта двоичный и зависит от архитектуры системы. Это означает, что потребуется сгенерировать файл шрифта на том же типе процессора, на котором работает PHP.

  Формат файла шрифта
  Позиция байта | Тип данных C | Описание
  --- | --- | ---
  байты 0-3 | int | Количество символов в шрифте
  байты 4-7 | int | Значение первого символа в шрифте; часто 32 — пробел
  байты 8-11 | int | Ширина пикселя каждого символа
  байты 12-15 | int | Высота пикселя каждого символа
  байты 16- | char | Массив с данными символов, по одному байту на пиксель в каждом символе, всего (количество символов * ширина * высота) байтов.

### Возвращаемые значения

Функция возвращает экземпляр класса GdFont или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Функция теперь возвращает экземпляр класса GdFont; раньше возвращалось значение с типом int.

### Примеры

Пример #1 Пример загрузки нового шрифта функцией imageloadfont()

    <?php

    // Создаём новое изображение
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Устанавливаем белый фон
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // Загружаем GD-шрифт и наносим надпись 'Привет'
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, 'Привет', $black);

    // Выводим изображение
    header('Content-type: image/png');

    imagepng($im);

    ?>

### Смотрите также

- imagefontwidth() - Получение ширины шрифта
- imagefontheight() - Получение высоты шрифта
- imagestring() - Рисует строку текста горизонтально

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Рисует открытый полигон

### Описание

Сигнатура с PHP 8.0.0 (не поддерживается с именованными аргументами)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Альтернативная сигнатура (устарела с PHP 8.0.0)

function imageopenpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

Функция imageopenpolygon() рисует открытый полигон на изображении `image`. Функция не рисует линию между последней и первой точкой, в отличие от функции imagepolygon().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`points`

  Массив с вершинами многоугольника, например:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Общее число точек, вершин, в виде значения не меньше 3.

  При вызове функции согласно сигнатуре без этого параметра массив `points` должен содержать чётное количество элементов, тогда значение параметра `num_points` функция вычислит как `count($points) / 2`.
`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `num_points` устарел.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример отрисовки открытого полигона функцией imageopenpolygon()

    <?php

    // Создаём пустое изображение
    $image = imagecreatetruecolor(400, 300);

    // Выделяем цвет для полигона
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Отрисовываем полигон
    imageopenpolygon(
        $image,
        array(
            0,
            0,
            100,
            200,
            300,
            200
        ),
        $col_poly
    );

    // Выводим изображение в браузер
    header('Content-type: image/png');

    imagepng($image);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagepolygon() - Рисует многоугольник

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — Копирует палитру из одного изображения в другое

### Описание

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

Функция imagepalettecopy() копирует палитру цветов из изображения `src` в изображение `dst`.

### Список параметров

`dst`

  Объект результирующего изображения.

`src`

  Объект исходного изображения.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `dst` и `src` теперь ожидают экземпляр класса GdImage; раньше ожидался ресурс (resource).

### Примеры

Пример #1 Пример копирования палитры функцией imagepalettecopy()

    <?php

    // Создание двух палитровых изображений
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // Зелёный фон у первого изображения
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // Копирование палитры из 1-го изображения во 2-е
    imagepalettecopy($palette2, $palette1);

    // Поскольку палитра теперь скопирована, устанавливаем зелёный цвет,
    // выделенный первому изображению, не вызывая  функцию imagecolorallocate() дважды
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // Вывод изображения в броузер
    header('Content-type: image/png');

    imagepng($palette2);

    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — Преобразовывает изображение на основе палитры в настоящий цвет

### Описание

function imagepalettetotruecolor(GdImage `$image`): bool

Функция преобразовывает изображение на основе палитры, которое создали функцией наподобие imagecreate(), в изображение с истинным цветом, как это делает функция imagecreatetruecolor().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Функция возвращает `true`, если преобразование завершилось, или если исходное изображение уже относится к truecolor-изображению, иначе возвращает значение `false`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример преобразования объекта изображения в изображение с истинным цветом

    <?php

    // В целях обратной совместимости
    if (!function_exists('imagepalettetotruecolor')) {
        function imagepalettetotruecolor(&$src)
        {
            if (imageistruecolor($src)) {
                return (true);
            }

            $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

            imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));

            $src = $dst;

            return (true);
        }
    }

    // Анонимное замыкание-помощник
    $typeof = function () use ($im) {
        echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
    };

    // Создаём изображение на основе палитры
    $im = imagecreate(100, 100);
    $typeof();

    // Преобразуем цвета изображения к истинным
    imagepalettetotruecolor($im);
    $typeof();

    ?>

Результат выполнения приведённого примера:

    typeof($im) = palette
    typeof($im) = true color

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- imageistruecolor() - Определяет, относится ли изображение к изображениям truecolor

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — Выводит PNG-изображение в браузер или файл

### Описание

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

Функция выводит или сохраняет PNG изображение `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

  > Замечание:

  > Недопустимо передавать значение `null` без передачи аргументов `quality` и `filters`.

`quality`

  Уровень сжатия: от 0 до 9, где 0 обозначает — без сжатия. Значение по умолчанию равняется `-1` и устанавливает уровень сжатия библиотеки zlib по умолчанию. Дополнительную информацию даёт » руководство по библиотеке zlib.

`filters`

  Параметр разрешает уменьшить размер PNG-файла. Это поле битовой маски, которое принимает произвольную комбинацию констант семейства `PNG_FILTER_*`. Константа `PNG_NO_FILTER` отключает, а константа `PNG_ALL_FILTERS` включает все фильтры. Значение по умолчанию равняется `-1` и отключает фильтрацию.

  Предостережение

  Системная библиотека libgd игнорирует параметр `filters`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

    <?php

    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);

    ?>

### Смотрите также

- imagegif() - Выводит изображение в браузер или записывает в файл
- imagewbmp() - Выводит изображение в браузер или записывает в файл
- imagejpeg() - Выводит изображение в браузер или записывает в файл
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой
- imagesavealpha() - Определяет, сохранять ли полную информацию альфа-канала при сохранении изображений

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — Рисует многоугольник

### Описание

Сигнатура с PHP 8.0.0 (не поддерживается с именованными аргументами)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

Альтернативная сигнатура (устарела с PHP 8.1.0)

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

Функция imagepolygon() создаёт многоугольник в изображении `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`points`

  Массив вершин многоугольника:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Общее число точек, вершин, не меньше 3.

  При вызове функции согласно сигнатуре без этого параметра массив `points` должен содержать чётное количество элементов, тогда значение параметра `num_points` функция вычислит как `count($points) / 2`.
`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `num_points` устарел.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример отрисовки многоугольника функцией imagepolygon()

    <?php

    // Создаём пустое изображение
    $image = imagecreatetruecolor(400, 300);

    // Создаём цвет полигона
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Отрисовываем многоугольник
    imagepolygon(
        $image,
        array(
            0,
            0,
            100,
            200,
            300,
            200
        ),
        $col_poly
    );

    // Выводим изображение в браузер
    header('Content-type: image/png');

    imagepng($image);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagefilledpolygon() - Рисует закрашенный многоугольник
- imageopenpolygon() - Рисует открытый полигон
- imagecreate() - Создаёт новое палитровое изображение
- imagecreatetruecolor() - Создаёт новое truecolor-изображение

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — Рисует прямоугольник

### Описание

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Функция imagerectangle() создаёт прямоугольник. Положение фигуры задаётся координатами противоположных углов. Точка с координатами 0, 0 соответствует верхнему левому углу изображения.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x1`

  Координата верхнего левого угла по оси x.

`y1`

  Координата верхнего левого угла по оси y.

`x2`

  Координата нижнего правого угла по оси x.

`y2`

  Координата нижнего правого угла по оси y.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример отрисовки прямоугольника функцией imagerectangle()

    <?php

    // Создаём изображение размером 200 на 200 пикселей
    $canvas = imagecreatetruecolor(200, 200);

    // Создаём цвета
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // Отрисовываем разноцветные прямоугольники
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);

Вывод приведённого примера будет похож на:

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Получает или устанавливает разрешение изображения

### Описание

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

Функция imageresolution() устанавливает или получает разрешение изображения в точках на дюйм (англ. dots per inch, сокр. DPI). При передаче в необязательные параметры значения `null` возвращается индексный массив со значениями текущего разрешения. При установке только параметра `resolution_x` функция добавит в метаданные одинаковое разрешение по горизонтали и вертикали. При установке двух параметров — один определяет горизонтальное, а другой вертикальное разрешение.

Разрешение сохраняется только как метаданные, которые доступны при чтении или записи изображений в форматы, которые поддерживают такой вид информации: PNG и JPEG. Изменение разрешения функцией не влияет на операции рисования. Разрешение по умолчанию для новых изображений — 96 DPI.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`resolution_x`

  Горизонтальное разрешение в DPI.

`resolution_y`

  Вертикальное разрешение в DPI.

### Возвращаемые значения

При вызове для получения информации о разрешении изображения функция возвращает индексный массив с информацией о горизонтальном и вертикальном разрешении, если выполнилась успешно, или `false`, если возникла ошибка. При вызове для установки разрешения изображения функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `resolution_x` и `resolution_y` теперь принимают значение `null`.

### Примеры

Пример #1 Пример установки и получения разрешения изображения

    <?php

    $im = imagecreatetruecolor(100, 100);

    imageresolution($im, 200);
    print_r(imageresolution($im));

    imageresolution($im, 300, 72);
    print_r(imageresolution($im));

Результат выполнения приведённого примера:

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — Поворачивает изображение с заданным углом

### Описание

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

Функция поворачивает изображение `image` на заданный аргументом `angle` угол в градусах.

Центр поворота — центр изображения. Поворачиваемое изображение иногда отличается размером от оригинала.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`angle`

  Угол поворота в градусах против часовой стрелки.

`background_color`

  Цвет фона свободной зоны после поворота.

### Возвращаемые значения

Функция возвращает объект повёрнутого изображения, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.3.0 | Удалили ненужный параметр `ignore_transparent`.
8.0.0 | Функция теперь возвращает экземпляр класса GDImage, если выполнилась успешно; раньше возвращался ресурс (resource).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Ненужный параметр `v` теперь ожидает значение с типом bool; раньше ожидалось значение с типом int.

### Примеры

Пример #1 Пример поворота изображения на 180 градусов

Пример поворачивает изображение на 180 градусов — вниз головой.

    <?php

    // Определяем название файла и угол поворота
    $filename = 'test.jpg';
    $degrees = 180;

    // Указываем тип содержимого
    header('Content-type: image/jpeg');

    // Загружаем изображение
    $source = imagecreatefromjpeg($filename);

    // Поворачиваем изображение
    $rotate = imagerotate($source, $degrees, 0);

    // Выводим изображение
    imagejpeg($rotate);

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание: Эта функция подвержена влиянию метода интерполяции, установленным функцией imagesetinterpolation().

### Смотрите также

- imagesetinterpolation() - Устанавливает метод интерполяции

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — Определяет, сохранять ли полную информацию альфа-канала при сохранении изображений

### Описание

function imagesavealpha(GdImage `$image`, bool `$enable`): true

Функция imagesavealpha() устанавливает флаг, который определяет, сохранится ли вместо одноцветной прозрачности полная информация альфа-канала, и сохраняет изображение. Установка флага поддерживается только для форматов изображений, которые содержат полную информацию об альфа-канале: `PNG`, `WebP` и `AVIF`.

> Замечание: Функцию imagesavealpha() вызывают только на изображениях в формате `PNG`, поскольку для форматов `WebP` и `AVIF` всегда сохраняется полный альфа-канал. Полагаться на поведение функции не рекомендуют из-за возможного изменения поведения в новых версиях. Поэтому функцию imagesavealpha() принудительно вызывают и на изображениях в форматах `WebP` и `AVIF`.

Для приоритетного сохранения альфа-канала потребуется отключить альфа-смешивание вызовом `imagealphablending($im, false)`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`enable`

  Параметр определяет, сохранять ли альфа-канал. Значение по умолчанию равняется `false`.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример настройки сохранения полной информации альфа-канала при сохранении изображения функцией imagesavealpha()

    <?php

    // Загрузка PNG-изображения с альфа-каналом
    $png = imagecreatefrompng('./alphachannel_example.png');

    // Выключение альфа-смешения
    imagealphablending($png, false);

    // Какие-то операции

    // Установка альфа-флага
    imagesavealpha($png, true);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/png');
    imagepng($png);

### Смотрите также

- imagealphablending() - Устанавливает режим сопряжения цветов для изображения

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Масштабировать изображение по заданной ширине и высоте

### Описание

function imagescale(
GdImage `$image`,
int `$width`,
int `$height` = -1,
int `$mode` = `IMG_BILINEAR_FIXED`
): GdImage|false

imagescale() масштабирует изображение, используя заданный алгоритм интерполяции.

> Замечание:

> В отличие от многих функций по работе с изображениями, imagescale() не изменяет переданный параметр `image`; вместо него будет возвращено новое изображение.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`width`

  Ширина для масштабирования.

`height`

  Высота для масштабирования изображения. Если этот параметр опущен или отрицателен, соотношение сторон будет сохранено.

`mode`

  Одна из констант `IMG_NEAREST_NEIGHBOUR`, `IMG_BILINEAR_FIXED`, `IMG_BICUBIC`, `IMG_BICUBIC_FIXED` или что-либо ещё (будет использовано два прохода).

  > Замечание: `IMG_WEIGHTED4` пока ещё не поддерживается.

### Возвращаемые значения

Возвращает объект масштабированного изображения в случае успешного выполнения или `false`, если возникла ошибка.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `width` или `height` приведёт к переполнению или недополнению.

Функция выбрасывает ошибку ValueError, если значение параметра `mode` некорректно.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `width` или `height` приведёт к переполнению или недополнению.
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `mode` некорректно.
8.0.0 | В случае успешного выполнения функция теперь возвращает экземпляр GDImage; ранее возвращался ресурс (resource).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Смотрите также

- imagecopyresized() - Копирует и изменяет размер части изображения
- imagecopyresampled() - Копирует и изменяет размер части изображения с ресемплированием

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — Устанавливает изображение кисти для рисования линий

### Описание

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

Функция imagesetbrush() устанавливает изображение кисти, которым функции наподобие imageline() и imagepolygon() рисуют линии в режимах `IMG_COLOR_BRUSHED` или `IMG_COLOR_STYLEDBRUSHED`.

Предостережение

Дополнительных действий после завершения работы с кистью не требуется, но при уничтожении изображения кисти рисовать цветами `IMG_COLOR_BRUSHED` или `IMG_COLOR_STYLEDBRUSHED` до установки нового изображения кисти нельзя!

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`brush`

  Объект изображения кисти.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `image` и `brush` теперь принимают объект GdImage; раньше принимался тип resource.

### Примеры

Пример #1 Пример установки изображения кисти функцией imagesetbrush()

    <?php

    // Загружаем минилоготип php
    $php = imagecreatefrompng('./php.png');

    // Создаём главное изображение размером 100 на 100 пикселей
    $im = imagecreatetruecolor(100, 100);

    // Заливаем фон белым цветом
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 99, 99, $white);

    // Устанавливаем кисть
    imagesetbrush($im, $php);

    // Рисуем кистью пару мазков, один поверх другого
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Устанавливает прямоугольник отсечения

### Описание

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

Функция imagesetclip() задаёт текущий прямоугольник отсечения — область, за пределами которой функция не станет рисовать пиксели.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x1`

  Координата верхнего левого угла по оси x.

`y1`

  Координата верхнего левого угла по оси y.

`x2`

  Координата нижнего правого угла по оси x.

`y2`

  Координата нижнего правого угла по оси y.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Смотрите также

- imagegetclip() - Получить отсекающий прямоугольник

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Устанавливает метод интерполяции

### Описание

function imagesetinterpolation(GdImage `$image`, int `$method` = `IMG_BILINEAR_FIXED`): bool

Устанавливает метод интерполяции, установка метода интерполяции влияет на отображение различных функций в GD, таких как функция imagerotate().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`method`

  Метод интерполяции, который может быть одним из следующих:

  - `IMG_BELL`: Фильтр Белла.
  - `IMG_BESSEL`: Фильтр Бесселя.
  - `IMG_BICUBIC`: Бикубическая интерполяция.
  - `IMG_BICUBIC_FIXED`: Фиксированная точка реализации бикубической интерполяции.
  - `IMG_BILINEAR_FIXED`: Реализация билинейной интерполяции с фиксированной запятой (`по умолчанию (также при создании изображения)`).
  - `IMG_BLACKMAN`: Оконная функция Блэкмана.
  - `IMG_BOX`: Фильтр Коробка размытия.
  - `IMG_BSPLINE`: Сплайн-интерполяция.
  - `IMG_CATMULLROM`: Кубическая эрмитовая сплайн-интерполяция.
  - `IMG_GAUSSIAN`: Гауссова функция.
  - `IMG_GENERALIZED_CUBIC`: Обобщённая кубическая сплайн-фрактальная интерполяция.
  - `IMG_HERMITE`: Интерполяция Эрмита.
  - `IMG_HAMMING`: Фильтр Хэмминга.
  - `IMG_HANNING`: Фильтр Хеннинга.
  - `IMG_MITCHELL`: Фильтр Митчелла.
  - `IMG_POWER`: Степенная интерполяция.
  - `IMG_QUADRATIC`: Обратная квадратичная интерполяция.
  - `IMG_SINC`: Синк функция.
  - `IMG_NEAREST_NEIGHBOUR`: Интерполяция ближайшего соседа.
  - `IMG_WEIGHTED4`: Весовой фильтр.
  - `IMG_TRIANGLE`: Треугольная интерполяция.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagesetinterpolation()

    <?php
    // Загрузка изображения
    $im = imagecreate(500, 500);

    // По умолчанию интерполяция IMG_BILINEAR_FIXED, переключитесь
    // на использование фильтра 'Митчелла':
    imagesetinterpolation($im, IMG_MITCHELL);

    // Continue to work with $im ...
    ?>

### Примечания

Изменение метода интерполяции влияет на следующие функции при отображении:

- imageaffine()
- imagerotate()

### Смотрите также

- imagegetinterpolation() - Получает метод интерполяции

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — Рисует точку

### Описание

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Функция imagesetpixel() рисует точку, или пиксель, по заданным координатам.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`x`

  Координата по оси x.

`y`

  Координата по оси y.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример рисования точки функцией imagesetpixel()

Рисование случайными точками, которое в итоге создаёт фрактальное изображение.

    <?php

    $x = 200;
    $y = 200;

    $gd = imagecreatetruecolor($x, $y);

    $corners[0] = array('x' => 100, 'y' =>  10);
    $corners[1] = array('x' =>   0, 'y' => 190);
    $corners[2] = array('x' => 200, 'y' => 190);

    $red = imagecolorallocate($gd, 255, 0, 0);

    for ($i = 0; $i < 100000; $i++) {
        imagesetpixel($gd, round($x), round($y), $red);
        $a = rand(0, 2);
        $x = ($x + $corners[$a]['x']) / 2;
        $y = ($y + $corners[$a]['y']) / 2;
    }

    header('Content-Type: image/png');
    imagepng($gd);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- imagecolorallocate() - Создание цвета для изображения
- imagecolorat() - Получение индекса цвета пиксела

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — Устанавливает стиль рисования линий

### Описание

function imagesetstyle(GdImage `$image`, array `$style`): bool

Функция imagesetstyle() устанавливает стиль, который будут использовать функции рисования линий наподобие imageline() и imagepolygon() при установке специального цвета `IMG_COLOR_STYLED` или `IMG_COLOR_STYLEDBRUSHED`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`style`

  Массив с цветами пикселей. Параметр принимает константу `IMG_COLOR_TRANSPARENT` для добавления прозрачной точки. Обратите внимание, что нельзя передавать в параметр `style` пустой массив.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Примеры

Следующий пример рисует пунктирную линию из левого верхнего угла изображения в правый нижний:

Пример #1 Пример установки стиля рисования линий функцией imagesetstyle()

    <?php

    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* Рисование пунктирной линии, 5 красных точек, 5 белых */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* Рисование линии из смайликов функциями imagesetbrush() с imagesetstyle() */
    $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
    imagesetstyle($im, $style);

    $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
    $w2 = imagecolorallocate($brush, 255, 255, 255);
    imagecolortransparent($brush, $w2);
    imagesetbrush($im, $brush);
    imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

    imagejpeg($im);

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- imagesetbrush() - Устанавливает изображение кисти для рисования линий
- imageline() - Рисует отрезок

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — Устанавливает толщину линий

### Описание

function imagesetthickness(GdImage `$image`, int `$thickness`): true

Функция imagesetthickness() через параметр `thickness` устанавливает значение толщины линий для рисования прямоугольников, многоугольников, дуг и других фигур в пикселях.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`thickness`

  Толщина линии в пикселах.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример установки толщины линий функцией imagesetthickness()

    <?php

    // Создаём изображение размером 200 на 100 пикселей
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Устанавливаем белый фон
    imagefilledrectangle($im, 0, 0, 199, 99, $white);

    // Устанавливаем толщину линий на 5 пикселей
    imagesetthickness($im, 5);

    // Отрисовываем прямоугольник
    imagerectangle($im, 14, 14, 185, 85, $black);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — Устанавливает изображение как элемент мозаичной заливки

### Описание

function imagesettile(GdImage `$image`, GdImage `$tile`): true

Функция imagesettile() устанавливает изображение как элемент мозаичной заливки, которым функции наподобие imagefill() или imagefilledpolygon() станут заливать области в режиме `IMG_COLOR_TILED`.

Плитка — объект изображения для замащивания областей изображения повторяющимся узором. В качестве плитки функция принимает произвольное GD-изображение. А при установке для изображения плитки индекса прозрачного цвета функцией imagecolortransparent() отдельные части нижележащей области станут просвечивать через мозаику, которую создаст функция.

Предостережение

Дополнительных действий после завершения работы с мозаичным элементом не требуется, но при уничтожении или разрешении PHP уничтожить изображение плитки рисовать цветом `IMG_COLOR_TILED` до установки нового изображения плитки нельзя!

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`tile`

  Объект изображения для установки элемента мозаики.

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметры `image` и `tile` теперь принимают объект GdImage; раньше принимался тип resource.

### Примеры

Пример #1 Пример установки изображения в качестве элемента мозаичной заливки функцией imagesettile()

    <?php

    // Загружаем внешнее изображение
    $zend = imagecreatefromgif('./zend.gif');

    // Создаём изображение размером 200 на 200 пикселей
    $im = imagecreatetruecolor(200, 200);

    // Устанавливаем мозаичный элемент
    imagesettile($im, $zend);

    // Заливаем область
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-Type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — Рисует строку текста горизонтально

### Описание

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Функция рисует текст `string` по заданным координатам.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().
`x`

  Координата верхнего левого угла по оси x.

`y`

  Координата верхнего левого угла по оси y.

`string`

  Строка текста.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример горизонтальной отрисовки строки текста функцией imagestring()

    <?php

    // Создаём изображение размером 100 на 30 пикселей
    $im = imagecreate(100, 30);

    // Устанавливаем белый фон и синий текст
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textcolor = imagecolorallocate($im, 0, 0, 255);

    // Наносим надпись в левом верхнем углу
    imagestring($im, 5, 0, 0, 'Hello world!', $textcolor);

    // Устанавливаем заголовок с MIME-типом изображения и выводим результат
    header('Content-type: image/png');
    imagepng($im);

Вывод приведённого примера будет похож на:

### Смотрите также

- imagestringup() - Рисует строку текста вертикально
- imageloadfont() - Загружает новый шрифт
- imagettftext() - Рисует текст на изображении шрифтом TrueType

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — Рисует строку текста вертикально

### Описание

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Функция рисует текст `string` вертикально по заданным координатам.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`font`
  Принимает значения 1, 2, 3, 4, 5 для встроенных шрифтов в кодировке latin2 (более высокое число соответствует большему шрифту) или экземпляр класса GdFont, который возвращает функция imageloadfont().
`x`

  Координата нижнего левого угла по оси x.

`y`

  Координата нижнего левого угла по оси y.

`string`

  Текст надписи.

`color`

  Идентификатор цвета, который добавила в палитру изображения функция imagecolorallocate().

### Возвращаемые значения

Функция возвращает логическое значение `true`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Параметр `font` теперь принимает как экземпляр класса GdFont, так и целое число (int); раньше параметр принимал только целое число (int).
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример вертикальной отрисовки строки текста функцией imagestringup()

    <?php

    // Создаём изображение размером 100 на 100 пикселей
    $im = imagecreatetruecolor(100, 100);

    // Наносим надпись
    $textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

    // Сохраняем изображение
    imagepng($im, './stringup.png');

Вывод приведённого примера будет похож на:

### Смотрите также

- imagestring() - Рисует строку текста горизонтально
- imageloadfont() - Загружает новый шрифт

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — Получение ширины изображения

### Описание

function imagesx(GdImage `$image`): int

Возвращает ширину заданного изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Возвращает ширину изображения `image`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagesx()

    <?php

    // создание изображения 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- getimagesize() - Получает размер изображения
- imagesy() - Получение высоты изображения

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — Получение высоты изображения

### Описание

function imagesy(GdImage `$image`): int

Возвращает высоту заданного изображения `image`.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.

### Возвращаемые значения

Возвращает высоту изображения `image`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример использования imagesy()

    <?php

    // Создание изображения 300*200
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### Смотрите также

- imagecreatetruecolor() - Создаёт новое truecolor-изображение
- getimagesize() - Получает размер изображения
- imagesx() - Получение ширины изображения

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — Преобразовывает truecolor-изображение в палитровое

### Описание

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

Функция imagetruecolortopalette() преобразовывает truecolor-изображение в палитровое. Код этой функции взяли из кода библиотеки Независимой Группы JPEG. Код модифицировали, чтобы сохранялось максимальное количество информации об альфа-компонентах цветов, и передавались цвета в лучшем виде, насколько это возможно. Но в итоге код работает не так хорошо, планировали. Поэтому функцию вызывают для вывода truecolor-изображений, она гарантирует самое высокое качество вывода. Но не больше того.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`dither`

  Со значением `true` изображение сглаживается. Сглаживание увеличивает шумность картинки, но в то же время даёт лучшую передачу цветов.

`num_colors`

  Задаёт максимальное количество цветов в палитре.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример преобразования truecolor-изображения в палитровое

    <?php

    // Создание truecolor-изображения
    $im = imagecreatetruecolor(100, 100);

    // Преобразование изображения в палитровое с 255 цветами без сглаживания
    imagetruecolortopalette($im, false, 255);

    // Сохранение изображения
    imagepng($im, './paletteimage.png');

    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта

### Описание

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Функция рассчитывает и возвращает обрамляющую рамку в пикселях для текста, который выводится на экран библиотекой FreeType.

> Замечание:

> До PHP 8.0.0 функция imageftbbox() была расширенной версией функции imagettfbbox(), которая дополнительно поддерживала параметр `extrainfo`. Начиная с 8.0.0 функция imagettfbbox() стала псевдонимом функции imageftbbox().

### Список параметров

`size`

  Размер шрифта в типографских пунктах.

`angle`

  Угол в градусах, под которым функция измерит значение аргумента `string`.

`fontfile`
  Путь к шрифту TrueType, который вы хотите использовать. В зависимости от того, какая библиотека GD загружена в PHP, если параметр `fontfile` не начинается с символа `/`, то к имени файла будет добавлено расширение `.ttf` и библиотека будет пытаться искать это имя файла по определённому библиотекой пути шрифтов. При работе с версиями библиотеки GD ниже 2.0.18 как «разделитель путей» для отдельных файлов шрифтов использовался символ `пробела`, а не точка с запятой. Непреднамеренное использование этой особенности приведёт к предупреждению: `Warning: Could not find/open font`. Единственное решение для этих версий библиотек — переместить файлы шрифтов в директорию, имя которой не содержит пробелов.

  Часто, когда шрифт лежит в том же каталоге, что и скрипт PHP, который работает с этим шрифтом, помогает следующий трюк.

      <?php

      // Установка переменной окружения для GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Имя шрифта для использования (обратите внимание, что расширение .ttf не указывается)
      $font = 'SomeFont';

  > Замечание: Обратите внимание, что open_basedir не применяется к `fontfile`.

`string`

  Строка, которую требуется измерить.

`options`

  Параметр аналогичен параметру функции imagettftext().

### Возвращаемые значения

Функция imagettfbbox() возвращает массив из 8 элементов, которые представляют координаты четырёх точек — вершин рамки обрамления текста, если выполнилась успешно, и `false`, если возникла ошибка.

ключ | содержимое
--- | ---
0 | нижний левый угол, координата X
1 | нижний левый угол, координата Y
2 | нижний правый угол, координата X
3 | нижний правый угол, координата Y
4 | верхний правый угол, координата X
5 | верхний правый угол, координата Y
6 | верхний левый угол, координата X
7 | верхний левый угол, Y координата

Точки располагаются относительно текста независимо от угла `angle`, поэтому «верхний левый» обозначает верхний левый угол, если смотреть на текст горизонтально.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Добавили параметр `options`.

### Примеры

Пример #1 Пример определения границ обрамления функцией imagettfbbox()

    <?php

    // Создаём изображение размером 300x150
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Устанавливаем белый фон
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Указываем путь к файлу шрифта
    $font = './arial.ttf';

    // Создаём рамку для текста
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // Устанавливаем координаты для осей X и Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Отрисовываем текст
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // Создаём другую рамку для другого текста
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // Задаём координаты так, чтобы текст шёл сразу за первой надписью
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Наносим вторую надпись
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // Выводим в браузер
    header('Content-Type: image/png');

    imagepng($im);

    ?>

### Примечания

> Замечание: Эта функция доступна только в случае, если PHP был скомпилирован с поддержкой freetype (--with-freetype-dir=DIR)

### Смотрите также

- imagettftext() - Рисует текст на изображении шрифтом TrueType
- imageftbbox() - Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — Рисует текст на изображении шрифтом TrueType

### Описание

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

Функция наносит текст `text` поверх изображения шрифтом TrueType.

> Замечание:

> До PHP 8.0.0 функция imagefttext() была расширенной версией функции imagettftext(), которая дополнительно поддерживала параметр `extrainfo`. Начиная с 8.0.0 функция imagettftext() стала псевдонимом функции imagefttext().

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`size`

  Размер шрифта в типографских пунктах.

`angle`

  Угол в градусах, 0 градусов обозначает расположение текста слева направо. Положительные значения означают поворот текста против часовой стрелки. Например, текст, который повернули на 90 градусов, потребуется читать снизу вверх.

`x`

  Координаты `x` и `y` определяют отправную точку первого символа текста — приблизительно левый нижний угол символа. Определение базовой точки этой функцией отличается от функции imagestring(), в которой координаты `x` и `y` определяют верхний левый угол первого символа. Например, «верхнюю левую» точку определяют координаты 0, 0.

`y`

  y-координата. Это позиция базовой линии шрифта, в общем случае она не совпадает с низшей точкой в символе.

`color`

  Индекс цвета. Отрицательный индекс цвета отключает сглаживание. Смотрите описание функции imagecolorallocate().

`fontfile`
  Путь к шрифту TrueType, который вы хотите использовать. В зависимости от того, какая библиотека GD загружена в PHP, если параметр `fontfile` не начинается с символа `/`, то к имени файла будет добавлено расширение `.ttf` и библиотека будет пытаться искать это имя файла по определённому библиотекой пути шрифтов. При работе с версиями библиотеки GD ниже 2.0.18 как «разделитель путей» для отдельных файлов шрифтов использовался символ `пробела`, а не точка с запятой. Непреднамеренное использование этой особенности приведёт к предупреждению: `Warning: Could not find/open font`. Единственное решение для этих версий библиотек — переместить файлы шрифтов в директорию, имя которой не содержит пробелов.

  Часто, когда шрифт лежит в том же каталоге, что и скрипт PHP, который работает с этим шрифтом, помогает следующий трюк.

      <?php

      // Установка переменной окружения для GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Имя шрифта для использования (обратите внимание, что расширение .ttf не указывается)
      $font = 'SomeFont';

  > Замечание: Обратите внимание, что open_basedir не применяется к `fontfile`.

`text`

  Текстовая строка в кодировке UTF-8.

  Для доступа к символам шрифта за пределом 127-й позиции в аргумент включают ссылки на десятичные цифровые символы в форме `&#8364;`. Параметр поддерживает шестнадцатеричный формат наподобие `&#xA9;`. Строки в кодировке UTF-8 передаются без преобразования.

  Именованные сущности наподобие `&copy;` не поддерживаются. Такие именованные сущности декодируют в строку в кодировке UTF-8 функцией html_entity_decode().

  Функция нарисует незакрашенный прямоугольник вместо символа, если шрифт не поддерживает символ в строке.

`options`

  Массив с ключом `linespacing`, который содержит значение float.

### Возвращаемые значения

Функция возвращает массив из 8 элементов, которые представляют координаты четырёх точек — вершин рамки обрамления текста. Массив представляет точки в следующем порядке: нижний левый, нижний правый, верхний правый, верхний левый угол. Точки относятся к тексту независимо от угла, поэтому «верхний левый» обозначает верхний левый угол, если смотреть на текст горизонтально. Функция возвращает `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Добавили параметр `options`.

### Примеры

Пример #1 Пример отрисовки текста функцией imagettftext()

Пример создаст изображение в формате PNG с белым фоном размером 400x30 пикселей и надписью "Тест..." черным цветом (с серой тенью) шрифтом Arial.

    <?php

    // Тип содержимого
    header('Content-Type: image/png');

    // Создание изображения
    $im = imagecreatetruecolor(400, 30);

    // Создание цветов
    $white = imagecolorallocate($im, 255, 255, 255);
    $grey = imagecolorallocate($im, 128, 128, 128);
    $black = imagecolorallocate($im, 0, 0, 0);
    imagefilledrectangle($im, 0, 0, 399, 29, $white);

    // Текст надписи
    $text = 'Тест...';

    // Замена пути к шрифту на пользовательский
    $font = 'arial.ttf';

    // Тень
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // Текст
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    imagepng($im);

    ?>

Вывод приведённого примера будет похож на:

### Примечания

> Замечание: Эта функция доступна только в случае, если PHP был скомпилирован с поддержкой freetype (--with-freetype-dir=DIR)

### Смотрите также

- imagettfbbox() - Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
- imagefttext() - Наносит текст на изображение путём рендеринга шрифта библиотекой FreeType 2
- imagestring() - Рисует строку текста горизонтально

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — Возвращает список типов изображений, поддерживаемых PHP сборкой

### Описание

function imagetypes(): int

Возвращает типы поддерживаемых текущей сборкой PHP изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает битовое поле соответствующее форматам изображений, которые поддерживаются текущей версией GD прилинкованной к PHP. Возвращаются следующие биты: `IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### Список изменений

Версия | Описание
--- | ---
8.1.0 | Добавлена константа `IMG_AVIF`.
7.2.0 | Добавлена константа `IMG_BMP`.
7.0.10 | Добавлена константа `IMG_WEBP`.

### Примеры

Пример #1 Проверка поддержки PNG

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "Поддержка PNG включена";
    }
    ?>

### Смотрите также

- gd_info() - Вывод информации о текущей установленной GD библиотеке

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — Выводит изображение в браузер или записывает в файл

### Описание

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

Функция imagewbmp() выводит или сохраняет изображение `image` в формате WBMP.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

`foreground_color`

  Параметр устанавливает цвет переднего плана путём установки идентификатора, который возвращает функция imagecolorallocate(). Цвет переднего плана по умолчанию — чёрный.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Параметр `foreground_color` теперь принимает значение `null`.

### Примеры

Пример #1 Пример вывода WBMP-изображения

    <?php

    // Создание пустого изображения и добавление текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Простая текстовая строка', $text_color);

    // Установка заголовка для типа содержимого image/vnd.wap.wbmp
    // Подсказка: смотрите описание типов содержимого на странице функции image_type_to_mime_type()
    header('Content-Type: image/vnd.wap.wbmp');

    // Вывод изображения
    imagewbmp($im);

    ?>

Пример #2 Пример сохранения WBMP-изображения

    <?php

    // Создание пустого изображения и добавление текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Простая текстовая строка', $text_color);

    // Сохранение изображения
    imagewbmp($im, 'simpletext.wbmp');

    ?>

Пример #3 Пример вывода изображения с изменённым верхним слоем

    <?php

    // Создание пустого изображения и добавление текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Простая текстовая строка', $text_color);

    // Установка заголовка для типа содержимого image/vnd.wap.wbmp
    // Подсказка: смотрите описание типов содержимого на странице функции image_type_to_mime_type()
    header('Content-Type: image/vnd.wap.wbmp');

    // Замена цвета
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);

    ?>

### Смотрите также

- image2wbmp() - Выводит изображение в браузер или записывает в файл
- imagepng() - Выводит PNG-изображение в браузер или файл
- imagegif() - Выводит изображение в браузер или записывает в файл
- imagejpeg() - Выводит изображение в браузер или записывает в файл
- imagetypes() - Возвращает список типов изображений, поддерживаемых PHP сборкой

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — Вывод WebP-изображение в браузер или файл

### Описание

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Функция выводит или сохраняет изображение `image` в формате WebP.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`file`

  Путь или ресурс открытого потока, который функция автоматически закрывает после возврата значения, для сохранения файла. Функция выведет поток необработанного изображения напрямую, если параметр не установили или передали в аргументе значение `null`.

`quality`

  Параметр `quality` определяет качество изображения и принимает значения в диапазоне от 0 для худшего качества, но меньшего размера файла, до 100 для наилучшего качества, но с наибольшим размером файла. При передаче значения `-1` для качества изображения устанавливается значение по умолчанию — `80`.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Ошибки

Функция выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Функция теперь выбрасывает ошибку ValueError, если значение параметра `quality` недопустимо.
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).

### Примеры

Пример #1 Пример сохранения WebP-файла

    <?php

    // Создать пустое изображение и добавить текст
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP with PHP', $text_color);

    // Сохранить изображение
    imagewebp($im, 'php.webp');

    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — Выводит XBM-изображение в браузер или в файл

### Описание

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

Функция выводит или сохраняет XBM-версию изображения `image`.

> Замечание: Функция imagexbm() не применяет отступов, поэтому ширина изображения должна быть кратна 8. Начиная с PHP 7.0.9 функция больше не применяет это ограничение.

### Список параметров

`image`
  Объект GdImage, который вернула функция imagecreatetruecolor() или другая функция генерации изображений.
`filename`

  Путь в виде значения с типом string, по которому требуется сохранить файл. Со значением `null` функция выведет поток необработанного изображения напрямую.

  По названию файла в аргументе `filename` без расширения .xbm функция также строит C-идентификаторы XBM-файла, при этом небуквенно-цифровые символы текущей локали заменяются подчеркиваниями. При передаче в аргументе `filename` значения `null` функция построит C-идентификаторы на основе значения `image`.

`foreground_color`

  Параметр устанавливает цвет верхнего слоя путём установки идентификатора, который вернула функция imagecolorallocate(). Верхний слой получает чёрный цвет по умолчанию. Остальные цвета интерпретируются как цвет фона.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Параметр `image` теперь принимает объект GdImage; раньше параметр принимал корректный `gd`-ресурс (resource).
8.0.0 | Параметр `foreground_color` теперь принимает значение `null`.
8.0.0 | Удалили четвёртый параметр, который функция не учитывала.

### Примеры

Пример #1 Пример сохранения XBM-файла

    <?php

    // Создание пустого изображения и добавление текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Простая текстовая строка', $text_color);

    // Сохранение изображения
    imagexbm($im, 'simpletext.xbm');

    ?>

Пример #2 Пример сохранение XBM-файла с другим цветом верхнего слоя

    <?php

    // Создание пустого изображения и добавление текста
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'Простая текстовая строка', $text_color);

    // Изменение цвета
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // Сохранение изображения
    imagexbm($im, NULL, $foreground_color);

    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — Встраивание двоичных IPTC данных в JPEG изображение

### Описание

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

Включает двоичные IPTC данные в JPEG изображение.

### Список параметров

`iptc_data`

  Данные.

`filename`

  Путь к JPEG изображению.

`spool`

  Если значение этого флага больше 2, то JPEG будет возвращён в виде строки. В противном случае, JPEG будет напечатан в STDOUT.

### Возвращаемые значения

Если `spool` меньше 2, будет возвращён JPEG или `false`, если возникла ошибка. В противном случае `true` в случае успешного выполнения или `false`, если возникла ошибка.

### Примеры

Пример #1 Встраивание IPTC данных в JPEG

    <?php

    // iptc_make_tag() функция от Thies C. Arntzen
    function iptc_make_tag($rec, $data, $value)
    {
        $length = strlen($value);
        $retval = chr(0x1C) . chr($rec) . chr($data);

        if($length < 0x8000)
        {
            $retval .= chr($length >> 8) .  chr($length & 0xFF);
        }
        else
        {
            $retval .= chr(0x80) .
                       chr(0x04) .
                       chr(($length >> 24) & 0xFF) .
                       chr(($length >> 16) & 0xFF) .
                       chr(($length >> 8) & 0xFF) .
                       chr($length & 0xFF);
        }

        return $retval . $value;
    }

    // Путь к jpeg файлу
    $path = './phplogo.jpg';

    // установка IPTC тэгов
    $iptc = array(
        '2#120' => 'Тестовое изображение',
        '2#116' => 'Copyright 2008-2009, The PHP Group'
    );

    // Преобразование IPTC тэгов в двоичный код
    $data = '';

    foreach($iptc as $tag => $string)
    {
        $tag = substr($tag, 2);
        $data .= iptc_make_tag(2, $tag, $string);
    }

    // Встраивание IPTC данных
    $content = iptcembed($data, $path);

    // запись нового изображения в файл
    $fp = fopen($path, "wb");
    fwrite($fp, $content);
    fclose($fp);
    ?>

### Примечания

> Замечание: Этой функции не требуется библиотека GD.

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — Разбор двоичных IPTC данных на отдельные теги

### Описание

function iptcparse(string `$iptc_block`): array|false

Разбирает » IPTC данные на отдельные теги.

### Список параметров

`iptc_block`

  Двоичные данные IPTC.

### Возвращаемые значения

Возвращает массив значений тегов, используя метки тегов в качестве индекса. Возвращает `false` в случае возникновения ошибки, а также если IPTC данные отсутствуют.

### Примеры

Пример #1 iptcparse() используется совместно с getimagesize()

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### Примечания

> Замечание: Этой функции не требуется библиотека GD.

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — Конвертирует изображение из формата JPEG в WBMP

Внимание

Начиная с PHP 7.2.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Конвертирует JPEG-файл в WBMP.

### Список параметров

`jpegname`

  Путь к JPEG-файлу.

`wbmpname`

  Путь для размещения WBMP-файла.

`dest_height`

  Высота WBMP-изображения.

`dest_width`

  Ширина WBMP-изображения.

`threshold`

  Пороговое значение, от 0 до 8 (включительно).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Примеры

Пример #1 Пример использования jpeg2wbmp()

    <?php
    // Путь к исходному jpeg-изображению
    $path = './test.jpg';

    // Получаем размеры изображения
    $image = getimagesize($path);

    // Конвертируем изображение
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### Смотрите также

- png2wbmp() - Преобразовывает PNG-файла в файл WBMP

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — Преобразовывает PNG-файла в файл WBMP

Внимание

Начиная с PHP 7.2.0 функция УСТАРЕЛА, а в PHP 8.0.0 функцию УДАЛИЛИ. Полагаться на функцию настоятельно не рекомендуют.

### Описание

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Преобразует PNG файл в WBMP.

### Список параметров

`pngname`

  Путь к PNG файлу.

`wbmpname`

  Путь к результирующему WBMP файлу.

`dest_height`

  Высота результирующего изображения.

`dest_width`

  Ширина результирующего изображения.

`threshold`

  Ограничение, от 0 до 8 (включительно).

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

Предостережение

Функция вернёт значение `true`, если вывести изображение средствами библиотеки libgd невозможно.

### Примеры

Пример #1 Пример использования png2wbmp()

    <?php
    // Путь к png
    $path = './test.png';

    // Получение размеров изображений
    $image = getimagesize($path);

    // Преобразование
    png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
    ?>

### Смотрите также

- jpeg2wbmp() - Конвертирует изображение из формата JPEG в WBMP

## Содержание

- gd_info — Вывод информации о текущей установленной GD библиотеке
- getimagesize — Получает размер изображения
- getimagesizefromstring — Получение размера изображения из строки данных
- image_type_to_extension — Получает расширение файла для типа изображения
- image_type_to_mime_type — Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- image2wbmp — Выводит изображение в браузер или записывает в файл
- imageaffine — Вернуть изображение, содержащее аффинно-преобразованное изображение src, используя дополнительную область ограничения
- imageaffinematrixconcat — Конкатенирует две аффинные матрицы преобразования
- imageaffinematrixget — Получает матрицу аффинного преобразования
- imagealphablending — Устанавливает режим сопряжения цветов для изображения
- imageantialias — Определяет, применять ли функции сглаживания
- imagearc — Рисует дугу
- imageavif — Выводит изображение в браузер или записывает в файл
- imagebmp — Выводит BMP-изображение в браузер или файл
- imagechar — Рисует символ по горизонтали
- imagecharup — Рисует символ по вертикали
- imagecolorallocate — Создание цвета для изображения
- imagecolorallocatealpha — Создаёт цвет для изображения
- imagecolorat — Получение индекса цвета пиксела
- imagecolorclosest — Получает ближайший индекс цвета
- imagecolorclosestalpha — Получает ближайший индекс цвета с учётом прозрачности
- imagecolorclosesthwb — Получает индекс цвета с заданными тоном, белизной и затемнением
- imagecolordeallocate — Удаляет цвет из палитры изображения
- imagecolorexact — Получает индекс цвета
- imagecolorexactalpha — Получает индекс цвета и альфа-компонента
- imagecolormatch — Приближает цвета палитрового изображения к truecolor-версии
- imagecolorresolve — Получает идентификатор конкретного цвета или его ближайший аналог
- imagecolorresolvealpha — Получает идентификатор конкретного цвета и альфа-компонента или его ближайший аналог
- imagecolorset — Устанавливает набор цветов для индекса палитры
- imagecolorsforindex — Получение цветов, соответствующих индексу
- imagecolorstotal — Определяет количество цветов в палитре изображения
- imagecolortransparent — Определяет цвет как прозрачный
- imageconvolution — Наложение искривляющей матрицы 3х3, используя коэффициент и смещение
- imagecopy — Копирует часть изображения
- imagecopymerge — Копирует часть изображения с наложением
- imagecopymergegray — Копирует часть изображения с наложением в градациях серого
- imagecopyresampled — Копирует и изменяет размер части изображения с ресемплированием
- imagecopyresized — Копирует и изменяет размер части изображения
- imagecreate — Создаёт новое палитровое изображение
- imagecreatefromavif — Создаёт новое изображение из файла или URL-адреса
- imagecreatefrombmp — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromgd — Создаёт новое изображение на основе GD-файла или URL-адреса
- imagecreatefromgd2 — Создаёт новое изображение на основе GD2-файла или URL-адреса
- imagecreatefromgd2part — Создаёт новое изображение на основе части GD2-файла или URL-адреса
- imagecreatefromgif — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromjpeg — Создаёт новое изображение из файла или URL-адреса
- imagecreatefrompng — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromstring — Создаёт новое изображение из представленного строкой потока
- imagecreatefromtga — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromwbmp — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromwebp — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromxbm — Создаёт новое изображение из файла или URL-адреса
- imagecreatefromxpm — Создаёт новое изображение из файла или URL-адреса
- imagecreatetruecolor — Создаёт новое truecolor-изображение
- imagecrop — Обрезает изображение до заданного прямоугольника
- imagecropauto — Обрезает изображение автоматически на основе заданного режима
- imagedashedline — Рисует пунктирную линию
- imagedestroy — Уничтожает изображение
- imageellipse — Рисует эллипс
- imagefill — Заливает фон
- imagefilledarc — Рисует и заливает дугу
- imagefilledellipse — Рисует эллипс с заливкой
- imagefilledpolygon — Рисует закрашенный многоугольник
- imagefilledrectangle — Рисует прямоугольник с заливкой
- imagefilltoborder — Заливает область изображения
- imagefilter — Применяет фильтр к изображению
- imageflip — Отражает изображение по осям
- imagefontheight — Получение высоты шрифта
- imagefontwidth — Получение ширины шрифта
- imageftbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
- imagefttext — Наносит текст на изображение путём рендеринга шрифта библиотекой FreeType 2
- imagegammacorrect — Применяет гамма-коррекцию к GD-изображению
- imagegd — Выводит GD-изображение в браузер или файл
- imagegd2 — Выводит GD2-изображение в браузер или файл
- imagegetclip — Получить отсекающий прямоугольник
- imagegetinterpolation — Получает метод интерполяции
- imagegif — Выводит изображение в браузер или записывает в файл
- imagegrabscreen — Захватывает изображение с экрана
- imagegrabwindow — Захватывает изображение окна
- imageinterlace — Включает или выключает интерлейсинг
- imageistruecolor — Определяет, относится ли изображение к изображениям truecolor
- imagejpeg — Выводит изображение в браузер или записывает в файл
- imagelayereffect — Устанавливает флаг альфа-смешивания, чтобы создать эффекты наложения изображений
- imageline — Рисует отрезок
- imageloadfont — Загружает новый шрифт
- imageopenpolygon — Рисует открытый полигон
- imagepalettecopy — Копирует палитру из одного изображения в другое
- imagepalettetotruecolor — Преобразовывает изображение на основе палитры в настоящий цвет
- imagepng — Выводит PNG-изображение в браузер или файл
- imagepolygon — Рисует многоугольник
- imagerectangle — Рисует прямоугольник
- imageresolution — Получает или устанавливает разрешение изображения
- imagerotate — Поворачивает изображение с заданным углом
- imagesavealpha — Определяет, сохранять ли полную информацию альфа-канала при сохранении изображений
- imagescale — Масштабировать изображение по заданной ширине и высоте
- imagesetbrush — Устанавливает изображение кисти для рисования линий
- imagesetclip — Устанавливает прямоугольник отсечения
- imagesetinterpolation — Устанавливает метод интерполяции
- imagesetpixel — Рисует точку
- imagesetstyle — Устанавливает стиль рисования линий
- imagesetthickness — Устанавливает толщину линий
- imagesettile — Устанавливает изображение как элемент мозаичной заливки
- imagestring — Рисует строку текста горизонтально
- imagestringup — Рисует строку текста вертикально
- imagesx — Получение ширины изображения
- imagesy — Получение высоты изображения
- imagetruecolortopalette — Преобразовывает truecolor-изображение в палитровое
- imagettfbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
- imagettftext — Рисует текст на изображении шрифтом TrueType
- imagetypes — Возвращает список типов изображений, поддерживаемых PHP сборкой
- imagewbmp — Выводит изображение в браузер или записывает в файл
- imagewebp — Вывод WebP-изображение в браузер или файл
- imagexbm — Выводит XBM-изображение в браузер или в файл
- iptcembed — Встраивание двоичных IPTC данных в JPEG изображение
- iptcparse — Разбор двоичных IPTC данных на отдельные теги
- jpeg2wbmp — Конвертирует изображение из формата JPEG в WBMP
- png2wbmp — Преобразовывает PNG-файла в файл WBMP

# Класс GdImage

(PHP 8)

## Введение

Полностью непрозрачный класс, заменяющий ресурсы `gd` в PHP 8.0.0.

## Обзор класса

final class GdImage {
}

# Класс GdFont

(PHP 8 >= 8.1.0)

## Введение

Полностью непрозрачный класс, заменяющий ресурс `gd font` в PHP 8.1.0.

## Обзор класса

final class GdFont {
}

- Установка и настройка
  - Требования
  - Установка
  - Настройка во время выполнения
  - Типы ресурсов
- Предопределённые константы
- Примеры
  - Создаёт PNG-изображение средствами PHP
  - Добавление водяных знаков на изображения через альфа-каналы
  - Создание полупрозрачного водяного знака функцией imagecopymerge
- Функции GD и функции для работы с изображениями
  - gd_info — Вывод информации о текущей установленной GD библиотеке
  - getimagesize — Получает размер изображения
  - getimagesizefromstring — Получение размера изображения из строки данных
  - image_type_to_extension — Получает расширение файла для типа изображения
  - image_type_to_mime_type — Получение Mime-типа для типа изображения, возвращаемого функциями getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
  - image2wbmp — Выводит изображение в браузер или записывает в файл
  - imageaffine — Вернуть изображение, содержащее аффинно-преобразованное изображение src, используя дополнительную область ограничения
  - imageaffinematrixconcat — Конкатенирует две аффинные матрицы преобразования
  - imageaffinematrixget — Получает матрицу аффинного преобразования
  - imagealphablending — Устанавливает режим сопряжения цветов для изображения
  - imageantialias — Определяет, применять ли функции сглаживания
  - imagearc — Рисует дугу
  - imageavif — Выводит изображение в браузер или записывает в файл
  - imagebmp — Выводит BMP-изображение в браузер или файл
  - imagechar — Рисует символ по горизонтали
  - imagecharup — Рисует символ по вертикали
  - imagecolorallocate — Создание цвета для изображения
  - imagecolorallocatealpha — Создаёт цвет для изображения
  - imagecolorat — Получение индекса цвета пиксела
  - imagecolorclosest — Получает ближайший индекс цвета
  - imagecolorclosestalpha — Получает ближайший индекс цвета с учётом прозрачности
  - imagecolorclosesthwb — Получает индекс цвета с заданными тоном, белизной и затемнением
  - imagecolordeallocate — Удаляет цвет из палитры изображения
  - imagecolorexact — Получает индекс цвета
  - imagecolorexactalpha — Получает индекс цвета и альфа-компонента
  - imagecolormatch — Приближает цвета палитрового изображения к truecolor-версии
  - imagecolorresolve — Получает идентификатор конкретного цвета или его ближайший аналог
  - imagecolorresolvealpha — Получает идентификатор конкретного цвета и альфа-компонента или его ближайший аналог
  - imagecolorset — Устанавливает набор цветов для индекса палитры
  - imagecolorsforindex — Получение цветов, соответствующих индексу
  - imagecolorstotal — Определяет количество цветов в палитре изображения
  - imagecolortransparent — Определяет цвет как прозрачный
  - imageconvolution — Наложение искривляющей матрицы 3х3, используя коэффициент и смещение
  - imagecopy — Копирует часть изображения
  - imagecopymerge — Копирует часть изображения с наложением
  - imagecopymergegray — Копирует часть изображения с наложением в градациях серого
  - imagecopyresampled — Копирует и изменяет размер части изображения с ресемплированием
  - imagecopyresized — Копирует и изменяет размер части изображения
  - imagecreate — Создаёт новое палитровое изображение
  - imagecreatefromavif — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefrombmp — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromgd — Создаёт новое изображение на основе GD-файла или URL-адреса
  - imagecreatefromgd2 — Создаёт новое изображение на основе GD2-файла или URL-адреса
  - imagecreatefromgd2part — Создаёт новое изображение на основе части GD2-файла или URL-адреса
  - imagecreatefromgif — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromjpeg — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefrompng — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromstring — Создаёт новое изображение из представленного строкой потока
  - imagecreatefromtga — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromwbmp — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromwebp — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromxbm — Создаёт новое изображение из файла или URL-адреса
  - imagecreatefromxpm — Создаёт новое изображение из файла или URL-адреса
  - imagecreatetruecolor — Создаёт новое truecolor-изображение
  - imagecrop — Обрезает изображение до заданного прямоугольника
  - imagecropauto — Обрезает изображение автоматически на основе заданного режима
  - imagedashedline — Рисует пунктирную линию
  - imagedestroy — Уничтожает изображение
  - imageellipse — Рисует эллипс
  - imagefill — Заливает фон
  - imagefilledarc — Рисует и заливает дугу
  - imagefilledellipse — Рисует эллипс с заливкой
  - imagefilledpolygon — Рисует закрашенный многоугольник
  - imagefilledrectangle — Рисует прямоугольник с заливкой
  - imagefilltoborder — Заливает область изображения
  - imagefilter — Применяет фильтр к изображению
  - imageflip — Отражает изображение по осям
  - imagefontheight — Получение высоты шрифта
  - imagefontwidth — Получение ширины шрифта
  - imageftbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
  - imagefttext — Наносит текст на изображение путём рендеринга шрифта библиотекой FreeType 2
  - imagegammacorrect — Применяет гамма-коррекцию к GD-изображению
  - imagegd — Выводит GD-изображение в браузер или файл
  - imagegd2 — Выводит GD2-изображение в браузер или файл
  - imagegetclip — Получить отсекающий прямоугольник
  - imagegetinterpolation — Получает метод интерполяции
  - imagegif — Выводит изображение в браузер или записывает в файл
  - imagegrabscreen — Захватывает изображение с экрана
  - imagegrabwindow — Захватывает изображение окна
  - imageinterlace — Включает или выключает интерлейсинг
  - imageistruecolor — Определяет, относится ли изображение к изображениям truecolor
  - imagejpeg — Выводит изображение в браузер или записывает в файл
  - imagelayereffect — Устанавливает флаг альфа-смешивания, чтобы создать эффекты наложения изображений
  - imageline — Рисует отрезок
  - imageloadfont — Загружает новый шрифт
  - imageopenpolygon — Рисует открытый полигон
  - imagepalettecopy — Копирует палитру из одного изображения в другое
  - imagepalettetotruecolor — Преобразовывает изображение на основе палитры в настоящий цвет
  - imagepng — Выводит PNG-изображение в браузер или файл
  - imagepolygon — Рисует многоугольник
  - imagerectangle — Рисует прямоугольник
  - imageresolution — Получает или устанавливает разрешение изображения
  - imagerotate — Поворачивает изображение с заданным углом
  - imagesavealpha — Определяет, сохранять ли полную информацию альфа-канала при сохранении изображений
  - imagescale — Масштабировать изображение по заданной ширине и высоте
  - imagesetbrush — Устанавливает изображение кисти для рисования линий
  - imagesetclip — Устанавливает прямоугольник отсечения
  - imagesetinterpolation — Устанавливает метод интерполяции
  - imagesetpixel — Рисует точку
  - imagesetstyle — Устанавливает стиль рисования линий
  - imagesetthickness — Устанавливает толщину линий
  - imagesettile — Устанавливает изображение как элемент мозаичной заливки
  - imagestring — Рисует строку текста горизонтально
  - imagestringup — Рисует строку текста вертикально
  - imagesx — Получение ширины изображения
  - imagesy — Получение высоты изображения
  - imagetruecolortopalette — Преобразовывает truecolor-изображение в палитровое
  - imagettfbbox — Определяет границы прямоугольного обрамления для текста, который библиотека freetype2 выводит на экран путём рендеринга шрифта
  - imagettftext — Рисует текст на изображении шрифтом TrueType
  - imagetypes — Возвращает список типов изображений, поддерживаемых PHP сборкой
  - imagewbmp — Выводит изображение в браузер или записывает в файл
  - imagewebp — Вывод WebP-изображение в браузер или файл
  - imagexbm — Выводит XBM-изображение в браузер или в файл
  - iptcembed — Встраивание двоичных IPTC данных в JPEG изображение
  - iptcparse — Разбор двоичных IPTC данных на отдельные теги
  - jpeg2wbmp — Конвертирует изображение из формата JPEG в WBMP
  - png2wbmp — Преобразовывает PNG-файла в файл WBMP
- GdImage — Класс GdImage
- GdFont — Класс GdFont

# Gmagick

# Введение

Внимание

Модуль добавили как ЭКСПЕРИМЕНТАЛЬНЫЙ. Поведение модуля, названия функций и документацию к модулю изменяют в новых выпусках PHP без уведомления. Модулем пользуются на свой страх и риск.

Gmagick — PHP-модуль, который помогает создавать, изменять и получать метаданные изображений через API-интерфейс к функциям библиотеки GraphicsMagick.

Библиотека GraphicsMagick — армейский швейцарский нож для обработки изображений. Библиотека работает с более чем 88 форматами, включая DPX, GIF, JPEG, JPEG-2000, PNG, PDF, PNM и TIFF.

Модуль Gmagick состоит из основного класса — Gmagick, класса GmagickDraw — волшебной палочки для рисования и класса GmagickPixel, экземпляры которого представляют один пиксель изображения (цвет, непрозрачность).

# Установка и настройка

## Содержание

- Требования
- Установка

## Требования

Модуль лучше всего работает с библиотекой GraphicsMagick версии 1.4+. Модуль Gmagick будет работать и с более старыми версиями, вплоть до GraphicsMagick 1.2.6, но отдельные функции и форматы не поддерживаются старыми версиями. Версия библиотеки GraphicsMagick для ОС Windows доступна на сайте GraphicsMagick. Про отличия модуля ImageMagick и библиотеки рассказывает » FAQ.

## Установка

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/gmagick.

> Замечание: Официальное название модуля — gmagick.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Цветовые константы
`Gmagick::COLOR_BLACK` (int)
  Чёрный
`Gmagick::COLOR_BLUE` (int)
  Синий
`Gmagick::COLOR_CYAN` (int)
  Бирюзовый
`Gmagick::COLOR_GREEN` (int)
  Зелёный
`Gmagick::COLOR_RED` (int)
  Красный
`Gmagick::COLOR_YELLOW` (int)
  Жёлтый
`Gmagick::COLOR_MAGENTA` (int)
  Пурпурный
`Gmagick::COLOR_OPACITY` (int)
  Непрозрачность
`Gmagick::COLOR_ALPHA` (int)
  Альфа-канал
`Gmagick::COLOR_FUZZ` (int)
  Распушка

Константы композитного оператора
`Gmagick::COMPOSITE_DEFAULT` (int)
  Композитный оператор по умолчанию
`Gmagick::COMPOSITE_UNDEFINED` (int)
  Неопределённый композитный оператор
`Gmagick::COMPOSITE_NO` (int)
  Композитный оператор не задан
`Gmagick::COMPOSITE_ADD` (int)
  Результат сложения изображений
`Gmagick::COMPOSITE_ATOP` (int)
  Результат имеет ту же форму, что и исходное изображение, но затемнённый с помощью композитного изображения в местах пересечения.
`Gmagick::COMPOSITE_BLEND` (int)
  Смешение изображения
`Gmagick::COMPOSITE_BUMPMAP` (int)
  То же, что и COMPOSITE_MULTIPLY, за исключением того, что исходное изображение сначала преобразуется к оттенкам серого.
`Gmagick::COMPOSITE_CLEAR` (int)
  Делает целевое изображение прозрачным.
`Gmagick::COMPOSITE_COLORBURN` (int)
  Затемняет целевое изображение, для отражения исходного изображения.
`Gmagick::COMPOSITE_COLORDODGE` (int)
  Осветляет целевое изображение, для отражения исходного изображения.
`Gmagick::COMPOSITE_COLORIZE` (int)
  Раскрашивает целевое изображение, используя композитное изображение.
`Gmagick::COMPOSITE_COPYBLACK` (int)
  Копирует чёрный канал из источника в приёмник
`Gmagick::COMPOSITE_COPYBLUE` (int)
  Копирует синий канал из источника в приёмник
`Gmagick::COMPOSITE_COPY` (int)
  Копирует источник в приёмник
`Gmagick::COMPOSITE_COPYCYAN` (int)
  Копирует бирюзовый канал из источника в приёмник
`Gmagick::COMPOSITE_COPYGREEN` (int)
  Копирует зелёный канал из источника в приёмник
`Gmagick::COMPOSITE_COPYMAGENTA` (int)
  Копирует пурпурный канал из источника в приёмник
`Gmagick::COMPOSITE_COPYOPACITY` (int)
  Копирует канал прозрачности из источника в приёмник
`Gmagick::COMPOSITE_COPYRED` (int)
  Копирует красный канал из источника в приёмник
`Gmagick::COMPOSITE_COPYYELLOW` (int)
  Копирует жёлтый канал из источника в приёмник
`Gmagick::COMPOSITE_DARKEN` (int)
  Затемнение приёмника
`Gmagick::COMPOSITE_DSTATOP` (int)
  Часть приёмника, лежащая внутри источника, накладывается на источник и заменяет приёмник
`Gmagick::COMPOSITE_DST` (int)
  Приёмник остаётся нетронутым
`Gmagick::COMPOSITE_DSTIN` (int)
  Часть внутри источника заменяет приёмник
`Gmagick::COMPOSITE_DSTOUT` (int)
  Часть вне источника заменяет приёмник
`Gmagick::COMPOSITE_DSTOVER` (int)
  Приёмник заменяет источник
`Gmagick::COMPOSITE_DIFFERENCE` (int)
  Вычитает более тёмное значение цвета из более светлого
`Gmagick::COMPOSITE_DISPLACE` (int)
  Сдвигает пиксели приёмника как задано в источнике
`Gmagick::COMPOSITE_DISSOLVE` (int)
  Растворяет источник в приёмнике
`Gmagick::COMPOSITE_EXCLUSION` (int)
  Создаёт эффект аналогичный Gmagick::COMPOSITE_DIFFERENCE, но выглядит как снижение контраста
`Gmagick::COMPOSITE_HARDLIGHT` (int)
  Умножает или осветляет цвета, в зависимости от значения цвета источника
`Gmagick::COMPOSITE_HUE` (int)
  Модифицирует оттенок приёмника в соответствии с источником
`Gmagick::COMPOSITE_IN` (int)
  Подмешивает источник в приёмник
`Gmagick::COMPOSITE_LIGHTEN` (int)
  Осветляет приёмник в соответствии с источником
`Gmagick::COMPOSITE_LUMINIZE` (int)
  Люминизирует приёмник в соответствии с источником
`Gmagick::COMPOSITE_MINUS` (int)
  Вычитает источник из приёмника
`Gmagick::COMPOSITE_MODULATE` (int)
  Модулирует яркость, насыщенность и оттенок приёмника в соответствии с источником
`Gmagick::COMPOSITE_MULTIPLY` (int)
  Умножает приёмник на источник
`Gmagick::COMPOSITE_OUT` (int)
  Накладывает внешние части источника на приёмник
`Gmagick::COMPOSITE_OVER` (int)
  Подмешивает источник поверх приёмника
`Gmagick::COMPOSITE_OVERLAY` (int)
  Перекрывает приёмник источником
`Gmagick::COMPOSITE_PLUS` (int)
  Добавляет источник к приёмнику
`Gmagick::COMPOSITE_REPLACE` (int)
  Заменяет приёмник источником
`Gmagick::COMPOSITE_SATURATE` (int)
  Меняет насыщенность приёмника в соответствии с источником
`Gmagick::COMPOSITE_SCREEN` (int)
  Источник и приёмник дополняются, после этого умножаются и заменяют приёмник
`Gmagick::COMPOSITE_SOFTLIGHT` (int)
  Затемняет или осветляет в зависимости от источника
`Gmagick::COMPOSITE_SRCATOP` (int)
  Часть источника, лежащая вне приёмника, подмешивается в приёмник
`Gmagick::COMPOSITE_SRC` (int)
  Источник копируется в приёмник
`Gmagick::COMPOSITE_SRCIN` (int)
  Часть источника, лежащая внутри приёмника заменяет приёмник
`Gmagick::COMPOSITE_SRCOUT` (int)
  Часть источника, лежащая вне приёмника заменяет приёмник
`Gmagick::COMPOSITE_SRCOVER` (int)
  Источник заменяет приёмник
`Gmagick::COMPOSITE_SUBTRACT` (int)
  Вычитает цвета изображения источника из изображения приёмника
`Gmagick::COMPOSITE_THRESHOLD` (int)
  Источник подмешивается к приёмнику, как определено в пороговом значении источника
`Gmagick::COMPOSITE_XOR` (int)
  Часть источника, лежащая вне приёмника комбинируется с частью приёмника лежащей вне источника

Константы режима монтажа
`Gmagick::MONTAGEMODE_FRAME` (int)
`Gmagick::MONTAGEMODE_UNFRAME` (int)
`Gmagick::MONTAGEMODE_CONCATENATE` (int)

Константы стиля
`Gmagick::STYLE_NORMAL` (int)
`Gmagick::STYLE_ITALIC` (int)
`Gmagick::STYLE_OBLIQUE` (int)
`Gmagick::STYLE_ANY` (int)

Константы фильтрации
`Gmagick::FILTER_UNDEFINED` (int)
`Gmagick::FILTER_POINT` (int)
`Gmagick::FILTER_BOX` (int)
`Gmagick::FILTER_TRIANGLE` (int)
`Gmagick::FILTER_HERMITE` (int)
`Gmagick::FILTER_HANNING` (int)
`Gmagick::FILTER_HAMMING` (int)
`Gmagick::FILTER_BLACKMAN` (int)
`Gmagick::FILTER_GAUSSIAN` (int)
`Gmagick::FILTER_QUADRATIC` (int)
`Gmagick::FILTER_CUBIC` (int)
`Gmagick::FILTER_CATROM` (int)
`Gmagick::FILTER_MITCHELL` (int)
`Gmagick::FILTER_LANCZOS` (int)
`Gmagick::FILTER_BESSEL` (int)
`Gmagick::FILTER_SINC` (int)

Константы типа изображения
`Gmagick::IMGTYPE_UNDEFINED` (int)
`Gmagick::IMGTYPE_BILEVEL` (int)
`Gmagick::IMGTYPE_GRAYSCALE` (int)
`Gmagick::IMGTYPE_GRAYSCALEMATTE` (int)
`Gmagick::IMGTYPE_PALETTE` (int)
`Gmagick::IMGTYPE_PALETTEMATTE` (int)
`Gmagick::IMGTYPE_TRUECOLOR` (int)
`Gmagick::IMGTYPE_TRUECOLORMATTE` (int)
`Gmagick::IMGTYPE_COLORSEPARATION` (int)
`Gmagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`Gmagick::IMGTYPE_OPTIMIZE` (int)

Константы разрешения
`Gmagick::RESOLUTION_UNDEFINED` (int)
`Gmagick::RESOLUTION_PIXELSPERINCH` (int)
`Gmagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Константы сжатия
`Gmagick::COMPRESSION_UNDEFINED` (int)
`Gmagick::COMPRESSION_NO` (int)
`Gmagick::COMPRESSION_BZIP` (int)
`Gmagick::COMPRESSION_FAX` (int)
`Gmagick::COMPRESSION_GROUP4` (int)
`Gmagick::COMPRESSION_JPEG` (int)
`Gmagick::COMPRESSION_JPEG2000` (int)
`Gmagick::COMPRESSION_LOSSLESSJPEG` (int)
`Gmagick::COMPRESSION_LZW` (int)
`Gmagick::COMPRESSION_RLE` (int)
`Gmagick::COMPRESSION_ZIP` (int)

Константы рисования
`Gmagick::PAINT_POINT` (int)
`Gmagick::PAINT_REPLACE` (int)
`Gmagick::PAINT_FLOODFILL` (int)
`Gmagick::PAINT_FILLTOBORDER` (int)
`Gmagick::PAINT_RESET` (int)

Гравитационные константы
`Gmagick::GRAVITY_NORTHWEST` (int)
`Gmagick::GRAVITY_NORTH` (int)
`Gmagick::GRAVITY_NORTHEAST` (int)
`Gmagick::GRAVITY_WEST` (int)
`Gmagick::GRAVITY_CENTER` (int)
`Gmagick::GRAVITY_EAST` (int)
`Gmagick::GRAVITY_SOUTHWEST` (int)
`Gmagick::GRAVITY_SOUTH` (int)
`Gmagick::GRAVITY_SOUTHEAST` (int)

Константы растяжения
`Gmagick::STRETCH_NORMAL` (int)
`Gmagick::STRETCH_ULTRACONDENSED` (int)
`Gmagick::STRETCH_CONDENSED` (int)
`Gmagick::STRETCH_SEMICONDENSED` (int)
`Gmagick::STRETCH_SEMIEXPANDED` (int)
`Gmagick::STRETCH_EXPANDED` (int)
`Gmagick::STRETCH_EXTRAEXPANDED` (int)
`Gmagick::STRETCH_ULTRAEXPANDED` (int)
`Gmagick::STRETCH_ANY` (int)

Align constants
`Gmagick::ALIGN_UNDEFINED` (int)
`Gmagick::ALIGN_LEFT` (int)
`Gmagick::ALIGN_CENTER` (int)
`Gmagick::ALIGN_RIGHT` (int)

Константы декорирования
`Gmagick::DECORATION_NO` (int)
`Gmagick::DECORATION_UNDERLINE` (int)
`Gmagick::DECORATION_OVERLINE` (int)
`Gmagick::DECORATION_LINETROUGH` (int)

Константы шума
`Gmagick::NOISE_UNIFORM` (int)
`Gmagick::NOISE_GAUSSIAN` (int)
`Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`Gmagick::NOISE_IMPULSE` (int)
`Gmagick::NOISE_LAPLACIAN` (int)
`Gmagick::NOISE_POISSON` (int)

Константы каналов
`Gmagick::CHANNEL_UNDEFINED` (int)
`Gmagick::CHANNEL_RED` (int)
`Gmagick::CHANNEL_GRAY` (int)
`Gmagick::CHANNEL_CYAN` (int)
`Gmagick::CHANNEL_GREEN` (int)
`Gmagick::CHANNEL_MAGENTA` (int)
`Gmagick::CHANNEL_BLUE` (int)
`Gmagick::CHANNEL_YELLOW` (int)
`Gmagick::CHANNEL_ALPHA` (int)
`Gmagick::CHANNEL_OPACITY` (int)
`Gmagick::CHANNEL_MATTE` (int)
`Gmagick::CHANNEL_BLACK` (int)
`Gmagick::CHANNEL_INDEX` (int)
`Gmagick::CHANNEL_ALL` (int)

Метрические константы
`Gmagick::METRIC_UNDEFINED` (int)
`Gmagick::METRIC_MEANABSOLUTEERROR` (int)
`Gmagick::METRIC_MEANSQUAREERROR` (int)
`Gmagick::METRIC_PEAKABSOLUTEERROR` (int)
`Gmagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`Gmagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Пиксельные константы
`Gmagick::PIXEL_CHAR` (int)
`Gmagick::PIXEL_DOUBLE` (int)
`Gmagick::PIXEL_FLOAT` (int)
`Gmagick::PIXEL_INTEGER` (int)
`Gmagick::PIXEL_LONG` (int)
`Gmagick::PIXEL_QUANTUM` (int)
`Gmagick::PIXEL_SHORT` (int)

Константы цветового пространства
`Gmagick::COLORSPACE_UNDEFINED` (int)
`Gmagick::COLORSPACE_RGB` (int)
`Gmagick::COLORSPACE_GRAY` (int)
`Gmagick::COLORSPACE_TRANSPARENT` (int)
`Gmagick::COLORSPACE_OHTA` (int)
`Gmagick::COLORSPACE_LAB` (int)
`Gmagick::COLORSPACE_XYZ` (int)
`Gmagick::COLORSPACE_YCBCR` (int)
`Gmagick::COLORSPACE_YCC` (int)
`Gmagick::COLORSPACE_YIQ` (int)
`Gmagick::COLORSPACE_YPBPR` (int)
`Gmagick::COLORSPACE_YUV` (int)
`Gmagick::COLORSPACE_CMYK` (int)
`Gmagick::COLORSPACE_SRGB` (int)
`Gmagick::COLORSPACE_HSB` (int)
`Gmagick::COLORSPACE_HSL` (int)
`Gmagick::COLORSPACE_HWB` (int)
`Gmagick::COLORSPACE_REC601LUMA` (int)
`Gmagick::COLORSPACE_REC709LUMA` (int)
`Gmagick::COLORSPACE_LOG` (int)

Константы метода виртуального пикселя
`Gmagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`Gmagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`Gmagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`Gmagick::VIRTUALPIXELMETHOD_EDGE` (int)
`Gmagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`Gmagick::VIRTUALPIXELMETHOD_TILE` (int)
`Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)

Константы предпросмотра
`Gmagick::PREVIEW_UNDEFINED` (int)
`Gmagick::PREVIEW_ROTATE` (int)
`Gmagick::PREVIEW_SHEAR` (int)
`Gmagick::PREVIEW_ROLL` (int)
`Gmagick::PREVIEW_HUE` (int)
`Gmagick::PREVIEW_SATURATION` (int)
`Gmagick::PREVIEW_BRIGHTNESS` (int)
`Gmagick::PREVIEW_GAMMA` (int)
`Gmagick::PREVIEW_SPIFF` (int)
`Gmagick::PREVIEW_DULL` (int)
`Gmagick::PREVIEW_GRAYSCALE` (int)
`Gmagick::PREVIEW_QUANTIZE` (int)
`Gmagick::PREVIEW_DESPECKLE` (int)
`Gmagick::PREVIEW_REDUCENOISE` (int)
`Gmagick::PREVIEW_ADDNOISE` (int)
`Gmagick::PREVIEW_SHARPEN` (int)
`Gmagick::PREVIEW_BLUR` (int)
`Gmagick::PREVIEW_THRESHOLD` (int)
`Gmagick::PREVIEW_EDGEDETECT` (int)
`Gmagick::PREVIEW_SPREAD` (int)
`Gmagick::PREVIEW_SOLARIZE` (int)
`Gmagick::PREVIEW_SHADE` (int)
`Gmagick::PREVIEW_RAISE` (int)
`Gmagick::PREVIEW_SEGMENT` (int)
`Gmagick::PREVIEW_SWIRL` (int)
`Gmagick::PREVIEW_IMPLODE` (int)
`Gmagick::PREVIEW_WAVE` (int)
`Gmagick::PREVIEW_OILPAINT` (int)
`Gmagick::PREVIEW_CHARCOALDRAWING` (int)
`Gmagick::PREVIEW_JPEG` (int)

Константы интента отрисовки
`Gmagick::RENDERINGINTENT_UNDEFINED` (int)
`Gmagick::RENDERINGINTENT_SATURATION` (int)
`Gmagick::RENDERINGINTENT_PERCEPTUAL` (int)
`Gmagick::RENDERINGINTENT_ABSOLUTE` (int)
`Gmagick::RENDERINGINTENT_RELATIVE` (int)

Константы правил заполнения
`Gmagick::FILLRULE_UNDEFINED` (int)
`Gmagick::FILLRULE_EVENODD` (int)
`Gmagick::FILLRULE_NONZERO` (int)

Константы блока пути (pathunit)
`Gmagick::PATHUNITS_UNDEFINED` (int)
`Gmagick::PATHUNITS_USERSPACE` (int)
`Gmagick::PATHUNITS_USERSPACEONUSE` (int)
`Gmagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Константы Linecap
`Gmagick::LINECAP_UNDEFINED` (int)
`Gmagick::LINECAP_BUTT` (int)
`Gmagick::LINECAP_ROUND` (int)
`Gmagick::LINECAP_SQUARE` (int)

Константы объединения линий
`Gmagick::LINEJOIN_UNDEFINED` (int)
`Gmagick::LINEJOIN_MITER` (int)
`Gmagick::LINEJOIN_ROUND` (int)
`Gmagick::LINEJOIN_BEVEL` (int)

Константы типа ресурса
`Gmagick::RESOURCETYPE_UNDEFINED` (int)
`Gmagick::RESOURCETYPE_AREA` (int)
`Gmagick::RESOURCETYPE_DISK` (int)
`Gmagick::RESOURCETYPE_FILE` (int)
`Gmagick::RESOURCETYPE_MAP` (int)
`Gmagick::RESOURCETYPE_MEMORY` (int)

Константы ориентации
`Gmagick::ORIENTATION_UNDEFINED` (int)
`Gmagick::ORIENTATION_TOPLEFT` (int)
`Gmagick::ORIENTATION_TOPRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMLEFT` (int)
`Gmagick::ORIENTATION_LEFTTOP` (int)
`Gmagick::ORIENTATION_RIGHTTOP` (int)
`Gmagick::ORIENTATION_RIGHTBOTTOM` (int)
`Gmagick::ORIENTATION_LEFTBOTTOM` (int)

Константы чересстрочной развёртки
`Gmagick::INTERLACE_UNDEFINED` (int)
`Gmagick::INTERLACE_NO` (int)
`Gmagick::INTERLACE_NONE` (int)
`Gmagick::INTERLACE_LINE` (int)
`Gmagick::INTERLACE_PLANE` (int)
`Gmagick::INTERLACE_PARTITION` (int)

# Примеры

Следующий код демонстрирует часто используемые операции Gmagick над изображениями.

Пример #1 Примеры использования Gmagick

    <?php
    // Создаём новый объект Gmagick
    $image = new Gmagick('example.jpg');

    // Создаём уменьшенную копию изображения. 0 для сохранения пропорций.
    $image->thumbnailimage(100, 0);

    // Создаём рамку вокруг изображения, после чего накладываем эффект масляной краски
    // Обратите внимание на цепочки преобразующих методов, поддерживаемых в gmagick
    $image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

    // Записываем полученное изображение в файл
    $image->write('example_thumbnail.jpg');
    ?>

# Класс Gmagick

(PECL gmagick >= Unknown)

## Введение

## Обзор класса

class Gmagick {
/* Методы */
public function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — Добавление нового изображения в список изображений объекта Gmagick

### Описание

public function Gmagick::addimage(Gmagick `$source`): Gmagick

Добавление нового изображения в объект Gmagick с текущей позиции объекта источника. После добавления итератор позиции смещается в конец списка.

### Список параметров

`source`
  Объект источник Gmagick

### Возвращаемые значения

Объект Gmagick с добавленным изображением

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Добавляет случайный шум к изображению

### Описание

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Добавляет случайный шум к изображению.

### Список параметров

`noise_type`
  Тип шума. Смотрите список констант типа шума.

### Возвращаемые значения

Объект Gmagick с добавленным шумом.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Подписать изображение текстом

### Описание

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Подписать изображение текстом.

### Список параметров

`GmagickDraw`
  Объект GmagickDraw, содержащий настройки для отрисовки текста.
`x`
  Горизонтальное смещение левого края текста в пикселях.
`y`
  Вертикальное смещение базовой линии текста в пикселях.
`angle`
  Угол, под которым размещать текст.
`text`
  Текст.

### Возвращаемые значения

Объект Gmagick с добавленной аннотацией.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Добавить размытие изображению

### Описание

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Добавить размытие изображению.

### Список параметров

`radius`
  Радиус размытия
`sigma`
  Стандартное отклонение

### Возвращаемые значения

Размытый объект Gmagick

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Добавить рамку к изображению

### Описание

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

Добавить рамку к изображению. Цвет рамки задаётся строкой, либо цветом фона объекта GmagickPixel.

### Список параметров

`color`
  Объект GmagickPixel object или строка, определяющая цвет рамки.
`width`
  Толщина рамки.
`height`
  Высота рамки.

### Возвращаемые значения

Объект Gmagick с добавленной рамкой.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Имитация рисования углём

### Описание

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Имитация рисования углём.

### Список параметров

`radius`
  Радиус гауссианы в пикселях, не считая центрального пикселя.
`sigma`
  Стандартное отклонение гауссианы в пикселях.

### Возвращаемые значения

Объект Gmagick с добавленным эффектом рисования углём.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Удаляет область изображения и подрезает его

### Описание

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

Удаляет область изображения и схлопывает его так, чтобы занять удалённую область.

### Список параметров

`width`
  Ширина вырезаемого участка.
`height`
  Высота вырезаемого участка.
`x`
  Горизонтальное смещение начала вырезки.
`y`
  Вертикальное смещение начала вырезки.

### Возвращаемые значения

Получившийся объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Зачищает все ресурсы, связанные с объектом Gmagick

### Описание

public function Gmagick::clear(): Gmagick

Зачищает все ресурсы, связанные с объектом Gmagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Очищенный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Добавить комментарий к изображению

### Описание

public function Gmagick::commentimage(string `$comment`): Gmagick

Добавляет комментарий к изображению.

### Список параметров

`comment`
  Комментарий.

### Возвращаемые значения

Получившийся объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Накладывает одно изображение на другое

### Описание

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Метод накладывает одно изображение на другое с заданным смещением.

### Список параметров

`source`
  Объект Gmagick, который содержит составное изображение.
`COMPOSE`
  Композитный оператор.
`x`
  Смещение столбца составного изображения.
`y`
  Смещение строки составного изображения.

### Возвращаемые значения

Метод возвращает объект Gmagick с композициями.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — Конструктор объекта Gmagick

### Описание

public function Gmagick::__construct(string `$filename` = ?)

Конструктор объекта Gmagick.

### Список параметров

`filename`
  Путь к загружаемому изображению, либо массив путей.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Обрезает изображение

### Описание

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Обрезает изображение.

### Список параметров

`width`
  Ширина сохраняемого участка.
`height`
  Высота сохраняемого участка.
`x`
  X координата левого верхнего угла сохраняемой области.
`y`
  Y координата левого верхнего угла сохраняемой области.

### Возвращаемые значения

Обрезанный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Создание обрезанного уменьшенного изображения

### Описание

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

Создаёт уменьшенное изображение фиксированного размера, сначала применяя масштабирование, а после вырезая необходимую область из центра.

### Список параметров

`width`
  Ширина целевого изображения.
`height`
  Высота целевого изображения.

### Возвращаемые значения

Получившийся объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — Вернуть самого себя

### Описание

public function Gmagick::current(): Gmagick

Возвращает ссылку на текущий объект gmagick с установленным указателем изображения в правильной последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

В случае успешного выполнения возвращает самого себя.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Смещает цветовую карту изображения

### Описание

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

Смещает цветовую карту изображения на заданное количество позиций. Если вы циклически изменяете цветовую карту несколько раз, вы можете произвести психоделический эффект.

### Список параметров

`displace`
  Количество смещений карты цветов.

### Возвращаемые значения

Возвращает себя в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Возвращает определённые пиксельные различия между изображениями

### Описание

public function Gmagick::deconstructimages(): Gmagick

Сравнивает каждое изображение со следующим в последовательности и возвращает максимальную ограничивающую область любых обнаруженных различий пикселей.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новый объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — Назначение despeckleimage

### Описание

public function Gmagick::despeckleimage(): Gmagick

Уменьшает спекл-шум на изображении, сохраняя края исходного изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick с уменьшенным спекл-шумом в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Gmagick::despeckleimage()

    <?php
    /* ... */
    ?>

Вывод приведённого примера будет похож на:

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Уничтожить объект Gmagick

### Описание

public function Gmagick::destroy(): bool

Уничтожить объект Gmagick и освободить все выделенные ему ресурсы

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Отображает объект GmagickDraw на текущем изображении

### Описание

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Отображает объект GmagickDraw на текущем изображении

### Список параметров

`GmagickDraw`
  Операции рисования для отображения на изображении.

### Возвращаемые значения

Нарисованный объект Gmagick

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Увеличивает края в изображении

### Описание

public function Gmagick::edgeimage(float `$radius`): Gmagick

Увеличивает края в изображении с помощью фильтра свёртки данного радиуса. Используйте радиус 0, и он будет выбран автоматически.

### Список параметров

`radius`
  Радиус операции.

### Возвращаемые значения

Объект Gmagick с увеличенными краями.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Возвращает изображение в градациях серого с трёхмерным эффектом

### Описание

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

Возвращает изображение в градациях серого с трёхмерным эффектом. Мы сворачиваем изображение с помощью гауссовского оператора, заданного радиуса и стандартного отклонения (сигма). Для получения разумных результатов радиус должен быть больше сигмы. При использовании радиуса 0, подходящий радиус выберется автоматически.

### Список параметров

`radius`
  Радиус эффекта.
`sigma`
  Сигма эффекта.

### Возвращаемые значения

Рельефный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Улучшает качество изображения с шумом

### Описание

public function Gmagick::enhanceimage(): Gmagick

Применяет цифровой фильтр, который улучшает качество изображения с шумом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Улучшенный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Выравнивает гистограмму изображения

### Описание

public function Gmagick::equalizeimage(): Gmagick

Выравнивает гистограмму изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Выравненный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Создаёт вертикальное зеркальное отображение

### Описание

public function Gmagick::flipimage(): Gmagick

Создаёт вертикальное зеркальное отображение путём отражения пикселей вокруг центральной оси X.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Перевёрнутый объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

### Смотрите также

- Gmagick::flopimage() - Создаёт горизонтальное зеркальное отображение

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Создаёт горизонтальное зеркальное отображение

### Описание

public function Gmagick::flopimage(): Gmagick

Создаёт горизонтальное зеркальное изображение, отражая пиксели вокруг центральной оси Y.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Отражённый объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

### Смотрите также

- Gmagick::flipimage() - Создаёт вертикальное зеркальное отображение

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Добавляет смоделированную трёхмерную границу

### Описание

public function Gmagick::frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick

Добавляет смоделированную трёхмерную рамку вокруг изображения. Ширина и высота определяют ширину границы вертикальной и горизонтальной сторон рамки. Внутренний и внешний скосы указывают ширину внутренней и внешней теней рамки.

### Список параметров

`color`
  Объект GmagickPixel или число с плавающей точкой, представляющее матовый цвет.
`width`
  Ширина границы.
`height`
  Высота границы.
`inner_bevel`
  Внутренняя ширина скоса.
`outer_bevel`
  Внешняя ширина скоса.

### Возвращаемые значения

Обрамлённый объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Гамма-коррекция изображения

### Описание

public function Gmagick::gammaimage(float `$gamma`): Gmagick

Гамма-коррекция изображения. Одно и то же изображение, просматриваемое на разных устройствах, будет иметь перцепционные различия в способах представления интенсивности изображения на экране. Укажите индивидуальные уровни гаммы для красного, зелёного и синего каналов или отрегулируйте все три с помощью параметра гаммы. Значения обычно колеблются от 0,8 до 2,3.

### Список параметров

`gamma`
  Количество гамма-коррекции.

### Возвращаемые значения

Гамма-скорректированный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Возвращает копирайт GraphicsMagick API в виде строки

### Описание

public function Gmagick::getcopyright(): string

Возвращает копирайт GraphicsMagick API в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает копирайт GraphicsMagick API и Magickwand C в виде строки.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — Возвращает имя файла связанного с последовательностью изображений

### Описание

public function Gmagick::getfilename(): string

Возвращает имя файла связанного с последовательностью изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя файла.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Возвращает цвет фона изображения

### Описание

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Возвращает цвет фона изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает цвет фона изображения в виде объекта GmagickPixel.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Возвращает цветность синей первичной точки

### Описание

public function Gmagick::getimageblueprimary(): array

Возвращает цветность синей первичной точки для изображения.

### Список параметров

`x`
  Цветность синей первичной точки по х-координате.
`y`
  Цветность синей первичной точки по y-координате.

### Возвращаемые значения

Массив, состоящий из "x" и "y" координат точки.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Возвращает цвет границы изображения

### Описание

public function Gmagick::getimagebordercolor(): GmagickPixel

Возвращает цвет границы изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект GmagickPixel, представляющий цвет границы

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Получает глубину для определённого канала изображения

### Описание

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Получает глубину для определённого канала изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Глубина канала изображения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Возвращает цвет индекса карты цветов

### Описание

public function Gmagick::getimagecolors(): int

Метод возвращает цвет индекса карты цветов.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает количество цветов изображения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Возвращает цветовое пространство изображения

### Описание

public function Gmagick::getimagecolorspace(): int

Возвращает цветовое пространство изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Цветовое пространство.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Возвращает составной оператор, связанный с изображением

### Описание

public function Gmagick::getimagecompose(): int

Возвращает составной оператор, связанный с изображением.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает составной оператор, связанный с изображением.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Получает задержку изображения

### Описание

public function Gmagick::getimagedelay(): int

Получает задержку изображения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает составной оператор, связанный с изображением.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Получает глубину изображения

### Описание

public function Gmagick::getimagedepth(): int

Получает глубину изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Глубина изображения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Получает метод удаления изображения

### Описание

public function Gmagick::getimagedispose(): int

Получает метод удаления изображения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает метод удаления изображения в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Получает экстремумы для изображения

### Описание

public function Gmagick::getimageextrema(): array

Возвращает ассоциативный массив с ключами "min" и "max". Вызывает GmagickException, если возникла ошибка.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив с ключами "min" и "max".

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Возвращает имя файла конкретного изображения в последовательности

### Описание

public function Gmagick::getimagefilename(): string

Возвращает имя файла конкретного изображения в последовательности

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя файла конкретного изображения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Возвращает формат конкретного изображения в последовательности

### Описание

public function Gmagick::getimageformat(): string

Возвращает формат конкретного изображения в последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает формат изображения в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Возвращает гамму изображения

### Описание

public function Gmagick::getimagegamma(): float

Возвращает гамму изображения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает гамму изображения в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Возвращает первичную зелёную точку

### Описание

public function Gmagick::getimagegreenprimary(): array

Возвращает первичную зелёную точку в виде массива с ключами "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив с ключами "x" и "y" в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Возвращает высоту изображения

### Описание

public function Gmagick::getimageheight(): int

Возвращает высоту изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает высоту изображения в пикселях.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Возвращает гистограмму изображения

### Описание

public function Gmagick::getimagehistogram(): array

Возвращает гистограмму изображения в виде массива объектов GmagickPixel. В случае возникновения ошибки выбрасывает исключение GmagickException.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает гистограмму изображения в виде массива объектов GmagickPixel.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Возвращает индекс текущего активного изображения

### Описание

public function Gmagick::getimageindex(): int

Возвращает индекс текущего активного изображения в объекте Gmagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает индекс текущего активного изображения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Получает схему чередования изображений

### Описание

public function Gmagick::getimageinterlacescheme(): int

Получает схему чередования изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает схему чередования как целое число в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Получает итерации изображения

### Описание

public function Gmagick::getimageiterations(): int

Получает итерации изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает итерации изображения в виде целого числа.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Проверяет, есть ли на изображении матовый канал

### Описание

public function Gmagick::getimagematte(): int

Возвращает `true`, если у изображения есть матовый канал, в противном случае возвращает `false`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если у изображения есть матовый канал, в противном случае возвращает `false`.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Возвращает изображение матового цвета

### Описание

public function Gmagick::getimagemattecolor(): GmagickPixel

Возвращает объект GmagickPixel в случае успешного выполнения. Выбрасывает GmagickException в случае возникновения ошибки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект GmagickPixel в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Возвращает именованный профайл изображения

### Описание

public function Gmagick::getimageprofile(string `$name`): string

Возвращает именованный профайл изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает именованный профайл изображения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Возвращает первичную красную точку

### Описание

public function Gmagick::getimageredprimary(): array

Возвращает первичную красную точку в виде массива с ключами "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает первичную красную точку в виде массива с ключами "x" и "y".

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Получает цель рендеринга изображения

### Описание

public function Gmagick::getimagerenderingintent(): int

Получает цель рендеринга изображения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Извлекает область изображения и возвращает её как новую палочку

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Возвращает разрешение изображения

### Описание

public function Gmagick::getimageresolution(): array

Возвращает разрешение изображения в виде массива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает разрешение изображения в виде массива.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Получает сцену изображения

### Описание

public function Gmagick::getimagescene(): int

Получает сцену изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сцену изображения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Создаёт подпись сообщения SHA-256

### Описание

public function Gmagick::getimagesignature(): string

Создаёт подпись сообщения SHA-256 для потока пикселей изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую хеш SHA-256 файла.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Возвращает потенциальный тип изображения

### Описание

public function Gmagick::getimagetype(): int

Возвращает потенциальный тип изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает потенциальный тип изображения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Возвращает единицы разрешения изображения

### Описание

public function Gmagick::getimageunits(): int

Возвращает единицы разрешения изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает единицы разрешения изображения.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Возвращает хроматическую белую точку

### Описание

public function Gmagick::getimagewhitepoint(): array

Возвращает хроматическую белую точку в виде ассоциативного массива с ключами "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает хроматическую белую точку в виде ассоциативного массива с ключами "x" и "y".

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Возвращает ширину изображения

### Описание

public function Gmagick::getimagewidth(): int

Возвращает ширину изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ширину изображения в пикселях.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Возвращает имя пакета GraphicsMagick

### Описание

public function Gmagick::getpackagename(): string

Возвращает имя пакета GraphicsMagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя пакета GraphicsMagick в виде строки.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Возвращает глубину цвета (бит на канал) объекта Gmagick в виде строки

### Описание

public function Gmagick::getquantumdepth(): array

Возвращает глубину цвета (бит на канал) объекта Gmagick в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает глубину цвета (бит на канал) объекта Gmagick в виде строки.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Возвращает дату релиза GraphicsMagick в виде строки

### Описание

public function Gmagick::getreleasedate(): string

Возвращает дату релиза GraphicsMagick в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дату релиза GraphicsMagick в виде строки.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Возвращает вертикальный и горизонтальный фактор дискретизации

### Описание

public function Gmagick::getsamplingfactors(): array

Возвращает вертикальный и горизонтальный фактор дискретизации.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает вертикальный и горизонтальный фактор дискретизации изображения в виде ассоциативного массива.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Возвращает размер, связанный с объектом Gmagick

### Описание

public function Gmagick::getsize(): array

Возвращает размер, связанный с объектом Gmagick в виде массива с ключами "columns" и "rows".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер, связанный с объектом Gmagick в виде массива с ключами "columns" и "rows".

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Возвращает версию GraphicsMagick API

### Описание

public function Gmagick::getversion(): array

Возвращает версию GraphicsMagick API в виде строки и числа.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает версию GraphicsMagick API в виде строки и числа.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Проверяет, есть ли ещё изображения в объекте

### Описание

public function Gmagick::hasnextimage(): mixed

Возвращает `true`, если при итерации вперёд по списку есть изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если при итерации вперёд по списку есть изображения и `false`, если нет.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Проверяет, есть ли ещё изображения в объекте при итерации назад

### Описание

public function Gmagick::haspreviousimage(): mixed

Возвращает `true`, если при итерации назад по списку есть изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если при итерации назад по списку есть изображения и `false`, если нет.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Создаёт копию изображения

### Описание

public function Gmagick::implodeimage(float `$radius`): mixed

Создаёт новое изображение, которое является копией существующего с пикселями, "сжатыми" на указанный процент.

### Список параметров

`radius`
  Радиус сжатия.

### Возвращаемые значения

Возвращает сжатый объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Добавляет метку к изображению

### Описание

public function Gmagick::labelimage(string `$label`): mixed

Добавляет метку к изображению.

### Список параметров

`label`
  Метка, которую необходимо добавить

### Возвращаемые значения

Gmagick с меткой.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Регулирует уровни изображения

### Описание

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

Регулирует уровни изображения, масштабируя цвета, попадающие между указанными белыми и чёрными точками, до полного доступного квантового диапазона. Предоставленные параметры представляют собой чёрные, средние и белые точки. Чёрная точка указывает на самый тёмный цвет изображения. Цвета темнее точки чёрного устанавливаются на ноль. Средняя точка определяет гамма-коррекцию, применяемую к изображению. Белая точка определяет самый светлый цвет изображения. Цвета ярче точки белого устанавливаются на максимальное квантовое значение.

### Список параметров

`blackPoint`
  Чёрная точка изображения.
`gamma`
  Значение гаммы.
`whitePoint`
  Белая точка изображения.
`channel`
  Укажите любую константу канала, которая действительна для вашего режима канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к списку констант канала.

### Возвращаемые значения

Объект Gmagick с выровненным изображением.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Пропорционально масштабирует изображение в 2 раза

### Описание

public function Gmagick::magnifyimage(): mixed

Масштабирует изображение пропорционально двойному исходному размеру.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Увеличенный объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Заменяет цвета изображения на ближайший цвет из эталонного изображения

### Описание

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Заменяет цвета изображения на ближайший цвет из эталонного изображения.

### Список параметров

`gmagick`
  Эталонное изображение.
`dither`
  Установите для этого целого числа значение, отличное от нуля, чтобы размыть отображаемое изображение.

### Возвращаемые значения

Объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Применяет цифровой фильтр

### Описание

public function Gmagick::medianfilterimage(float `$radius`): void

Применяет цифровой фильтр, улучшающий качество зашумлённого изображения. Каждый пиксель заменяется медианой в наборе соседних пикселей, определяемых радиусом.

### Список параметров

`radius`
  Радиус окрестности пикселя.

### Возвращаемые значения

Объект Gmagick с применённым медианным фильтром.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Масштабирует изображение пропорционально половине его размера

### Описание

public function Gmagick::minifyimage(): Gmagick

Метод масштабирования изображения пропорционально половине исходного размера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Управляет яркостью, насыщенностью и оттенком

### Описание

public function Gmagick::modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick

Позволяет управлять яркостью, насыщенностью и оттенком изображения. Оттенок - это процент абсолютного поворота от текущей позиции. Например, значение 50 приводит к повороту против часовой стрелки на 90 градусов, 150 приводит к повороту по часовой стрелке на 90 градусов, значения 0 и 200 приводят к повороту на 180 градусов.

### Список параметров

`brightness`
  Изменение яркости в процентах (от -100 до +100).
`saturation`
  Процентное изменение насыщенности (от -100 до +100)
`hue`
  Процент изменения оттенка (от -100 до +100)

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Имитирует размытие при движении

### Описание

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

Имитирует размытие при движении. Сворачивает изображение с помощью гауссовского оператора заданного радиуса и стандартного отклонения (sigma). Для получения приемлемых результатов radius должен быть больше sigma. При использовании значения radius, равного 0, Gmagick::motionblurimage() выберет для вас подходящий радиус. Параметр angle задаёт угол размытия движения.

### Список параметров

`radius`
  Радиус в пикселях, не считая центрального пикселя.
`sigma`
  Стандартное отклонение в пикселях.
`angle`
  Угол, под которым применяется эффект.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Создаёт новое изображение

### Описание

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Создаёт новое изображение с указанным фоновым цветом.

### Список параметров

`width`
  Ширина нового изображения.
`height`
  Высота нового изображения.
`background`
  Цвет фона, используемый для этого изображения в виде числа с плавающей точкой.
`format`
  Формат изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Осуществляет переход к следующему изображению

### Описание

public function Gmagick::nextimage(): bool

Связывает следующее изображение в списке изображений с объектом Gmagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Повышает контрастность цветного изображения

### Описание

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

Повышает контрастность цветного изображения, регулируя цвет пикселей для охвата всего диапазона доступных цветов.

### Список параметров

`channel`
  Определяет, какой канал нормализовать.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Имитирует эффект картины маслом

### Описание

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

Применяет фильтр со специальным эффектом, имитирующий картину маслом. Каждый пиксель заменяется наиболее часто встречающимся цветом в круговой области, определяемой радиусом.

### Список параметров

`radius`
  Радиус круговой окрестности.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Осуществляет переход к предыдущему изображению в объекте

### Описание

public function Gmagick::previousimage(): bool

Связывает предыдущее изображение в списке изображений с объектом Gmagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Добавляет или удаляет профиль из изображения

### Описание

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

Добавляет или удаляет ICC, IPTC или общий профиль из изображения. Если значение profile равно `null`, профиль удаляется из изображения, в противном случае добавляется. Используйте значение `*` для параметра name и `null` для параметра profile, чтобы удалить все профили из изображения.

### Список параметров

`name`
  Имя профиля, который нужно добавить или удалить: ICC, IPTC или общий профиль.
`profile`
  Профиль.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Анализирует цвета эталонного изображения

### Описание

public function Gmagick::quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Анализирует цвета в эталонном изображении и выбирает фиксированное количество цветов для представления изображения. Целью алгоритма является минимизация разницы в цвете между входным и выходным изображением при минимизации времени обработки.

### Список параметров

`numColors`
  Количество цветов.
`colorspace`
  Цветовое пространство, в котором выполнится уменьшение цвета, обычно RGB.
`treeDepth`
  Обычно это целое значение равно нулю или единице. Ноль или единица указывает Quantize выбрать оптимальную глубину дерева Log4(number_colors). Дерево этой глубины обычно обеспечивает наилучшее представление эталонного изображения с наименьшим объёмом памяти и максимальной скоростью вычислений. В некоторых случаях, например для изображения с низкой цветовой дисперсией (несколько цветов), требуется значение, отличное от Log4(number_colors). Чтобы полностью развернуть дерево цветов, используйте значение 8.
`dither`
  Значение, отличное от нуля, распределяет разницу между исходным изображением и соответствующим алгоритмом уменьшения цвета на соседние пиксели вдоль кривой Гильберта.
`measureError`
  Значение, отличное от нуля, измеряет разницу между исходным и квантованным изображениями. Эта разница составляет полную ошибку квантования. Ошибка вычисляется путём суммирования по всем пикселям изображения квадрата расстояния в пространстве RGB между значением каждого эталонного пикселя и его квантованным значением.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — Анализирует цвета в последовательности изображений

### Описание

public function Gmagick::quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Анализирует цвета в последовательности изображений и выбирает фиксированное количество цветов для представления изображения. Целью алгоритма является минимизация разницы в цвете между входным и выходным изображением при минимизации времени обработки.

### Список параметров

`numColors`
  Количество цветов.
`colorspace`
  Цветовое пространство, в котором выполнится уменьшение цвета, обычно RGB.
`treeDepth`
  Обычно это целое значение равно нулю или единице. Ноль или единица указывает Quantize выбрать оптимальную глубину дерева Log4(number_colors). Дерево этой глубины обычно обеспечивает наилучшее представление эталонного изображения с наименьшим объёмом памяти и максимальной скоростью вычислений. В некоторых случаях, например для изображения с низкой цветовой дисперсией (несколько цветов), требуется значение, отличное от Log4(number_colors). Чтобы полностью развернуть дерево цветов, используйте значение 8.
`dither`
  Значение, отличное от нуля, распределяет разницу между исходным изображением и соответствующим алгоритмом уменьшения цвета на соседние пиксели вдоль кривой Гильберта.
`measureError`
  Значение, отличное от нуля, измеряет разницу между исходным и квантованным изображениями. Эта разница составляет полную ошибку квантования. Ошибка вычисляется путём суммирования по всем пикселям изображения квадрата расстояния в пространстве RGB между значением каждого эталонного пикселя и его квантованным значением.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Возвращает массив, представляющий метрики шрифта

### Описание

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

Возвращает массив, представляющий метрики шрифта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Возвращает настроенные шрифты

### Описание

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Возвращает шрифты, поддерживаемые Gmagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Возвращает форматы, поддерживаемые Gmagick

### Описание

public function Gmagick::queryformats(string `$pattern` = "*"): array

Возвращает форматы, поддерживаемые Gmagick.

### Список параметров

`pattern`
  Задаёт строку (string), содержащую шаблон.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Применяет радиальное размытие к изображению

### Описание

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Применяет радиальное размытие к изображению.

### Список параметров

`angle`
  Угол размытия в градусах.
`channel`
  Связанный канал.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Создаёт имитацию эффекта трёхмерной кнопки

### Описание

public function Gmagick::raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick

Создаёт имитацию эффекта трёхмерной кнопки, осветляя и затемняя края изображения. Ширина и высота элементов raise_info определяют ширину вертикального и горизонтального края эффекта.

### Список параметров

`width`
  Ширина области, которую нужно поднять.
`height`
  Высота поднимаемой площади.
`x`
  Координата X.
`y`
  Координата Y.
`raise`
  Значение, отличное от нуля, создаёт эффект трёхмерного возвышения, в противном случае - эффект понижения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Читает изображение из файла

### Описание

public function Gmagick::read(string `$filename`): Gmagick

Читает изображение из файла.

### Список параметров

`filename`
  Имя файла.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Читает изображение из файла

### Описание

public function Gmagick::readimage(string `$filename`): Gmagick

Читает изображение из файла.

### Список параметров

`filename`
  Имя файла.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Читает изображение из бинарной строки

### Описание

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Читает изображение из бинарной строки.

### Список параметров

`imageContents`
  Контент изображения.
`filename`
  Имя файла изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — Читает изображение или последовательность изображений из файлового дескриптора

### Описание

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Читает изображение или последовательность изображений из файлового дескриптора.

### Список параметров

`fp`
  Дескриптор файла.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Сглаживает контуры изображения

### Описание

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

Сглаживает контуры изображения, сохраняя при этом информацию о краях. Алгоритм работает, заменяя каждый пиксель ближайшим по значению соседом. Сосед определяется значением radius. Используйте значение radius, равное 0, и Gmagick::reducenoiseimage() выберет для вас подходящий радиус.

### Список параметров

`radius`
  Радиус окрестности пикселя.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Удаляет изображение из списка

### Описание

public function Gmagick::removeimage(): Gmagick

Удаляет изображение из списка.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Удаляет именованный профайл изображения и возвращает его

### Описание

public function Gmagick::removeimageprofile(string `$name`): string

Удаляет именованный профайл изображения и возвращает его.

### Список параметров

`name`
  Имя профайла: ICC, IPTC, или базовый профайл.

### Возвращаемые значения

Именованный профайл.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Изменяет разрешение изображения до желаемого

### Описание

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Изменяет разрешение изображения до желаемого.

### Список параметров

`xResolution`
  Новое разрешение по оси x.
`yResolution`
  Новое разрешение по оси y.
`filter`
  Фильтр изображений для использования.
`blur`
  Коэффициент размытия, где больше значение больше 1 делает изображение более размытым, значение меньше 1 - менее размытым.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Масштабирует изображение

### Описание

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

Масштабирует изображение до желаемых размеров с помощью фильтра.

### Список параметров

`width`
  Количество столбцов в масштабированном изображении.
`height`
  Количество строк в масштабированном изображении.
`filter`
  Фильтр изображений для использования.
`blur`
  Коэффициент размытия, где больше значение больше 1 делает изображение более размытым, значение меньше 1 - менее размытым.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Смещает изображение

### Описание

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Смещает изображение в соответствии с x и y.

### Список параметров

`x`
  Смещение по оси x.
`y`
  Смещение по оси y.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Поворачивает изображение

### Описание

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

Поворачивает изображение на указанное количество градусов. Пустые треугольники, оставшиеся от поворота изображения, заполняются цветом фона.

### Список параметров

`color`
  Пиксель фона.
`degrees`
  Число градусов для поворота изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Масштабирует размер изображения

### Описание

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Масштабирует размер изображения до заданных размеров. Другой параметр будет рассчитан, если в качестве любого из параметров будет передан 0.

### Список параметров

`width`
  Количество столбцов в масштабированном изображении.
`height`
  Количество строк в масштабированном изображении.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Отделяет канал от изображения

### Описание

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

Отделяет канал от изображения и возвращает изображение в оттенках серого. Канал - это определённый цветовой компонент каждого пикселя изображения.

### Список параметров

`channel`
  Одна из констант канала (`Gmagick::CHANNEL_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — Устанавливает для объекта качество сжатия по умолчанию

### Описание

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Метод устанавливает для объекта качество сжатия по умолчанию.

### Список параметров

`quality`
  Значение качества сжатия по умолчанию в библиотеке GraphicsMagick равно 75.

### Возвращаемые значения

Метод возвращает объект Gmagick, если выполнился успешно.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

### Примеры

Пример #1 Пример установки качества сжатия по умолчанию методом Gmagick::setCompressionQuality()

    <?php

    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);

    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — Устанавливает имя файла перед чтением или записью изображения

### Описание

public function Gmagick::setfilename(string `$filename`): Gmagick

Устанавливает имя файла перед чтением или записью изображения.

### Список параметров

`filename`
  Имя файла.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Устанавливает цвет фона изображения

### Описание

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Устанавливает цвет фона изображения.

### Список параметров

`color`
  Фоновая пиксельная палочка.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Устанавливает цветность изображения голубой основной точкой

### Описание

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Устанавливает цветность изображения голубой основной точкой.

### Список параметров

`x`
  X-координата голубой основной точки.
`y`
  Y-координата голубой основной точки.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Устанавливает цвет рамки изображения

### Описание

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Устанавливает цвет рамки изображения.

### Список параметров

`color`
  Цвет рамки.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Устанавливает глубину определённого канала изображения

### Описание

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Устанавливает глубину определённого канала изображения.

### Список параметров

`channel`
  Одна из констант канала (`Gmagick::CHANNEL_*`).
`depth`
  Глубина изображения в битах.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Устанавливает цветовое пространство изображения

### Описание

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Устанавливает цветовое пространство изображения.

### Список параметров

`colorspace`
  Одна из констант Цветового пространства (`Gmagick::COLORSPACE_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Устанавливает оператор составного изображения

### Описание

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Устанавливает оператор составного изображения.

### Список параметров

`composite`
  Оператор составного изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Устанавливает задержку изображения

### Описание

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Устанавливает задержку изображения.

### Список параметров

`delay`
  Задержка изображения в 1/100 секунды.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Устанавливает глубину изображения

### Описание

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Устанавливает глубину изображения.

### Список параметров

`depth`
  Глубина изображения в битах: 8, 16 или 32.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Устанавливает метод удаления изображения

### Описание

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Устанавливает метод удаления изображения.

### Список параметров

`disposeType`
  Тип удаления изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Устанавливает имя файла конкретного изображения в последовательности

### Описание

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Устанавливает имя файла конкретного изображения в последовательности.

### Список параметров

`filename`
  Имя файла изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Устанавливает формат определённого изображения

### Описание

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Устанавливает формат определённого изображения в последовательности.

### Список параметров

`imageFormat`
  Формат изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Устанавливает гамму изображения

### Описание

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Устанавливает гамму изображения.

### Список параметров

`gamma`
  Гамма изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Устанавливает цветность изображения зелёной первичной точкой

### Описание

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Устанавливает цветность изображения зелёной первичной точкой.

### Список параметров

`x`
  X-координата зелёной основной точки.
`y`
  Y-координата зелёной основной точки.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Устанавливает итератор в положение в списке изображений, заданном параметром index

### Описание

public function Gmagick::setimageindex(int `$index`): Gmagick

Устанавливает итератор в положение в списке изображений, заданном параметром index.

### Список параметров

`index`
  Номер сцены.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Устанавливает схему чересстрочной развёртки изображения

### Описание

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Устанавливает схему чересстрочной развёртки изображения.

### Список параметров

`interlace`
  Одна из констант схемы чересстрочного изображения (`Gmagick::INTERLACE_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Устанавливает итерации изображения

### Описание

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Устанавливает итерации изображения.

### Список параметров

`iterations`
  Задержка изображения в 1/100 секунды.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Добавляет именованный профиль в объект Gmagick

### Описание

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

Добавляет именованный профиль в объект Gmagick. Если профиль с таким именем уже существует, он заменяется. Метод отличается от метода Gmagick::profileimage() тем, что он не применяет цветовые профили CMS.

### Список параметров

`name`
  Имя профиля для добавления или удаления: ICC, IPTC или общий профиль.
`profile`
  Профиль.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Устанавливает цветность изображения красной основной точкой

### Описание

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Устанавливает цветность изображения красной основной точкой.

### Список параметров

`x`
  X-координата красной основной точки.
`y`
  Y-координата красной основной точки

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Устанавливает способ рендеринга изображения

### Описание

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Устанавливает способ рендеринга изображения.

### Список параметров

`rendering_intent`
  Одна из констант способа отображения (`Gmagick::RENDERINGINTENT_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Устанавливает разрешение изображения

### Описание

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Устанавливает разрешение изображения.

### Список параметров

`xResolution`
  Разрешение изображения х.
`yResolution`
  Разрешение изображения y.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Устанавливает сцену изображения

### Описание

public function Gmagick::setimagescene(int `$scene`): Gmagick

Устанавливает сцену изображения.

### Список параметров

`scene`
  Номер сцены изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Устанавливает тип изображения

### Описание

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Устанавливает тип изображения.

### Список параметров

`imgType`
  Одна из констант типа изображения (`Gmagick::IMGTYPE_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Устанавливает единицы разрешения изображения

### Описание

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Устанавливает единицы разрешения изображения.

### Список параметров

`resolution`
  Одна из констант разрешения (`Gmagick::RESOLUTION_*`).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Устанавливает цветность изображения белой точкой

### Описание

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Устанавливает цветность изображения белой точкой.

### Список параметров

`x`
  X-координата белой основной точки.
`y`
  Y-координата белой основной точки.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Устанавливает факторы выборки изображения

### Описание

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Устанавливает факторы выборки изображения.

### Список параметров

`factors`
  Массив значений с типом float, представляющий фактор выборки для каждого компонента цвета (в порядке RGB).

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Устанавливает размер объекта Gmagick

### Описание

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Устанавливает размер объекта Gmagick. Установите его, прежде чем читать сырой формат изображения, такой как `Gmagick::COLORSPACE_RGB`, `Gmagick::COLORSPACE_GRAY` или `Gmagick::COLORSPACE_CMYK`.

### Список параметров

`columns`
  Ширина в пикселях.
`rows`
  Высота в пикселях.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Создаёт параллелограмм

### Описание

public function Gmagick::shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick

Сдвигает один край изображения по оси X или Y, образуя параллелограмм. Сдвиг в направлении X сдвигает край по оси X, а сдвиг в направлении Y перемещает край по оси Y. Величина сдвига контролируется углом сдвига. Для сдвига в направлении X xShear измеряется относительно оси Y, и аналогичным образом для сдвига в направлении Y yShear измеряется относительно оси X. Пустые треугольники, оставшиеся от обрезки изображения, заполняются цветом фона.

### Список параметров

`color`
  Фоновая пиксельная палочка.
`xShear`
  Число градусов для сдвига изображения по оси X.
`yShear`
  Число градусов для сдвига изображения по оси Y.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Применяет соляризационный эффект к изображению

### Описание

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

Применяет особый эффект к изображению, подобный эффекту, достигаемому в фотолаборатории с помощью выборочного экспонирования областей светочувствительной бумаги на свет. Порог варьируется от 0 до QuantumRange и является мерой степени соляризации.

### Список параметров

`threshold`
  Степень соляризации.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Случайно смещает каждый пиксель в блоке

### Описание

public function Gmagick::spreadimage(float `$radius`): Gmagick

Метод специальных эффектов, который случайным образом смещает каждый пиксель в блоке, заданном параметром radius.

### Список параметров

`radius`
  Выберите случайный пиксель в окрестности этого пространства.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Снимает изображение всех профилей и комментариев

### Описание

public function Gmagick::stripimage(): Gmagick

Снимает изображение всех профилей и комментариев.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Закручивает пиксели вокруг центра изображения

### Описание

public function Gmagick::swirlimage(float `$degrees`): Gmagick

Закручивает пиксели вокруг центра изображения, где градусы указывают размах дуги, по которой перемещается каждый пиксель. Вы получаете более драматический эффект, когда градусы перемещаются от 1 до 360.

### Список параметров

`degrees`
  Определяет герметичность закрученного эффекта.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Изменяет размер изображения

### Описание

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Изменяет размер изображения до заданных размеров и удаляет все связанные профили. Цель заключается в создании небольших миниатюрных изображений, подходящих для показа в Интернете. Если в качестве третьего параметра задано значение `true`, то параметры столбцов и строк используются в качестве максимумов для каждой стороны. Обе стороны будут уменьшены до совпадения или меньше, чем параметр, заданный для стороны.

### Список параметров

`width`
  Ширина изображения.
`height`
  Высота изображения.

### Возвращаемые значения

Объект Gmagick в случае успешного выполнения.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Удаляет края с изображения

### Описание

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Удаляет края, которые являются цветом фона с изображения.

### Список параметров

`fuzz`
  По умолчанию цель должна точно соответствовать определённому цвету пикселя. Однако во многих случаях два цвета могут незначительно отличаться. Размытый элемент изображения определяет, насколько допустимо определять, чтобы два цвета считались одинаковыми. Параметр представляет собой изменение квантового диапазона.

### Возвращаемые значения

Объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Псевдоним Gmagick::writeimage()

### Описание

Псевдоним метода Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Записывает изображение в указанный файл

### Описание

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

Записывает изображение в указанный файл. Если в качестве имени файла указано `null`, то изображение будет записано в файл, заданный Gmagick::readimage() или Gmagick::setimagefilename().

### Список параметров

`filename`
  Имя файла.

### Возвращаемые значения

Объект Gmagick.

### Ошибки

Вызывает GmagickException, если возникла ошибка.

## Содержание

- Gmagick::addimage — Добавление нового изображения в список изображений объекта Gmagick
- Gmagick::addnoiseimage — Добавляет случайный шум к изображению
- Gmagick::annotateimage — Подписать изображение текстом
- Gmagick::blurimage — Добавить размытие изображению
- Gmagick::borderimage — Добавить рамку к изображению
- Gmagick::charcoalimage — Имитация рисования углём
- Gmagick::chopimage — Удаляет область изображения и подрезает его
- Gmagick::clear — Зачищает все ресурсы, связанные с объектом Gmagick
- Gmagick::commentimage — Добавить комментарий к изображению
- Gmagick::compositeimage — Накладывает одно изображение на другое
- Gmagick::__construct — Конструктор объекта Gmagick
- Gmagick::cropimage — Обрезает изображение
- Gmagick::cropthumbnailimage — Создание обрезанного уменьшенного изображения
- Gmagick::current — Вернуть самого себя
- Gmagick::cyclecolormapimage — Смещает цветовую карту изображения
- Gmagick::deconstructimages — Возвращает определённые пиксельные различия между изображениями
- Gmagick::despeckleimage — Назначение despeckleimage
- Gmagick::destroy — Уничтожить объект Gmagick
- Gmagick::drawimage — Отображает объект GmagickDraw на текущем изображении
- Gmagick::edgeimage — Увеличивает края в изображении
- Gmagick::embossimage — Возвращает изображение в градациях серого с трёхмерным эффектом
- Gmagick::enhanceimage — Улучшает качество изображения с шумом
- Gmagick::equalizeimage — Выравнивает гистограмму изображения
- Gmagick::flipimage — Создаёт вертикальное зеркальное отображение
- Gmagick::flopimage — Создаёт горизонтальное зеркальное отображение
- Gmagick::frameimage — Добавляет смоделированную трёхмерную границу
- Gmagick::gammaimage — Гамма-коррекция изображения
- Gmagick::getcopyright — Возвращает копирайт GraphicsMagick API в виде строки
- Gmagick::getfilename — Возвращает имя файла связанного с последовательностью изображений
- Gmagick::getimagebackgroundcolor — Возвращает цвет фона изображения
- Gmagick::getimageblueprimary — Возвращает цветность синей первичной точки
- Gmagick::getimagebordercolor — Возвращает цвет границы изображения
- Gmagick::getimagechanneldepth — Получает глубину для определённого канала изображения
- Gmagick::getimagecolors — Возвращает цвет индекса карты цветов
- Gmagick::getimagecolorspace — Возвращает цветовое пространство изображения
- Gmagick::getimagecompose — Возвращает составной оператор, связанный с изображением
- Gmagick::getimagedelay — Получает задержку изображения
- Gmagick::getimagedepth — Получает глубину изображения
- Gmagick::getimagedispose — Получает метод удаления изображения
- Gmagick::getimageextrema — Получает экстремумы для изображения
- Gmagick::getimagefilename — Возвращает имя файла конкретного изображения в последовательности
- Gmagick::getimageformat — Возвращает формат конкретного изображения в последовательности
- Gmagick::getimagegamma — Возвращает гамму изображения
- Gmagick::getimagegreenprimary — Возвращает первичную зелёную точку
- Gmagick::getimageheight — Возвращает высоту изображения
- Gmagick::getimagehistogram — Возвращает гистограмму изображения
- Gmagick::getimageindex — Возвращает индекс текущего активного изображения
- Gmagick::getimageinterlacescheme — Получает схему чередования изображений
- Gmagick::getimageiterations — Получает итерации изображения
- Gmagick::getimagematte — Проверяет, есть ли на изображении матовый канал
- Gmagick::getimagemattecolor — Возвращает изображение матового цвета
- Gmagick::getimageprofile — Возвращает именованный профайл изображения
- Gmagick::getimageredprimary — Возвращает первичную красную точку
- Gmagick::getimagerenderingintent — Получает цель рендеринга изображения
- Gmagick::getimageresolution — Возвращает разрешение изображения
- Gmagick::getimagescene — Получает сцену изображения
- Gmagick::getimagesignature — Создаёт подпись сообщения SHA-256
- Gmagick::getimagetype — Возвращает потенциальный тип изображения
- Gmagick::getimageunits — Возвращает единицы разрешения изображения
- Gmagick::getimagewhitepoint — Возвращает хроматическую белую точку
- Gmagick::getimagewidth — Возвращает ширину изображения
- Gmagick::getpackagename — Возвращает имя пакета GraphicsMagick
- Gmagick::getquantumdepth — Возвращает глубину цвета (бит на канал) объекта Gmagick в виде строки
- Gmagick::getreleasedate — Возвращает дату релиза GraphicsMagick в виде строки
- Gmagick::getsamplingfactors — Возвращает вертикальный и горизонтальный фактор дискретизации
- Gmagick::getsize — Возвращает размер, связанный с объектом Gmagick
- Gmagick::getversion — Возвращает версию GraphicsMagick API
- Gmagick::hasnextimage — Проверяет, есть ли ещё изображения в объекте
- Gmagick::haspreviousimage — Проверяет, есть ли ещё изображения в объекте при итерации назад
- Gmagick::implodeimage — Создаёт копию изображения
- Gmagick::labelimage — Добавляет метку к изображению
- Gmagick::levelimage — Регулирует уровни изображения
- Gmagick::magnifyimage — Пропорционально масштабирует изображение в 2 раза
- Gmagick::mapimage — Заменяет цвета изображения на ближайший цвет из эталонного изображения
- Gmagick::medianfilterimage — Применяет цифровой фильтр
- Gmagick::minifyimage — Масштабирует изображение пропорционально половине его размера
- Gmagick::modulateimage — Управляет яркостью, насыщенностью и оттенком
- Gmagick::motionblurimage — Имитирует размытие при движении
- Gmagick::newimage — Создаёт новое изображение
- Gmagick::nextimage — Осуществляет переход к следующему изображению
- Gmagick::normalizeimage — Повышает контрастность цветного изображения
- Gmagick::oilpaintimage — Имитирует эффект картины маслом
- Gmagick::previousimage — Осуществляет переход к предыдущему изображению в объекте
- Gmagick::profileimage — Добавляет или удаляет профиль из изображения
- Gmagick::quantizeimage — Анализирует цвета эталонного изображения
- Gmagick::quantizeimages — Анализирует цвета в последовательности изображений
- Gmagick::queryfontmetrics — Возвращает массив, представляющий метрики шрифта
- Gmagick::queryfonts — Возвращает настроенные шрифты
- Gmagick::queryformats — Возвращает форматы, поддерживаемые Gmagick
- Gmagick::radialblurimage — Применяет радиальное размытие к изображению
- Gmagick::raiseimage — Создаёт имитацию эффекта трёхмерной кнопки
- Gmagick::read — Читает изображение из файла
- Gmagick::readimage — Читает изображение из файла
- Gmagick::readimageblob — Читает изображение из бинарной строки
- Gmagick::readimagefile — Читает изображение или последовательность изображений из файлового дескриптора
- Gmagick::reducenoiseimage — Сглаживает контуры изображения
- Gmagick::removeimage — Удаляет изображение из списка
- Gmagick::removeimageprofile — Удаляет именованный профайл изображения и возвращает его
- Gmagick::resampleimage — Изменяет разрешение изображения до желаемого
- Gmagick::resizeimage — Масштабирует изображение
- Gmagick::rollimage — Смещает изображение
- Gmagick::rotateimage — Поворачивает изображение
- Gmagick::scaleimage — Масштабирует размер изображения
- Gmagick::separateimagechannel — Отделяет канал от изображения
- Gmagick::setCompressionQuality — Устанавливает для объекта качество сжатия по умолчанию
- Gmagick::setfilename — Устанавливает имя файла перед чтением или записью изображения
- Gmagick::setimagebackgroundcolor — Устанавливает цвет фона изображения
- Gmagick::setimageblueprimary — Устанавливает цветность изображения голубой основной точкой
- Gmagick::setimagebordercolor — Устанавливает цвет рамки изображения
- Gmagick::setimagechanneldepth — Устанавливает глубину определённого канала изображения
- Gmagick::setimagecolorspace — Устанавливает цветовое пространство изображения
- Gmagick::setimagecompose — Устанавливает оператор составного изображения
- Gmagick::setimagedelay — Устанавливает задержку изображения
- Gmagick::setimagedepth — Устанавливает глубину изображения
- Gmagick::setimagedispose — Устанавливает метод удаления изображения
- Gmagick::setimagefilename — Устанавливает имя файла конкретного изображения в последовательности
- Gmagick::setimageformat — Устанавливает формат определённого изображения
- Gmagick::setimagegamma — Устанавливает гамму изображения
- Gmagick::setimagegreenprimary — Устанавливает цветность изображения зелёной первичной точкой
- Gmagick::setimageindex — Устанавливает итератор в положение в списке изображений, заданном параметром index
- Gmagick::setimageinterlacescheme — Устанавливает схему чересстрочной развёртки изображения
- Gmagick::setimageiterations — Устанавливает итерации изображения
- Gmagick::setimageprofile — Добавляет именованный профиль в объект Gmagick
- Gmagick::setimageredprimary — Устанавливает цветность изображения красной основной точкой
- Gmagick::setimagerenderingintent — Устанавливает способ рендеринга изображения
- Gmagick::setimageresolution — Устанавливает разрешение изображения
- Gmagick::setimagescene — Устанавливает сцену изображения
- Gmagick::setimagetype — Устанавливает тип изображения
- Gmagick::setimageunits — Устанавливает единицы разрешения изображения
- Gmagick::setimagewhitepoint — Устанавливает цветность изображения белой точкой
- Gmagick::setsamplingfactors — Устанавливает факторы выборки изображения
- Gmagick::setsize — Устанавливает размер объекта Gmagick
- Gmagick::shearimage — Создаёт параллелограмм
- Gmagick::solarizeimage — Применяет соляризационный эффект к изображению
- Gmagick::spreadimage — Случайно смещает каждый пиксель в блоке
- Gmagick::stripimage — Снимает изображение всех профилей и комментариев
- Gmagick::swirlimage — Закручивает пиксели вокруг центра изображения
- Gmagick::thumbnailimage — Изменяет размер изображения
- Gmagick::trimimage — Удаляет края с изображения
- Gmagick::write — Псевдоним Gmagick::writeimage
- Gmagick::writeimage — Записывает изображение в указанный файл

# Класс GmagickDraw

(PECL gmagick >= Unknown)

## Введение

## Обзор класса

class GmagickDraw {
/* Методы */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — Рисует текст на изображении

### Описание

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Рисует текст на изображении.

### Список параметров

`x`
  Координата x слева от текста.
`y`
  Координата y относительно базовой линии текста.
`text`
  Текст для рисования.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Рисует дугу

### Описание

public function GmagickDraw::arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw

Рисует дугу, находящуюся в пределах ограничивающего прямоугольника на изображении.

### Список параметров

`sx`
  Начальная координата x ограничивающего прямоугольника.
`sy`
  Начальная координата y ограничивающего прямоугольника.
`ex`
  Конечная координата x ограничивающего прямоугольника.
`ey`
  Конечная координата y ограничивающего прямоугольника.
`sd`
  Начальный градус поворота.
`ed`
  Конечный градус поворота.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Рисует кривую Безье

### Описание

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Рисует кривую Безье через набор точек на изображении.

### Список параметров

`coordinate_array`
  Массив координат.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Рисует эллипс на изображении

### Описание

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Рисует эллипс на изображении.

### Список параметров

`ox`
  Исходная координата x.
`oy`
  Исходная координата y.
`rx`
  Радиус в x.
`ry`
  Радиус в y.
`start`
  Начальный градус поворота.
`end`
  Конечный градус поворота.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Возвращает цвет заливки

### Описание

public function GmagickDraw::getfillcolor(): GmagickPixel

Возвращает цвет заливки, используемый для рисования объектов с заливкой.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Цвет заливки GmagickPixel, используемый для рисования объектов с заливкой.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Возвращает значение прозрачности, используемое при рисовании

### Описание

public function GmagickDraw::getfillopacity(): float

Возвращает значение прозрачности, используемое при рисовании.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает прозрачность, используемую при рисовании с использованием цвета заливки или текстуры заливки. Значение полностью непрозрачного цвета - 1.0.

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — Возвращает шрифт

### Описание

public function GmagickDraw::getfont(): mixed

Возвращает строку, определяющую шрифт, используемый при аннотировании текстом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку (string) в случае успешного выполнения или `false`, если шрифт не установлен.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Возвращает размер шрифта

### Описание

public function GmagickDraw::getfontsize(): float

Возвращает размер шрифта, используемый при аннотировании текстом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер шрифта, связанный с текущим объектом GmagickDraw.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Возвращает стиль шрифта

### Описание

public function GmagickDraw::getfontstyle(): int

Возвращает стиль шрифта, используемый при аннотировании текстом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает константу стиля шрифта (STYLE_), связанную с объектом GmagickDraw, или `0`, если стиль не установлен.

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — Возвращает толщину шрифта

### Описание

public function GmagickDraw::getfontweight(): int

Возвращает толщину шрифта, используемую при аннотировании текстом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число (int) в случае успешного выполнения или 0, если толщина не установлена.

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — Возвращает цвет, используемый для обводки контуров объекта

### Описание

public function GmagickDraw::getstrokecolor(): GmagickPixel

Возвращает цвет, используемый для обводки контуров объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект GmagickPixel, который описывает цвет.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Возвращает прозрачность обведённых контуров объекта

### Описание

public function GmagickDraw::getstrokeopacity(): float

Возвращает прозрачность обведённых контуров объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает число с плавающей точкой (float), описывающее прозрачность.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Возвращает ширину обводки, используемой для отрисовки контуров объекта

### Описание

public function GmagickDraw::getstrokewidth(): float

Возвращает ширину обводки, используемой для отрисовки контуров объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает число с плавающей точкой (float), описывающее ширину обводки.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Возвращает оформление текста

### Описание

public function GmagickDraw::gettextdecoration(): int

Возвращает оформление, применённое при аннотации текста.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает одну из констант DECORATION_ или 0, если оформление не установлено.

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — Возвращает кодовый набор, используемый для текстовых аннотаций

### Описание

public function GmagickDraw::gettextencoding(): mixed

Возвращает строку, определяющую кодовый набор, используемый для текстовых аннотаций.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку с указанием кодового набора или `false`, если кодировка текста не задана.

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — Рисует линию

### Описание

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

Рисует линию на изображении, используя текущий цвет обводки, её прозрачность и ширину.

### Список параметров

`sx`
  Начальная координата x.
`sy`
  Начальная координата y.
`ex`
  Конечная координата x.
`ey`
  Конечная координата y.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Рисует точку

### Описание

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Рисует точку, используя текущий цвет и толщину обводки по указанным координатам.

### Список параметров

`x`
  Координата x.
`y`
  Координата y.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Рисует многоугольник

### Описание

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

Рисует многоугольник с использованием текущей обводки, её ширины, цвета заливки или текстуры с использованием указанного массива координат.

### Список параметров

`coordinates`
  Массив координат.

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Рисует ломаную линию

### Описание

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

Рисует ломаную линию с использованием текущей обводки, её ширины, цвета заливки или текстуры с использованием указанного массива координат.

### Список параметров

`coordinate_array`
  Массив координат.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Рисует прямоугольник

### Описание

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

Рисует прямоугольник по двум координатам с использованием текущих параметров обводки, ширины обводки и заливки.

### Список параметров

`x1`
  Первая координата x.
`y1`
  Первая координата y.
`x2`
  Вторая координата x.
`y2`
  Вторая координата y.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Применяет указанный поворот к текущему координатному пространству

### Описание

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Применяет указанный поворот к текущему координатному пространству.

### Список параметров

`degrees`
  Угол поворота

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Рисует прямоугольник с закруглёнными углами

### Описание

public function GmagickDraw::roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw

Рисует прямоугольник с закруглёнными углами по двум координатам и радиусам углов x и y, используя текущую обводку, её ширину и настройки заливки.

### Список параметров

`x1`
  Первая координата x.
`y1`
  Первая координата y.
`x2`
  Вторая координата x.
`y2`
  Вторая координата y.
`rx`
  Радиус угла в горизонтальном направлении.
`ry`
  Радиус угла в вертикальном направлении.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Регулирует коэффициент масштабирования

### Описание

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

Регулирует коэффициент масштабирования для применения в горизонтальном и вертикальном направлениях к текущему координатному пространству.

### Список параметров

`x`
  горизонтальный коэффициент масштабирования
`y`
  вертикальный коэффициент масштабирования

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Устанавливает цвет заливки, который будет использоваться для рисования объектов с заливкой

### Описание

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Устанавливает цвет заливки, который будет использоваться для рисования объектов с заливкой.

### Список параметров

`color`
  GmagickPixel или строка (string), указывающая цвет, используемый для заливки.

### Возвращаемые значения

Объект GmagickDraw в случае успешного выполнения.

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — Устанавливает непрозрачность заливки

### Описание

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

Устанавливает непрозрачность при рисовании с использованием цвета заливки или текстуры заливки. Установка значения 1.0 сделает заливку полностью непрозрачной.

### Список параметров

`fill_opacity`
  Непрозрачность заливки

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Устанавливает указанный шрифт для использования при аннотации текста

### Описание

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Устанавливает полностью указанный шрифт для использования при аннотации текста.

### Список параметров

`font`
  Имя шрифта.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Устанавливает размер шрифта для использования при аннотации текста

### Описание

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Устанавливает размер шрифта для использования при аннотации текста.

### Список параметров

`pointsize`
  Размер шрифта

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Устанавливает стиль шрифта для использования при аннотации текста

### Описание

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

Устанавливает стиль шрифта, который будет использоваться при аннотации текста. Использование AnyStyle действует как «любой».

### Список параметров

`style`
  Стиль шрифта (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle).

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Устанавливает толщину шрифта

### Описание

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Устанавливает толщину шрифта для использования при аннотации текста.

### Список параметров

`weight`
  Толщина шрифта (допустимый диапазон - 100-900).

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Устанавливает цвет, используемый для обводки контуров объекта

### Описание

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Устанавливает цвет, используемый для обводки контуров объекта.

### Список параметров

`color`
  GmagickPixel или строка (string), представляющая цвет обводки.

### Возвращаемые значения

Объект GmagickDraw в случае успешного выполнения.

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Определяет прозрачность обводки контуров объекта

### Описание

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Определяет прозрачность обводки контуров объекта.

### Список параметров

`stroke_opacity`
  Прозрачность обводки. При значении 1.0 - непрозрачная.

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Устанавливает ширину обводки, используемой для отрисовки контуров объекта

### Описание

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Устанавливает ширину обводки, используемой для отрисовки контуров объекта.

### Список параметров

`width`
  Ширина обводки

### Возвращаемые значения

Объект GmagickDraw.

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Определяет оформление

### Описание

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Задаёт оформление, которое будет применяться при аннотировании текстом.

### Список параметров

`int`
  Оформление текста. Одно из следующих значений: NoDecoration, UnderlineDecoration, OverlineDecoration или LineThroughDecoration.

### Возвращаемые значения

Объект Gmagick.

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Задаёт кодовый набор текста

### Описание

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

Задаёт кодовый набор, который будет использоваться для текстовых аннотаций. Единственная кодировка символов, которая может быть указана в настоящее время, - это "UTF-8" для представления Unicode как последовательности байтов. Укажите пустую строку, чтобы установить кодировку текста по умолчанию в системе. Для успешного аннотирования текста с использованием Unicode могут потребоваться шрифты, поддерживающие Unicode.

### Список параметров

`encoding`
  Строка символов, определяющая кодировку текста.

### Возвращаемые значения

Объект Gmagick.

## Содержание

- GmagickDraw::annotate — Рисует текст на изображении
- GmagickDraw::arc — Рисует дугу
- GmagickDraw::bezier — Рисует кривую Безье
- GmagickDraw::ellipse — Рисует эллипс на изображении
- GmagickDraw::getfillcolor — Возвращает цвет заливки
- GmagickDraw::getfillopacity — Возвращает значение прозрачности, используемое при рисовании
- GmagickDraw::getfont — Возвращает шрифт
- GmagickDraw::getfontsize — Возвращает размер шрифта
- GmagickDraw::getfontstyle — Возвращает стиль шрифта
- GmagickDraw::getfontweight — Возвращает толщину шрифта
- GmagickDraw::getstrokecolor — Возвращает цвет, используемый для обводки контуров объекта
- GmagickDraw::getstrokeopacity — Возвращает прозрачность обведённых контуров объекта
- GmagickDraw::getstrokewidth — Возвращает ширину обводки, используемой для отрисовки контуров объекта
- GmagickDraw::gettextdecoration — Возвращает оформление текста
- GmagickDraw::gettextencoding — Возвращает кодовый набор, используемый для текстовых аннотаций
- GmagickDraw::line — Рисует линию
- GmagickDraw::point — Рисует точку
- GmagickDraw::polygon — Рисует многоугольник
- GmagickDraw::polyline — Рисует ломаную линию
- GmagickDraw::rectangle — Рисует прямоугольник
- GmagickDraw::rotate — Применяет указанный поворот к текущему координатному пространству
- GmagickDraw::roundrectangle — Рисует прямоугольник с закруглёнными углами
- GmagickDraw::scale — Регулирует коэффициент масштабирования
- GmagickDraw::setfillcolor — Устанавливает цвет заливки, который будет использоваться для рисования объектов с заливкой
- GmagickDraw::setfillopacity — Устанавливает непрозрачность заливки
- GmagickDraw::setfont — Устанавливает указанный шрифт для использования при аннотации текста
- GmagickDraw::setfontsize — Устанавливает размер шрифта для использования при аннотации текста
- GmagickDraw::setfontstyle — Устанавливает стиль шрифта для использования при аннотации текста
- GmagickDraw::setfontweight — Устанавливает толщину шрифта
- GmagickDraw::setstrokecolor — Устанавливает цвет, используемый для обводки контуров объекта
- GmagickDraw::setstrokeopacity — Определяет прозрачность обводки контуров объекта
- GmagickDraw::setstrokewidth — Устанавливает ширину обводки, используемой для отрисовки контуров объекта
- GmagickDraw::settextdecoration — Определяет оформление
- GmagickDraw::settextencoding — Задаёт кодовый набор текста

# Класс GmagickPixel

(PECL gmagick >= Unknown)

## Введение

## Обзор класса

class GmagickPixel {
/* Методы */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — Конструктора класса GmagickPixel

### Описание

public function GmagickPixel::__construct(string `$color` = ?)

Создаёт новый объект класса GmagickPixel. Если указан цвет, то объект будет инициализирован этим цветом.

### Список параметров

`color`
  Опциональный параметр, используется для начального значения цвета объекта.

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Возвращает цвет

### Описание

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Возвращает цвет объекта GmagickPixel в виде массива (array) либо строки (string). Если для цвета установлена прозрачность, то её значение возвращается в четвёртом элементе списка.

### Список параметров

`as_array`
  `true` для типа возвращаемого значения array, а не string.
`normalize_array`
  Значение цветов будут нормированы, если `true`.

### Возвращаемые значения

string или array со значениями цветов, нормированными, если параметр `normalize_array` установлен в `true`. Бросает исключение GmagickPixelException в случае возникновения ошибки.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Получить количество пикселей изображения, имеющих заданный цвет

### Описание

public function GmagickPixel::getcolorcount(): int

Возвращает количество пикселей изображения, имеющих заданный цвет.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество пикселей изображения, имеющих заданный цвет, в случае успешного выполнения. В случае возникновения ошибки выбрасывает исключение GmagickPixelException.

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — Возвращает нормализованное значение для заданного цветового канала

### Описание

public function GmagickPixel::getcolorvalue(int `$color`): float

Возвращает нормализованное значение для заданного цветового канала в виде числа с плавающей точкой в диапазоне от 0 до 1.

### Список параметров

`color`
  Цветовой канал. Одна из констант цветовых каналов Gmagick.

### Возвращаемые значения

Возвращает нормализованное значение для заданного цветового канала, либо, в случае возникновения ошибки, выбрасывает исключение GmagickPixelException.

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — Задать цвет

### Описание

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

Задать цвет в формате объекта GmagickPixel с помощью строки (например, "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", и т.д.).

### Список параметров

`color`
  Определение цвета для инициализации объекта GmagickPixel.

### Возвращаемые значения

Объект GmagickPixel.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Установить нормализованное значение цветового канала

### Описание

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

Устанавливает нормализованное значение цветового канала. Значение должно быть числом с плавающей точкой (float) в диапазоне от 0 до 1. Также данная функция может использоваться для задания канала прозрачности объекта GmagickPixel.

### Список параметров

`color`
  Цветовой канал. Одна из констант цветовых каналов Gmagick.
`value`
  Устанавливаемое значение. Число с плавающей точкой в диапазоне от 0 до 1.

### Возвращаемые значения

Объект GmagickPixel в случае успешного выполнения.

## Содержание

- GmagickPixel::__construct — Конструктора класса GmagickPixel
- GmagickPixel::getcolor — Возвращает цвет
- GmagickPixel::getcolorcount — Получить количество пикселей изображения, имеющих заданный цвет
- GmagickPixel::getcolorvalue — Возвращает нормализованное значение для заданного цветового канала
- GmagickPixel::setcolor — Задать цвет
- GmagickPixel::setcolorvalue — Установить нормализованное значение цветового канала

- Установка и настройка
  - Требования
  - Установка
- Предопределённые константы
- Примеры
- Gmagick — Класс Gmagick
  - Gmagick::addimage — Добавление нового изображения в список изображений объекта Gmagick
  - Gmagick::addnoiseimage — Добавляет случайный шум к изображению
  - Gmagick::annotateimage — Подписать изображение текстом
  - Gmagick::blurimage — Добавить размытие изображению
  - Gmagick::borderimage — Добавить рамку к изображению
  - Gmagick::charcoalimage — Имитация рисования углём
  - Gmagick::chopimage — Удаляет область изображения и подрезает его
  - Gmagick::clear — Зачищает все ресурсы, связанные с объектом Gmagick
  - Gmagick::commentimage — Добавить комментарий к изображению
  - Gmagick::compositeimage — Накладывает одно изображение на другое
  - Gmagick::__construct — Конструктор объекта Gmagick
  - Gmagick::cropimage — Обрезает изображение
  - Gmagick::cropthumbnailimage — Создание обрезанного уменьшенного изображения
  - Gmagick::current — Вернуть самого себя
  - Gmagick::cyclecolormapimage — Смещает цветовую карту изображения
  - Gmagick::deconstructimages — Возвращает определённые пиксельные различия между изображениями
  - Gmagick::despeckleimage — Назначение despeckleimage
  - Gmagick::destroy — Уничтожить объект Gmagick
  - Gmagick::drawimage — Отображает объект GmagickDraw на текущем изображении
  - Gmagick::edgeimage — Увеличивает края в изображении
  - Gmagick::embossimage — Возвращает изображение в градациях серого с трёхмерным эффектом
  - Gmagick::enhanceimage — Улучшает качество изображения с шумом
  - Gmagick::equalizeimage — Выравнивает гистограмму изображения
  - Gmagick::flipimage — Создаёт вертикальное зеркальное отображение
  - Gmagick::flopimage — Создаёт горизонтальное зеркальное отображение
  - Gmagick::frameimage — Добавляет смоделированную трёхмерную границу
  - Gmagick::gammaimage — Гамма-коррекция изображения
  - Gmagick::getcopyright — Возвращает копирайт GraphicsMagick API в виде строки
  - Gmagick::getfilename — Возвращает имя файла связанного с последовательностью изображений
  - Gmagick::getimagebackgroundcolor — Возвращает цвет фона изображения
  - Gmagick::getimageblueprimary — Возвращает цветность синей первичной точки
  - Gmagick::getimagebordercolor — Возвращает цвет границы изображения
  - Gmagick::getimagechanneldepth — Получает глубину для определённого канала изображения
  - Gmagick::getimagecolors — Возвращает цвет индекса карты цветов
  - Gmagick::getimagecolorspace — Возвращает цветовое пространство изображения
  - Gmagick::getimagecompose — Возвращает составной оператор, связанный с изображением
  - Gmagick::getimagedelay — Получает задержку изображения
  - Gmagick::getimagedepth — Получает глубину изображения
  - Gmagick::getimagedispose — Получает метод удаления изображения
  - Gmagick::getimageextrema — Получает экстремумы для изображения
  - Gmagick::getimagefilename — Возвращает имя файла конкретного изображения в последовательности
  - Gmagick::getimageformat — Возвращает формат конкретного изображения в последовательности
  - Gmagick::getimagegamma — Возвращает гамму изображения
  - Gmagick::getimagegreenprimary — Возвращает первичную зелёную точку
  - Gmagick::getimageheight — Возвращает высоту изображения
  - Gmagick::getimagehistogram — Возвращает гистограмму изображения
  - Gmagick::getimageindex — Возвращает индекс текущего активного изображения
  - Gmagick::getimageinterlacescheme — Получает схему чередования изображений
  - Gmagick::getimageiterations — Получает итерации изображения
  - Gmagick::getimagematte — Проверяет, есть ли на изображении матовый канал
  - Gmagick::getimagemattecolor — Возвращает изображение матового цвета
  - Gmagick::getimageprofile — Возвращает именованный профайл изображения
  - Gmagick::getimageredprimary — Возвращает первичную красную точку
  - Gmagick::getimagerenderingintent — Получает цель рендеринга изображения
  - Gmagick::getimageresolution — Возвращает разрешение изображения
  - Gmagick::getimagescene — Получает сцену изображения
  - Gmagick::getimagesignature — Создаёт подпись сообщения SHA-256
  - Gmagick::getimagetype — Возвращает потенциальный тип изображения
  - Gmagick::getimageunits — Возвращает единицы разрешения изображения
  - Gmagick::getimagewhitepoint — Возвращает хроматическую белую точку
  - Gmagick::getimagewidth — Возвращает ширину изображения
  - Gmagick::getpackagename — Возвращает имя пакета GraphicsMagick
  - Gmagick::getquantumdepth — Возвращает глубину цвета (бит на канал) объекта Gmagick в виде строки
  - Gmagick::getreleasedate — Возвращает дату релиза GraphicsMagick в виде строки
  - Gmagick::getsamplingfactors — Возвращает вертикальный и горизонтальный фактор дискретизации
  - Gmagick::getsize — Возвращает размер, связанный с объектом Gmagick
  - Gmagick::getversion — Возвращает версию GraphicsMagick API
  - Gmagick::hasnextimage — Проверяет, есть ли ещё изображения в объекте
  - Gmagick::haspreviousimage — Проверяет, есть ли ещё изображения в объекте при итерации назад
  - Gmagick::implodeimage — Создаёт копию изображения
  - Gmagick::labelimage — Добавляет метку к изображению
  - Gmagick::levelimage — Регулирует уровни изображения
  - Gmagick::magnifyimage — Пропорционально масштабирует изображение в 2 раза
  - Gmagick::mapimage — Заменяет цвета изображения на ближайший цвет из эталонного изображения
  - Gmagick::medianfilterimage — Применяет цифровой фильтр
  - Gmagick::minifyimage — Масштабирует изображение пропорционально половине его размера
  - Gmagick::modulateimage — Управляет яркостью, насыщенностью и оттенком
  - Gmagick::motionblurimage — Имитирует размытие при движении
  - Gmagick::newimage — Создаёт новое изображение
  - Gmagick::nextimage — Осуществляет переход к следующему изображению
  - Gmagick::normalizeimage — Повышает контрастность цветного изображения
  - Gmagick::oilpaintimage — Имитирует эффект картины маслом
  - Gmagick::previousimage — Осуществляет переход к предыдущему изображению в объекте
  - Gmagick::profileimage — Добавляет или удаляет профиль из изображения
  - Gmagick::quantizeimage — Анализирует цвета эталонного изображения
  - Gmagick::quantizeimages — Анализирует цвета в последовательности изображений
  - Gmagick::queryfontmetrics — Возвращает массив, представляющий метрики шрифта
  - Gmagick::queryfonts — Возвращает настроенные шрифты
  - Gmagick::queryformats — Возвращает форматы, поддерживаемые Gmagick
  - Gmagick::radialblurimage — Применяет радиальное размытие к изображению
  - Gmagick::raiseimage — Создаёт имитацию эффекта трёхмерной кнопки
  - Gmagick::read — Читает изображение из файла
  - Gmagick::readimage — Читает изображение из файла
  - Gmagick::readimageblob — Читает изображение из бинарной строки
  - Gmagick::readimagefile — Читает изображение или последовательность изображений из файлового дескриптора
  - Gmagick::reducenoiseimage — Сглаживает контуры изображения
  - Gmagick::removeimage — Удаляет изображение из списка
  - Gmagick::removeimageprofile — Удаляет именованный профайл изображения и возвращает его
  - Gmagick::resampleimage — Изменяет разрешение изображения до желаемого
  - Gmagick::resizeimage — Масштабирует изображение
  - Gmagick::rollimage — Смещает изображение
  - Gmagick::rotateimage — Поворачивает изображение
  - Gmagick::scaleimage — Масштабирует размер изображения
  - Gmagick::separateimagechannel — Отделяет канал от изображения
  - Gmagick::setCompressionQuality — Устанавливает для объекта качество сжатия по умолчанию
  - Gmagick::setfilename — Устанавливает имя файла перед чтением или записью изображения
  - Gmagick::setimagebackgroundcolor — Устанавливает цвет фона изображения
  - Gmagick::setimageblueprimary — Устанавливает цветность изображения голубой основной точкой
  - Gmagick::setimagebordercolor — Устанавливает цвет рамки изображения
  - Gmagick::setimagechanneldepth — Устанавливает глубину определённого канала изображения
  - Gmagick::setimagecolorspace — Устанавливает цветовое пространство изображения
  - Gmagick::setimagecompose — Устанавливает оператор составного изображения
  - Gmagick::setimagedelay — Устанавливает задержку изображения
  - Gmagick::setimagedepth — Устанавливает глубину изображения
  - Gmagick::setimagedispose — Устанавливает метод удаления изображения
  - Gmagick::setimagefilename — Устанавливает имя файла конкретного изображения в последовательности
  - Gmagick::setimageformat — Устанавливает формат определённого изображения
  - Gmagick::setimagegamma — Устанавливает гамму изображения
  - Gmagick::setimagegreenprimary — Устанавливает цветность изображения зелёной первичной точкой
  - Gmagick::setimageindex — Устанавливает итератор в положение в списке изображений, заданном параметром index
  - Gmagick::setimageinterlacescheme — Устанавливает схему чересстрочной развёртки изображения
  - Gmagick::setimageiterations — Устанавливает итерации изображения
  - Gmagick::setimageprofile — Добавляет именованный профиль в объект Gmagick
  - Gmagick::setimageredprimary — Устанавливает цветность изображения красной основной точкой
  - Gmagick::setimagerenderingintent — Устанавливает способ рендеринга изображения
  - Gmagick::setimageresolution — Устанавливает разрешение изображения
  - Gmagick::setimagescene — Устанавливает сцену изображения
  - Gmagick::setimagetype — Устанавливает тип изображения
  - Gmagick::setimageunits — Устанавливает единицы разрешения изображения
  - Gmagick::setimagewhitepoint — Устанавливает цветность изображения белой точкой
  - Gmagick::setsamplingfactors — Устанавливает факторы выборки изображения
  - Gmagick::setsize — Устанавливает размер объекта Gmagick
  - Gmagick::shearimage — Создаёт параллелограмм
  - Gmagick::solarizeimage — Применяет соляризационный эффект к изображению
  - Gmagick::spreadimage — Случайно смещает каждый пиксель в блоке
  - Gmagick::stripimage — Снимает изображение всех профилей и комментариев
  - Gmagick::swirlimage — Закручивает пиксели вокруг центра изображения
  - Gmagick::thumbnailimage — Изменяет размер изображения
  - Gmagick::trimimage — Удаляет края с изображения
  - Gmagick::write — Псевдоним Gmagick::writeimage
  - Gmagick::writeimage — Записывает изображение в указанный файл
- GmagickDraw — Класс GmagickDraw
  - GmagickDraw::annotate — Рисует текст на изображении
  - GmagickDraw::arc — Рисует дугу
  - GmagickDraw::bezier — Рисует кривую Безье
  - GmagickDraw::ellipse — Рисует эллипс на изображении
  - GmagickDraw::getfillcolor — Возвращает цвет заливки
  - GmagickDraw::getfillopacity — Возвращает значение прозрачности, используемое при рисовании
  - GmagickDraw::getfont — Возвращает шрифт
  - GmagickDraw::getfontsize — Возвращает размер шрифта
  - GmagickDraw::getfontstyle — Возвращает стиль шрифта
  - GmagickDraw::getfontweight — Возвращает толщину шрифта
  - GmagickDraw::getstrokecolor — Возвращает цвет, используемый для обводки контуров объекта
  - GmagickDraw::getstrokeopacity — Возвращает прозрачность обведённых контуров объекта
  - GmagickDraw::getstrokewidth — Возвращает ширину обводки, используемой для отрисовки контуров объекта
  - GmagickDraw::gettextdecoration — Возвращает оформление текста
  - GmagickDraw::gettextencoding — Возвращает кодовый набор, используемый для текстовых аннотаций
  - GmagickDraw::line — Рисует линию
  - GmagickDraw::point — Рисует точку
  - GmagickDraw::polygon — Рисует многоугольник
  - GmagickDraw::polyline — Рисует ломаную линию
  - GmagickDraw::rectangle — Рисует прямоугольник
  - GmagickDraw::rotate — Применяет указанный поворот к текущему координатному пространству
  - GmagickDraw::roundrectangle — Рисует прямоугольник с закруглёнными углами
  - GmagickDraw::scale — Регулирует коэффициент масштабирования
  - GmagickDraw::setfillcolor — Устанавливает цвет заливки, который будет использоваться для рисования объектов с заливкой
  - GmagickDraw::setfillopacity — Устанавливает непрозрачность заливки
  - GmagickDraw::setfont — Устанавливает указанный шрифт для использования при аннотации текста
  - GmagickDraw::setfontsize — Устанавливает размер шрифта для использования при аннотации текста
  - GmagickDraw::setfontstyle — Устанавливает стиль шрифта для использования при аннотации текста
  - GmagickDraw::setfontweight — Устанавливает толщину шрифта
  - GmagickDraw::setstrokecolor — Устанавливает цвет, используемый для обводки контуров объекта
  - GmagickDraw::setstrokeopacity — Определяет прозрачность обводки контуров объекта
  - GmagickDraw::setstrokewidth — Устанавливает ширину обводки, используемой для отрисовки контуров объекта
  - GmagickDraw::settextdecoration — Определяет оформление
  - GmagickDraw::settextencoding — Задаёт кодовый набор текста
- GmagickPixel — Класс GmagickPixel
  - GmagickPixel::__construct — Конструктора класса GmagickPixel
  - GmagickPixel::getcolor — Возвращает цвет
  - GmagickPixel::getcolorcount — Получить количество пикселей изображения, имеющих заданный цвет
  - GmagickPixel::getcolorvalue — Возвращает нормализованное значение для заданного цветового канала
  - GmagickPixel::setcolor — Задать цвет
  - GmagickPixel::setcolorvalue — Установить нормализованное значение цветового канала

# Обработка изображений (ImageMagick)

# Введение

Внимание

Модуль добавили как ЭКСПЕРИМЕНТАЛЬНЫЙ. Поведение модуля, названия функций и документацию к модулю изменяют в новых выпусках PHP без уведомления. Модулем пользуются на свой страх и риск.

Imagick — встроенный модуль PHP, который помогает создавать и изменять изображения через API-интерфейс библиотеки ImageMagick.

## О ImageMagick

ImageMagick — набор программного обеспечения, с которым создают, редактируют и компонуют растровые изображения. Набор ПО умеет читать, конвертировать и записывать изображения в более 100 форматах, включая DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG и TIFF.

ImageMagick Studio LLC — некоммерческая организация, которая специализируется на разработке бесплатного графического программного обеспечения.

# Установка и настройка

## Содержание

- Требования
- Установка
- Настройка во время выполнения

## Требования

## Требования к установке на платформах, которые отличаются от Windows

Для работы модуля требуется библиотека ImageMagick >= 6.2.4. Количество форматов файлов, которые будет поддерживать модуль Imagick, зависит от количества форматов, которые поддерживает установленная библиотека ImageMagick. Например, для работы с PDF-документами библиотеке Imagemagick требуется библиотека ghostscript.

## Установка

Модуль » PECL не поставляется вместе с PHP.

Информацию об установке этого PECL-модуля даёт глава руководства «Установка PECL-модулей». Дополнительная информация о новых версиях, скачивании, исходных файлах, о разработчике и журнале изменений доступна по адресу: » https://pecl.php.net/package/imagick.

> Замечание: Официальное название модуля — imagick.

Пользователям ОС Windows модуль в виде готового DLL-файла, который содержится в пакете загрузки, доступен на сайте репозитория » PECL. Пакеты загрузки уже содержат DLL-файл расширения — php_imagick.dll, который требуется поместить в каталог, на который указывает директива extension_dir. Пакеты также содержат DLL-файлы библиотеки ImageMagick, которые требуется поместить в переменной окружения PATH. Начиная с Imagick 3.6.0 пакеты также содержат в каталоге config файлы XML-конфигурации; чтобы вместо встроенных значений по умолчанию использовать файлы XML-конфигурации, файлы требуется поместить по пути `%USERPROFILE%/.config/ImageMagick` или по альтернативному пути, на который указывает переменная окружения MAGICK_CONFIGURE_PATH. Дополнительную информацию даёт » документация к файлам конфигурации библиотеки ImageMagick.

## Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Конфигурационные опции Imagick
Имя | По умолчанию | Место изменения | Список изменений
--- | --- | --- | ---
imagick.locale_fix | `false` | `INI_ALL` | Доступно начиная с Imagick 2.1.0
imagick.progress_monitor | `false` | `INI_SYSTEM` | Доступно начиная с Imagick 2.2.2
imagick.skip_version_check | `false` | `INI_SYSTEM` | Доступно с Imagick 3.3.0

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Краткое разъяснение конфигурационных директив.

`imagick.locale_fix` bool

  Исправление ошибки рисования с локалью, используя '`,`' в качестве разделителя.

`imagick.progress_monitor` bool

  Используется для включения мониторинга прогресса.

`imagick.skip_version_check` bool

  Когда Imagic загружен, он проверяет, что версия ImageMagick, с которой он был скомпилирован, совпадает с текущей используемой версией и, если не совпадает, выводит предупреждение.Это предупреждение можно подавить, установив данный параметр.

  Использовать Imagic с версией ImageMagick отличной от той, с которой он был скомпилирован, не рекомендуется. Он может работать, а может завершаться аварийно, либо вести себя непредсказуемо.

# Предопределённые константы

Следующие константы определяются модулем и доступны, только если модуль либо собрали в PHP, либо динамически загрузили при выполнении кода.

Константы семейства `COLOR_*`

Константы цветовых типов. Константы часто передают как аргументы методов класса ImagickPixel.

`imagick::COLOR_BLACK` (int)
  Чёрный
`imagick::COLOR_BLUE` (int)
  Синий
`imagick::COLOR_CYAN` (int)
  Сине-зелёный
`imagick::COLOR_GREEN` (int)
  Зелёный
`imagick::COLOR_RED` (int)
  Красный
`imagick::COLOR_YELLOW` (int)
  Жёлтый
`imagick::COLOR_MAGENTA` (int)
  Пурпурный
`imagick::COLOR_OPACITY` (int)
  Прозрачность цвета
`imagick::COLOR_ALPHA` (int)
  Альфа-канал для цвета
`imagick::COLOR_FUZZ` (int)
  'Fuzz factor' для цвета. Смотрите документацию по ImageMagick.

Константы семейства `DISPOSE_*`

Константы расположения

`imagick::DISPOSE_UNRECOGNIZED` (int)
  Не распознан
`imagick::DISPOSE_UNDEFINED` (int)
  Не задан
`imagick::DISPOSE_NONE` (int)
  Нет расположения
`imagick::DISPOSE_BACKGROUND` (int)
  Фон
`imagick::DISPOSE_PREVIOUS` (int)
  Предыдущее

Константы семейства `COMPOSITE_*`
`imagick::COMPOSITE_DEFAULT` (int)
  Оператор наложения по умолчанию
`imagick::COMPOSITE_UNDEFINED` (int)
  Неопределённый оператор наложения
`imagick::COMPOSITE_NO` (int)
  Не установленный оператор наложения
`imagick::COMPOSITE_ADD` (int)
  Результатом будет изображение + изображение
`imagick::COMPOSITE_ATOP` (int)
  Результатом будет изображение такой же формы, но наложение изображения затемнит изображение в местах перекрытия форм
`imagick::COMPOSITE_BLEND` (int)
  Смесь изображения
`imagick::COMPOSITE_BUMPMAP` (int)
  То же, что COMPOSITE_MULTIPLY, за исключением того, что источник сначала преобразуется в оттенки серого
`imagick::COMPOSITE_CLEAR` (int)
  Делает целевое изображение прозрачным
`imagick::COMPOSITE_COLORBURN` (int)
  Затемняет конечное изображение с учётом исходного изображения
`imagick::COMPOSITE_COLORDODGE` (int)
  Повышенная яркость конечного изображения с учётом исходного изображения
`imagick::COMPOSITE_COLORIZE` (int)
  Раскраска целевого изображения с помощью составного изображения
`imagick::COMPOSITE_COPYBLACK` (int)
  Копирует чёрный цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPYBLUE` (int)
  Копирует синий цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPY` (int)
  Копирует исходное изображение в целевое
`imagick::COMPOSITE_COPYCYAN` (int)
  Копирует сине-зелёный цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPYGREEN` (int)
  Копирует зелёный цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPYMAGENTA` (int)
  Копирует пурпурный цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPYOPACITY` (int)
  Копирует прозрачность из исходного изображения в целевое
`imagick::COMPOSITE_COPYRED` (int)
  Копирует красный цвет из исходного изображения в целевое
`imagick::COMPOSITE_COPYYELLOW` (int)
  Копирует жёлтый цвет из исходного изображения в целевое
`imagick::COMPOSITE_DARKEN` (int)
  Затемняет целевое изображение
`imagick::COMPOSITE_DSTATOP` (int)
  Область назначения, которая находится внутри исходного изображения накладывается поверх исходного и заменяет назначение
`imagick::COMPOSITE_DST` (int)
  Целевое изображение остаётся нетронутым
`imagick::COMPOSITE_DSTIN` (int)
  Область внутри исходного изображения заменяется заданным изображением
`imagick::COMPOSITE_DSTOUT` (int)
  Область снаружи исходного изображения заменяется заданным изображением
`imagick::COMPOSITE_DSTOVER` (int)
  Исходное изображение заменяется заданным
`imagick::COMPOSITE_DIFFERENCE` (int)
  Вычитание более тёмного цвета из двух составляющих
`imagick::COMPOSITE_DISPLACE` (int)
  Смещение пикселей заданного изображения по аналогии с исходным изображением
`imagick::COMPOSITE_DISSOLVE` (int)
  Растворение исходного изображения в заданном
`imagick::COMPOSITE_EXCLUSION` (int)
  Создание эффекта, похожего на imagick::COMPOSITE_DIFFERENCE, но с более низким контрастом
`imagick::COMPOSITE_HARDLIGHT` (int)
  Умножает или осветляет цвет, в зависимости от исходного значения цвета
`imagick::COMPOSITE_HUE` (int)
  Изменение оттенка заданного изображения по аналогии с исходным изображением
`imagick::COMPOSITE_IN` (int)
  Наложение исходного изображения на заданное
`imagick::COMPOSITE_LIGHTEN` (int)
  Освещает заданное изображение по аналогии с исходным изображением
`imagick::COMPOSITE_LUMINIZE` (int)
  Изменение яркости заданного изображения по аналогии с исходным изображением
`imagick::COMPOSITE_MINUS` (int)
  Вычитает исходное изображение из заданного
`imagick::COMPOSITE_MODULATE` (int)
  Модулирует целевые яркость, насыщенности и тон по аналогии с исходным изображением
`imagick::COMPOSITE_MULTIPLY` (int)
  Перемножает цель и источник
`imagick::COMPOSITE_OUT` (int)
  Наложение внешних частей источника на цель
`imagick::COMPOSITE_OVER` (int)
  Наложение источника на цель
`imagick::COMPOSITE_OVERLAY` (int)
  Преобразование "Overlay"
`imagick::COMPOSITE_PLUS` (int)
  Добавляет источник к цели
`imagick::COMPOSITE_REPLACE` (int)
  Заменяет цель источником
`imagick::COMPOSITE_SATURATE` (int)
  Меняет насыщенность цели в соответствии с источником
`imagick::COMPOSITE_SCREEN` (int)
  Источник и цель сначала дополняются, потом перемножаются, а потом источник заменяет цель.
`imagick::COMPOSITE_SOFTLIGHT` (int)
  Затемняет или осветляет цвета, в зависимости от источника
`imagick::COMPOSITE_SRCATOP` (int)
  Часть источника, лежащая внутри цели, накладывается на цель
`imagick::COMPOSITE_SRC` (int)
  Источник копируется в цель
`imagick::COMPOSITE_SRCIN` (int)
  Часть источника, лежащая внутри цели, заменяет цель
`imagick::COMPOSITE_SRCOUT` (int)
  Часть источника, лежащая вне цели, заменяет цель
`imagick::COMPOSITE_SRCOVER` (int)
  Источник заменяет цель
`imagick::COMPOSITE_SUBTRACT` (int)
  Вычитает цвета источника из цели
`imagick::COMPOSITE_THRESHOLD` (int)
  Источник накладывается на цель как определено порогом источника
`imagick::COMPOSITE_XOR` (int)
  Часть источника, лежащая вне цели комбинируется с частью цели, лежащей вне источника

Константы семейства `MONTAGEMODE_*`

`imagick::MONTAGEMODE_FRAME` (int)
`imagick::MONTAGEMODE_UNFRAME` (int)
`imagick::MONTAGEMODE_CONCATENATE` (int)

Константы семейства `STYLE_*`

`imagick::STYLE_NORMAL` (int)
`imagick::STYLE_ITALIC` (int)
`imagick::STYLE_OBLIQUE` (int)
`imagick::STYLE_ANY` (int)

Константы семейства `FILTER_*`

`imagick::FILTER_UNDEFINED` (int)
`imagick::FILTER_POINT` (int)
`imagick::FILTER_BOX` (int)
`imagick::FILTER_TRIANGLE` (int)
`imagick::FILTER_HERMITE` (int)
`imagick::FILTER_HANNING` (int)
`imagick::FILTER_HAMMING` (int)
`imagick::FILTER_BLACKMAN` (int)
`imagick::FILTER_GAUSSIAN` (int)
`imagick::FILTER_QUADRATIC` (int)
`imagick::FILTER_CUBIC` (int)
`imagick::FILTER_CATROM` (int)
`imagick::FILTER_MITCHELL` (int)
`imagick::FILTER_LANCZOS` (int)
`imagick::FILTER_BESSEL` (int)
`imagick::FILTER_SINC` (int)

Константы семейства `IMGTYPE_*`

`imagick::IMGTYPE_UNDEFINED` (int)
`imagick::IMGTYPE_BILEVEL` (int)
`imagick::IMGTYPE_GRAYSCALE` (int)
`imagick::IMGTYPE_GRAYSCALEMATTE` (int)
`imagick::IMGTYPE_PALETTE` (int)
`imagick::IMGTYPE_PALETTEMATTE` (int)
`imagick::IMGTYPE_TRUECOLOR` (int)
`imagick::IMGTYPE_TRUECOLORMATTE` (int)
`imagick::IMGTYPE_COLORSEPARATION` (int)
`imagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`imagick::IMGTYPE_OPTIMIZE` (int)

Константы семейства `RESOLUTION_*`

`imagick::RESOLUTION_UNDEFINED` (int)
`imagick::RESOLUTION_PIXELSPERINCH` (int)
`imagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Константы семейства `COMPRESSION_*`

`imagick::COMPRESSION_UNDEFINED` (int)
`imagick::COMPRESSION_NO` (int)
`imagick::COMPRESSION_BZIP` (int)
`imagick::COMPRESSION_FAX` (int)
`imagick::COMPRESSION_GROUP4` (int)
`imagick::COMPRESSION_JPEG` (int)
`imagick::COMPRESSION_JPEG2000` (int)
`imagick::COMPRESSION_LOSSLESSJPEG` (int)
`imagick::COMPRESSION_LZW` (int)
`imagick::COMPRESSION_RLE` (int)
`imagick::COMPRESSION_ZIP` (int)
`imagick::COMPRESSION_DXT1` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.0 или выше.
`imagick::COMPRESSION_DXT3` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.0 или выше.
`imagick::COMPRESSION_DXT5` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.0 или выше.

Константы семейства `PAINT_*`

`imagick::PAINT_POINT` (int)
`imagick::PAINT_REPLACE` (int)
`imagick::PAINT_FLOODFILL` (int)
`imagick::PAINT_FILLTOBORDER` (int)
`imagick::PAINT_RESET` (int)

Константы семейства `GRAVITY_*`

`imagick::GRAVITY_NORTHWEST` (int)
`imagick::GRAVITY_NORTH` (int)
`imagick::GRAVITY_NORTHEAST` (int)
`imagick::GRAVITY_WEST` (int)
`imagick::GRAVITY_CENTER` (int)
`imagick::GRAVITY_EAST` (int)
`imagick::GRAVITY_SOUTHWEST` (int)
`imagick::GRAVITY_SOUTH` (int)
`imagick::GRAVITY_SOUTHEAST` (int)

Константы семейства `STRETCH_*`

`imagick::STRETCH_NORMAL` (int)
`imagick::STRETCH_ULTRACONDENSED` (int)
`imagick::STRETCH_CONDENSED` (int)
`imagick::STRETCH_SEMICONDENSED` (int)
`imagick::STRETCH_SEMIEXPANDED` (int)
`imagick::STRETCH_EXPANDED` (int)
`imagick::STRETCH_EXTRAEXPANDED` (int)
`imagick::STRETCH_ULTRAEXPANDED` (int)
`imagick::STRETCH_ANY` (int)

Константы семейства `ALIGN_*`

`imagick::ALIGN_UNDEFINED` (int)
`imagick::ALIGN_LEFT` (int)
`imagick::ALIGN_CENTER` (int)
`imagick::ALIGN_RIGHT` (int)

Константы семейства `DECORATION_*`

`imagick::DECORATION_NO` (int)
`imagick::DECORATION_UNDERLINE` (int)
`imagick::DECORATION_OVERLINE` (int)
`imagick::DECORATION_LINETROUGH` (int)

Константы семейства `NOISE_*`

`imagick::NOISE_UNIFORM` (int)
`imagick::NOISE_GAUSSIAN` (int)
`imagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`imagick::NOISE_IMPULSE` (int)
`imagick::NOISE_LAPLACIAN` (int)
`imagick::NOISE_POISSON` (int)
`imagick::NOISE_RANDOM` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.

Константы семейства `CHANNEL_*`

`imagick::CHANNEL_UNDEFINED` (int)
`imagick::CHANNEL_RED` (int)
`imagick::CHANNEL_GRAY` (int)
`imagick::CHANNEL_CYAN` (int)
`imagick::CHANNEL_GREEN` (int)
`imagick::CHANNEL_MAGENTA` (int)
`imagick::CHANNEL_BLUE` (int)
`imagick::CHANNEL_YELLOW` (int)
`imagick::CHANNEL_ALPHA` (int)
`imagick::CHANNEL_OPACITY` (int)
`imagick::CHANNEL_MATTE` (int)
`imagick::CHANNEL_BLACK` (int)
`imagick::CHANNEL_INDEX` (int)
`imagick::CHANNEL_ALL` (int)
`imagick::CHANNEL_DEFAULT` (int)

Константы семейства `METRIC_*`

`imagick::METRIC_UNDEFINED` (int)
`imagick::METRIC_MEANABSOLUTEERROR` (int)
`imagick::METRIC_MEANSQUAREERROR` (int)
`imagick::METRIC_PEAKABSOLUTEERROR` (int)
`imagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`imagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Константы семейства `PIXEL_*`

`imagick::PIXEL_CHAR` (int)
`imagick::PIXEL_DOUBLE` (int)
`imagick::PIXEL_FLOAT` (int)
`imagick::PIXEL_INTEGER` (int)
  Доступно только для ImageMagick < 7.
`imagick::PIXEL_LONG` (int)
`imagick::PIXEL_QUANTUM` (int)
`imagick::PIXEL_SHORT` (int)

Константы семейства `EVALUATE_*`

`imagick::EVALUATE_UNDEFINED` (int)
`imagick::EVALUATE_ADD` (int)
`imagick::EVALUATE_AND` (int)
`imagick::EVALUATE_DIVIDE` (int)
`imagick::EVALUATE_LEFTSHIFT` (int)
`imagick::EVALUATE_MAX` (int)
`imagick::EVALUATE_MIN` (int)
`imagick::EVALUATE_MULTIPLY` (int)
`imagick::EVALUATE_OR` (int)
`imagick::EVALUATE_RIGHTSHIFT` (int)
`imagick::EVALUATE_SET` (int)
`imagick::EVALUATE_SUBTRACT` (int)
`imagick::EVALUATE_XOR` (int)
`imagick::EVALUATE_POW` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_LOG` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_THRESHOLD` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_IMPULSENOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_POISSONNOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_COSINE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_SINE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.
`imagick::EVALUATE_ADDMODULUS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.4 или выше.

Константы семейства `COLORSPACE_*`

`imagick::COLORSPACE_UNDEFINED` (int)
`imagick::COLORSPACE_RGB` (int)
`imagick::COLORSPACE_GRAY` (int)
`imagick::COLORSPACE_TRANSPARENT` (int)
`imagick::COLORSPACE_OHTA` (int)
`imagick::COLORSPACE_LAB` (int)
`imagick::COLORSPACE_XYZ` (int)
`imagick::COLORSPACE_YCBCR` (int)
`imagick::COLORSPACE_YCC` (int)
`imagick::COLORSPACE_YIQ` (int)
`imagick::COLORSPACE_YPBPR` (int)
`imagick::COLORSPACE_YUV` (int)
`imagick::COLORSPACE_CMYK` (int)
`imagick::COLORSPACE_SRGB` (int)
`imagick::COLORSPACE_HSB` (int)
`imagick::COLORSPACE_HSL` (int)
`imagick::COLORSPACE_HWB` (int)
`imagick::COLORSPACE_REC601LUMA` (int)
`imagick::COLORSPACE_REC709LUMA` (int)
`imagick::COLORSPACE_LOG` (int)
`imagick::COLORSPACE_CMY` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.2 или выше.

Константы семейства `VIRTUALPIXELMETHOD_*`

`imagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`imagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`imagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`imagick::VIRTUALPIXELMETHOD_EDGE` (int)
`imagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`imagick::VIRTUALPIXELMETHOD_TILE` (int)
`imagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)
`imagick::VIRTUALPIXELMETHOD_MASK` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.2 или выше.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.2 или выше.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.2 или выше.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.2 или выше.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.3 или выше.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.3 или выше.

Константы семейства `PREVIEW_*`

`imagick::PREVIEW_UNDEFINED` (int)
`imagick::PREVIEW_ROTATE` (int)
`imagick::PREVIEW_SHEAR` (int)
`imagick::PREVIEW_ROLL` (int)
`imagick::PREVIEW_HUE` (int)
`imagick::PREVIEW_SATURATION` (int)
`imagick::PREVIEW_BRIGHTNESS` (int)
`imagick::PREVIEW_GAMMA` (int)
`imagick::PREVIEW_SPIFF` (int)
`imagick::PREVIEW_DULL` (int)
`imagick::PREVIEW_GRAYSCALE` (int)
`imagick::PREVIEW_QUANTIZE` (int)
`imagick::PREVIEW_DESPECKLE` (int)
`imagick::PREVIEW_REDUCENOISE` (int)
`imagick::PREVIEW_ADDNOISE` (int)
`imagick::PREVIEW_SHARPEN` (int)
`imagick::PREVIEW_BLUR` (int)
`imagick::PREVIEW_THRESHOLD` (int)
`imagick::PREVIEW_EDGEDETECT` (int)
`imagick::PREVIEW_SPREAD` (int)
`imagick::PREVIEW_SOLARIZE` (int)
`imagick::PREVIEW_SHADE` (int)
`imagick::PREVIEW_RAISE` (int)
`imagick::PREVIEW_SEGMENT` (int)
`imagick::PREVIEW_SWIRL` (int)
`imagick::PREVIEW_IMPLODE` (int)
`imagick::PREVIEW_WAVE` (int)
`imagick::PREVIEW_OILPAINT` (int)
`imagick::PREVIEW_CHARCOALDRAWING` (int)
`imagick::PREVIEW_JPEG` (int)

Константы семейства `RENDERINGINTENT_*`

`imagick::RENDERINGINTENT_UNDEFINED` (int)
`imagick::RENDERINGINTENT_SATURATION` (int)
`imagick::RENDERINGINTENT_PERCEPTUAL` (int)
`imagick::RENDERINGINTENT_ABSOLUTE` (int)
`imagick::RENDERINGINTENT_RELATIVE` (int)

Константы семейства `INTERLACE_*`

`imagick::INTERLACE_UNDEFINED` (int)
`imagick::INTERLACE_NO` (int)
`imagick::INTERLACE_LINE` (int)
`imagick::INTERLACE_PLANE` (int)
`imagick::INTERLACE_PARTITION` (int)
`imagick::INTERLACE_GIF` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.4 или выше.
`imagick::INTERLACE_JPEG` (int)
`imagick::INTERLACE_PNG` (int)

Константы семейства `FILLRULE_*`

`imagick::FILLRULE_UNDEFINED` (int)
`imagick::FILLRULE_EVENODD` (int)
`imagick::FILLRULE_NONZERO` (int)

Константы семейства `PATHUNITS_*`

`imagick::PATHUNITS_UNDEFINED` (int)
`imagick::PATHUNITS_USERSPACE` (int)
`imagick::PATHUNITS_USERSPACEONUSE` (int)
`imagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Константы семейства `LINECAP_*`

`imagick::LINECAP_UNDEFINED` (int)
`imagick::LINECAP_BUTT` (int)
`imagick::LINECAP_ROUND` (int)
`imagick::LINECAP_SQUARE` (int)

Константы семейства `LINEJOIN_*`

`imagick::LINEJOIN_UNDEFINED` (int)
`imagick::LINEJOIN_MITER` (int)
`imagick::LINEJOIN_ROUND` (int)
`imagick::LINEJOIN_BEVEL` (int)

Константы семейства `RESOURCETYPE_*`

`imagick::RESOURCETYPE_UNDEFINED` (int)
`imagick::RESOURCETYPE_AREA` (int)
  Определяет максимальную ширину * высоту изображения, которое может находиться в пиксеном кеше.
`imagick::RESOURCETYPE_DISK` (int)
  Определяет максимальное количество дискового пространства в байтах, разрешённых для использования в пиксельном кеше.
`imagick::RESOURCETYPE_FILE` (int)
  Определяет максимальное количество открытых файлов пиксельного кеша..
`imagick::RESOURCETYPE_MAP` (int)
  Определяет максимальное количество памяти, в байтах, под пиксельный кеш.
`imagick::RESOURCETYPE_MEMORY` (int)
  Определяет максимальное количество памяти, в байтах, под пиксельный кеш из кучи.
`imagick::RESOURCETYPE_THREAD` (int)
  Определяет максимальное количество параллельных потоков. Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.7.8 или выше.

Константы семейства `LAYERMETHOD_*`

`imagick::LAYERMETHOD_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_COALESCE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_DISPOSE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.2.9 или выше.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::LAYERMETHOD_MERGE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.7 или выше.
`imagick::LAYERMETHOD_FLATTEN` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.7 или выше.
`imagick::LAYERMETHOD_MOSAIC` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.7 или выше.

Константы семейства `ORIENTATION_*`

`imagick::ORIENTATION_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_TOPLEFT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_TOPRIGHT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_LEFTTOP` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_RIGHTTOP` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.0 или выше.

Константы семейства `DISTORTION_*`

`imagick::DISTORTION_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_AFFINE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_ARC` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_BILINEAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_PERSPECTIVE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.6 или выше.
`imagick::DISTORTION_POLYNOMIAL` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_POLAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_DEPOLAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_BARREL` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_BARRELINVERSE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_SHEPARDS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DISTORTION_SENTINEL` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.

Константы семейства `ALPHACHANNEL_*`

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.8 или выше.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.8 или выше.
`imagick::ALPHACHANNEL_RESET` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.8 или выше.
`imagick::ALPHACHANNEL_SET` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.8 или выше.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_COPY` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_SHAPE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.5.3 или выше.
`imagick::ALPHACHANNEL_REMOVE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.7.8 или выше.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.9.0 или выше.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.9.0 или выше.
`imagick::ALPHACHANNEL_ON` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 7.0.0 или выше.
`imagick::ALPHACHANNEL_OFF` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 7.0.0 или выше.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 7.0.0 или выше.

Константы семейства `SPARSECOLORMETHOD_*`

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.

Константы семейства `FUNCTION_*`

`imagick::FUNCTION_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.9 или выше.
`imagick::FUNCTION_POLYNOMIAL` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.9 или выше.
`imagick::FUNCTION_SINUSOID` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.9 или выше.

Константы семейства `INTERPOLATE_*`

`imagick::INTERPOLATE_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_AVERAGE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_BICUBIC` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_BILINEAR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_FILTER` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_INTEGER` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_MESH` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.2 или выше.
`imagick::INTERPOLATE_SPLINE` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.3.4 или выше.

Константы семейства `DITHERMETHOD_*`

`imagick::DITHERMETHOD_UNDEFINED` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DITHERMETHOD_NO` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  Эта константа доступна, если Imagick был скомпилирован с версией ImageMagick 6.4.6 или выше.

# Примеры

## Содержание

- Базовое использование

## Базовое использование

Модуль Imagick чрезвычайно упрощает манипулирование изображениями в PHP через объектно-ориентированный интерфейс. Вот короткий пример того, как сделать миниатюру:

Пример #1 Создание миниатюры через объект Imagick

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');

    // Если в качестве параметра ширины или высоты передать 0,
    // соотношение сторон сохраняется
    $image->thumbnailImage(100, 0);

    echo $image;

    ?>

С библиотекой SPL и другими объектно-ориентированными функциями, которые поддерживает модуль Imagick, без усилий изменяют размер каждого файла в каталоге (полезно для пакетного изменения размера больших цифровых изображений для просмотра на веб-страницах). Пример изменяет размер, поскольку может потребоваться сохранить отдельные метаданные:

Пример #2 Создание миниатюр для всех JPG-файлов в директории

    <?php

    $images = new Imagick(glob('images/*.JPG'));

    foreach($images as $image) {
        // Передаём в метод thumbnailImage значение 0, чтобы сохранить соотношение сторон
        $image->thumbnailImage(1024,0);
    }

    $images->writeImages();

    ?>

Этот пример создаёт отражение изображения. Отражение создаётся зеркальным отображением и наложением градиента на нём. Затем оригинальное изображение и его отражение накладываются на холст.

Пример #3 Создание отражения

    <?php

    /* Чтение изображения */
    $im = new Imagick("test.png");

    /* Миниатюра изображения */
    $im->thumbnailImage(200, null);

    /* Создание рамки для изображения */
    $im->borderImage(new ImagickPixel("white"), 5, 5);

    /* Клонируем изображение и зеркально поворачиваем его */
    $reflection = $im->clone();
    $reflection->flipImage();

    /* Создаём градиент. Это будет наложением для отражения */
    $gradient = new Imagick();

    /* Градиент должен быть достаточно большой для изображения и его рамки */
    $gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

    /* Наложение градиента на отражение */
    $reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

    /* Добавляем прозрачность. Требуется ImageMagick 6.2.9 или выше */
    $reflection->setImageOpacity( 0.3 );

    /* Создаём пустой холст */
    $canvas = new Imagick();

    /* Холст должен быть достаточно большой, чтобы вместить оба изображения */
    $width = $im->getImageWidth() + 40;
    $height = ($im->getImageHeight() * 2) + 30;
    $canvas->newImage($width, $height, new ImagickPixel("black"));
    $canvas->setImageFormat("png");

    /* Наложение оригинального изображения и отражения на холст */
    $canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
    $canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

    /* Вывод изображения */
    header("Content-Type: image/png");
    echo $canvas;

    ?>

Вывод приведённого примера будет похож на:

Этот пример иллюстрирует, как использовать заливку во время рисования.

Пример #4 Заливка текста градиентом

    <?php

    /* Создание нового объекта imagick */
    $im = new Imagick();

    /* Создание нового изображения. Будет играть роль шаблона заливки */
    $im->newPseudoImage(50, 50, "gradient:red-black");

    /* Создаём объект imagickdraw */
    $draw = new ImagickDraw();

    /* Запускаем новый шаблон с названием "gradient" */
    $draw->pushPattern('gradient', 0, 0, 50, 50);

    /* Смешиваем градиент с шаблоном */
    $draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

    /* Закрываем шаблон */
    $draw->popPattern();

    /* Используем шаблон с названием «gradient» для заливки */
    $draw->setFillPatternURL('#gradient');

    /* Устанавливаем размер шрифта в 52 */
    $draw->setFontSize(52);

    /* Добавляем свой текст */
    $draw->annotation(20, 50, "Hello World!");

    /* Создаём новый объект холста и белое изображение */
    $canvas = new Imagick();
    $canvas->newImage(350, 70, "white");

    /* Рисуем ImagickDraw на холсте */
    $canvas->drawImage($draw);

    /* устанавливаем чёрную рамку шириной 1px вокруг изображения */
    $canvas->borderImage('black', 1, 1);

    /* Устанавливаем формат PNG */
    $canvas->setImageFormat('png');

    /* Вывод изображения */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

Вывод приведённого примера будет похож на:

Работа с анимированными GIF-изображениями

Пример #5 Чтение GIF-изображения и изменение размера каждого фрейма

    <?php

    /* Создание нового объекта imagick и чтение в GIF */
    $im = new Imagick("example.gif");

    /* Изменение размера всех фреймов */
    foreach ($im as $frame) {
        /* фреймы 50x50 */
        $frame->thumbnailImage(50, 50);

        /* Устанавливаем виртуальный холст для коррекции размера */
        $frame->setImagePage(50, 50, 0, 0);
    }

    /* Обратите внимание, вызываем метод writeImages, а не writeImage */
    $im->writeImages("example_small.gif", true);

    ?>

Работа с примитивом «эллипс» и пользовательскими шрифтами

Пример #6 Создание PHP-логотипа

    <?php

    /* Установка ширины и высоты в пропорции логотипа PHP */
    $width = 400;
    $height = 210;

    /* Создание объекта Imagick с поддержкой прозрачности */
    $img = new Imagick();
    $img->newImage($width, $height, new ImagickPixel('transparent'));

    /* Новый объект ImagickDraw  для отрисовки эллипса */
    $draw = new ImagickDraw();

    /* Установка пурпурного цвета заливки для эллипса */
    $draw->setFillColor('#777bb4');

    /* Задание размеров эллипса */
    $draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);

    /* Отрисовка эллипса */
    $img->drawImage($draw);

    /* Сброс цвета заливки с пурпурного на чёрный для текста (заметьте, что мы работаем с объектом ImagickDraw повторно) */
    $draw->setFillColor('black');

    /* Задание обводки границы белым цветом */
    $draw->setStrokeColor('white');

    /* Задание толщины обводки */
    $draw->setStrokeWidth(2);

    /* Задание кёрнинга (отрицательные значения означают, что буквы будут ближе друг к другу) */
    $draw->setTextKerning(-8);

    /* Задание шрифта и его размера, которые используются в логотипе PHP */
    $draw->setFont('Handel Gothic.ttf');
    $draw->setFontSize(150);

    /* Центрирование текста вертикально и горизонтально */
    $draw->setGravity(Imagick::GRAVITY_CENTER);

    /* Добавление текста «php» со смещением по Y на -10 на холст (внутри эллипса) */
    $img->annotateImage($draw, 0, -10, 0, 'php');
    $img->setImageFormat('png');

    /* Установка заголовка для PNG-файла и вывод изображения */
    header('Content-Type: image/png');
    echo $img;

    ?>

Вывод приведённого примера будет похож на:

# Класс Imagick

(PECL imagick 2, PECL imagick 3)

## Обзор класса

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function writeImagesFile(resource `$filehandle`, string `$format` = ?): bool
}

## Методы изображения и глобальные методы

Класс Imagick имеет возможность удерживать и обрабатывать несколько изображений одновременно. Это достигается за счёт внутреннего стека, в котором существует указатель, указывающий на текущее изображение. Некоторые функции работают со всеми изображениями в классе Imagick, но всё-таки, большинство работает только с текущим изображением во внутреннем стеке. По соглашению, имена методов могут содержать слово Image для обозначения того, что они влияют только на текущее изображение в стеке.

## Методы класса

Здесь приведён список наиболее используемых методов, объединённых в группы по назначению:

Методы класса по назначению
Эффекты изображения | Методы получения | Методы установки | Чтение/запись изображений | Другие
--- | --- | --- | --- | ---
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
| Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

# Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — Добавляет адаптивный фильтр размытия к изображению

### Описание

public function Imagick::adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Добавляет адаптивный фильтр размытия к изображению. Интенсивность адаптивного размытия значительно уменьшается к краям изображения, в то время как стандартное размытие равномерно распределяется по всему изображению. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`radius`

  Радиус Гаусса, в пикселях, не считая центрального пикселя. Если передан 0, то радиус будет выбран автоматически.

`sigma`

  Стандартное отклонение Гаусса, в пикселях.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::adaptiveBlurImage():

Адаптивное размытие изображения и отображение его в браузере.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->adaptiveBlurImage(5,3);
    echo $image;

    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- Imagick::blurImage() - Добавляет фильтр размытия к изображению
- Imagick::motionBlurImage() - Имитирует размытие в движении
- Imagick::radialBlurImage() - Радиальное размытие изображения

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — Адаптивное изменение размера изображения с данными триангуляции

### Описание

public function Imagick::adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Адаптивное изменение размера изображения с данными триангуляции. Позволяет избежать размытия через резкое изменение цвета. Чаще всего используется для уменьшения изображений чуть меньше "размера для web"; получается плохо, когда полноразмерное изображение адаптивно изменяется в миниатюру. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

> Замечание: Поведение параметра `bestfit` изменили в Imagick 3.0.0. До этой версии при размерах 400 x 300 точек изображение размером 200 x 150 точек оставалось нетронутым. В Imagick 3.0.0 и более поздних версиях изображение будет масштабироваться до размера 400 x 300 точек, поскольку такой размер «больше остальных соответствует» заданным размерам. Потребуется указать как ширину, так и высоту, если задали параметр `bestfit`.

### Список параметров

`columns`

  Количество столбцов в масштабе изображения.

`rows`

  Количество строк в масштабе изображения.

`bestfit`

  Будет ли подгоняться изображение внутри ограничительной рамки.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Добавлен необязательный параметр подгонки.
PECL imagick 2.1.0 | Метод теперь поддерживает пропорциональное масштабирование. Для этого нужно передать 0 одному из параметров.

### Примеры

Пример #1 Пример использования Imagick::adaptiveResizeImage()

Изменение размеров изображения обычно используемых в web. Этот метод лучше всего работает при небольшом изменении размера.

    <?php
    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');
    $image->adaptiveResizeImage(1024,768);

    echo $image;
    ?>

### Смотрите также

- Imagick::chopImage() - Удаляет область изображения и обрезает его
- Imagick::cropImage() - Извлекает область изображения
- Imagick::magnifyImage() - Пропорционально масштабирует изображение в два раза
- Imagick::minifyImage() - Масштабирует изображение пропорционально половине его размера
- Imagick::resizeImage() - Масштабирует изображение
- Imagick::scaleImage() - Масштабирует размер изображения
- Imagick::shaveImage() - Удаляет пиксели по краям изображения
- Imagick::thumbnailImage() - Изменяет размер изображения
- Imagick::trimImage() - Удаляет края с изображения

# Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — Адаптивное изменение резкости изображения

### Описание

public function Imagick::adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Адаптивное изменение резкости изображения с большей интенсивностью на краях изображения и с меньшей ближе к середине. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`radius`

  Радиус Гаусса, в пикселях, не считая центрального пикселя. Используйте 0 для авто-выбора.

`sigma`

  Стандартное отклонение Гаусса, в пикселях.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::adaptiveSharpenImage()

Адаптивное изменение резкости изображения с радиусом 2 и сигмой 1.

    <?php
    try {
        $image = new Imagick('image.png');
        $image->adaptiveSharpenImage(2,1);
    } catch(ImagickException $e) {
        echo 'Ошибка: ' , $e->getMessage();
        die();
    }
    header('Content-type: image/png');
    echo $image;
    ?>

### Смотрите также

- Imagick::sharpenImage() - Повышает резкость изображения

# Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — Выбор порога для каждого пикселя в зависимости от диапазона интенсивности

### Описание

public function Imagick::adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool

Выбор индивидуального ограничения для каждого пикселя в зависимости от диапазона значений интенсивности вокруг этого пикселя. Это даёт возможность установить порог изображения, в котором гистограмма глобальной интенсивности не содержит отличительных пиков.

### Список параметров

`width`

  Область соседей по ширине.

`height`

  Область соседей по высоте.

`offset`

  Среднее смещение

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::adaptiveThresholdImage()

    <?php
    function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
        $imagick = new \Imagick(realpath($imagePath));
        $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
        $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — Добавляет новое изображение к списку изображений объекта Imagick

### Описание

public function Imagick::addImage(Imagick `$source`): bool

Добавляет новое изображение к объекту Imagick из текущего положения исходного объекта. После этой операции перемещается позиция итератора в конец списка.

### Список параметров

`source`

  Исходный объект Imagick

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Накладывает случайный шум на изображение

### Описание

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Накладывает случайный шум на изображение.

### Список параметров

`noise_type`

  Тип шума. Обратитесь к списку констант шума.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::addNoiseImage()

    <?php
    function addNoiseImage($noiseType, $imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->addNoiseImage($noiseType, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — Преобразовывает изображения

### Описание

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Преобразовывает изображения как продиктовано аффинной матрицей.

### Список параметров

`matrix`

  Аффинная матрица.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования метода Imagick::affineTransformImage()

    <?php
    function affineTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $draw = new \ImagickDraw();

        $angle = deg2rad(40);

        $affineRotate = array(
            "sx" => cos($angle), "sy" => cos($angle),
            "rx" => sin($angle), "ry" => -sin($angle),
            "tx" => 0, "ty" => 0,
        );

        $draw->affine($affineRotate);

        $imagick->affineTransformImage($draw);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — Анимация одного или нескольких изображений

### Описание

public function Imagick::animateImages(string `$x_server`): bool

Метод производит анимацию изображения на локальном или удалённом X сервере. Метод не доступен в Windows. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`x_server`

  Адрес X сервера

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::displayImage() - Выводит изображение

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Добавляет текстовый комментарий на изображение

### Описание

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Добавляет текстовый комментарий на изображение.

### Список параметров

`draw_settings`

  Объект ImagickDraw с настройками наносимого текста

`x`

  Горизонтальное смещение в пикселях слева от текста

`y`

  Вертикальное смещение в пикселях к базовому тексту

`angle`

  Угол под которым выводится текст. Положительное значение: направление от верхнего левого угла до нижнего правого угла. Отрицательное значение: от нижнего левого угла до верхнего правого угла.

`text`

  Строка с текстом

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::annotateImage():

Добавление текста к пустому изображению

    <?php
    /* Создаём объекты */
    $image = new Imagick();
    $draw = new ImagickDraw();
    $pixel = new ImagickPixel( 'gray' );

    /* Новое изображение */
    $image->newImage(800, 75, $pixel);

    /* Чёрный текст */
    $draw->setFillColor('black');

    /* Настройки шрифта */
    $draw->setFont('Bookman-DemiItalic');
    $draw->setFontSize( 30 );

    /* Создаём текст */
    $image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

    /* Устанавливаем формат изображения */
    $image->setImageFormat('png');

    /* Выводим изображение с заголовками */
    header('Content-type: image/png');
    echo $image;

    ?>

### Смотрите также

- ImagickDraw::annotation() - Рисует текст на картинке
- ImagickDraw::setFont() - Устанавливает указанный шрифт для использования при аннотировании текстом

# Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — Объединяет набор изображений

### Описание

public function Imagick::appendImages(bool `$stack`): Imagick

Объединяет набор изображений в одно большое изображение.

### Список параметров

`stack`

  Стоит ли складывать изображения вертикально. По умолчанию (или если указано `false`) изображения складываются слева направо. Если `stack` установлен в `true`, то изображения складываются сверху вниз.

### Возвращаемые значения

В случае успешного выполнения возвращает экземпляр Imagick.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::appendImages()

    <?php

    /* Создаём новый объект imagick */
    $im = new Imagick();

    /* создаём красное, зелёное и синее изображения */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Соединяем все изображения в одно */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Выводим изображение */
    $combined->setImageFormat("png");
    header("Content-Type: image/png");
    echo $combined;
    ?>

Вывод приведённого примера будет похож на:

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Настраивает уровни определённого канала изображения

### Описание

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Настраивает уровни определённого канала изображения, масштабируя минимальное и максимальное значения до полного квантового диапазона.

### Список параметров

`channel`

  На каком канале следует выполнить автоматическое выравнивание.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — Усредняет набор изображений

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::averageImages(): Imagick

Усредняет набор изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

В случае успешного выполнения возвращает объект Imagick.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Перевести все пиксели ниже порогового значения в чёрный цвет

### Описание

public function Imagick::blackThresholdImage(mixed `$threshold`): bool

Работает так же, как Imagick::thresholdImage(), но изменяются только пиксели ниже порогового значения, в то время как остальные пиксели остаются неизменными.

### Список параметров

`threshold`

  Пороговое значение ниже которого все пиксели станут чёрными

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | В качестве параметра возможно передавать цвет строкой. В предыдущих версиях разрешалось передавать только ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::blackThresholdImage()

    <?php
    function blackThresholdImage($imagePath, $thresholdColor) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blackthresholdimage($thresholdColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Приглушает цвета изображения

### Описание

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Приглушает цвета изображения для имитации сцены в ночное время при лунном свете.

### Список параметров

`factor`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::blueShiftImage()

    <?php
    function blueShiftImage($imagePath, $blueShift) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blueShiftImage($blueShift);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — Добавляет фильтр размытия к изображению

### Описание

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Добавляет фильтр размытия к изображению. Необязательный третий параметр служит для размытия определённого канала.

### Список параметров

`radius`

  Радиус размытия

`sigma`

  Стандартное отклонение

`channel`

  Константа Channeltype. Если не указано, то будут размыты все каналы.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::blurImage():

Размытие изображения и отправка его в браузер.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->blurImage(5,3);
    echo $image;

    ?>

### Смотрите также

- Imagick::adaptiveBlurImage() - Добавляет адаптивный фильтр размытия к изображению
- Imagick::motionBlurImage() - Имитирует размытие в движении
- Imagick::radialBlurImage() - Радиальное размытие изображения

# Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — Окружает изображение рамкой

### Описание

public function Imagick::borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool

Окружает изображение рамкой с цветом, установленным в объекте ImagickPixel.

### Список параметров

`bordercolor`

  Объект ImagickPixel или строка, содержащая цвет рамки

`width`

  Ширина рамки

`height`

  Высота рамки

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | В качестве цвета разрешено передавать строку. Предыдущие версии допускали только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::borderImage()

    <?php
    function borderImage($imagePath, $color, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->borderImage($color, $width, $height);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Изменяет яркость и/или контраст изображения

### Описание

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Изменяет яркость и/или контраст изображения. Преобразовывает параметры яркости и контрастности в наклон и пересечение и вызывает полиномическую функцию для применения к изображению.

### Список параметров

`brightness`

`contrast`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования метода Imagick::brightnessContrastImage()

    <?php
    function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->brightnessContrastImage($brightness, $contrast, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — Рисование углём

### Описание

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Рисование углём.

### Список параметров

`radius`

  Радиус Гаусса, в пикселях, не включая центральный пиксель

`sigma`

  Стандартное отклонение Гаусса, в пикселях

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::charcoalImage()

    <?php
    function charcoalImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->charcoalImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — Удаляет область изображения и обрезает его

### Описание

public function Imagick::chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Удаляет выбранную область с реструктуризацией изображения.

### Список параметров

`width`

  Ширина обрезаемой области

`height`

  Высота обрезаемой области

`x`

  Начало обрезаемой области по оси X

`y`

  Начало обрезаемой области по оси Y

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Использование Imagick::chopImage():

Пример использования Imagick::chopImage

    <?php
    /* Создаём объекты */
    $image = new Imagick();
    $pixel = new ImagickPixel( 'gray' );

    /* Новое изображение */
    $image->newImage(400, 200, $pixel);

    /* Обрезка изображения */
    $image->chopImage(200, 200, 0, 0);

    /* Установка формата изображения */
    $image->setImageFormat('png');

    /* Вывод изображения с заголовками */
    header('Content-type: image/png');
    echo $image;

    ?>

### Смотрите также

- Imagick::cropImage() - Извлекает область изображения

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Ограничивает диапазон цветов от 0 до квантовой глубины

### Описание

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Ограничивает диапазон цветов от 0 до квантовой глубины.

### Список параметров

`channel`

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Очищает все ресурсы, связанные с объектом Imagick

### Описание

public function Imagick::clear(): bool

Очищает все ресурсы, связанные с объектом Imagick

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Обрезка вдоль ближайшего контура с профилем 8BIM

### Описание

public function Imagick::clipImage(): bool

Обрезка вдоль ближайшего контура с профилем 8BIM, если он предоставлен.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Клипы вдоль именованных путей из профиля 8BIM, если они есть

### Описание

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

Клипы вдоль именованных путей из профиля 8BIM, если они есть. Более поздние операции вступают в силу внутри пути. Идентификатор может быть числом, если ему предшествует # для работы с пронумерованным путём, например, укажите "#1", чтобы использовать первый путь.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`pathname`

`inside`

### Возвращаемые значения

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Отсечь вдоль обозначенного контура с профилем 8BIM

### Описание

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

Отсекает изображение вдоль обозначенного контура с профилем 8BIM, если он предоставлен. Последующие операции будут применяться к внутреннему контуру. Так же может быть числом, если ему предшествует символ #. Это необходимо для работы с пронумерованными контурами, например, "#1" для использования первого контура.

### Список параметров

`pathname`

  Обозначенный контур

`inside`

  Если установлено `true`, то последующие операции будут применяться к внутреннему контуру. Иначе, последующие операции будут применяться к внешнему контуру.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Создаёт точную копию объекта Imagick

### Описание

public function Imagick::clone(): Imagick

Создаёт точную копию объекта Imagick.

Внимание

Функция устарела (DEPRECATED) с imagick версии 3.1.0, взамен неё используйте ключевое слово clone.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Будет возвращена копия объекта Imagick.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 3.1.0 | Метод устарел в пользу ключевого слова clone.

### Примеры

Пример #1 Клонирование объекта Imagick в разных версиях

    <?php
    // Клонирование объекта Imagick в imagick 2.x и 3.0:
    $newImage = $image->clone();

    // Клонирование объекта Imagick с версии 3.1.0:
    $newImage = clone $image;
    ?>

# Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — Заменяет цвета в изображении

### Описание

public function Imagick::clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Заменяет цвета в изображении, используя таблицу соответствия. Необязательный второй параметр заменяет цвета в указанном канале. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`lookup_table`

  Объект Imagick, содержащий таблицу соответствия цветов.

`channel`

  Константа Channeltype. Если не указано, то по умолчанию замена происходит во всех каналах.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Использование Imagick::clutImage():

Замена цвета в изображении, используя таблицу соответствия.

    <?php
    $image = new Imagick('test.jpg');
    $clut = new Imagick();
    $clut->newImage(1, 1, new ImagickPixel('black'));
    $image->clutImage($clut);
    $image->writeImage('test_out.jpg');
    ?>

### Смотрите также

- Imagick::adaptiveBlurImage() - Добавляет адаптивный фильтр размытия к изображению
- Imagick::motionBlurImage() - Имитирует размытие в движении
- Imagick::radialBlurImage() - Радиальное размытие изображения

# Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — Компонует набор изображений

### Описание

public function Imagick::coalesceImages(): Imagick

Скомпонованный набор изображений с соблюдением любых смещений страниц и методов удаления. Анимационные последовательности GIF, MIFF и MNG обычно начинаются с фона изображения, и каждое последующее изображение изменяется по размеру и смещению. Возвращает новый объект Imagick, где каждое изображение в последовательности имеет тот же размер, что и первое и скомпоновано со следующим изображением в последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новый объект Imagick в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Изменяет значение цвета любого пикселя, соответствующего целевому

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Изменяет значение цвета любого пикселя, соответствующего целевому и являющегося ближайшим соседом.

### Список параметров

`fill`

  Объект ImagickPixel, содержащий цвет заливки.

`fuzz`

  Мера округления (fuzz). Например, присвойте fuzz значение, равное 10, и красный цвет с интенсивностью 100 и 102 соответственно теперь будет интерпретироваться как один и тот же цвет для целей заливки.

`bordercolor`

  Объект ImagickPixel, содержащий цвет границы.

`x`

  Начальная позиция заливки по X.

`y`

  Начальная позиция заливки по Y.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет использовать представляющую цвет строку в качестве первого и третьего параметров. Предыдущие версии позволяли использовать только объект ImagickPixel.

# Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — Смешивание цвета заливки с изображением

### Описание

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Смешивает цвет заливки с каждым пикселем изображения.

### Список параметров

`colorize`

  Объект ImagickPixel или строка, содержащая цвет

`opacity`

  Объект ImagickPixel или дробное число, содержащее значение прозрачности. 1.0 означает без прозрачности, 0.0 означает полную прозрачность.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Для первого параметра разрешено передавать цвет в виде строки и указывать значение прозрачности во втором параметре. Предыдущие версии допускали только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::colorizeImage()

    <?php
    function colorizeImage($imagePath, $color, $opacity) {
        $imagick = new \Imagick(realpath($imagePath));
        $opacity = $opacity / 255.0;
        $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
        $imagick->colorizeImage($color, $opacityColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Применяет преобразование цвета к изображению

### Описание

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

Метод применяет преобразование цвета к изображению. Метод изменяет насыщенность, вращение оттенка, яркость альфа-канала и другие эффекты. Хотя разработчики применяют матрицы преобразования переменного размера, обычно для изображения цветовой модели RGBA используется матрица 5x5, а для модели CMYKA матрица 6x6 или RGBA со смещениями. Матрица аналогична матрицам мультимедийной платформы Adobe Flash, но с двумя отличиями: смещения указывают в столбце 6 вместо столбца 5 для поддержки изображений цветовой модели CMYKA и норализуют смещения; смещение Flash делится на 255.

### Список параметров

`color_matrix`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример преобразования цвета методом Imagick::colorMatrixImage()

    <?php

    function colorMatrixImage($imagePath, $colorMatrix)
    {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        // Пример цветовой матрицы:
        //    $colorMatrix = [
        //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
        //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
        //    ];

        $background = new \Imagick();
        $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

        $background->setImageFormat('png');

        $imagick->setImageFormat('png');
        $imagick->colorMatrixImage($colorMatrix);

        $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

        header("Content-Type: image/png");
        echo $background->getImageBlob();
    }

    ?>

# Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — Объединяет одно или несколько изображений в одно изображение

### Описание

public function Imagick::combineImages(int `$channelType`): Imagick

Объединяет одно или несколько изображений в одно изображение. Значение оттенков серого пикселей каждого изображения в последовательности присваивается по порядку указанным каналам объединённого изображения. Типичный порядок: изображение 1 => красный, 2 => зелёный, 3 => синий и т.д.

### Список параметров

`channelType`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Добавляет комментарий к вашему изображению

### Описание

public function Imagick::commentImage(string `$comment`): bool

Добавляет комментарий к вашему изображению.

### Список параметров

`comment`

  Комментарий для добавления

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::commentImage():

Комментирование изображения и получение комментария:

    <?php

    /* Создать новый объект Imagick */
    $im = new imagick();

    /* Создать пустое изображение */
    $im->newImage(100, 100, new ImagickPixel("red"));

    /* Добавить комментарий к изображению */
    $im->commentImage("Привет, Мир!");

    /* Показать комментарий */
    echo $im->getImageProperty("comment");

    ?>

# Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — Возвращает разницу в одном или нескольких изображениях

### Описание

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Сравнивает одно или несколько изображений и возвращает разностное изображение.

### Список параметров

`image`

  Объект Imagick, содержащий изображение для сравнения.

`channelType`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

`metricType`

  Одна из констант типа METRIC.

### Возвращаемые значения

Массив, состоящий из `new_wand` и `distortion`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Возвращает максимальную ограничивающую область между изображениями

### Описание

public function Imagick::compareImageLayers(int `$method`): Imagick

Сравнивает каждое изображение со следующим в последовательности и возвращает максимальную ограничивающую область любых обнаруженных различий пикселей. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`method`

  Одна из констант метода слоя.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::compareImageLayers()

Сравнение слоёв изображения

    <?php
    /* создание новый объект imagick */
    $im = new Imagick("test.gif");

    /* оптимизирование слои изображения */
    $result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

    /* работа с $result */
    ?>

### Смотрите также

- Imagick::optimizeImageLayers() - Удаляет повторяющиеся части изображений для оптимизации
- Imagick::writeImages() - Записывает изображение или последовательность изображений
- Imagick::writeImage() - Записывает изображение по указанному имени файла

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Сравнивает изображение с восстановленным изображением

### Описание

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Возвращает массив, содержащий восстановленное изображение и разницу между изображениями.

### Список параметров

`compare`

  Изображение для сравнения.

`metric`

  Укажите допустимую константу типа метрики. Смотрите список констант метрики.

### Возвращаемые значения

Возвращает массив, содержащий восстановленное изображение и разницу между изображениями.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::compareImages():

Сравнение изображения и отображение восстановленного изображения

    <?php

    $image1 = new imagick("image1.png");
    $image2 = new imagick("image2.png");

    $result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
    $result[0]->setImageFormat("png");

    header("Content-Type: image/png");
    echo $result[0];

    ?>

# Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — Накладывает одно изображение на другое

### Описание

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Накладывает одно изображение на другое с указанным смещением. Любые дополнительные аргументы, необходимые для алгоритма наложения, следует передавать в setImageArtifact с 'compose:args' в качестве первого параметра и данных в качестве второго параметра.

### Список параметров

`composite_object`

  Объект Imagick, содержащий накладываемое изображение.

`compose`

  Оператор наложения. Смотрите Константы оператора наложения.

`x`

  Смещение столбца накладываемого изображения.

`y`

  Смещение строки накладываемого изображения.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::compositeImage():

Наложение двух изображений с помощью 'математического' метода наложения

    <?php

    // Эквивалентно запуску команды
    // convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

    $src1 = new \Imagick("./src1.png");
    $src2 = new \Imagick("./src2.png");

    $src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
    $src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
    $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
    $src1->writeImage("./output.png");

    ?>

### Смотрите также

- Imagick::setImageArtifact() - Устанавливает артефакт изображения

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — Конструктор объекта Imagick

### Описание

public function Imagick::__construct(mixed `$files` = ?)

Создаёт экземпляр Imagick для отдельного изображения или группы изображений.

### Список параметров

`files`

  Путь к изображению для загрузки или массив таких путей. Пути могут содержать групповые символы для имён файлов или могут являться URL.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Изменяет контраст изображения

### Описание

public function Imagick::contrastImage(bool `$sharpen`): bool

Увеличивает разницу в интенсивности между светлыми и тёмными элементами изображения. Установите увеличение резкости на значение, отличное от 0, чтобы увеличить контраст изображения, в противном случае контраст уменьшается.

### Список параметров

`sharpen`

  Значение резкости

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::contrastImage()

    <?php
    function contrastImage($imagePath, $contrastType) {
        $imagick = new \Imagick(realpath($imagePath));
        if ($contrastType != 2) {
            $imagick->contrastImage($contrastType);
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — Повышает контрастность цветного изображения

### Описание

public function Imagick::contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Повышает контрастность цветного изображения, регулируя цвет пикселей для охвата всего диапазона доступных цветов. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`black_point`

  Чёрная точка.

`white_point`

  Белая точка.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. `Imagick::CHANNEL_ALL`. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Применяет пользовательское ядро свёртки к изображению

### Описание

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Применяет пользовательское ядро свёртки к изображению.

### Список параметров

`kernel`

  Ядро свёртки.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::convolveImage()

    <?php
    function convolveImage($imagePath, $bias, $kernelMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($kernelMatrix);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Получает количество изображений

### Описание

public function Imagick::count(int `$mode` = 0): int

Возвращает количество изображений.

### Список параметров

`mode`

  Неиспользуемый аргумент. В настоящее время в PHP есть не очень чётко определённая функция, где вызов count() для счётного объекта может (или не может) требовать, чтобы метод принял параметр. Параметр должен соответствовать интерфейсу счётного, даже если он не используется.

### Возвращаемые значения

Возвращает количество изображений.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — Извлекает область изображения

### Описание

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Извлекает область изображения.

### Список параметров

`width`

  Ширина обрезания

`height`

  Высота обрезания

`x`

  Координата X верхнего левого угла области обрезания

`y`

  Координата Y верхнего левого угла области обрезания

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::cropImage()

    <?php
    function cropImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->cropImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — Создаёт обрезанную миниатюру

### Описание

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

Создаёт миниатюру фиксированного размера, сначала масштабируя изображение вверх или вниз и обрезая указанную область от центра.

### Список параметров

`width`

  Ширина миниатюры

`height`

  Высота миниатюры

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Возвращает ссылку на текущий объект Imagick

### Описание

public function Imagick::current(): Imagick

Возвращает ссылку на текущий объект imagick с указателем на изображение в правильной последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает себя в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Отображает цветовую карту изображения

### Описание

public function Imagick::cycleColormapImage(int `$displace`): bool

Смещает цветовую карту изображения на заданное количество позиций. Если вы циклически изменяете цветовую карту несколько раз, вы можете произвести психоделический эффект.

### Список параметров

`displace`

  Количество для смещения цветовой карты.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Расшифровывает изображение

### Описание

public function Imagick::decipherImage(string `$passphrase`): bool

Расшифровывает изображение, которое было зашифровано ранее. Изображение должно быть зашифровано с использованием Imagick::encipherImage(). Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.9 или старше.

### Список параметров

`passphrase`

  Пароль

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::encipherImage() - Шифрует изображение

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Возвращает определённые пиксельные различия между изображениями

### Описание

public function Imagick::deconstructImages(): Imagick

Сравнивает каждое изображение со следующим в последовательности и возвращает максимальную ограничивающую область любых обнаруженных различий пикселей.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новый объект Imagick в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Удаляет артефакт изображения

### Описание

public function Imagick::deleteImageArtifact(string `$artifact`): bool

Удаляет артефакт, связанный с изображением. Разница между свойствами изображения и артефактами изображения заключается в том, что свойства являются общедоступными, а артефакты - частными. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.5.7 или старше.

### Список параметров

`artifact`

  Название артефакта для удаления

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Смотрите также

- Imagick::setImageArtifact() - Устанавливает артефакт изображения
- Imagick::getImageArtifact() - Возвращает артефакт изображения

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Удаляет свойство изображения

### Описание

public function Imagick::deleteImageProperty(string `$name`): bool

Удаляет свойство изображения.

### Список параметров

`name`

  Имя свойства для удаления.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Удаляет перекос с изображения

### Описание

public function Imagick::deskewImage(float `$threshold`): bool

Метод можно использовать для удаления перекоса, например, отсканированных изображений, если бумага не была правильно размещена на поверхности сканирования. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.5 или старше.

### Список параметров

`threshold`

  Размер перекоса

### Возвращаемые значения

### Примеры

Пример #1 Пример использования Imagick::deskewImage()

    <?php
    function deskewImage($threshold) {
        $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
        $deskewImagick = clone $imagick;

        //Это единственное, что требуется для удаления перекоса.
        $deskewImagick->deskewImage($threshold);

        //Остальная часть этого примера - сделать результат очевидным,
        //потому что в противном случае результат не очевиден.
        $trim = 9;

        $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
        $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
        $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $newCanvas = new \Imagick();
        $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
        $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
        $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

        header("Content-Type: image/jpg");
        echo $newCanvas->getImageBlob();
    }

    ?>

# Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — Уменьшает спекл-шум на изображении

### Описание

public function Imagick::despeckleImage(): bool

Уменьшает спекл-шум на изображении, сохраняя края исходного изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::despeckleImage()

    <?php
    function despeckleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->despeckleImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Удаляет объект Imagick

### Описание

public function Imagick::destroy(): bool

Удаляет объект Imagick и освобождает все ресурсы связанные с ним. Метод устарел и следует использовать Imagick::clear.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Выводит изображение

### Описание

public function Imagick::displayImage(string `$servername`): bool

Данный метод выводит изображение на X сервер.

### Список параметров

`servername`

  Имя X сервера

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Выводит изображение или последовательность изображений

### Описание

public function Imagick::displayImages(string `$servername`): bool

Выводит изображение или последовательность изображений на X сервер.

### Список параметров

`servername`

  Имя X сервера

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Искажает изображение, используя различные методы искажения

### Описание

public function Imagick::distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool

Искажает изображение, используя различные методы искажения, сопоставляя поисковые запросы цвета исходного изображения с новым целевым изображением, обычно того же размера, что и исходное изображение, если для параметра "bestfit" установлено значение `true`.

Если параметр "bestfit" включён и это позволяет искажение, целевое изображение настраивается таким образом, чтобы исходное изображение полностью соответствовало конечному целевому изображению, которое будет иметь соответствующий размер и смещение. Также во многих случаях при сопоставлении будет учитываться виртуальное смещение исходного изображения.

Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`method`

  Метод искажения изображения. Смотрите константы искажения.

`arguments`

  Аргументы для выбранного метода искажения.

`bestfit`

  Попытка изменить размер места назначения, чтобы он соответствовал искажённому источнику.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::distortImage():

Искажение изображения и отображение в браузере.

    <?php
    /* Создание нового объекта */
    $im = new Imagick();

    /* Создание нового узора в виде шахматной доски */
    $im->newPseudoImage(100, 100, "pattern:checkerboard");

    /* Установка формата изображения на png */
    $im->setImageFormat('png');

    /* Заполнение новых видимых областей прозрачным цветом */
    $im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

    /* Активация матовости */
    $im->setImageMatte(true);

    /* Контрольные точки для искажения */
    $controlPoints = array( 10, 10,
                            10, 5,

                            10, $im->getImageHeight() - 20,
                            10, $im->getImageHeight() - 5,

                            $im->getImageWidth() - 10, 10,
                            $im->getImageWidth() - 10, 20,

                            $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                            $im->getImageWidth() - 10, $im->getImageHeight() - 30);

    /* Выполнение искажения */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

    /* Вывод изображения */
    header("Content-Type: image/png");
    echo $im;
    ?>

Вывод приведённого примера будет похож на:

### Смотрите также

- Imagick::blurImage() - Добавляет фильтр размытия к изображению
- Imagick::motionBlurImage() - Имитирует размытие в движении
- Imagick::radialBlurImage() - Радиальное размытие изображения

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — Выполняет рендеринг объекта ImagickDraw на текущем изображении

### Описание

public function Imagick::drawImage(ImagickDraw `$draw`): bool

Выполняет рендеринг объекта ImagickDraw на текущем изображении.

### Список параметров

`draw`

  Операции рисования, выполняемые к изображению.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Усиливает края в изображении

### Описание

public function Imagick::edgeImage(float `$radius`): bool

Увеличивает края в изображении с помощью фильтра свёртки данного радиуса. Используйте радиус 0, и он будет выбран автоматически.

### Список параметров

`radius`

  Радиус операции.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::edgeImage()

    <?php
    function edgeImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->edgeImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — Возвращает изображение в градациях серого с трёхмерным эффектом

### Описание

public function Imagick::embossImage(float `$radius`, float `$sigma`): bool

Возвращает изображение в градациях серого с трёхмерным эффектом. Мы сворачиваем изображение с помощью гауссовского оператора заданного радиуса и стандартного отклонения (сигма). Для получения разумных результатов радиус должен быть больше сигмы. Используйте радиус 0, и он будет выбран автоматически.

### Список параметров

`radius`

  Радиус эффекта

`sigma`

  Сигма эффекта

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::embossImage()

    <?php
    function embossImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->embossImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — Шифрует изображение

### Описание

public function Imagick::encipherImage(string `$passphrase`): bool

Преобразовывает обычные пиксели в зашифрованные пиксели. Изображение не читается, пока не будет расшифровано функцией Imagick::decipherImage() Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.9 или старше.

### Список параметров

`passphrase`

  Пароль

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::decipherImage() - Расшифровывает изображение

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Улучшает качество шумного изображения

### Описание

public function Imagick::enhanceImage(): bool

Применяет цифровой фильтр, который улучшает качество изображения с шумом.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::enhanceImage()

    <?php
    function enhanceImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->enhanceImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — Выравнивает гистограмму изображения

### Описание

public function Imagick::equalizeImage(): bool

Выравнивает гистограмму изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::equalizeImage()

    <?php
    function equalizeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->equalizeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — Применяет выражение к изображению

### Описание

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Применяет к изображению арифметическое, реляционное или логическое выражение. Используйте эти операторы для осветления или затемнения изображения, для увеличения или уменьшения контрастности изображения или для создания "негатива" изображения.

### Список параметров

`op`

  Оператор вычисления.

`constant`

  Значение оператора.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::evaluateImage()

Использование evaluateImage для уменьшения непрозрачности изображения.

    <?php
    // Создание нового объекта с изображением
    $im = new Imagick('example-alpha.png');

    // Уменьшение значнения альфа-канала на 50%
    $im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    // Вывод изображения
    header("Content-Type: image/png");
    echo $im;
    ?>

# Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — Экспортирует пиксели изображения

### Описание

public function Imagick::exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array

Экспортирует пиксели изображения в массив. Параметр map определяет порядок экспортируемых пикселей. Размер возвращаемого массива - `width * height * strlen(map)`. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.7 или старше.

### Список параметров

`x`

  Координата X экспортируемой области.

`y`

  Координата Y экспортируемой области.

`width`

  Ширина экспортируемой области.

`height`

  Высота экспортируемой области.

`map`

  Порядок экспортируемых пикселей. Например `"RGB"`. Допустимые символы для map: R, G, B, A, O, C, Y, M, K, I и P.

`STORAGE`

  Обратитесь к этому списку констант типа PIXEL.

### Возвращаемые значения

Возвращает массив, содержащий значения пикселей.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::exportImagePixels()

Экспорт пикселей изображения в массив

    <?php

    /* Создание нового объекта */
    $im = new Imagick();

    /* Создание нового изображения */
    $im->newPseudoImage(0, 0, "magick:rose");

    /* Экспорт пикселей изображения */
    $pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

    /* Вывод */
    var_dump($pixels);
    ?>

Результат выполнения приведённого примера:

    array(12) {
      [0]=>
      int(72)
      [1]=>
      int(64)
      [2]=>
      int(57)
      [3]=>
      int(69)
      [4]=>
      int(59)
      [5]=>
      int(43)
      [6]=>
      int(124)
      [7]=>
      int(120)
      [8]=>
      int(-96)
      [9]=>
      int(91)
      [10]=>
      int(84)
      [11]=>
      int(111)
    }

# Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — Устанавливает размер изображения

### Описание

public function Imagick::extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Удобный метод для установки размера изображения. Метод устанавливает размер изображения и позволяет задать координаты x,y там, где начинается новая область. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.1 или старше.

Предостережение

До ImageMagick 6.5.7-8 (1623) значение $x было положительным при сдвиге влево и отрицательным при сдвиге вправо, а значение $y было положительным при сдвиге изображения вверх и отрицательным при сдвиге изображения вниз. Где-то между ImageMagick 6.3.7 (1591) и ImageMagick 6.5.7-8 (1623) оси $x и $y были перевёрнуты так, что значение $x было отрицательным при сдвиге влево и положительным при сдвиге вправо, а значение $y было отрицательным при сдвиге изображения вверх и положительным при сдвиге изображения вниз. Где-то между ImageMagick 6.5.7-8 (1623) и ImageMagick 6.6.9-7 (1641) оси $x и $y были возвращены обратно к функциональности до ImageMagick 6.5.7-8 (1623).

### Список параметров

`width`

  Новая ширина.

`height`

  Новая высота.

`x`

  Позиция X для нового размера.

`y`

  Позиция Y для нового размера.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::resizeImage() - Масштабирует изображение
- Imagick::thumbnailImage() - Изменяет размер изображения
- Imagick::cropImage() - Извлекает область изображения

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Применяет пользовательское ядро свёртки к изображению

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Применяет пользовательское ядро свёртки к изображению.

### Список параметров

`ImagickKernel`

  Экземпляр ImagickKernel, представляющий либо одно ядро, либо связанную серию ядер.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::filter()

    <?php
    function filter($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $matrix = [
            [-1, 0, -1],
            [0,  5,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $strength = 0.5;
        $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(1 - $strength);

        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — Объединяет последовательность изображений

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::flattenImages(): Imagick

Объединяет последовательность изображений. Полезно для объединения слоёв Photoshop в одно изображение.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Создаёт вертикальное зеркало изображения

### Описание

public function Imagick::flipImage(): bool

Создаёт вертикальное зеркало изображения, отражая пиксели вокруг центральной оси X.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::flopimage() - Создаёт горизонтальное зеркальное отображение

# Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — Изменяет значение цвета любого пикселя, соответствующего целевому

### Описание

public function Imagick::floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Изменяет значение цвета любого пикселя, соответствующего целевому и являющегося ближайшим соседом. Данный метод - замена устаревшему Imagick::paintFloodFillImage(). Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.8 или старше.

### Список параметров

`fill`

  Объект ImagickPixel или строка, содержащая цвет заливки.

`fuzz`

  Мера округления (fuzz). Например, установите значение fuzz в 10 и красный цвет с интенсивностью 100 и 102 будет интерпретироваться как один и тот же цвет.

`target`

  Объект ImagickPixel или строка, содержащая целевой цвет для рисования.

`x`

  Начальная позиция заливки по X.

`y`

  Начальная позиция заливки по Y.

`invert`

  Если значение равно `true`, закрашивает любой пиксель, не соответствующий целевому цвету.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::floodfillPaintImage()

    <?php

    /* Создание нового объекта Imagick */
    $im = new Imagick();

    /* Создание красных, зеленых и синих изображения */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Сложение изображений в одно*/
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Сохранение промежуточного изображения для сравнения */
    $combined->writeImage("floodfillpaint_intermediate.png");

    /* Целевой пиксель для рисования */
    $x = 1;
    $y = 1;

    /* Получение цвета, которым рисуем */
    $target = $combined->getImagePixelColor($x, $y);

    /* Закрашивание пикселя в позиции 1,1 черным и всех соседних пикселей,
       соответствующих целевому цвету */
    $combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

    /* Сохранение результата */
    $combined->writeImage("floodfillpaint_result.png");
    ?>

Вывод приведённого примера будет похож на:

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Создаёт горизонтальное зеркальное отображение

### Описание

public function Imagick::flopImage(): bool

Создаёт горизонтальное зеркало изображения, отражая пиксели вокруг центральной оси Y.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::flipimage() - Создаёт вертикальное зеркало изображения

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Реализует дискретное преобразование Фурье

### Описание

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

Реализует дискретное преобразование Фурье (ДПФ) изображения в виде пары величина / фаза или пары, состоящей из реального / мнимого изображений.

### Список параметров

`magnitude`

  Если значение равно true, будет возвращена пара величина / фаза, иначе - пара, состоящая из реального / мнимого изображений.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::forwardFourierTransformImage()

    <?php
    //Служебная функция для forwardTransformImage
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        //Рисование круга на оси Y с центром в точках
        //x, y, который касается начала координат
        $draw->circle(250, 250, 220, 250);

        $imagick = new \Imagick();
        $imagick->newImage(512, 512, "black");
        $imagick->drawImage($draw);
        $imagick->gaussianBlurImage(20, 20);
        $imagick->autoLevelImage();

        return $imagick;
    }

    function forwardFourierTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

        $mask = createMask();
        $imagick->forwardFourierTransformImage(true);

        @$imagick->setimageindex(0);
        $magnitude = $imagick->getimage();

        @$imagick->setimageindex(1);
        $imagickPhase = $imagick->getimage();

        if (true) {
            $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
        }

        if (false) {
            $output = clone $imagickPhase;
            $output->setimageformat('png');
            header("Content-Type: image/png");
            echo $output->getImageBlob();
        }

        $magnitude->inverseFourierTransformImage($imagickPhase, true);

        $magnitude->setimageformat('png');
        header("Content-Type: image/png");
        echo $magnitude->getImageBlob();
    }

    ?>

# Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — Добавляет имитацию трёхмерной границы

### Описание

public function Imagick::frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool

Добавляет имитацию трёхмерной границы вокруг изображения. Ширина и высота определяют ширину границы вертикальной и горизонтальной сторон рамки. Внутренний и внешний скосы указывают ширину внутренней и внешней тени рамки.

### Список параметров

`matte_color`

  Объект ImagickPixel или строка, представляющая матовый цвет.

`width`

  Ширина границы.

`height`

  Высота границы.

`inner_bevel`

  Ширина внутреннего скоса.

`outer_bevel`

  Ширина внешнего скоса.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет использовать представляющую цвет строку в качестве первого. Предыдущие версии позволяли использовать только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::frameImage()

    <?php
    function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
        $imagick = new \Imagick(realpath($imagePath));

        $width = $width + $innerBevel + $outerBevel;
        $height = $height + $innerBevel + $outerBevel;

        $imagick->frameimage(
            $color,
            $width,
            $height,
            $innerBevel,
            $outerBevel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — Применяет функцию к изображению

### Описание

public function Imagick::functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Метод применяет арифметическое, реляционное или логическое выражение к псевдоизображению.

Смотрите также раздел » ImageMagick v6 Examples - Image Transformations — Function, Multi-Argument Evaluate

Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.9 или старше.

### Список параметров

`function`

  Параметр принимает константу из списка констант семейства FUNCTION_*.

`arguments`

  Массив аргументов, которые требуется передать в функцию.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример создания синусоидального градиента

    <?php

    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(3, -90);
    $imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    header("Content-Type: image/png");
    $imagick->setImageFormat("png");
    echo $imagick->getImageBlob();

    ?>

Вывод приведённого примера будет похож на:

Пример #2 Пример создания градиента из полинома (4x^2 - 4x + 1)

    <?php

    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(4, -4, 1);
    $imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

    header("Content-Type: image/png");
    $imagick->setimageformat("png");
    echo $imagick->getImageBlob();

    ?>

Вывод приведённого примера будет похож на:

Пример #3 Пример создания сложного градиента из полинома (4x^2 - 4x^2 + 1), модулированного синусоидальным градиентом

    <?php

    $imagick1 = new Imagick();
    $imagick1->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(9, -90);
    $imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    $imagick2 = new Imagick();
    $imagick2->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(0.5, 0);
    $imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
    $imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

    header("Content-Type: image/png");
    $imagick1->setImageFormat("png");
    echo $imagick1->getImageBlob();

    ?>

Вывод приведённого примера будет похож на:

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Оценивает выражение для каждого пикселя в изображении

### Описание

public function Imagick::fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick

Оценивает выражение для каждого пикселя в изображении. Посмотрите подробнее про » Оператор изображения Fx со специальными эффектами для получения дополнительной информации.

### Список параметров

`expression`

  Выражение

`channel`

  Укажите любую постоянную канала, которая подходит для вашего режима канала. Чтобы применить к более чем одному каналу, объедините константы типа канала, используя побитовые операторы. Просмотрите этот список констант канала.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::fxImage()

    <?php
    function fxImage() {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(200, 200, "xc:white");

        $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
        $fxImage = $imagick->fxImage($fx);

        header("Content-Type: image/png");
        $fxImage->setimageformat('png');
        echo $fxImage->getImageBlob();
    }

    ?>

# Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — Гамма-коррекция изображения

### Описание

public function Imagick::gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Гамма-коррекция изображения. Одно и то же изображение, просматриваемое на разных устройствах, будет различаться в восприятии, в способе представления интенсивности изображения на экране. Укажите индивидуальные уровни гаммы для красного, зелёного и синего каналов или отрегулируйте все три с помощью параметра гаммы. Обычно значения варьируются от 0.8 до 2.3.

### Список параметров

`gamma`

  Величина гамма-коррекции.

`channel`

  Укажите любую константу канала, которая соответствует вашему режиму канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к этому списку констант канала.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::gammaImage()

    <?php
    function gammaImage($imagePath, $gamma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gammaImage($gamma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — Размывает изображение

### Описание

public function Imagick::gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Размывает изображение. Сворачивает изображение с помощью гауссовского оператора заданного радиуса и стандартного отклонения (sigma). Для получения приемлемых результатов radius должен быть больше sigma. При использовании значения radius, равного 0, метод выберет подходящий радиус.

### Список параметров

`radius`

  Радиус в пикселях, не считая центрального пикселя.

`sigma`

  Стандартное отклонение в пикселях.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::gaussianBlurImage()

    <?php
    function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gaussianBlurImage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — Возвращает цветовую палитру

### Описание

public function Imagick::getColorspace(): int

Возвращает значение глобальной цветовой палитры. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.5.7 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, которое можно сравнить с константами COLORSPACE.

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — Возвращает тип сжатия объекта

### Описание

public function Imagick::getCompression(): int

Возвращает тип сжатия объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает константу сжатия

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Возвращает качество сжатия объекта

### Описание

public function Imagick::getCompressionQuality(): int

Возвращает качество сжатия объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает число, означающее качество сжатия

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Возвращает копирайт API ImageMagick в виде строки

### Описание

public static function Imagick::getCopyright(): string

Возвращает копирайт API ImageMagick в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку содержащую копирайт Imagemagick и Magickwand C API.

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — Имя файла результирующего изображения

### Описание

public function Imagick::getFilename(): string

Возвращает имя файла, связанное с результирующим изображением.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Возвращает название шрифта

### Описание

public function Imagick::getFont(): string

Возвращает значение шрифта объекта. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.7 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую название шрифта или `false`, если шрифт не установлен.

### Смотрите также

- Imagick::setFont() - Устанавливает шрифт
- ImagickDraw::setFont() - Устанавливает указанный шрифт для использования при аннотировании текстом
- ImagickDraw::getFont() - Возвращает шрифт

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Возвращает формат Imagick объекта

### Описание

public function Imagick::getFormat(): string

Возвращает формат Imagick объекта.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает формат изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Возвращает значение гравитации (притяжения)

### Описание

public function Imagick::getGravity(): int

Возвращает глобальное значение гравитации объекта Imagick. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.0 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает значение гравитации. Смотрите список констант гравитации.

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — Возвращает домашний URL библиотеки ImageMagick

### Описание

public static function Imagick::getHomeURL(): string

Возвращает домашний URL библиотеки ImageMagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ссылку домашней страницы imagemagick.

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Возвращает новый объект Imagick

### Описание

public function Imagick::getImage(): Imagick

Возвращает новый объект Imagick с текущей последовательностью изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает новый объект Imagick с текущей последовательностью изображений.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — Проверяет, есть ли у изображения альфа-канал

### Описание

public function Imagick::getImageAlphaChannel(): bool

Метод возвращает информацию о том, есть ли у изображения альфа-канал.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает `true`, если у изображения есть значение альфа-канала, и `false`, если нет, т. е. формат изображения — RGB, а не RGBA, или у изображения формат CMYK, а не CMYKA.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL-модуль imagick 3.6.0 | Теперь метод возвращает логическое значение (bool); раньше возвращалось целое число (int).

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Возвращает артефакт изображения

### Описание

public function Imagick::getImageArtifact(string `$artifact`): string

Возвращает артефакт, связанный с изображением. Разница между свойствами изображения и артефактами изображения заключается в том, что свойства являются общедоступными, а артефакты - закрытыми.

### Список параметров

`artifact`

  Имя артефакта.

### Возвращаемые значения

Возвращает значение артефакта в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Смотрите также

- Imagick::setImageArtifact() - Устанавливает артефакт изображения
- Imagick::deleteImageArtifact() - Удаляет артефакт изображения

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Возвращает именованный атрибут

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageAttribute(string `$key`): string

Возвращает именованный атрибут.

### Список параметров

`key`

  Ключ возвращаемого атрибута.

### Возвращаемые значения

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Возвращает цвет фона изображения

### Описание

public function Imagick::getImageBackgroundColor(): ImagickPixel

Возвращает цвет фона изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ImagickPixel с установленным цветом фона изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Возвращает последовательность изображений в виде BLOB

### Описание

public function Imagick::getImageBlob(): string

Реализует форматы изображений напрямую в память. Возвращает последовательность изображений в виде строки. Формат изображения определяет формат возвращаемого BLOB-объекта (GIF, JPEG, PNG и т.д.). Чтобы вернуть другой формат изображения, используйте Imagick::setImageFormat().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую изображение.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Возвращает основную точку синего цвета для изображения

### Описание

public function Imagick::getImageBluePrimary(): array

Возвращает основную точку синего цвета для изображения.

### Список параметров

`x`

  Цветность основной синей точки по оси x.

`y`

  Цветность основной синей точки по оси y.

### Возвращаемые значения

Массив, состоящий из координат точки "x" и "y".

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Возвращает цвет рамки изображения

### Описание

public function Imagick::getImageBorderColor(): ImagickPixel

Возвращает цвет рамки изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Возвращает глубину для определённого канала изображения

### Описание

public function Imagick::getImageChannelDepth(int `$channel`): int

Возвращает глубину для определённого канала изображения.

### Список параметров

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Сравнивает каналы изображения с восстановленным изображением

### Описание

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

Сравнивает один или несколько каналов изображения с восстановленным изображением и возвращает указанный показатель искажения.

### Список параметров

`reference`

  Объект Imagick для сравнения.

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

`metric`

  Одна из констант типа METRIC.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Возвращает искажения канала

### Описание

public function Imagick::getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float

Сравнивает один или несколько каналов изображения с восстановленным изображением и возвращает указанный показатель искажения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.4 или старше.

### Список параметров

`reference`

  Объект Imagick, содержащий изображение, с которым производится сравнение.

`metric`

  Обратитесь к этому списку констант типа METRIC.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Возвращает число с плавающей точкой (float), описывающее искажение канала.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Возвращает экстремумы для одного или нескольких каналов изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageChannelExtrema(int `$channel`): array

Получает экстремумы для одного или нескольких каналов изображения. Возвращаемое значение - ассоциативный массив с ключами "minima" и "maxima".

### Список параметров

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — Возвращает эксцесс и асимметрию определённого канала

### Описание

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Возвращает эксцесс и асимметрию определённого канала. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.9 или старше.

### Список параметров

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Возвращает массив с элементами `kurtosis` и `skewness`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Возвращает среднее и стандартное отклонение

### Описание

public function Imagick::getImageChannelMean(int `$channel`): array

Возвращает среднее и стандартное отклонение одного или нескольких каналов изображения.

### Список параметров

`channel`

  Укажите любую константу CHANNEL, которая подходит для вашего режима канала. Для применения более чем к одному каналу объедините константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Возвращает массив с элементами `"mean"` и `"standardDeviation"`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Возвращает диапазон каналов

### Описание

public function Imagick::getImageChannelRange(int `$channel`): array

Возвращает диапазон для одного или нескольких каналов изображения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.0 или старше.

### Список параметров

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Возвращает массив, содержащий минимальные и максимальные значения канала(ов).

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Возвращает статистику для каждого канала изображения

### Описание

public function Imagick::getImageChannelStatistics(): array

Возвращает статистику для каждого канала изображения. Статистика включает глубину канала, его минимумы и максимумы, среднее и стандартное отклонение.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Возвращает обтравочную маску изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageClipMask(): Imagick

Возвращает обтравочную маску изображения. Обтравочнуя маска - объект Imagick, содержащий обтравочную маску. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект Imagick, содержащий обтравочную маску.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Возвращает цвет указанного индекса палитры

### Описание

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Возвращает цвет указанного индекса палитры.

### Список параметров

`index`

  Смещение в палитре изображения.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Возвращает число уникальных цветов в изображении

### Описание

public function Imagick::getImageColors(): int

Возвращает число уникальных цветов в изображении в виде целого числа (int).

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — Возвращает цветовую палитру изображения

### Описание

public function Imagick::getImageColorspace(): int

Возвращает целое число, соответствующее значению одной из COLORSPACE констант.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — Возвращает составной оператор, связанный с изображением

### Описание

public function Imagick::getImageCompose(): int

Возвращает составной оператор, связанный с изображением.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Возвращает текущий тип компрессии изображения

### Описание

public function Imagick::getImageCompression(): int

Возвращает текущий тип компрессии изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает константу компрессии

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Возвращает текущее качество сжатия изображения

### Описание

public function Imagick::getImageCompressionQuality(): int

Получает текущее качество сжатия изображения

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, описывающее сжатие изображения.

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Возвращает задержку изображения

### Описание

public function Imagick::getImageDelay(): int

Возвращает задержку изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает задержку изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Возвращает глубину изображения

### Описание

public function Imagick::getImageDepth(): int

Возвращает глубину изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Глубина изображения.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Возвращает метод удаления изображения

### Описание

public function Imagick::getImageDispose(): int

Возвращает метод удаления изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает метод удаления изображения в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Сравнивает изображение с восстановленным изображением

### Описание

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Сравнивает изображение с восстановленным изображением и возвращает указанный показатель искажения.

### Список параметров

`reference`

  Объект Imagick для сравнения.

`metric`

  Одна из констант типа METRIC.

### Возвращаемые значения

Возвращает показатель искажения, использованный для изображения (или его наилучшее предположение).

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Возвращает экстремумы изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageExtrema(): array

Возвращает экстремумы изображения. Возвращает ассоциативный массив с ключами "min" и "max".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив с ключами "min" и "max".

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Возвращает имя файла конкретного изображения в последовательности

### Описание

public function Imagick::getImageFilename(): string

Возвращает имя файла конкретного изображения в последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку с именем файла изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Возвращает формат конкретного изображения в последовательности

### Описание

public function Imagick::getImageFormat(): string

Возвращает формат конкретного изображения в последовательности.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую формат изображения в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Возвращает гамму изображения

### Описание

public function Imagick::getImageGamma(): float

Возвращает гамму изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает гамму изображения в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Возвращает ширину и высоту в виде ассоциативного массива

### Описание

public function Imagick::getImageGeometry(): array

Возвращает ширину и высоту в виде ассоциативного массива.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает массив с шириной и высотой изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Возвращает значение гравитации (притяжения)

### Описание

public function Imagick::getImageGravity(): int

Возвращает значение гравитации изображения. В отличие от Imagick::getGravity(), этот метод возвращает гравитацию, установленную для текущего изображения в последовательности. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.4 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает значение гравитации. Смотрите список констант гравитации.

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — Возвращает первичную точку цветности зелёного

### Описание

public function Imagick::getImageGreenPrimary(): array

Возвращает первичную точку цветности зелёного. Возвращает массив с ключами "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

В случае успешного выполнения возвращает массив с ключами "x" и "y", случае возникновения ошибки выбрасывает исключение ImagickException.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Возвращает высоту изображения

### Описание

public function Imagick::getImageHeight(): int

Возвращает высоту изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает высоту изображения в пикселях.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Возвращает гистограмму изображения

### Описание

public function Imagick::getImageHistogram(): array

Возвращает гистограмму изображения в виде массива объектов ImagickPixel.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает гистограмму изображения в виде массива объектов ImagickPixel.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Генерация Imagick::getImageHistogram()

    <?php
    function getColorStatistics($histogramElements, $colorChannel) {
        $colorStatistics = [];

        foreach ($histogramElements as $histogramElement) {
            $color = $histogramElement->getColorValue($colorChannel);
            $color = intval($color * 255);
            $count = $histogramElement->getColorCount();

            if (array_key_exists($color, $colorStatistics)) {
                $colorStatistics[$color] += $count;
            }
            else {
                $colorStatistics[$color] = $count;
            }
        }

        ksort($colorStatistics);

        return $colorStatistics;
    }

    function getImageHistogram($imagePath) {

        $backgroundColor = 'black';

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(0); // делает линии маскимально тонкими

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        $histogramWidth = 256;
        $histogramHeight = 100; // высота для каждого сегмента RGB

        $imagick = new \Imagick(realpath($imagePath));
        //Измените размер изображения, чтобы он был маленьким, иначе PHP может не хватить памяти
        //Это может привести к плохим результатам для изображений, которые являются патологически "пиксельными"
        $imagick->adaptiveResizeImage(200, 200, true);
        $histogramElements = $imagick->getImageHistogram();

        $histogram = new \Imagick();
        $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
        $histogram->setImageFormat('png');

        $getMax = function ($carry, $item)  {
            if ($item > $carry) {
                return $item;
            }
            return $carry;
        };

        $colorValues = [
            'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
            'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
            'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
        ];

        $max = array_reduce($colorValues['red'] , $getMax, 0);
        $max = array_reduce($colorValues['lime'] , $getMax, $max);
        $max = array_reduce($colorValues['blue'] , $getMax, $max);

        $scale =  $histogramHeight / $max;

        $count = 0;
        foreach ($colorValues as $color => $values) {
            $draw->setstrokecolor($color);

            $offset = ($count + 1) * $histogramHeight;

            foreach ($values as $index => $value) {
                $draw->line($index, $offset, $index, $offset - ($value * $scale));
            }
            $count++;
        }

        $histogram->drawImage($draw);

        header( "Content-Type: image/png" );
        echo $histogram;
    }

    ?>

# Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — Возвращает индекс текущего активного изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageIndex(): int

Возвращает индекс текущего активного изображения в объекте Imagick. Этот метод объявлен устаревшим. Используйте Imagick::getIteratorIndex().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, содержащее индекс изображения в стеке.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Получает схему чересстрочного изображения

### Описание

public function Imagick::getImageInterlaceScheme(): int

Получает схему чересстрочного изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

В случае успешного выполнения возвращает схему чередования как целое число. Вызывает ImagickException, если возникла ошибка.

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Возвращает метод интерполяции

### Описание

public function Imagick::getImageInterpolateMethod(): int

Возвращает метод интерполяции для указанного изображения. Метод является одной из констант `Imagick::INTERPOLATE_*`.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает метод интерполяции в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Возвращает итерации изображения

### Описание

public function Imagick::getImageIterations(): int

Возвращает итерации изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает итерации изображения в виде целого числа.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Возвращает длину изображения в байтах

### Описание

public function Imagick::getImageLength(): int

Возвращает длину изображения в байтах.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, содержащее текущий размер изображения.

### Примеры

Пример #1 Пример использования Imagick::getImageLength():

Получение длины изображения в байтах

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' байт';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — Возвращает, если изображение содержит матовый канал

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageMatte(): bool

Возвращает `true`, если изображение содержит матовый канал, в противном случае возвращает false. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Возвращает матовый цвет изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageMatteColor(): ImagickPixel

Возвращает матовый цвет изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает объект ImagickPixel в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Возвращает MIME-тип изображения

### Описание

public function Imagick::getImageMimeType(): string

Возвращает MIME-тип изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Возвращает ориентацию изображения

### Описание

public function Imagick::getImageOrientation(): int

Возвращает ориентацию изображения. Возвращаемое значение - одна из констант ORIENTATION.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число (int) в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Возвращает геометрию страницы

### Описание

public function Imagick::getImagePage(): array

Возвращает геометрию страницы, связанную с изображением, в массиве с ключами "width", "height", "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает геометрию страницы, связанную с изображением, в массиве с ключами "width", "height", "x" и "y".

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Возвращает цвет указанного пикселя

### Описание

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Возвращает цвет указанного пикселя.

### Список параметров

`x`

  Координата x пикселя.

`y`

  Координата y пикселя.

### Возвращаемые значения

Возвращает экземпляр ImagickPixel для цвета в заданных координатах.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Возвращает именованный профиль изображения

### Описание

public function Imagick::getImageProfile(string `$name`): string

Возвращает именованный профиль изображения.

### Список параметров

`name`

  Имя возвращаемого профиля.

### Возвращаемые значения

Возвращает строку, содержащую профиль изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Возвращает профили изображений

### Описание

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

Возвращает все связанные профили, соответствующие шаблону. Если в качестве второго параметра передаётся `false`, возвращаются только имена профилей. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`pattern`

  Шаблон для имён профилей.

`include_values`

  Определяет, следует ли возвращать только имена профилей. Если передано значение `false` то будут возвращены только имена профилей.

### Возвращаемые значения

Возвращает массив, содержащий профили изображений или имена профилей.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Возвращает свойства изображения

### Описание

public function Imagick::getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array

Возвращает все свойства, удовлетворяющие шаблону. Если в качестве второго параметра передано `false`, то возвращаются только названия свойств. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`pattern`

  Шаблон для поиска свойств.

`include_values`

  Вернуть только имена свойств. Если передано `false`, то возвращаются только имена свойств.

### Возвращаемые значения

Возвращает массив, содержащий свойства изображения или их имена.

### Примеры

Пример #1 Использование Imagick::getImageProperties():

Пример извлечения EXIF-информации.

    <?php

    /* Создание объекта */
    $im = new imagick("/path/to/example.jpg");

    /* Получение EXIF-информации */
    $exifArray = $im->getImageProperties("exif:*");

    /* Цикл по EXIF-свойствам */
    foreach ($exifArray as $name => $property)
    {
        echo "{$name} => {$property}<br />\n";
    }

    ?>

# Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — Возвращает именованное свойство изображения

### Описание

public function Imagick::getImageProperty(string `$name`): string

Возвращает именованное свойство изображения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.2 или старше.

### Список параметров

`name`

  Имя свойства (например, Exif:DateTime).

### Возвращаемые значения

Возвращает строку, содержащую свойство изображения, или false, если свойство с заданным именем не существует.

### Примеры

Пример #1 Пример использования Imagick::getImageProperty():

Задание и получение свойства изображения

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Смотрите также

- Imagick::setImageProperty() - Устанавливает свойство изображения

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Возвращает красную первичную точку цветности

### Описание

public function Imagick::getImageRedPrimary(): array

Возвращает красную первичную точку цветности в виде массива с ключами "x" and "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает красную первичную точку цветности в виде массива с ключами "x" and "y". Вызывает ImagickException, если возникла ошибка.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Извлекает область изображения

### Описание

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

Извлекает область изображения и возвращает её в виде нового объекта Imagick.

### Список параметров

`width`

  Ширина извлечённой области.

`height`

  Высота извлечённой области.

`x`

  Координата X левого верхнего угла извлечённой области.

`y`

  Координата Y левого верхнего угла извлечённой области.

### Возвращаемые значения

Извлекает область изображения и возвращает её в виде новой палочки.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Возвращает схему цветопередачи изображения

### Описание

public function Imagick::getImageRenderingIntent(): int

Возвращает схему цветопередачи изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает схему цветопередачи изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — Возвращает разрешение изображения по X и Y

### Описание

public function Imagick::getImageResolution(): array

Возвращает разрешение изображения X и Y.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает разрешение в виде массива.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Возвращает все последовательности изображений в виде большого двоичного объекта

### Описание

public function Imagick::getImagesBlob(): string

Реализует форматы изображений напрямую в память. Метод возвращает все последовательности изображений в виде строки. Формат изображения определяет формат возвращаемого большого двоичного объекта (GIF, JPEG, PNG и т.д.). Чтобы вернуть другой формат изображения, используйте Imagick::setImageFormat().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую изображения. В случае возникновения ошибки выбрасывает исключение ImagickException.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Возвращает сцену изображения

### Описание

public function Imagick::getImageScene(): int

Возвращает сцену изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает сцену изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Генерирует хеш SHA-256

### Описание

public function Imagick::getImageSignature(): string

Генерирует хеш SHA-256 для потока пикселей изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает строку, содержащую SHA-256 хеш файла.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Возвращает размер изображения в байтах

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::getImageSize(): int

Возвращает размер изображения в байтах. Этот метод устарел и следует использовать Imagick::getImageLength().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, содержащее текущий размер изображения.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Получает количество кадров в секунду для изображения

### Описание

public function Imagick::getImageTicksPerSecond(): int

Получает количество кадров в секунду для изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество кадров в секунду для изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Возвращает общую плотность чернил изображения

### Описание

public function Imagick::getImageTotalInkDensity(): float

Возвращает общую плотность чернил изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает общую плотность чернил изображения. Вызывает ImagickException, если возникла ошибка.

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Возвращает возможный тип изображения

### Описание

public function Imagick::getImageType(): int

Получение возможного типа изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает возможный тип изображения.

- `imagick::IMGTYPE_UNDEFINED`
- `imagick::IMGTYPE_BILEVEL`
- `imagick::IMGTYPE_GRAYSCALE`
- `imagick::IMGTYPE_GRAYSCALEMATTE`
- `imagick::IMGTYPE_PALETTE`
- `imagick::IMGTYPE_PALETTEMATTE`
- `imagick::IMGTYPE_TRUECOLOR`
- `imagick::IMGTYPE_TRUECOLORMATTE`
- `imagick::IMGTYPE_COLORSEPARATION`
- `imagick::IMGTYPE_COLORSEPARATIONMATTE`
- `imagick::IMGTYPE_OPTIMIZE`

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — Возвращает единицы измерения разрешения изображения

### Описание

public function Imagick::getImageUnits(): int

Возвращает единицы измерения разрешения изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает единицы измерения разрешения изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Возвращает метод виртуального пикселя

### Описание

public function Imagick::getImageVirtualPixelMethod(): int

Возвращает метод виртуального пикселя для указанного изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает метод виртуального пикселя в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Возвращает белую точку цветности

### Описание

public function Imagick::getImageWhitePoint(): array

Возвращает белую точку цветности в виде ассоциативного массива с ключами "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает белую точку цветности в виде ассоциативного массива с ключами "x" и "y".

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Возвращает ширину изображения

### Описание

public function Imagick::getImageWidth(): int

Возвращает ширину изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ширину изображения в пикселях.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Получает схему сжатия изображения

### Описание

public function Imagick::getInterlaceScheme(): int

Получает схему сжатия изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Получает схему сжатия изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Возвращает индекс текущего активного изображения

### Описание

public function Imagick::getIteratorIndex(): int

Возвращает индекс текущего активного изображения в объекте Imagick. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает целое число, содержащее индекс изображения в стеке.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::getIteratorIndex():

Создание изображения, установка и получение индекса итератора

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Смотрите также

- Imagick::setIteratorIndex() - Устанавливает позицию итератора
- Imagick::getImageIndex() - Возвращает индекс текущего активного изображения
- Imagick::setImageIndex() - Устанавливает позицию итератора

# Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — Возвращает количество изображений в объекте

### Описание

public function Imagick::getNumberImages(): int

Возвращает количество изображений, связанных с объектом Imagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает количество изображений, связанных с объектом Imagick.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Возвращает значение, связанное с указанным ключом

### Описание

public function Imagick::getOption(string `$key`): string

Возвращает значение, связанное с объектом для указанного ключа.

### Список параметров

`key`

  Название опции.

### Возвращаемые значения

Возвращает значение, связанное с палочкой и указанным ключом.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Возвращает имя пакета ImageMagick

### Описание

public static function Imagick::getPackageName(): string

Возвращает имя пакета ImageMagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает имя пакета ImageMagick в виде строки.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Возвращает геометрию страницы

### Описание

public function Imagick::getPage(): array

Возвращает геометрию страницы, связанную с объектом Imagick, в виде ассоциативного массива с ключами "width", "height", "x" и "y".

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает геометрию страницы, связанную с объектом Imagick, в виде ассоциативного массива с ключами "width", "height", "x" и "y", в случае ошибки выбрасывает исключение ImagickException.

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — Возвращает MagickPixelIterator

### Описание

public function Imagick::getPixelIterator(): ImagickPixelIterator

Возвращает MagickPixelIterator.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ImagickPixelIterator в случае успешного выполнения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::getPixelIterator()

    <?php
    function getPixelIterator($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        foreach ($imageIterator as $row => $pixels) { /* Проход по строкам пикселей в цикле */
            foreach ($pixels as $column => $pixel) { /* Проход по пикселям в строке (по столбцам) */
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    $pixel->setColor("rgba(0, 0, 0, 0)"); /* Закрашивание каждого второго пикселя в черный цвет */
                }
            }
            $imageIterator->syncIterator(); /* Синхронизация итератора, это важно делать на каждой итерации. */
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — Возвращает объект ImagickPixelIterator для секции изображения

### Описание

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Возвращает объект ImagickPixelIterator для секции изображения.

### Список параметров

`x`

  Координата области X.

`y`

  Координата области Y.

`columns`

  Ширина области.

`rows`

  Высота области.

### Возвращаемые значения

Возвращает объект ImagickPixelIterator для секции изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования функции Imagick::getPixelRegionIterator()

Пробегает по пикселям вверху слева изображения и заменяет их на чёрные.

    <?php
    $im = new Imagick(realpath("./testImage.png"));
    $areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

    foreach ($areaIterator as $rowIterator) {
        foreach ($rowIterator as $pixel) {
            // Красит каждый пиксель черным
            $pixel->setColor("rgba(0, 0, 0, 0)");
        }
        $areaIterator->syncIterator();
    }
    $im->writeImage("./output.png");
    ?>

# Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — Возвращает размер точки

### Описание

public function Imagick::getPointSize(): float

Возвращает значение размера точки объекта. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.7 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает float, содержащее размер точки.

### Смотрите также

- Imagick::setPointSize() - Устанавливает размер точки

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Возвращает квантовый диапазон ImageMagick

### Описание

public static function Imagick::getQuantum(): int

Возвращает квантовый диапазон ImageMagick. Если HDRI был включён, то тип - float, если нет - int.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Возвращает величину глубины

### Описание

public static function Imagick::getQuantumDepth(): array

Возвращает величину глубины объекта Imagick в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает величину глубины объекта Imagick в виде строки.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Возвращает величину размера спектра Imagick

### Описание

public static function Imagick::getQuantumRange(): array

Возвращает величину размера спектра для объекта Imagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив, содержащий размер спектра как целое число int (`"quantumRangeLong"`) и как строку string (`"quantumRangeString"`).

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Получает запись StringRegistry

### Описание

public static function Imagick::getRegistry(string `$key`): string

Получает запись StringRegistry для указанного ключа или false, если не задано.

### Список параметров

`key`

  Запись, которую нужно получить.

### Возвращаемые значения

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Возвращает дату релиза ImageMagick

### Описание

public static function Imagick::getReleaseDate(): string

Возвращает дату релиза ImageMagick в виде строки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает дату релиза ImageMagick в виде строки.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Возвращает размер используемой памяти указанного ресурса

### Описание

public static function Imagick::getResource(int `$type`): int

Возвращает размер используемой памяти указанного ресурса в мегабайтах.

### Список параметров

`type`

  Смотрите список констант типов ресурсов.

### Возвращаемые значения

Возвращает размер используемой памяти указанного ресурса в мегабайтах.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Возвращает лимит ресурсов

### Описание

public static function Imagick::getResourceLimit(int `$type`): int

Метод возвращает лимит ресурсов.

### Список параметров

`type`

  Параметр принимает константу типа ресурса .

### Возвращаемые значения

Метод возвращает заданный лимит ресурсов. Единица измерения размера зависит от типа ограничиваемого ресурса

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Смотрите также

- Imagick::setResourceLimit() - Устанавливает лимит для конкретного ресурса

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — Возвращает горизонтальный и вертикальный фактор выборки

### Описание

public function Imagick::getSamplingFactors(): array

Возвращает горизонтальный и вертикальный фактор выборки.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает ассоциативный массив с горизонтальным и вертикальным фактором выборки изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Возвращает размер, связанный с объектом Imagick

### Описание

public function Imagick::getSize(): array

Получает размер в пикселях объекта Imagick, предварительно заданный с помощью функции Imagick::setSize().

> Замечание:

> Этот метод всего лишь возвращает размер, установленный Imagick::setSize(). Если вам необходимо получить реальные размеры изображения, используйте функции Imagick::getImageWidth() и Imagick::getImageHeight().

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер, связанный с объектом Imagick в виде массива с ключами "columns" (столбцы) и "rows" (строки).

### Примеры

Пример #1 Получение размера исходного изображения RGB, установленные в 200x400, после масштабирования до 400x800

    <?php
    //Устанавливаем размер и загружаем изображение
    $img = new Imagick();
    $img->setSize(200, 400);
    $img->readImage("image.rgb");

    $img->scaleImage(400, 800);

    $size = $img->getSize();
    print_r($size);

    echo $img->getImageWidth()."x".$img->getImageHeight();
    ?>

Результат выполнения приведённого примера:

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Возвращает размер смещения

### Описание

public function Imagick::getSizeOffset(): int

Возвращает размер смещения, связанный с объектом Imagick. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает размер смещения, связанный с объектом Imagick.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Возвращает версию API ImageMagick

### Описание

public static function Imagick::getVersion(): array

Возвращает версию API ImageMagick как строку и число.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает версию API ImageMagick как строку и число.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Заменяет цвета в изображении

### Описание

public function Imagick::haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Заменяет цвета в изображении с помощью таблицы поиска Hald. Hald-изображения могут быть созданы с использованием цветового кодера HALD.

### Список параметров

`clut`

  Объект Imagick, содержащий поисковое Hald-изображение.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::haldClutImage()

    <?php
    function haldClutImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
        $imagickPalette->sepiatoneImage(55);
        $imagick->haldClutImage($imagickPalette);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — Проверяет, содержит ли объект больше изображений

### Описание

public function Imagick::hasNextImage(): bool

Возвращает `true`, если объект содержит больше изображений при перемещении вперёд по списку.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если объект содержит больше изображений при перемещении вперёд по списку, возвращает `false`, если изображений нет.

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — Проверяет, есть ли у объекта предыдущее изображение

### Описание

public function Imagick::hasPreviousImage(): bool

Возвращает `true`, если объект содержит больше изображений при перемещении по списку в обратном направлении.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Возвращает `true`, если объект содержит больше изображений при перемещении по списку в обратном направлении, возвращает `false`, если изображений нет.

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Заменяет любые встроенные символы форматирования соответствующим свойством изображения

### Описание

public function Imagick::identifyFormat(string `$embedText`): string|false

Заменяет любые встроенные символы форматирования соответствующим свойством изображения и возвращает интерпретированный текст. Посмотрите http://www.imagemagick.org/script/escape.php, чтобы узнать про последовательности экранирования.

### Список параметров

`embedText`

  Строка, содержащая последовательности форматирования, например, "Поле обрезки: %@ количество уникальных цветов: %k".

### Возвращаемые значения

Возвращает формат или `false`, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::identifyFormat()

    <?php
            $output = "Вывод 'Поле обрезки: %@ количество уникальных цветов: %k': <br/>";
            $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
            $output .= $imagick->identifyFormat("Поле обрезки: %@ количество уникальных цветов: %k");

    ?>

# Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — Определяет изображение и получает атрибуты

### Описание

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Метод определяет изображение и возвращает его атрибуты в виде массива. Атрибуты изображения включают ширину, высоту, размер и другие.

### Список параметров

`appendRawOutput`

  Метод включит в массив необработанный вывод, если значение параметра установили равным `true`.

### Возвращаемые значения

Метод возвращает массив атрибутов. Атрибуты изображения включают ширину, высоту, размер и другие.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример результата

    Array
    (
        [imageName] => /some/path/image.jpg
        [format] => JPEG (Joint Photographic Experts Group JFIF format)
        [geometry] => Array
            (
                [width] => 90
                [height] => 90
            )

        [type] => TrueColor
        [colorSpace] => RGB
        [resolution] => Array
            (
                [x] => 300
                [y] => 300
            )

        [units] => PixelsPerInch
        [fileSize] => 1.88672kb
        [compression] => JPEG
        [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
    )

# Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — Создаёт копию изображения

### Описание

public function Imagick::implodeImage(float `$radius`): bool

Создаёт новое изображение, которое является копией существующего с пикселями, "сжатыми" на указанный процент.

### Список параметров

`radius`

  Радиус сжатия.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::implodeImage()

    <?php
    function implodeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->implodeImage(0.0001);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — Импортирует пиксели изображения

### Описание

public function Imagick::importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool

Импортирует пиксели из массива в изображение. `map` обычно "RGB". Этот метод накладывает следующие ограничения на параметры: количество пикселей в массиве должно соответствовать `width` x `height` количеству пикселей. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.5 или старше.

### Список параметров

`x`

  Положение изображения по оси X.

`y`

  Положение изображения по оси Y.

`width`

  Ширина изображения.

`height`

  Высота изображения.

`map`

  Карта упорядочения пикселей в виде строки. Это может быть, например, `RGB`. Значение может быть любой комбинацией или порядком: R = красный, G = зелёный, B = синий, A = альфа (0 - прозрачный), O = непрозрачный (0 - непрозрачный), C = голубой, Y = жёлтый, M = пурпурный, K = чёрный, I = интенсивность (для оттенков серого), P = заполнитель.

`storage`

  Метод хранения пикселей. Смотрите список констант пикселей.

`pixels`

  Массив пикселей.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::importImagePixels()

    <?php

    /* Создание массива пикселей. 2000 пикселей на цветную полосу */
    $count = 2000 * 3;

    $pixels =
       array_merge(array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0));

    /* Ширина и высота. Площадь - это количество пикселей, разделённое на три.
    Три происходит от "RGB", три значения на пиксель. */
    $width = $height = pow((count($pixels) / 3), 0.5);

    /* Создание пустого изображения */
    $im = new Imagick();
    $im->newImage($width, $height, 'gray');

    /* Импорт пикселей в изображение.
       width * height * strlen("RGB") должно соответствовать count($pixels) */
    $im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

    /* Вывод изображения */
    $im->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $im;

    ?>

Вывод приведённого примера будет похож на:

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Реализует дискретное преобразование Фурье

### Описание

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

Реализует дискретное преобразование Фурье (ДПФ) изображения в виде пары величина / фаза или пары, состоящей из реального / мнимого изображений.

Внимание

Функцию пока не задокументировали; для знакомства доступен только список аргументов.

### Список параметров

`complement`

  Второе изображение, которое нужно объединить с данным, чтобы сформировать либо пару величина / фаза, либо пару из реального / мнимого изображений.

`magnitude`

  Если значение равно true, будет возвращена пара величина / фаза, иначе - пара, состоящая из реального / мнимого изображений.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Добавляет метку к изображению

### Описание

public function Imagick::labelImage(string `$label`): bool

Добавляет метку к изображению.

### Список параметров

`label`

  Добавляемая метка.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Регулирует уровни изображения

### Описание

public function Imagick::levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Регулирует уровни изображения, масштабируя цвета, попадающие между указанными белыми и чёрными точками, до полного доступного квантового диапазона. Предоставленные параметры представляют собой чёрные, средние и белые точки. Чёрная точка определяет самый тёмный цвет изображения. Цвета темнее точки чёрного устанавливаются на ноль. Средняя точка определяет гамма-коррекцию, применяемую к изображению. Белая точка определяет самый светлый цвет изображения. Для цветов ярче точки белого устанавливается максимальное квантовое значение.

### Список параметров

`blackPoint`

  Чёрная точка изображения.

`gamma`

  Значение гаммы.

`whitePoint`

  Белая точка изображения.

`channel`

  Укажите любую константу канала, которая соответствует вашему режиму канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к этому списку констант канала.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::levelImage()

    <?php
    function levelImage($blackPoint, $gamma, $whitePoint) {
        $imagick = new \Imagick();
        $imagick->newPseudoimage(500, 500, 'gradient:black-white');

        $imagick->setFormat('png');
        $quantum = $imagick->getQuantum();
        $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — Растягивает с насыщением яркость изображения

### Описание

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Растягивает с насыщением яркость изображения.

### Список параметров

`blackPoint`

  Чёрная точка изображения

`whitePoint`

  Белая точка изображения

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::linearStretchImage()

    <?php
    function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
        $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — Анимирует изображение или изображения

### Описание

public function Imagick::liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool

Масштабирует изображения с использованием метода liquid rescaling. Он представляет собой реализацию техники seam carving. Чтобы метод работал должным образом, ImageMagick должен быть скомпилирован с поддержкой liblqr. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.9 или старше.

### Список параметров

`width`

  Ширина целевого размера.

`height`

  Высота целевого размера.

`delta_x`

  Определяет, сколько шов может проходить по оси x. При передаче значения 0 швы становятся прямыми.

`rigidity`

  Вводит уклон для непрямых швов. Этот параметр обычно равен 0.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::resizeImage() - Масштабирует изображение

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — Перечисляет все настройки реестра

### Описание

public static function Imagick::listRegistry(): array

Перечисляет все настройки реестра. Возвращает массив всех пар ключ/значение в реестре.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Массив, содержащий ключи и значения реестра.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Пропорционально масштабирует изображение в два раза

### Описание

public function Imagick::magnifyImage(): bool

Масштабирует изображение в два раза пропорционально оригинальному размеру.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::magnifyImage()

    <?php
    function magnifyImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->magnifyImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — Заменяет цвета изображения на ближайший цвет из эталонного изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### Список параметров

`map`

`dither`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Изменяет значение прозрачности цвета

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Изменяет значение прозрачности любого пикселя, который соответствует цели и является ближайшим соседом. Если указан метод `FillToBorderMethod`, значение прозрачности изменяется для любого соседнего пикселя, который не соответствует элементу bordercolor изображения.

### Список параметров

`alpha`

  Уровень прозрачности: 1.0 - полностью непрозрачный, а 0.0 - полностью прозрачный.

`fuzz`

  Элемент fuzz изображения определяет, насколько допустимо считать два цвета одинаковыми.

`bordercolor`

  Объект ImagickPixel или строка, представляющая цвет рамки.

`x`

  Начальная координата X операции.

`y`

  Начальная координата Y операции.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет строку, представляющую цвет, в качестве третьего параметра. Предыдущие версии допускали только объект ImagickPixel.

# Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — Применяет цифровой фильтр

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::medianFilterImage(float `$radius`): bool

Применяет цифровой фильтр, улучшающий качество изображения с шумом. Каждый пиксель заменяется медианой в наборе соседних пикселей, определяемых радиусом.

### Список параметров

`radius`

  Радиус соседних пикселей.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::medianFilterImage()

    <?php
    function medianFilterImage($radius, $imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->medianFilterImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — Объединяет слои изображения

### Описание

public function Imagick::mergeImageLayers(int `$layer_method`): Imagick

Объединяет слои изображения в один. Метод полезен при работе с форматами изображений, в которых используется несколько слоёв, например PSD. Объединение контролируется с помощью `layer_method`, который определяет способ объединения слоёв. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.7 или старше.

### Список параметров

`layer_method`

  Одна из констант `Imagick::LAYERMETHOD_*`.

### Возвращаемые значения

Возвращает объект Imagick, содержащий объединённое изображение.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::mergeImageLayers()

    <?php
    function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath1));

        $imagick2 = new \Imagick(realpath($imagePath2));
        $imagick->addImage($imagick2);
        $imagick->setImageFormat('png');

        $result = $imagick->mergeImageLayers($layerMethodType);
        header("Content-Type: image/png");
        echo $result->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::flattenImages() - Объединяет последовательность изображений

# Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — Масштабирует изображение пропорционально половине его размера

### Описание

public function Imagick::minifyImage(): bool

Удобный метод масштабирования изображения пропорционально половине его исходного размера.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Управляйте яркостью, насыщенностью и оттенком

### Описание

public function Imagick::modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool

Позволяет управлять яркостью, насыщенностью и оттенком изображения. Оттенок - это процент абсолютного поворота от текущей позиции. Например, 50 приводит к повороту против часовой стрелки на 90 градусов, а 150 - к повороту по часовой стрелке на 90 градусов, 0 и 200 - оба приводят к повороту на 180 градусов.

### Список параметров

`brightness`

`saturation`

`hue`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::modulateImage()

    <?php
    function modulateImage($imagePath, $hue, $brightness, $saturation) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->modulateImage($brightness, $saturation, $hue);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — Создаёт составное изображение

### Описание

public function Imagick::montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick

Создаёт составное изображение путём объединения нескольких отдельных изображений. Изображения размещаются на составном изображении мозаикой, при этом имя изображения может отображаться сразу под отдельной плиткой.

### Список параметров

`draw`

  Название, размер и цвет шрифта берутся из этого объекта.

`tile_geometry`

  Количество плиток в строке и на странице (например, 6x4+0+0).

`thumbnail_geometry`

  Предпочтительный размер изображения и размер границы каждой миниатюры (например, 120x120+4+3).

`mode`

  Режим кадрирования миниатюр, смотрите константы режима кадрирования.

`frame`

  Обведите изображение декоративной рамкой (например, 15x15+3+3). Цвет рамки соответствует матовому цвету эскиза.

### Возвращаемые значения

Создаёт составное изображение и возвращает его как новый объект Imagick.

# Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — Преобразовывает набор изображений

### Описание

public function Imagick::morphImages(int `$number_frames`): Imagick

Преобразовывает набор изображений. И пиксели изображения, и размер линейно интерполируются, чтобы создать видимость метаморфозы от одного изображения к другому.

### Список параметров

`number_frames`

  Количество создаваемых промежуточных изображений.

### Возвращаемые значения

Метод возвращает новый объект Imagick в случае успешного выполнения. Вызывает ImagickException, если возникла ошибка.

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Применяет к изображению ядро, предоставленное пользователем, в соответствии с заданным методом морфологии

### Описание

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Применяет к изображению ядро, предоставленное пользователем, в соответствии с заданным методом морфологии.

### Список параметров

`morphologyMethod`

  Какой метод морфологии использовать: одна из констант \Imagick::MORPHOLOGY_*.

`iterations`

  Количество итераций для применения морфологической функции. Значение -1 означает цикл до тех пор, пока не будет найдено никаких изменений. Как это применяется, может зависеть от метода морфологии. Обычно это значение равно 1.

`ImagickKernel`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования метода Convolve Imagick::morphology()

    <?php
    $imagick = $this->getCharacter();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
    $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();

    ?>

Пример #2 Пример использования метода Correlate Imagick::morphology()

    <?php
    // Верхний левый пиксель должен быть чёрным.
    // Нижний правый пиксель должен быть белым
    // На остальное нам всё равно.

    $imagick = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
    $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
    header("Content-Type: image/png");
    echo $imagick->getImageBlob();

    ?>

Пример #3 Пример использования метода Erode Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #4 Пример использования метода Erode Intensity Imagick::morphology()

    <?php
    $canvas = $this->getCharacter();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
    $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #5 Пример использования метода Dilate Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #6 Пример использования метода Dilate intensity Imagick::morphology()

    <?php
    $canvas = $this->getCharacter();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
    $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #7 Пример использования метода Distance с ядром Chebyshev Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
    $canvas->autoLevelImage();
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #8 Пример использования метода Distance с ядром Manhattan Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
    $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
    $canvas->autoLevelImage();
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #9 Пример использования метода Distance с ядром ocatagonal Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
    $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
    $canvas->autoLevelImage();
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #10 Пример использования метода Distance с ядром Euclidean Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
    $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
    $canvas->autoLevelImage();
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #11 Пример использования метода Edge Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #12 Пример использования метода Open Imagick::morphology()

    <?php
    // В результате вы увидите, что "Open" сглаживает контур, округляя все острые точки, и удаляет все части, которые меньше используемой формы.
    // Он также отключит или откроет любые тонкие мосты.
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
    $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #13 Пример использования метода Open intensity Imagick::morphology()

    <?php
    // В результате вы увидите, что "Open" сглаживает контур, округляя все острые точки, и удаляет все части, которые меньше используемой формы.
    // Он также отключит или откроет любые тонкие мосты.

    $canvas = $this->getCharacter();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
    $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #14 Пример использования метода Close Imagick::morphology()

    <?php
    // Основное использование метода "Close" - уменьшить или удалить любые дыры или пробелы в размере Структурного элемента ядра.
    // Это "близкие" части фона примерно такого размера.
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
    $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #15 Пример использования метода Close Intensity Imagick::morphology()

    <?php
    // Основное использование метода "Close" - уменьшить или удалить любые дыры или пробелы в размере Структурного элемента ядра.
    // Это "близкие" части фона примерно такого размера.
    $canvas = $this->getCharacter();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
    $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #16 Пример использования метода Smooth Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #17 Пример использования метода Edge in Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #18 Пример использования метода Edge out Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
    $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #19 Метод "TopHat", или, точнее, "White TopHat", возвращает пиксели, которые были удалены открытием фигуры, то есть пиксели, которые были удалены для округления точек, и соединение, соединённое мостом между фигурами. Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
    $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #20 Метод "TopHat", или, точнее, "Black TopHat", возвращает пиксели, которые были удалены закрытием фигуры, то есть пиксели, которые использовались для заполнения дыр, зазоров и мостов. Imagick::morphology()

    <?php

    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
    $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #21 Пример использования метода Hit и Miss Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    // Находит все пиксели с 3 пикселями правого края
    $matrix = [[1, false, false, 0]];
    $kernel = \ImagickKernel::fromMatrix(
        $matrix,
        [0, 0]
    );
    $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #22 Пример использования метода Thinning Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
    $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
    $leftEdgeKernel->addKernel($rightEdgeKernel);

    $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #23 Пример использования метода Thicken Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
    $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
    $leftEdgeKernel->addKernel($rightEdgeKernel);

    $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #24 Пример использования метода Thick для создания выпуклой оболочки Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
    $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

    // Утолщённая морфология не справляется с небольшими зазорами.
    // Закрываем их близкой морфологией.
    $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
    $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
    $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #25 Пример использования метода Iterative morphology Imagick::morphology()

    <?php
    $canvas = $this->getCharacterOutline();
    $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
    $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
    $canvas->autoLevelImage();
    header("Content-Type: image/png");
    echo $canvas->getImageBlob();

    ?>

Пример #26 Пример использования вспомогательной функции для получения силуэта изображения Imagick::morphology()

    <?php

    function getCharacterOutline() {
        $imagick = new \Imagick(realpath("./images/character.png"));
        $character = new \Imagick();
        $character->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:white"
        );
        $canvas = new \Imagick();
        $canvas->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:black"
        );

        $character->compositeimage(
            $imagick,
            \Imagick::COMPOSITE_COPYOPACITY,
            0, 0
        );
        $canvas->compositeimage(
            $character,
            \Imagick::COMPOSITE_ATOP,
            0, 0
        );
        $canvas->setFormat('png');

        return $canvas;
    }
    ?>

# Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — Формирует мозаику из изображений

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::mosaicImages(): Imagick

Выкладывает мозаику из последовательности изображений, чтобы сформировать единое связное изображение. Возвращает палочку с каждым изображением в последовательности, составленным в месте, определённом смещением страницы изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Имитирует размытие в движении

### Описание

public function Imagick::motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Имитирует размытие в движении. Сворачивает изображение с помощью гауссовского оператора заданного радиуса и стандартного отклонения (сигма). Для получения разумных результатов радиус должен быть больше сигмы. Используйте радиус 0, и MotionBlurImage() выберет подходящий радиус самостоятельно. Угол задаёт угол размытия движения.

### Список параметров

`radius`

  Радиус гауссианы в пикселях, не считая центрального пикселя.

`sigma`

  Стандартное отклонение Гаусса в пикселях.

`angle`

  Применение эффекта под этим углом.

`channel`

  Укажите любую константу канала, которая действительна для вашего режима канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к списку констант канала. Аргумент канала влияет только в том случае, если Imagick скомпилирован с ImageMagick версии 6.4.4 или выше.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::motionBlurImage()

    <?php
    function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

# Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — Инвертирует цвета в эталонном изображении

### Описание

public function Imagick::negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Инвертирует цвета в эталонном изображении. Параметр Grayscale означает, что в изображении инвертируются только значения оттенков серого.

### Список параметров

`gray`

  Определяет, нужно ли инвертировать только пиксели в оттенках серого в изображении.

`channel`

  Укажите любую константу CHANNEL, которая подходит для заданного режима канала. Для применения более чем к одному каналу необходимо объединить константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::negateImage()

    <?php
    function negateImage($imagePath, $grayOnly, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->negateImage($grayOnly, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — Создаёт новое изображение

### Описание

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

Создаёт новое изображение и связывает значение ImagickPixel в качестве цвета фона

### Список параметров

`cols`

  Столбцы в новом изображении

`rows`

  Строки в новом изображении

`background`

  Цвет фона, используемый для этого изображения

`format`

  Формат изображения. Этот параметр был добавлен в Imagick версии 2.0.1.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь допускается строка, представляющая цвет, в качестве третьего параметра. Ранее допускался только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::newImage():

Создание нового изображения и его отображение.

    <?php

    $image = new Imagick();
    $image->newImage(100, 100, new ImagickPixel('red'));
    $image->setImageFormat('png');

    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — Создаёт новое изображение

### Описание

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Создаёт новое изображение с использованием псевдоформатов ImageMagick.

### Список параметров

`columns`

  Столбцы в новом изображении.

`rows`

  Строки в новом изображении.

`pseudoString`

  Строка, содержащая определение псевдоизображения.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::newPseudoImage()

    <?php
    function newPseudoImage($canvasType) {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(300, 300, $canvasType);
        $imagick->setImageFormat("png");
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
    //newPseudoImage("radial-gradient:red-blue");
    newPseudoImage("plasma:fractal");

    ?>

# Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — Переходит к следующему изображению

### Описание

public function Imagick::nextImage(): bool

Связывает следующее изображение в списке изображений с объектом Imagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Повышает контрастность цветного изображения

### Описание

public function Imagick::normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Повышает контрастность цветного изображения, регулируя цвет пикселей для охвата всего диапазона доступных цветов.

### Список параметров

`channel`

  Укажите любую константу CHANNEL, которая подходит для заданного режима канала. Для применения более чем к одному каналу необходимо объединить константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::normalizeImage()

    <?php
    function normalizeImage($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $original = clone $imagick;
        $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
        $imagick->normalizeImage($channel);
        $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — Имитирует картину маслом

### Описание

public function Imagick::oilPaintImage(float `$radius`): bool

Применяет фильтр со специальным эффектом, имитирующий картину маслом. Каждый пиксель заменяется наиболее часто встречающимся цветом в круговой области, определяемой радиусом.

### Список параметров

`radius`

  Радиус круговой области.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::oilPaintImage()

    <?php
    function oilPaintImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->oilPaintImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — Изменяет значение цвета любого пикселя, соответствующего целевому

### Описание

public function Imagick::opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Изменяет любой пиксель, соответствующий цвету, на цвет, определённый заливкой. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.8 или старше.

### Список параметров

`target`

  Объект ImagickPixel или строка, содержащая цвет, который нужно изменить

`fill`

  Цвет замены

`fuzz`

  Мера округления (fuzz). Например, установите значение fuzz в 10 и красный цвет с интенсивностью 100 и 102 будет интерпретироваться как один и тот же цвет.

`invert`

  Если `true` закрашивается любой пиксель, не соответствующий целевому цвету.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Удаляет повторяющиеся части изображений для оптимизации

### Описание

public function Imagick::optimizeImageLayers(): bool

Сравнивает каждое изображение, расположенное в формате GIF, с предыдущим изображением в последовательности. Исходя из этого, функция пытается выбрать наименьшее обрезанное изображение для замены каждого кадра, сохраняя при этом результаты анимации. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::optimizeImageLayers()

Чтение, оптимизация и запись изображения в формате GIF

    <?php
    /* создание нового объекта imagick */
    $im = new Imagick("test.gif");

    /* оптимизация слоёв изображения */
    $im->optimizeImageLayers();

    /* запись изображения обратно */
    $im->writeImages("test_optimized.gif", true);
    ?>

### Смотрите также

- Imagick::compareImageLayers() - Возвращает максимальную ограничивающую область между изображениями
- Imagick::writeImages() - Записывает изображение или последовательность изображений
- Imagick::writeImage() - Записывает изображение по указанному имени файла

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Выполняет упорядоченный дизеринг

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Выполняет упорядоченный дизеринг на основе ряда предопределённых карт пороговых значений дизеринга, но с несколькими уровнями интенсивности, которые могут быть разными для разных каналов в соответствии с входными аргументами. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.1 или старше.

### Список параметров

`threshold_map`

  Строка, содержащая имя используемой карты порогового дизеринга.

`channel`

  Укажите любую константу канала, которая действительна для вашего режима канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к списку констант канала.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::orderedPosterizeImage()

    <?php
    function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->orderedPosterizeImage($orderedPosterizeType);
        $imagick->setImageFormat('png');

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //orderedPosterizeImage($imagePath, 'o4x4,3,3');
    //orderedPosterizeImage($imagePath, 'o8x8,6,6');
    orderedPosterizeImage($imagePath, 'h8x8a');
    ?>

# Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — Изменяет значение цвета любого пикселя, соответствующего цели

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Изменяет значение цвета любого пикселя, который соответствует цели и является ближайшим соседом. Начиная с ImageMagick 6.3.8 этот метод устарел и вместо него следует использовать Imagick::floodfillPaintImage().

### Список параметров

`fill`

  Объект ImagickPixel или строка, содержащая цвет заливки.

`fuzz`

  Мера округления (fuzz). Для примера, установите значение fuzz в 10 и красный цвет с интенсивностью 100 и 102 будет интерпретироваться как один и тот же цвет.

`bordercolor`

  Объект ImagickPixel или строка, содержащая целевой цвет для рисования.

`x`

  Начальная позиция заливки по оси X.

`y`

  Начальная позиция заливки по оси Y.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Изменяет любой пиксель, соответствующий цвету

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Изменяет любой пиксель, соответствующий цвету, на цвет, определённый заливкой.

### Список параметров

`target`

  Изменяет целевой цвет на цвет заливки в изображении. Объект ImagickPixel или строка, представляющая целевой цвет.

`fill`

  Объект ImagickPixel или строка, представляющая цвет заливки.

`fuzz`

  Мера округления (fuzz) изображения определяет, насколько приемлемо рассматривать два цвета как один и тот же.

`channel`

  Укажите любую константу канала, которая соответствует вашему режиму канала. Чтобы применить более чем к одному каналу, объедините константы типа канала с помощью побитовых операторов. Обратитесь к этому списку констант канала.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь допускается передавать строку, представляющую цвет, в первый и второй параметр. Предыдущие версии допускали только объект ImagickPixel.

# Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — Изменяет любой пиксель, соответствующий цвету, на цвет, определённый заливкой

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Изменяет любой пиксель, соответствующий цвету, на цвет, определённый заливкой.

### Список параметров

`target`

  Целевой цвет, заменяемый на указанное значение непрозрачности в изображении.

`alpha`

  Уровень прозрачности: 1.0 - полностью непрозрачный, 0.0 - полностью прозрачный.

`fuzz`

  Определяет, насколько допустимо считать два цвета одинаковыми.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь разрешает использовать строку, представляющую цвет, в качестве первого параметра. Предыдущие версии допускали только объект ImagickPixel.

# Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — Получает основные атрибуты изображения

### Описание

public function Imagick::pingImage(string `$filename`): bool

Метод можно использовать для запроса ширины, высоты, размера и формата изображения без считывания всего изображения в память.

### Список параметров

`filename`

  Имя файла, из которого следует прочитать информацию.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Быстро извлекает атрибуты

### Описание

public function Imagick::pingImageBlob(string `$image`): bool

Метод можно использовать для запроса ширины, высоты, размера и формата изображения без считывания всего изображения в память. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`image`

  Строка, содержащая изображение.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::pingImageBlob()

Получение изображения из строки

    <?php
    /* чтение содержимого изображения */
    $image = file_get_contents("test.jpg");

    /* создание нового объекта imagick */
    $im = new Imagick();

    /* передача строки объекту imagick */
    $im->pingImageBlob($image);

    /* вывод ширины и высоты изображения */
    echo $im->getImageWidth() . 'x' . $im->getImageHeight();
    ?>

### Смотрите также

- Imagick::pingImage() - Получает основные атрибуты изображения
- Imagick::pingImageFile() - Получает базовые атрибуты изображения упрощённым способом
- Imagick::readImage() - Читает изображение из файла
- Imagick::readImageBlob() - Считывает изображение из двоичной строки
- Imagick::readImageFile() - Читает изображение из открытого дескриптора файла

# Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — Получает базовые атрибуты изображения упрощённым способом

### Описание

public function Imagick::pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool

Метод можно использовать для запроса ширины, высоты, размера и формата изображения без считывания всего изображения в память. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`filehandle`

  Открытый дескриптор файла изображения.

`fileName`

  Необязательное имя файла для данного изображения.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::pingImageFile()

Открытие удалённой локации

    <?php
    /* Открытие удалённой локации с помощью fopen */
    $fp = fopen("http://example.com/test.jpg");

    /* Создание нового объекта Imagick */
    $im = new Imagick();

    /* Передача дескриптора объекту Imagick */
    $im->pingImageFile($fp);
    ?>

### Смотрите также

- Imagick::pingImage() - Получает основные атрибуты изображения
- Imagick::pingImageBlob() - Быстро извлекает атрибуты
- Imagick::readImage() - Читает изображение из файла
- Imagick::readImageBlob() - Считывает изображение из двоичной строки
- Imagick::readImageFile() - Читает изображение из открытого дескриптора файла

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Имитирует фото Polaroid

### Описание

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Имитирует фото Polaroid. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.2 или старше.

### Список параметров

`properties`

  Свойства Polaroid.

`angle`

  Угол Polaroid.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::polaroidImage()

Пример использования Imagick::polaroidImage()

    <?php
    /* Создание объекта */
    $image = new Imagick('source.png');

    /* Установка непрозрачности */
    $image->polaroidImage(new ImagickDraw(), 25);

    /* Вывод изображения */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — Уменьшает изображение до ограниченного количества уровней цвета

### Описание

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Уменьшает изображение до ограниченного количества уровней цвета.

### Список параметров

`levels`

`dither`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::posterizeImage()

    <?php
    function posterizeImage($imagePath, $posterizeType, $numberLevels) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->posterizeImage($numberLevels, $posterizeType);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

    ?>

# Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — Быстрое определение подходящих параметров для обработки изображений

### Описание

public function Imagick::previewImages(int `$preview`): bool

Размещает 9 миниатюр указанного изображения с помощью операции обработки изображения, применяемой с разной интенсивностью. Это помогает быстро определить подходящий параметр для операции обработки изображения.

### Список параметров

`preview`

  Тип предварительного просмотра. Смотрите константы типа предварительного просмотра

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Переходит к предыдущему изображению в объекте

### Описание

public function Imagick::previousImage(): bool

Связывает предыдущее изображение в списке изображений с объектом Imagick.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Добавляет или удаляет профиль изображения

### Описание

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

Метод добавляет или удаляет из изображения профиль ICC, IPTC или общий профиль. Если значение параметра `profile` равно `null`, то профиль удаляется из изображения, а не добавляется.

Для удаления всех профилей из изображения, используйте `'*'` в качестве значения параметра `name` и `null` в качестве значения параметра `profile`.

### Список параметров

`name`
  Имя профиля.
`profile`
  Данные профиля. Если `null`, указанный профиль будет удалён.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Анализирует цвета эталонного изображения

### Описание

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Список параметров

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::quantizeImage()

    <?php
    function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — Анализирует цвета в последовательности изображений

### Описание

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Список параметров

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Возвращает массив, представляющий метрики шрифта

### Описание

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Возвращает многомерный массив, представляющий метрики шрифта.

### Список параметров

`properties`

  Объект ImagickDraw, содержащий свойства шрифта.

`text`

  Текст.

`multiline`

  Многострочный параметр. Если оставить пустым, он определяется автоматически.

### Возвращаемые значения

Возвращает многомерный массив, представляющий метрики шрифта.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::queryFontMetrics():

Запрашивает метрики для текста и выводит результаты на экран.

    <?php
    /* Создание нового объекта Imagick */
    $im = new Imagick();

    /* Создание нового объекта Imagick */
    $draw = new ImagickDraw();

    /* Установка шрифта */
    $draw->setFont('/path/to/font.ttf');

    /* Вывод метрики шрифта, автоматическое определение многострочного параметра */
    var_dump($im->queryFontMetrics($draw, "Hello World!"));
    ?>

# Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — Возвращает настроенные шрифты

### Описание

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Возвращает настроенные шрифты.

### Список параметров

`pattern`

  Шаблон запроса

### Возвращаемые значения

Возвращает массив, содержащий настроенные шрифты.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::queryFonts()

    <?php
            $output = '';
            $output .= "Шрифты, соответствующие 'Helvetica*':<br/>";

            $fontList = \Imagick::queryFonts("Helvetica*");

            foreach ($fontList as $fontName) {
                $output .= '<li>'. $fontName."</li>";
            }

            return $output;

    ?>

# Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Возвращает форматы, поддерживаемые Imagick

### Описание

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Возвращает форматы, поддерживаемые Imagick.

### Список параметров

`pattern`

### Возвращаемые значения

Возвращает массив, содержащий форматы, поддерживаемые Imagick.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::queryFormats()

    <?php
        function render() {
            $output = "";
            $input = \Imagick::queryformats();
            $columns = 6;

            $output .= "<table border='2'>";

            for ($i=0; $i < count($input); $i += $columns) {
                $output .= "<tr>";
                for ($c=0; $c<$columns; $c++) {
                    $output .= "<td>";
                    if (($i + $c) <  count($input)) {
                        $output .= $input[$i + $c];
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

    ?>

# Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — Радиальное размытие изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Радиальное размытие изображения.

### Список параметров

`angle`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::radialBlurImage()

    <?php
    function radialBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Размытие 3 раза с разными радиусами
        $imagick->radialBlurImage(3);
        $imagick->radialBlurImage(5);
        $imagick->radialBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — Создаёт имитацию эффекта 3D-кнопки

### Описание

public function Imagick::raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool

Создаёт имитацию трёхмерного эффекта кнопки, осветляя и затемняя края изображения. Ширина и высота элементов raise_info определяют ширину вертикального и горизонтального края эффекта.

### Список параметров

`width`

`height`

`x`

`y`

`raise`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::raiseImage()

    <?php
    function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
        $imagick = new \Imagick(realpath($imagePath));

        //x и y ничего не делают?
        $imagick->raiseImage($width, $height, $x, $y, $raise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — Создаёт высококонтрастное двухцветное изображение

### Описание

public function Imagick::randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Изменяет значение отдельных пикселей в зависимости от интенсивности каждого пикселя по сравнению с пороговым значением. В результате получается высококонтрастное двухцветное изображение. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`low`

  Нижняя точка.

`high`

  Верхняя точка.

`channel`

  Укажите любую константу CHANNEL, которая подходит для заданного режима канала. Для применения более чем к одному каналу необходимо объединить константы типа CHANNEL с помощью побитовых операторов. Обратитесь к этому списку констант CHANNEL.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::randomThresholdImage()

    <?php
    function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->randomThresholdimage(
            $lowThreshold * \Imagick::getQuantum(),
            $highThreshold * \Imagick::getQuantum(),
            $channel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — Читает изображение из файла

### Описание

public function Imagick::readImage(string `$filename`): bool

Читает изображение из файла.

### Список параметров

`filename`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — Считывает изображение из двоичной строки

### Описание

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

Считывает изображение из двоичной строки.

### Список параметров

`image`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::readImageBlob()

    <?php
    function readImageBlob() {
        $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
     NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
     cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
     gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
     0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
     aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
     v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
     NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
     Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
     AAAAAElFTkSuQmCC";

        $imageBlob = base64_decode($base64);

        $imagick = new Imagick();
        $imagick->readImageBlob($imageBlob);

        header("Content-Type: image/png");
        echo $imagick;
    }

    ?>

# Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — Читает изображение из открытого дескриптора файла

### Описание

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Читает изображение из открытого дескриптора файла.

### Список параметров

`filehandle`

`fileName`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Читает изображение из массива имён файлов

### Описание

public function Imagick::readImages(array `$filenames`): bool

Читает изображение из массива имён файлов. Все изображения хранятся в одном объекте Imagick.

### Список параметров

`filenames`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Перекрашивает изображение

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::recolorImage(array `$matrix`): bool

Преобразование, масштабирование, сдвиг или поворот цветов изображения. Метод поддерживает матрицы переменного размера, но обычно матрица 5x5 используется для RGBA, а 6x6 - для CMYK. Последняя строка должна содержать нормализованные значения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`matrix`

  Матрица, содержащая значения цвета.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::recolorImage()

    <?php
    function recolorImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $remapColor = [ 1, 0, 0,
            0, 0, 1,
            0, 1, 0,];

    //$remapColor = [
    //    1.438, -0.122, -0.016,  0, 0, -0.03,
    //    -0.062,  1.378, -0.016,  0, 0,  0.05,
    //    -0.062, -0.122, 1.483,   0, 0, -0.02,
    //];

        @$imagick->recolorImage($remapColor);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::displayImage() - Выводит изображение

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Сглаживает контуры изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::reduceNoiseImage(float `$radius`): bool

Сглаживает контуры изображения, сохраняя при этом информацию о краях. Алгоритм работает, заменяя каждый пиксель ближайшим по значению соседом. Сосед определяется радиусом. При использовании радиуса 0, Imagick::reduceNoiseImage() выберет подходящий радиус автоматически.

### Список параметров

`radius`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::reduceNoiseImage()

    <?php
    function reduceNoiseImage($imagePath, $reduceNoise) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->reduceNoiseImage($reduceNoise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — Переназначает цвета изображения

### Описание

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

Заменяет цвета изображения на те, которые определены параметром `replacement`. Цвета заменяются наиболее близким из возможных. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.5 или старше.

### Список параметров

`replacement`

  Объект Imagick, содержащий заменяющие цвета.

`DITHER`

  Обратитесь к списку констант DITHERMETHOD.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Удаляет изображение из списка изображений

### Описание

public function Imagick::removeImage(): bool

Удаляет изображение из списка изображений.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Удаляет именованный профиль изображения и возвращает его

### Описание

public function Imagick::removeImageProfile(string `$name`): string

Удаляет именованный профиль изображения и возвращает его.

### Список параметров

`name`

### Возвращаемые значения

Возвращает строку, содержащую профиль изображения.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Отображает все предыдущие команды рисования

### Описание

public function Imagick::render(): bool

Отображает все предыдущие команды рисования.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Преобразовывает изображение к нужному разрешению

### Описание

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Преобразовывает изображение к нужному разрешению.

### Список параметров

`x_resolution`

`y_resolution`

`filter`

`blur`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования метода Imagick::resampleImage()

    <?php
    function resampleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — Сбрасывает страницу изображения

### Описание

public function Imagick::resetImagePage(string `$page`): bool

Определение страницы в виде строки. Строка имеет формат WxH+x+y. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`page`

  Определение страницы. Например, `7168x5147+0+0`.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Масштабирует изображение

### Описание

public function Imagick::resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Масштабирует изображение до желаемых размеров с помощью filter.

> Замечание: Поведение параметра `bestfit` изменили в Imagick 3.0.0. До этой версии при размерах 400 x 300 точек изображение размером 200 x 150 точек оставалось нетронутым. В Imagick 3.0.0 и более поздних версиях изображение будет масштабироваться до размера 400 x 300 точек, поскольку такой размер «больше остальных соответствует» заданным размерам. Потребуется указать как ширину, так и высоту, если задали параметр `bestfit`.

### Список параметров

`columns`

  Ширина изображения.

`rows`

  Высота изображения.

`filter`

  Обратитесь к списку констант FILTER.

`blur`

  Коэффициент размытия, где значение > 1 делает изображение более размытым, а значение < 1 - более резким.

`bestfit`

  Необязательный параметр подгонки.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Добавлен необязательный параметр подгонки. Теперь метод поддерживает пропорциональное масштабирование. Для пропорционального масштабирования необходимо передать ноль в качестве любого параметра.

### Примеры

Пример #1 Пример использования Imagick::resizeImage()

    <?php
    function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
        //Коэффициент размытия, где значение >  1 делает изображение более размытым, а значение < 1 - более резким.
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

        $cropWidth = $imagick->getImageWidth();
        $cropHeight = $imagick->getImageHeight();

        if ($cropZoom) {
            $newWidth = $cropWidth / 2;
            $newHeight = $cropHeight / 2;

            $imagick->cropimage(
                $newWidth,
                $newHeight,
                ($cropWidth - $newWidth) / 2,
                ($cropHeight - $newHeight) / 2
            );

            $imagick->scaleimage(
                $imagick->getImageWidth() * 4,
                $imagick->getImageHeight() * 4
            );
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — Смещает изображение

### Описание

public function Imagick::rollImage(int `$x`, int `$y`): bool

Смещает изображение в соответствии с определением x и y.

### Список параметров

`x`

  Смещение по оси X.

`y`

  Смещение по оси Y.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::rollImage()

    <?php
    function rollImage($imagePath, $rollX, $rollY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rollimage($rollX, $rollY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — Поворачивает изображение

### Описание

public function Imagick::rotateImage(mixed `$background`, float `$degrees`): bool

Поворачивает изображение на указанное количество градусов. Пустые треугольники, оставшиеся от поворота изображения, заполняются цветом фона.

### Список параметров

`background`

  Цвет фона.

`degrees`

  Угол поворота в градусах. Угол поворота интерпретируется как количество градусов для поворота изображения по часовой стрелке.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь разрешено использование строки, представляющей цвет, в качестве первого параметра. Предыдущие версии допускали только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::rotateImage()

    <?php
    function rotateImage($imagePath, $angle, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotateimage($color, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Применяет вращательное размытие к изображению

### Описание

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Применяет вращательное размытие к изображению.

### Список параметров

`angle`

  Угол размытия.

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::rotationalBlurImage()

    <?php
    function rotationalBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotationalBlurImage(3);
        $imagick->rotationalBlurImage(5);
        $imagick->rotationalBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — Скругляет углы изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool

Скругляет углы изображения. Первые два параметра управляют степенью округления, а три последних параметра могут использоваться для точной настройки процесса округления. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше. Этот метод недоступен, если Imagick был скомпилирован с версией ImageMagick 7.0.70или старше.

### Список параметров

`x_rounding`

  Округление по x.

`y_rounding`

  Округление по y.

`stroke_width`

  Ширина обводки.

`displace`

  Смещение изображения.

`size_correction`

  Коррекция размера.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::roundCorners()

Закругление углов изображения

    <?php

    $image = new Imagick();
    $image->newPseudoImage(100, 100, "magick:rose");
    $image->setImageFormat("png");

    $image->roundCorners(5,3);
    $image->writeImage("rounded.png");
    ?>

# Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — Масштабирует изображение с пиксельной выборкой

### Описание

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

Масштабирует изображение до желаемых размеров с помощью выборки пикселей. В отличие от других методов масштабирования, этот метод не вводит дополнительный цвет в масштабируемое изображение.

### Список параметров

`columns`

`rows`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Масштабирует размер изображения

### Описание

public function Imagick::scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Масштабирует изображение до заданных размеров. Второй параметр будет вычислен, если в качестве любого из параметров будет передан 0.

> Замечание: Поведение параметра `bestfit` изменили в Imagick 3.0.0. До этой версии при размерах 400 x 300 точек изображение размером 200 x 150 точек оставалось нетронутым. В Imagick 3.0.0 и более поздних версиях изображение будет масштабироваться до размера 400 x 300 точек, поскольку такой размер «больше остальных соответствует» заданным размерам. Потребуется указать как ширину, так и высоту, если задали параметр `bestfit`.

### Список параметров

`columns`

`rows`

`bestfit`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Добавлен необязательный параметр fit. Метод теперь поддерживает пропорциональное масштабирование. Передайте ноль в качестве любого параметра для пропорционального масштабирования.

### Примеры

Пример #1 Пример использования Imagick::scaleImage()

    <?php
    function scaleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->scaleImage(150, 150, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — Сегментирует изображение

### Описание

public function Imagick::segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool

Анализирует изображение и определяет похожие объекты. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.5 или старше.

### Список параметров

`COLORSPACE`

  Одна из констант COLORSPACE.

`cluster_threshold`

  Процент, описывающий минимальное количество пикселей, содержащихся в гексаэдре, прежде чем он будет считаться корректным.

`smooth_threshold`

  Устраняет шум на гистограмме.

`verbose`

  Определяет, выводить ли подробную информацию о распознанных классах.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования Imagick::segmentImage()

    <?php
    function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Выборочное размытие изображения в пределах порогового значения контрастности

### Описание

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Выборочное размытие изображения в пределах порогового значения контрастности. Это похоже на маску нерезкости, которая увеличивает резкость всего, если контраст превышает определённый порог.

### Список параметров

`radius`

`sigma`

`threshold`

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::selectiveBlurImage()

    <?php
    function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — Отделяет канал от изображения

### Описание

public function Imagick::separateImageChannel(int `$channel`): bool

Отделяет канал от изображения и возвращает изображение в оттенках серого. Канал - это определённый цветовой компонент каждого пикселя изображения.

### Список параметров

`channel`

  Определяет, какой 'канал' вернуть. Для цветовых пространств, отличных от RGB, можно использовать константы CHANNEL_RED, CHANNEL_GREEN, CHANNEL_BLUE для обозначения 1-го, 2-го и 3-го каналов.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::separateImageChannel()

    <?php
    function separateImageChannel($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->separateimagechannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

    ?>

# Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — Тонирование изображения сепией

### Описание

public function Imagick::sepiaToneImage(float `$threshold`): bool

Применяет к изображению специальный эффект, аналогичный эффекту, достигаемому в фотолаборатории с помощью тонирования сепией. Порог варьируется от 0 до QuantumRange и является мерой степени тонирования сепии. Порог 80 - хорошая отправная точка для разумного тона.

### Список параметров

`threshold`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::sepiaToneImage()

    <?php
    function sepiaToneImage($imagePath, $sepia) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sepiaToneImage($sepia);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — Устанавливает цвет фона объекта по умолчанию

### Описание

public function Imagick::setBackgroundColor(mixed `$background`): bool

Устанавливает цвет фона объекта по умолчанию.

### Список параметров

`background`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет использовать представляющую цвет строку в качестве параметра. Предыдущие версии позволяли использовать только объект ImagickPixel.

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — Устанавливает цветовое пространство

### Описание

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Устанавливает значение глобального цветового пространства для объекта. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.5.7 или старше.

### Список параметров

`COLORSPACE`

  Одна из констант COLORSPACE.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Устанавливает тип сжатия объекта по умолчанию

### Описание

public function Imagick::setCompression(int `$compression`): bool

Устанавливает тип сжатия объекта по умолчанию.

### Список параметров

`compression`

  Тип сжатия. Смотрите константы Imagick::COMPRESSION_*.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Устанавливает качество сжатия объекта по умолчанию

### Описание

public function Imagick::setCompressionQuality(int `$quality`): bool

Устанавливает качество сжатия объекта по умолчанию.

Предостережение

Этот метод работает только для новых изображений, например, созданных с помощью Imagick::newPseudoImage. Для существующих изображений следует использовать Imagick::setImageCompressionQuality().

### Список параметров

`quality`

  Целое число (int) от 1 до 100, 1 = высокая степень сжатия, 100 = низкая степень сжатия.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setCompressionQuality()

    <?php
    function setCompressionQuality($imagePath, $quality) {

        $backgroundImagick = new \Imagick(realpath($imagePath));
        $imagick = new \Imagick();
        $imagick->setCompressionQuality($quality);
        $imagick->newPseudoImage(
            $backgroundImagick->getImageWidth(),
            $backgroundImagick->getImageHeight(),
            'canvas:white'
        );

        $imagick->compositeImage(
            $backgroundImagick,
            \Imagick::COMPOSITE_ATOP,
            0,
            0
        );

        $imagick->setFormat("jpg");
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — Устанавливает имя файла перед чтением или записью изображения

### Описание

public function Imagick::setFilename(string `$filename`): bool

Устанавливает имя файла перед чтением или записью изображения.

### Список параметров

`filename`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Устанавливает итератор Imagick для первого изображения

### Описание

public function Imagick::setFirstIterator(): bool

Устанавливает итератор Imagick для первого изображения.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Устанавливает шрифт

### Описание

public function Imagick::setFont(string `$font`): bool

Устанавливает объекту свойство шрифт. Метод можно использовать, например, для установки шрифта для caption: формат псевдоизображений. Шрифт должен быть настроен в конфигурации ImageMagick или должен существовать файл с именем `font`. Метод не следует путать с методом ImagickDraw::setFont(), который устанавливает шрифт для определённого объекта ImagickDraw. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.7 или старше.

### Список параметров

`font`

  Имя шрифта или файла.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setFont()

Пример использования Imagick::setFont

    <?php
    /* Создание нового объекта Imagick */
    $im = new Imagick();

    /* Установка шрифта для объекта */
    $im->setFont("example.ttf");

    /* Создание нового заголовка */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Работа с изображением */
    ?>

### Смотрите также

- Imagick::getFont() - Возвращает название шрифта
- ImagickDraw::setFont() - Устанавливает указанный шрифт для использования при аннотировании текстом
- ImagickDraw::getFont() - Возвращает шрифт

# Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Устанавливает формат объекта Imagick

### Описание

public function Imagick::setFormat(string `$format`): bool

Устанавливает формат объекта Imagick.

### Список параметров

`format`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Устанавливает гравитацию

### Описание

public function Imagick::setGravity(int `$gravity`): bool

Устанавливает глобальное свойство гравитации для объекта Imagick. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.0 или старше.

### Список параметров

`gravity`

  Свойство гравитации. Обратитесь к списку констант GRAVITY.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Заменяет изображение в объекте

### Описание

public function Imagick::setImage(Imagick `$replace`): bool

Заменяет текущую последовательность изображений изображением из заменяющего объекта.

### Список параметров

`replace`

  Заменяющий объект Imagick.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImage()

Пример использования Imagick::setImage()

    <?php
    /* Создание объектов */
    $image = new Imagick('source.jpg');
    $replace = new Imagick('replace.jpg');

    /* source.jpg заменяется на replace.jpg */
    $image->setImage($replace);

    /* Вывод изображения */
    header('Content-type: image/jpeg');
    echo $image;

    ?>

# Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — Устанавливает альфа-канал изображения

### Описание

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Активирует или деактивирует альфа-канал изображения. Параметр `mode` - одна из констант `Imagick::ALPHACHANNEL_*`. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.8 или старше.

### Список параметров

`mode`

  Одна из констант `Imagick::ALPHACHANNEL_*`.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Смотрите также

- Imagick::setImageMatte() - Устанавливает матовый канал изображения
- Константы альфа-канала Imagick

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Устанавливает артефакт изображения

### Описание

public function Imagick::setImageArtifact(string `$artifact`, string `$value`): bool

Связывает артефакт с изображением. Разница между свойствами изображения и артефактами изображения заключается в том, что свойства являются общедоступными, а артефакты - закрытыми. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.5.7 или старше.

### Список параметров

`artifact`

  Имя артефакта.

`value`

  Значение артефакта.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageArtifact()

    <?php
    function setImageArtifact() {

        $src1 = new \Imagick(realpath("./images/artifact/source1.png"));
        $src2 = new \Imagick(realpath("./images/artifact/source2.png"));

        $src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
        $src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
        $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

        $src1->setImageFormat('png');
        header("Content-Type: image/png");
        echo $src1->getImagesBlob();
    }

    ?>

### Смотрите также

- Imagick::getImageArtifact() - Возвращает артефакт изображения
- Imagick::deleteImageArtifact() - Удаляет артефакт изображения

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Устанавливает атрибут изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Устанавливает атрибут изображения.

### Список параметров

`key`

`value`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Устанавливает цвет фона изображения

### Описание

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Устанавливает цвет фона изображения.

### Список параметров

`background`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет использовать представляющую цвет строку в качестве параметра. Предыдущие версии позволяли использовать только объект ImagickPixel.

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — Устанавливает смещение изображения для любого метода, который свёртывает изображение

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageBias(float `$bias`): bool

Устанавливает смещение изображения для любого метода, который свёртывает изображение (например, Imagick::ConvolveImage()).

### Список параметров

`bias`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageBias()

    <?php
    //требуется ImageMagick версии 6.9.0-1, чтобы оказывать влияние на convolveImage
    function setImageBias($bias) {
        $imagick = new \Imagick(realpath("images/stack.jpg"));

        $xKernel = array(
            -0.70, 0, 0.70,
            -0.70, 0, 0.70,
            -0.70, 0, 0.70
        );

        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

        $imagick->setImageFormat('png');

        header('Content-type: image/png');
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Устанавливает смещение изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageBiasQuantum(float `$bias`): void

Устанавливает смещение изображения. Смещение должно масштабироваться от `0` (без регулировки) до `1` (квантовое значение).

### Список параметров

`bias`

### Возвращаемые значения

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Устанавливает цветность изображения голубой основной точкой

### Описание

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Устанавливает цветность изображения голубой основной точкой.

### Список параметров

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Устанавливает цвет рамки изображения

### Описание

public function Imagick::setImageBorderColor(mixed `$border`): bool

Устанавливает цвет рамки изображения.

### Список параметров

`border`

  Цвет рамки

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь разрешается передавать строку, представляющую цвет в качестве параметра. Предыдущие версии допускают только объект ImagickPixel.

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — Устанавливает глубину определённого канала изображения

### Описание

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Устанавливает глубину определённого канала изображения.

### Список параметров

`channel`

`depth`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Устанавливает маску клипа

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Устанавливает маску клипа изображения из другого объекта Imagick. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.6 или старше.

### Список параметров

`clip_mask`

  Объект Imagick, содержащий маску клипа

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageClipMask()

    <?php
    function setImageClipMask($imagePath) {
        $imagick = new \Imagick();
        $imagick->readImage(realpath($imagePath));

        $width = $imagick->getImageWidth();
        $height = $imagick->getImageHeight();

        $clipMask = new \Imagick();
        $clipMask->newPseudoImage(
            $width,
            $height,
            "canvas:transparent"
        );

        $draw = new \ImagickDraw();
        $draw->setFillColor('white');
        $draw->circle(
            $width / 2,
            $height / 2,
            ($width / 2) + ($width / 4),
            $height / 2
        );
        $clipMask->drawImage($draw);
        $imagick->setImageClipMask($clipMask);

        $imagick->negateImage(false);
        $imagick->setFormat("png");

        header("Content-Type: image/png");
        echo $imagick->getImagesBlob();

    }

    ?>

# Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — Устанавливает цвет указанного индекса цветовой карты

### Описание

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Устанавливает цвет указанного индекса цветовой карты.

### Список параметров

`index`

`color`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Устанавливает цветовое пространство изображения

### Описание

public function Imagick::setImageColorspace(int `$colorspace`): bool

Устанавливает цветовое пространство изображения. Метод следует использовать при создании новых изображений. Чтобы изменить цветовое пространство существующего изображения, вы должны использовать Imagick::transformImageColorspace().

### Список параметров

`colorspace`

  Одна из COLORSPACE констант

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Устанавливает оператор составного изображения

### Описание

public function Imagick::setImageCompose(int `$compose`): bool

Устанавливает оператор составного изображения, полезный для указания, как составлять эскиз изображения при использовании метода Imagick::montageImage().

### Список параметров

`compose`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — Устанавливает сжатие изображения

### Описание

public function Imagick::setImageCompression(int `$compression`): bool

### Список параметров

`compression`

  Одна из `COMPRESSION` констант

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — Устанавливает качество сжатия изображения

### Описание

public function Imagick::setImageCompressionQuality(int `$quality`): bool

Устанавливает качество сжатия изображения.

### Список параметров

`quality`

  Качество сжатия изображения в виде целого числа

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageCompressionQuality()

    <?php
    function setImageCompressionQuality($imagePath, $quality) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageCompressionQuality($quality);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — Устанавливает задержку изображения

### Описание

public function Imagick::setImageDelay(int `$delay`): bool

Устанавливает задержку изображения. Для анимированного изображения это количество времени, в течение которого этот кадр изображения должен отображаться до отображения следующего кадра.

Задержка может быть установлена индивидуально для каждого кадра в изображении.

### Список параметров

`delay`

  Количество времени, выраженное в 'тиках', для которого должно отображаться изображение. Для анимированных GIF-файлов есть 100 тиков в секунду, поэтому значение 20 будет равно 20/100 секунды, то есть 1/5 секунды.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Изменить анимированный GIF с помощью Imagick::setImageDelay()

    <?php

    // Измените анимированный GIF, чтобы его кадры воспроизводились с переменной скоростью,
    // варьируясь от показа в течение 50 мс до 0 мс,
    // что приведёт к пропуску фрейма в большинстве браузеров.
    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageDelay((($frameCount % 11) * 5));
        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/path/to/save/output.gif", true);

    ?>

# Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — Устанавливает глубину изображения

### Описание

public function Imagick::setImageDepth(int `$depth`): bool

Устанавливает глубину изображения.

### Список параметров

`depth`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Устанавливает метод удаления изображения

### Описание

public function Imagick::setImageDispose(int `$dispose`): bool

Устанавливает метод удаления изображения.

### Список параметров

`dispose`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Устанавливает размер изображения

### Описание

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Устанавливает размер изображения (то есть столбцы & строки).

### Список параметров

`columns`

`rows`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Устанавливает имя файла конкретного изображения

### Описание

public function Imagick::setImageFilename(string `$filename`): bool

Устанавливает имя файла конкретного изображения в последовательности.

### Список параметров

`filename`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — Устанавливает формат определённого изображения

### Описание

public function Imagick::setImageFormat(string `$format`): bool

Устанавливает формат определённого изображения в последовательности.

### Список параметров

`format`

  Строковое представление формата изображения. Поддержка формата зависит от установки ImageMagick.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Устанавливает гамму изображения

### Описание

public function Imagick::setImageGamma(float `$gamma`): bool

Устанавливает гамму изображения.

### Список параметров

`gamma`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Устанавливает гравитацию изображения

### Описание

public function Imagick::setImageGravity(int `$gravity`): bool

Устанавливает свойство гравитации для текущего изображения. Метод можно использовать для установки свойства гравитации для одной последовательности изображений. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.4 или старше.

### Список параметров

`gravity`

  Свойство гравитации. Обратитесь к списку gravity констант.

### Возвращаемые значения

Функция не возвращает значения после выполнения.

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Устанавливает цветность изображения зелёной первичной точкой

### Описание

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Устанавливает цветность изображения зелёной первичной точкой.

### Список параметров

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Устанавливает позицию итератора

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageIndex(int `$index`): bool

Устанавливает итератор в позицию в списке изображений, указанную параметром index.

Этот метод объявлен устаревшим. Используйте Imagick::setIteratorIndex().

### Список параметров

`index`

  Позиция для установки итератора.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Устанавливает сжатие изображения

### Описание

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Устанавливает сжатие изображения.

### Список параметров

`interlace_scheme`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Устанавливает метод интерполяции пикселей изображения

### Описание

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Устанавливает метод интерполяции пикселей изображения.

### Список параметров

`method`

  Метод, являющийся одной из констант `Imagick::INTERPOLATE_*`.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Устанавливает итерации изображения

### Описание

public function Imagick::setImageIterations(int `$iterations`): bool

Устанавливает количество итераций, когда анимированное изображение повторяется.

### Список параметров

`iterations`

  Число итераций, которые изображение должно повторить. Используйте значение '0' для непрерывного повторения.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageIterations()

    <?php

    $imagick = new Imagick(realpath("Test.gif"));

    $imagick = $imagick->coalesceImages();
    $imagick->setImageIterations(1);
    $imagick = $imagick->deconstructImages();

    $imagick->writeImages('/path/to/save/OnceOnly.gif', true);

    ?>

# Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — Устанавливает матовый канал изображения

### Описание

public function Imagick::setImageMatte(bool `$matte`): bool

Устанавливает матовый канал изображения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`matte`

  Значение true активирует матовый канал, false - отключает.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Устанавливает матовый цвет изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Устанавливает матовый цвет изображения.

### Список параметров

`matte`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь позволяет использовать представляющую цвет строку в качестве параметра. Предыдущие версии позволяли использовать только объект ImagickPixel.

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — Устанавливает уровень непрозрачности изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::setImageOpacity(float `$opacity`): bool

Устанавливает изображение на указанный уровень непрозрачности. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.1 или старше. Метод работает со всеми каналами, что означает, например, что значение непрозрачности 0.5 сделает все прозрачные области частично непрозрачными. Чтобы добавить прозрачности в области, которые ещё непрозрачны, используйте Imagick::evaluateImage().

### Список параметров

`opacity`

  Уровень прозрачности: 1.0 - полностью непрозрачный, а 0.0 - полностью прозрачный.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setImageOpacity()

Пример использования Imagick::setImageOpacity().

    <?php
    /* Создание объекта */
    $image = new Imagick('source.png');

    /* Установка непрозрачности */
    $image->setImageOpacity(0.7);

    /* Вывод изображения */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — Устанавливает ориентацию изображения

### Описание

public function Imagick::setImageOrientation(int `$orientation`): bool

Устанавливает ориентацию изображения.

### Список параметров

`orientation`

  Одна из констант ORIENTATION

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setImageOrientation()

    <?php
    // Кажется, ничего не делает
    function setImageOrientation($imagePath, $orientationType) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOrientation($orientationType);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — Устанавливает геометрию страницы изображения

### Описание

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Устанавливает геометрию страницы изображения.

### Список параметров

`width`

`height`

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Добавляет именованный профиль к объекту Imagick

### Описание

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

Добавляет именованный профиль к объекту Imagick. Если профиль с таким именем уже существует, он заменяется. Этот метод отличается от метода Imagick::ProfileImage() тем, что он не применяет какие-либо цветовые профили CMS.

### Список параметров

`name`

`profile`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Устанавливает свойство изображения

### Описание

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Устанавливает именованное свойство изображения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.2 или старше.

### Список параметров

`name`

`value`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setImageProperty()

Установка и получение свойств изображения

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Смотрите также

- Imagick::getImageProperty() - Возвращает именованное свойство изображения

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Устанавливает красную первичную точку цветности изображения

### Описание

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Устанавливает красную первичную точку цветности изображения.

### Список параметров

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Устанавливает схему цветопередачи изображения

### Описание

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Устанавливает схему цветопередачи изображения.

### Список параметров

`rendering_intent`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Устанавливает разрешение изображения

### Описание

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Устанавливает разрешение изображения.

### Список параметров

`x_resolution`

`y_resolution`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::setImageResolution()

    <?php
    function setImageResolution($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageResolution(50, 50);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — Устанавливает сцену изображения

### Описание

public function Imagick::setImageScene(int `$scene`): bool

Устанавливает сцену изображения.

### Список параметров

`scene`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Устанавливает продолжительность отображения кадра

### Описание

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Регулирует продолжительность отображения кадра анимированного изображения.

> Замечание:

> Для анимированных GIF-изображений эта функция не изменяет количество "тактов изображения" в секунду, которое всегда определяется как 100. Вместо этого она регулирует количество времени, в течение которого отображается кадр, чтобы имитировать изменение "тактов в секунду".

> Например, для анимированного GIF-изображения, где каждый кадр отображается в течение 20 тактов (1/5 секунды), когда вызывается этот метод для каждого кадра этого изображения с аргументом `50`, кадры корректируются и будут отображаться в течение 40 тактов (2/5 секунды) и анимация будет воспроизводиться с половиной исходной скорости.

### Список параметров

`ticks_per_second`

  Продолжительность, в течение которой должно отображаться изображение, выражается в тактах в секунду.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Изменение анимированного GIF-изображения с помощью Imagick::setImageTicksPerSecond()

    <?php

    // Изменение анимированного gif-изображения так, чтобы первая половина gif воспроизводилась с половинной скоростью,
    // а вторая половина воспроизводилась с удвоенной скоростью.

    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $totalFrames = $imagick->getNumberImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageTicksPerSecond(50);

        if ($frameCount < ($totalFrames / 2)) {
            // Измените кадр так, чтобы он отображался вдвое дольше, чем сейчас.
            $imagick->setImageTicksPerSecond(50);
        } else {
            // Измените кадр так, чтобы он отображался вдвое меньше, чем сейчас.
            $imagick->setImageTicksPerSecond(200);
        }

        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/path/to/save/output.gif", true);

    ?>

# Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — Устанавливает тип изображения

### Описание

public function Imagick::setImageType(int `$image_type`): bool

Устанавливает тип изображения.

### Список параметров

`image_type`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Устанавливает единицы измерения разрешения изображения

### Описание

public function Imagick::setImageUnits(int `$units`): bool

Устанавливает единицы измерения разрешения изображения.

### Список параметров

`units`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Устанавливает метод виртуального пикселя

### Описание

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Устанавливает метод виртуального пикселя.

### Список параметров

`method`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Устанавливает белую точку цветности изображения

### Описание

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Устанавливает белую точку цветности изображения.

### Список параметров

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Устанавливает сжатие изображения

### Описание

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Устанавливает сжатие изображения.

### Список параметров

`interlace_scheme`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Устанавливает позицию итератора

### Описание

public function Imagick::setIteratorIndex(int `$index`): bool

Устанавливает итератор в позицию в списке изображений, указанную с помощью параметра index. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`index`

  Позиция для установки итератора.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setIteratorIndex():

Создание изображения, установка и получение индекса итератора

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Смотрите также

- Imagick::getIteratorIndex() - Возвращает индекс текущего активного изображения
- Imagick::getImageIndex() - Возвращает индекс текущего активного изображения
- Imagick::setImageIndex() - Устанавливает позицию итератора

# Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Устанавливает итератор Imagick к последнему изображению

### Описание

public function Imagick::setLastIterator(): bool

Устанавливает итератор Imagick к последнему изображению.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Устанавливает опцию

### Описание

public function Imagick::setOption(string `$key`, string `$value`): bool

Метод связывает опции с палочкой.

### Список параметров

`key`

`value`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример попытки достичь размера '$extent' методом Imagick::setOption()

    <?php

    function renderJPG($extent)
    {
        $imagePath = $this->control->getImagePath();

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setOption('jpeg:extent', $extent);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

Пример #2 Пример работы метода Imagick::setOption()

    <?php

    function renderPNG($imagePath, $format)
    {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('png');
        $imagick->setOption('png:format', $format);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    // Сохраняем как 64-битное PNG-изображение
    renderPNG($imagePath, 'png64');

    ?>

Пример #3 Пример работы метода Imagick::setOption()

    <?php

    function renderCustomBitDepthPNG()
    {
        $imagePath = $this->control->getImagePath();

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('png');
        $imagick->setOption('png:bit-depth', '16');
        $imagick->setOption('png:color-type', 6);

        header("Content-Type: image/png");

        $crash = true;

        if ($crash) {
            echo $imagick->getImageBlob();
        } else {
            $tempFilename = tempnam('./', 'imagick');
            $imagick->writeimage(realpath($tempFilename));
            echo file_get_contents($tempFilename);
        }
    }

    ?>

# Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Устанавливает геометрию страницы объекта Imagick

### Описание

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Устанавливает геометрию страницы объекта Imagick.

### Список параметров

`width`

`height`

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Устанавливает размер точки

### Описание

public function Imagick::setPointSize(float `$point_size`): bool

Устанавливает объекту свойство размера точки. Метод можно использовать, например, для установки размера шрифта для caption: формата псевдоизображений. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.7 или старше.

### Список параметров

`point_size`

  Размер точки.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setPointSize()

Пример использования Imagick::setPointSize

    <?php
    /* Создание нового объекта Imagick */
    $im = new Imagick();

    /* Установка шрифта для объекта */
    $im->setFont("example.ttf");

    /* Установка размера */
    $im->setPointSize(12);

    /* Создание заголовка */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Работа с изображением */
    ?>

### Смотрите также

- Imagick::getPointSize() - Возвращает размер точки

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Устанавливает callback-функцию, которая будет вызываться во время обработки изображения Imagick

### Описание

public function Imagick::setProgressMonitor(callable `$callback`): bool

Устанавливает callback-функцию, которая будет вызываться во время обработки изображения Imagick.

### Список параметров

`callback`

  Callback-функция прогресса для вызова. Она должна вернуть true, если обработка изображения должна продолжаться, или false, если её нужно отменить. Параметр offset указывает прогресс, а параметр span - общий объем работы, который необходимо выполнить.

  function callback ( mixed `$offset` , mixed `$span` ): bool
  Предостережение

  Значения, передаваемые в callback-функцию, не согласованы. В частности, параметр span может увеличиваться во время обработки изображения. Из-за этого вычисление прогресса выполнения операции с изображением в процентах не является тривиальным.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setProgressMonitor()

    <?php
            $abortReason = null;

            try {
                $imagick = new \Imagick(realpath($this->control->getImagePath()));
                $startTime = time();

                $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                    if (((100 * $offset) / $span)  > 20) {
                        $abortReason = "Обработка достигла 20%";
                        return false;
                    }

                    $nowTime = time();

                    if ($nowTime - $startTime > 5) {
                        $abortReason = "Обработка изображения заняла более 5 секунд";
                        return false;
                    }
                    if (($offset % 5) == 0) {
                        echo "Прогресс: $offset / $span <br/>";
                    }
                    return true;
                };

                $imagick->setProgressMonitor($callback);

                $imagick->waveImage(2, 15);

                echo "Длина данных: ".strlen($imagick->getImageBlob());
            }
            catch(\ImagickException $e) {
                if ($abortReason != null) {
                    echo "Обработка изображения была прервана: ".$abortReason."<br/>";
                }
                else {
                    echo "Поймано исключение ImagickException: ".$e->getMessage()." Тип исключения - ".get_class($e);
                }
            }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Устанавливает значение для записи реестра ImageMagick с именем key

### Описание

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

Устанавливает значение для записи реестра ImageMagick с именем key. Наиболее полезно для установки временного пути, который определяет, где ImageMagick создаёт временные изображения, например, при обработке PDF-файлов.

### Список параметров

`key`

`value`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Устанавливает разрешение изображения

### Описание

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Устанавливает разрешение изображения.

### Список параметров

`x_resolution`

  Горизонтальное разрешение.

`y_resolution`

  Вертикальное разрешение.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примечания

Imagick::setResolution() необходимо вызывать перед загрузкой или созданием изображения.

### Смотрите также

- Imagick::setImageResolution() - Устанавливает разрешение изображения
- Imagick::getImageResolution() - Возвращает разрешение изображения по X и Y

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Устанавливает лимит для конкретного ресурса

### Описание

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

Данный метод используется для изменения лимита ресурсов исходной библиотеки ImageMagick.

### Список параметров

`type`

  Обратитесь к списку констант RESOURCETYPE.

`limit`

  Одна из констант RESOURCETYPE. Единица измерения зависит от типа ограничиваемого ресурса.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Смотрите также

- Imagick::getResourceLimit() - Возвращает лимит ресурсов

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Устанавливает коэффициенты выборки изображений

### Описание

public function Imagick::setSamplingFactors(array `$factors`): bool

Устанавливает коэффициенты выборки изображений.

### Список параметров

`factors`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::setSamplingFactors()

    <?php
    function setSamplingFactors($imagePath) {

        $imagePath = "../imagick/images/FineDetail.png";
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

        $compressed = $imagick->getImageBlob();

        $reopen = new \Imagick();
        $reopen->readImageBlob($compressed);

        $reopen->resizeImage(
            $reopen->getImageWidth() * 4,
            $reopen->getImageHeight() * 4,
            \Imagick::FILTER_POINT,
            1
        );

        header("Content-Type: image/jpg");
        echo $reopen->getImageBlob();
    }

    ?>

# Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Устанавливает размер объекта Imagick

### Описание

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Устанавливает размер объекта Imagick. Установите его перед чтением необработанного формата изображения, такого как RGB, GRAY или CMYK.

### Список параметров

`columns`

`rows`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Устанавливает размер и смещение объекта Imagick

### Описание

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Устанавливает размер и смещение объекта Imagick. Установите его перед чтением необработанного формата изображения, такого как RGB, GRAY или CMYK. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`columns`

  Ширина в пикселях.

`rows`

  Высота в пикселях.

`offset`

  Смещение изображения.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Устанавливает атрибут типа изображения

### Описание

public function Imagick::setType(int `$image_type`): bool

Устанавливает атрибут типа изображения.

### Список параметров

`image_type`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Создаёт 3D-эффект

### Описание

public function Imagick::shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool

Светит дальний свет на изображение для создания трёхмерного эффекта. Вы управляете расположением источника света с помощью азимута и возвышения; азимут измеряется в градусах от оси X, а высота измеряется в пикселях над осью Z. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`gray`

  Значение, отличное от нуля, оттеняет интенсивность каждого пикселя.

`azimuth`

  Определяет направление источника света.

`elevation`

  Определяет направление источника света.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Выбрасывает исключение ImagickException в случае возникновения ошибки.

### Примеры

Пример #1 Пример использования Imagick::shadeImage()

    <?php
    function shadeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadeImage(true, 45, 20);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — Имитирует тень изображения

### Описание

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Имитирует тень изображения.

### Список параметров

`opacity`

`sigma`

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::shadowImage()

    <?php
    function shadowImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadowImage(0.4, 10, 50, 5);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — Повышает резкость изображения

### Описание

public function Imagick::sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Повышает резкость изображения. Сворачивание изображения с помощью гауссовского оператора заданного радиуса и стандартного отклонения (сигма). Для разумных результатов радиус должен быть больше сигмы. Используйте радиус 0, и Imagick::sharpenImage() выберет подходящий для вас радиус.

### Список параметров

`radius`

`sigma`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::sharpenImage()

    <?php
    function sharpenImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sharpenimage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — Удаляет пиксели по краям изображения

### Описание

public function Imagick::shaveImage(int `$columns`, int `$rows`): bool

Удаляет пиксели по краям изображения. Метод выделяет память, необходимую для новой структуры изображения, и возвращает указатель на новое изображение.

### Список параметров

`columns`

`rows`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::shaveImage()

    <?php
    function shaveImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shaveImage(100, 50);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — Создаёт параллелограмм

### Описание

public function Imagick::shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool

Сдвигает один край изображения по оси X или Y, образуя параллелограмм. Сдвиг в направлении X сдвигает край по оси X, а сдвиг в направлении Y перемещает край по оси Y. Величина сдвига контролируется углом сдвига. Для сдвига в направлении X, x_shear измеряется относительно оси Y и аналогично для сдвига в направлении Y, y_shear измеряется относительно оси X. Пустые треугольники, оставшиеся от обрезки изображения, заполняются цветом фона.

### Список параметров

`background`

  Цвет фона.

`x_shear`

  Количество градусов для сдвига по оси X.

`y_shear`

  Количество градусов для сдвига по оси Y.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь допускается строка, представляющая цвет, в качестве первого параметра. Ранее допускался только объект ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::shearImage()

    <?php
    function shearImage($imagePath, $color, $shearX, $shearY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shearimage($color, $shearX, $shearY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — Регулирует контраст изображения

### Описание

public function Imagick::sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Регулирует контраст изображения с помощью алгоритма нелинейного сигмоидального контраста. Увеличьте контраст изображения с помощью сигмоидальной передаточной функции без насыщения светлых участков или теней. Контрастность указывает, насколько увеличить контраст (0 - нет; 3 - типичный; 20 - усиление); Средняя точка указывает, где попадают средние тона в результирующем изображении (0 - белый; 50 - средний серый; 100 - чёрный). Установите резкость на `true` для увеличения контрастности изображения, в противном случае контрастность уменьшается.

Смотрите также » Примеры ImageMagick v6 - Преобразования изображений - Контраст сигмоидальной нелинейности.

### Список параметров

`sharpen`

  Если true, контраст увеличивается, если false - уменьшается.

`alpha`

  Количество применяемого контраста. 1 - очень мало, 5 - значительное, 20 - максимальная величина.

`beta`

  Где будет середина градиента. Это значение должно быть в диапазоне от 0 до 1 - вне зависимости от квантового значения ImageMagick.

`channel`

  К каким цветовым каналам будет применяться контраст.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Создание градиентного изображения, используя Imagick::sigmoidalContrastImage(), подходящую для плавного смешивания двух изображений вместе, со смешиванием, определяемого контрастом и средней точкой.

    <?php

    function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
        $imagick = new Imagick();
        $imagick->newPseudoImage($width, $height, 'gradient:black-white');
        $quanta = $imagick->getQuantumRange();
        $imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

        return $imagick;
    }

    ?>

# Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — Имитирует набросок карандашом

### Описание

public function Imagick::sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool

Имитирует набросок карандашом. Изображение сворачивается с помощью гауссовского оператора, заданного радиуса и стандартного отклонения (сигма). Для разумных результатов радиус должен быть больше сигмы. Используйте радиус 0, чтобы Imagick::sketchImage() использовала подходящий радиус самостоятельно. Угол задаёт угол размытия движения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`radius`

  Радиус гауссианы в пикселях, не считая центрального пикселя.

`sigma`

  Стандартное отклонение гауссианы в пикселях.

`angle`

  Применяется эффект под указанным углом.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::sketchImage()

    <?php
    function sketchImage($imagePath, $radius, $sigma, $angle) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sketchimage($radius, $sigma, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Берёт все изображения из текущего указателя изображения в конец списка изображений и перемещает их

### Описание

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

Берёт все изображения из текущего указателя изображения в конец списка изображений и перемещает их друг к другу сверху вниз, если параметру stack установлено значение true, в противном случае - слева направо.

### Список параметров

`stack`

`offset`

### Возвращаемые значения

Новое размытое изображение.

### Примеры

Пример #1 Пример использования Imagick::smushImages()

    <?php
    function smushImages($imagePath, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = new \Imagick(realpath($imagePath2));

        $imagick->addimage($imagick2);
        $smushed = $imagick->smushImages(false, 50);
        $smushed->setImageFormat('jpg');
        header("Content-Type: image/jpg");
        echo $smushed->getImageBlob();
    }

    ?>

# Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — Применяет к изображению эффект соляризации

### Описание

public function Imagick::solarizeImage(int `$threshold`): bool

Применяет к изображению специальный эффект, аналогичный эффекту, достигаемому в фотолаборатории путём выборочного воздействия света на участки фоточувствительной бумаги. Порог варьируется от 0 до QuantumRange и является мерой степени соляризации.

### Список параметров

`threshold`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::solarizeImage()

    <?php
    function solarizeImage($imagePath, $solarizeThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — Интерполирует цвета

### Описание

public function Imagick::sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Учитывая массив аргументов, содержащий числовые значения, метод интерполирует цвета, найденные с этими координатами, по всему изображению, используя `sparse_method`. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.4.5 или старше.

### Список параметров

`SPARSE_METHOD`

  Обратитесь к этому списку sparse method constants

`arguments`

  Массив, содержащий координаты. Массив в формате `array(1,1, 2,45)`

`channel`

  Передайте любую корректную для вашего режима канала константу. Для применения к более чем одному каналу, комбинируйте константы каналов с помощью побитовых операторов. По умолчанию равно `Imagick::CHANNEL_DEFAULT`. Обратитесь к списку констант каналов

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric2() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(
                400, 400,
                $points,
                \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
            );
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Пример #2 SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage()

    <?php
        function renderImageBilinear() {
            $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Пример #3 SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage()

    <?php
        function renderImageShepards() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Пример #4 SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage()

    <?php
        function renderImageVoronoi() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Пример #5 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric() {
            $points = [
                [0, 0, 'skyblue'],
                [-1, 1, 'skyblue'],
                [1, 1, 'black'],
            ];
            $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Пример #6 createGradientImage is used by other examples. Imagick::sparseColorImage()

    <?php
    function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

        $imagick = new \Imagick();
        $imagick->newImage($width, $height, "white");
        $imagick->setImageFormat("png");

        $barycentricPoints = array();

        foreach ($colorPoints as $colorPoint) {

            if ($absolute == true) {
                $barycentricPoints[] = $colorPoint[0];
                $barycentricPoints[] = $colorPoint[1];
            }
            else {
                $barycentricPoints[] = $colorPoint[0] * $width;
                $barycentricPoints[] = $colorPoint[1] * $height;
            }

            if (is_string($colorPoint[2])) {
                $imagickPixel = new \ImagickPixel($colorPoint[2]);
            }
            else if ($colorPoint[2] instanceof \ImagickPixel) {
                $imagickPixel = $colorPoint[2];
            }
            else{
                $errorMessage = sprintf(
                    "Значение %s не является ни строкой, ни классом ImagickPixel. Не может использовать в качестве цвета.",
                    $colorPoint[2]
                );

                throw new \InvalidArgumentException(
                    $errorMessage
                );
            }

            $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
            $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
            $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
            $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

            $barycentricPoints[] = $red;
            $barycentricPoints[] = $green;
            $barycentricPoints[] = $blue;
            $barycentricPoints[] = $alpha;
        }

        $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

        return $imagick;
    }

    ?>

# Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — Склеивает сплошной цвет в изображение

### Описание

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Склеивает сплошной цвет в изображение.

### Список параметров

`width`

`height`

`x`

`y`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::spliceImage()

    <?php
    function spliceImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spliceImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — Случайно смещает каждый пиксель в блоке

### Описание

public function Imagick::spreadImage(float `$radius`): bool

Метод специальных эффектов, который случайным образом смещает каждый пиксель в блоке, заданном параметром radius.

### Список параметров

`radius`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::spreadImage()

    <?php
    function spreadImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spreadImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Модификация изображения с помощью функции статистики

### Описание

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Заменяет каждый пиксель соответствующей статистикой из окрестности указанной ширины и высоты.

### Список параметров

`type`

`width`

`height`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::statisticImage()

    <?php
    function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->statisticImage(
            $statisticType,
            $width,
            $height,
            $channel
        );

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

    ?>

# Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — Скрывает цифровой водяной знак в изображении

### Описание

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

Скрывает цифровой водяной знак в изображении. Восстановите скрытый водяной знак позже, чтобы доказать подлинность изображения. Смещение определяет начальную позицию на изображении, чтобы скрыть водяной знак.

### Список параметров

`watermark_wand`

`offset`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Объединяет два изображения

### Описание

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

Объединяет два изображения и создаёт одно изображение, которое является составной частью левого и правого изображения стереопары.

### Список параметров

`offset_wand`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — Снимает изображение всех профилей и комментариев

### Описание

public function Imagick::stripImage(): bool

Снимает изображение всех профилей и комментариев.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Выполняет поиск фрагмента изображения в текущем изображении и возвращает второстепенное изображение

### Описание

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

Выполняет поиск фрагмента изображения в текущем изображении и возвращает второстепенное изображение, в котором точное совпадение является полностью белым, а если ни один из пикселей не совпадает — чёрным, в противном случае - некоторым промежуточным уровнем серого. Вы также можете передать необязательные параметры bestMatch и similarity. После вызова функции similarity будет установлено на "score" сходства между второстепенным изображением и соответствующей позицией на большом изображении, bestMatch будет содержать ассоциативный массив с элементами x, y, width, height, которые описывают совпадающую область.

### Список параметров

`Imagick`

`offset`

`similarity`

  Новое изображение, отображающее степень сходства в каждом пикселе.

### Возвращаемые значения

### Примеры

Пример #1 Пример использования Imagick::subImageMatch()

    <?php
    function subImageMatch($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = clone $imagick;
        $imagick2->cropimage(40, 40, 250, 110);
        $imagick2->vignetteimage(0, 1, 3, 3);

        $similarity = null;
        $bestMatch = null;
        $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

        $comparison->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — Закручивает пиксели вокруг центра изображения

### Описание

function Imagick::swirlImage(float `$degrees`): bool

Закручивает пиксели вокруг центра изображения, где градусы указывают размах дуги, по которой перемещается каждый пиксель. Вы получаете более драматический эффект, когда градусы перемещаются от 1 до 360.

### Список параметров

`degrees`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::swirlImage()

    <?php
    function swirlImage($imagePath, $swirl) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->swirlImage($swirl);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — Многократно размещает изображение текстуры

### Описание

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Многократно размещает изображение текстуры поперёк и вниз по холсту изображения.

### Список параметров

`texture_wand`

  Объект Imagick для использования в качестве изображения текстуры.

### Возвращаемые значения

Возвращает новый объект Imagick, к которому применена повторяющаяся текстура.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::textureImage()

    <?php
    function textureImage($imagePath) {
        $image = new \Imagick();
        $image->newImage(640, 480, new \ImagickPixel('pink'));
        $image->setImageFormat("jpg");
        $texture = new \Imagick(realpath($imagePath));
        $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
        $image = $image->textureImage($texture);
        header("Content-Type: image/jpg");
        echo $image;
    }

    ?>

# Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — Изменяет отдельные пиксели на основе порогового значения

### Описание

public function Imagick::thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Изменяет отдельные пиксели в зависимости от их интенсивности по сравнению с пороговым значением. Результатом будет высоко-контрастное, двухцветное изображение.

### Список параметров

`threshold`

`channel`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::thresholdImage()

    <?php
    function thresholdimage($imagePath, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — Изменяет размер изображения

### Описание

public function Imagick::thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool

Метод изменяет размерность изображения до заданных размеров и удаляет цветовые профили и другие метаданные изображения. Цель состоит в том, чтобы создавать легкие миниатюры изображений для отображения на вебе. При передаче в третий параметр значения `true` параметры столбцов и строк определяют предельные размеры каждой стороны. Функция пропорционально уменьшает изображение, пока каждая сторона не совпадёт со значением или не станет меньше значения параметра этой стороны.

> Замечание: Поведение параметра `bestfit` изменили в Imagick 3.0.0. До этой версии при размерах 400 x 300 точек изображение размером 200 x 150 точек оставалось нетронутым. В Imagick 3.0.0 и более поздних версиях изображение будет масштабироваться до размера 400 x 300 точек, поскольку такой размер «больше остальных соответствует» заданным размерам. Потребуется указать как ширину, так и высоту, если задали параметр `bestfit`.

### Список параметров

`columns`

  Ширина изображения.

`rows`

  Высота изображения.

`bestfit`

  Определяет, следует ли принудительно устанавливать максимальные значения.

`fill`

  Изображение заливается фоновым цветом изображения, если изображение не заполняет область на 100 %.

`legacy`

  Параметр принудительно округляет меньшую сторону изображения до ближайшего целого вниз, даже если значение дробной части больше или равно 0.5.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример изменения размера изображения функцией Imagick::thumbnailImage()

    <?php

    function thumbnailImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setbackgroundcolor('rgb(64, 64, 64)');
        $imagick->thumbnailImage(100, 100, true, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — Применяет вектор цвета к каждому пикселю изображения

### Описание

public function Imagick::tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool

Применяет вектор цвета к каждому пикселю изображения. Длина вектора равна 0 для чёрного и белого и максимальная длина для полутонов. Функция векторного взвешивания: f(x)=(1-(4.0*((x-0.5)*(x-0.5)))).

### Список параметров

`tint`

`opacity`

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
PECL imagick 2.1.0 | Теперь разрешает строку, представляющую цвет, в качестве первого параметра и число с плавающей точкой, представляющее значение непрозрачности, в качестве второго параметра. Предыдущие версии допускали только объекты ImagickPixel.

### Примеры

Пример #1 Пример использования Imagick::tintImage()

    <?php
    function tintImage($r, $g, $b, $a) {
        $a = $a / 100;

        $imagick = new \Imagick();
        $imagick->newPseudoImage(400, 400, 'gradient:black-white');

        $tint = new \ImagickPixel("rgb($r, $g, $b)");
        $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
        $imagick->tintImage($tint, $opacity);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Возвращает изображение в виде строки

### Описание

public function Imagick::__toString(): string

Метод возвращает текущее изображение в виде строки. Метод вернёт только одно изображение; метод не следует вызывать на объектах Imagick, которые содержат несколько изображений, например анимированный GIF или PDF с несколькими страницами.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Метод возвращает содержимое строки в случае успешного выполнения или пустую строку, если возникла ошибка.

### Смотрите также

- Imagick::getImageBlob() - Возвращает последовательность изображений в виде BLOB
- Imagick::getImagesBlob() - Возвращает все последовательности изображений в виде большого двоичного объекта

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — Удобный метод настройки размера кадрирования и геометрии изображения

Внимание

Функция объявлена УСТАРЕВШЕЙ в Imagick 3.4.4. Полагаться на эту функцию крайне не рекомендуется.

### Описание

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

Удобный метод настройки размера кадрирования и геометрии изображения из строк. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`crop`

  Строка геометрии обрезки. Геометрия определяет подобласть изображения для обрезки.

`geometry`

  Строка геометрии изображения. Геометрия определяет окончательный размер изображения.

### Возвращаемые значения

Возвращает объект Imagick, содержащий преобразованное изображение.

### Примеры

Пример #1 Пример использования Imagick::transformImage():

В примере создаётся чёрное изображение размером 100x100.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");
    $new_image = $image->transformImage("100x100", "100x100");
    $new_image->writeImage('test_out.jpg');
    ?>

### Смотрите также

- Imagick::cropImage() - Извлекает область изображения
- Imagick::resizeImage() - Масштабирует изображение
- Imagick::thumbnailImage() - Изменяет размер изображения

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Преобразовывает изображение в новое цветовое пространство

### Описание

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Преобразовывает изображение в новое цветовое пространство.

### Список параметров

`colorspace`

  Цветовое пространство, в которое должно быть преобразовано изображение, одна из констант COLORSPACE, например, Imagick::COLORSPACE_CMYK.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования метода Imagick::transformImageColorspace()

Преобразовывает изображение в новое цветовое пространство, а затем извлекает отдельный канал, чтобы можно было просмотреть значения отдельных каналов.

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        //канал должен быть одной из констант канала, например \Imagick::CHANNEL_BLUE
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### Смотрите также

- Imagick::setColorSpace() - Устанавливает цветовое пространство

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Рисует пиксели прозрачными

### Описание

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Рисует пиксели, соответствующие целевому цвету, прозрачным. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.3.8 или старше.

### Список параметров

`target`

  Целевой цвет для рисования

`alpha`

  Уровень прозрачности: 1.0 полностью непрозрачный, тогда как 0.0 полностью прозрачен.

`fuzz`

  Мера округления (fuzz). Например, установите значение fuzz в 10 и красный цвет с интенсивностью 100 и 102 будет интерпретироваться как один и тот же цвет.

`invert`

  Если `true`, закрашивает любой пиксель, который не соответствует целевому цвету.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::transparentPaintImage()

    <?php
    function transparentPaintImage($color, $alpha, $fuzz) {
        $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

        //Должен быть в формате, который поддерживает прозрачность
        $imagick->setimageformat('png');

        $imagick->transparentPaintImage(
            $color, $alpha, $fuzz * \Imagick::getQuantum(), false
        );

        //Не требуется, но помогает убирать оставленные пиксели
        $imagick->despeckleimage();

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — Создаёт вертикальное зеркальное отображение

### Описание

public function Imagick::transposeImage(): bool

Создаёт вертикальное зеркальное изображение, отражая пиксели вокруг центральной оси X, поворачивая их на 90 градусов. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::transverseImage() - Создаёт горизонтальное зеркальное отображение

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Создаёт горизонтальное зеркальное отображение

### Описание

public function Imagick::transverseImage(): bool

Создаёт горизонтальное зеркальное изображение, отражая пиксели вокруг центральной оси Y, поворачивая их на 270 градусов. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Смотрите также

- Imagick::transposeImage() - Создаёт вертикальное зеркальное отображение

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Удаляет края с изображения

### Описание

public function Imagick::trimImage(float `$fuzz`): bool

Удаляет края, которые являются цветом фона с изображения. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

`fuzz`

  По умолчанию цель должна точно соответствовать определённому цвету пикселя. Однако во многих случаях два цвета могут незначительно отличаться. Размытый элемент изображения определяет, насколько допустимо, чтобы два цвета считались одинаковыми. Этот параметр представляет собой изменение квантового диапазона.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Ошибки

Функция выбрасывает исключение ImagickException, если возникла ошибка.

### Примеры

Пример #1 Пример использования Imagick::trimImage():

Обрежьте изображение, затем отобразите в браузере.

    <?php
    /* Создайте объект и прочитайте изображение в */
    $im = new Imagick("image.jpg");

    /* Обрежьте изображение. */
    $im->trimImage(0);

    /* Выведите изображение */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### Смотрите также

- Imagick::getQuantumDepth() - Возвращает величину глубины
- Imagick::getQuantumRange() - Возвращает величину размера спектра Imagick
- imagecropauto() - Обрезает изображение автоматически на основе заданного режима

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — Отбрасывает всё, кроме одного, любого цвета пикселя

### Описание

public function Imagick::uniqueImageColors(): bool

Отбрасывает всё, кроме одного, любого цвета пикселя. Метод доступен, если модуль Imagick скомпилировали с версией ImageMagick 6.2.9 или старше.

### Список параметров

Сигнатура функции не содержит параметров.

### Возвращаемые значения

Функция в случае успешной работы возвращает `true`.

### Примеры

Пример #1 Пример использования Imagick::uniqueImageColors()

    <?php
    function uniqueImageColors($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Reduce the image to 256 colours nicely.
        $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
        $imagick->uniqueImageColors();
        $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — Резкость изображения

### Описание

public function Imagick::unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Резкость изображения. Мы сворачиваем изображение с помощью гауссовского оператора заданного радиуса и стандартного отклонения (сигма). Для получения разумных результатов радиус должен быть больше сигмы. Укажите радиус 0, чтобы Imagi
[file cut: first 33554432 bytes kept]
